Tasks, Activities & Notifications in Jules

Product documentation — How Jules keeps your team aligned: action items that get done, a full record of everything that happened, and the right people notified at the right time.

---

Table of Contents

1. Overview

2. Task System

3. Task Types & Templates

4. Activity Feed

5. Activity Sources

6. Activity Summary (Site Dashboard)

7. Notification System

8. Watchers

9. Stepper Workflow

10. Audit Logs

11. How It All Connects

12. Key Business Rules

13. Glossary

---

Overview

Jules provides three complementary layers of operational tracking:

• Tasks — discrete, assignable action items with due dates, tied to any entity in Jules (operations, containers, invoices, sites, shipments, allocations).

• Activities — a structured, searchable log of commercial interactions: calls, visits, emails, meetings, and internal notes.

• Notifications — a configurable event-driven system that pushes alerts to users when things change across the platform.

Together these modules form the operational backbone for collaboration across trading, logistics, finance, and back-office teams.

---

Task System

A task is an action item assigned to a user, optionally linked to a specific Jules entity. Tasks help teams track work that must happen around an operation, container, invoice, shipment, allocation, or site.

Task Fields

Linked Entities

A task can be attached to exactly one Jules entity at creation time:

The TaskLinkedEntityEnum enumerates all valid entity types, including purchase agreements, sale agreements, credit notes, debit notes, and provider/purchase reports.

Task Lifecycle

There is no intermediate status — a task is either open or done. Deletion is permanent and triggers a notification to the previously assigned user.

Task Filtering & Sorting

Tasks support rich filtering to power inbox and dashboard views:

Sorting options (TaskSortByEnum): creation date ascending/descending, update date ascending/descending, due date ascending/descending.

Due Date Urgency Classification

Tasks can be classified by urgency relative to today:

Note: The dueDateFilter enum is deprecated in favor of the dueDate date range filter.

External Task Access

Tasks created with isExternal = true are accessible to portal users (counterparties using the Jules client portal). This enables collaborative task management across organizational boundaries without exposing internal data.

---

Task Types & Templates

Task Types (TaskType)

A task type is a configurable label that categorizes tasks across the platform. Task types make it easy to filter, group, and report on tasks by function (e.g., "Documentation", "Payment Follow-Up", "Inspection", "Customs").

Task types can be filtered by linkedEntity to show only relevant types for a given context (e.g., only container-related types when creating a task on a container), and an excludeOtherType flag suppresses the generic fallback option.

Task Templates (TaskTemplate)

A task template defines a reusable task blueprint at the organization level. Templates allow teams to standardize recurring workflows — for example, a checklist that should be completed for every export operation.

Templates are defined at the organization level and queried in bulk. They are used to batch-create tasks (createMany mutation) when a workflow is initialized, pre-populating the task list with all the standard steps.

---

Activity Feed

An activity (internally called a "note") is a structured log entry capturing a commercial or operational interaction. Activities are the primary audit trail for relationship management in Jules.

Typical uses include:

• Logging a phone call with a supplier about pricing

• Recording a site visit to a customer

• Noting a negotiation outcome on an operation

• Tracking a follow-up meeting scheduled with a counterparty

Activity Fields

Activity Filtering

Activities can be filtered extensively for CRM-style views:

A free-text searchText parameter enables full-text search across activity content.

Pull Sync for Mobile

Activities support a pull sync query (pullSyncActivities) designed for the mobile application. This query uses cursor-based pagination (lastId + minUpdatedAt) to efficiently fetch only activities that have changed since the last sync — critical for offline-first mobile workflows.

Activity Notifications

When an activity is created, Jules automatically publishes an ON_NOTE_CREATION event to the notification queue. When updated, an ON_NOTE_EDIT event is published. Watchers on the activity receive these notifications.

---

Activity Sources

An activity source captures the channel through which a commercial interaction took place. Sources are a simple, org-configurable lookup list.

Sources are created on demand — if you type a new source value when logging an activity, Jules automatically creates it in the organization's source list (createIfNotExists logic). This makes the list self-curating without requiring upfront configuration.

---

Activity Summary (Site Dashboard)

The ActivitySummary module provides aggregated KPI counts displayed on site overview cards. For each site, Jules computes:

These counts are computed via SQL subqueries and joined against the sites table, giving a fast aggregated view without loading individual records. This powers the site list view where each row shows a summary of activity at a glance.

---

Notification System

Jules uses an event-driven notification pipeline that decouples the action that triggers a notification from its delivery.

Notification Workflows

A notification workflow (NotificationWorkflowEnum) is a named event that the platform can trigger. Users and administrators configure which workflows they are subscribed to. There are over 80 workflows covering every major platform action:

Task workflows:

Operation workflows:

Logistics workflows:

Finance workflows:

Document & compliance workflows:

CRM & master data workflows:

The Event–Notification Pattern

Jules uses a two-table pattern to manage notification delivery:

1. Event (events table): A deduplicated record of what happened. If multiple rapid changes happen to the same object before the notification is sent, Jules upserts the event (merging changes) rather than creating duplicates — preventing notification storms.

2. Notification (notifications table): The actual delivery records, one per recipient per channel. Each notification carries:

   • recipientId — who receives it

   • channelType — email, push, in-app

   • templateId — which message template to use

   • schedule — when to send it (supports delayed/scheduled delivery)

   • isSent — delivery status flag

   • cc — carbon copy recipients

The notification worker queries scheduled notifications within the current hour (getSchedulledEventNotifications) and dispatches them via the appropriate channel.

Notification Config

NotificationConfig is the per-user preference layer: each user's subscriptions to NotificationWorkflowEnum values are stored and queried via userNotificationWorkflows. This allows users to opt in or out of specific notification types from their profile settings.

---

Watchers

Watchers provide a subscription mechanism that links users to specific Jules entities. A watcher on an entity will receive notifications when that entity changes, regardless of their organization-wide notification config.

Watchable Entity Types

Cascading Watch Logic

The watcher system implements intelligent cascading subscription and cascading unsubscription:

Unsubscription is parent-aware: when a user tries to unwatch a container, Jules first checks whether they are still watching a parent entity (an operation or shipment) that includes that container. If they are, the container watch is preserved. This prevents accidental gaps in coverage.

Watcher Identifiers

Watchers are stored using a composite objectUid string: {ENTITY_TYPE}_{entityId} (e.g., OPERATION_4521, CONTAINER_892). This makes the watcher table entity-agnostic — a single table covers all watchable types.

Updating Watchers

• Single watcher: updateWatcher(type: SUBSCRIBE | UNSUBSCRIBE, watchedObjectId, watchedObjectType, watcherId) — subscribe or unsubscribe one user.

• Batch watchers: updateWatchers(watchedObjectId, watchedObjectType, watcherIds[]) — replace the full list of watchers on an entity. Jules diffs the current list against the new list and applies only the necessary adds and removes.

---

Stepper Workflow

The Stepper is a configurable workflow engine that attaches structured progress tracking to Jules entities. It tracks which steps in a predefined checklist have been completed for a given entity.

How the Stepper Works

Stepper configs are organization-level templates (stepper_configs table) that define:

• stepName: The name of the step

• options: The set of valid values for this step

• order: Display order

• linkedEntity: Which entity type this config applies to

• conditions: An optional JavaScript expression evaluated against the entity's data — if the condition is false, this stepper config is skipped for that entity

When a relevant event occurs (e.g., a booking is confirmed), Jules evaluates all stepper configs against the entity's current data and links the matching ones via linked_entities_to_stepper_configs. This ensures each entity only shows the steps that are relevant to its current state.

Supported Entity Types

The Stepper currently writes values to:

Progress is stored as a JSON field (stepperValues) directly on the entity row. This means step state is available alongside other entity data in a single query — no join required.

Updating Stepper Values

The updateStepperValues(linkedEntityId, linkedEntity, values: JSON) mutation merges the new values with the existing JSON object (spread operator semantics). This allows partial updates — updating one step does not reset others.

Note: The older StepperConfig GraphQL type is deprecated. The current implementation uses a database-driven configuration approach, not a GraphQL-exposed config query.

---

Audit Logs

The Audit Log is a comprehensive, tamper-evident record of every write operation performed on the platform. Every INSERT, UPDATE, and DELETE on tracked tables is captured automatically via a PostgreSQL trigger and written to the logs table.

What Gets Logged

Audit Log Fields

Log Groups (logUid)

Every mutation in Jules generates a logUid — a unique identifier that groups all the database writes that happened within a single logical operation. For example, creating an operation with two quality lines will generate one logUid that covers the operation insert, both quality line inserts, and any related records created in the same transaction. This makes it possible to replay or investigate a complete user action as a single atomic unit.

Querying Audit Logs

Audit logs support powerful filtering:

When filtering by a specific operation (objectId with PURCHASE or SALE type), the audit log query automatically includes child records: it returns not just the operation's own log entries, but also logs for its quality lines, containers, loadings, and deliveries. This gives a complete picture of everything that happened on an operation without requiring multiple queries.

Platform Classification

Each log entry is tagged with the platform that initiated the change:

Access Control

Audit log access is gated by the AUDIT_LOGS / VIEW permission via Permit.io. This is typically restricted to administrators and compliance roles.

---

How It All Connects

Tasks, activities, notifications, the stepper, and audit logs are not independent silos — they form an interconnected operational fabric:

---

Key Business Rules

1. Task notification sequence

When a task is created, a notification of type ON_TASK_ASSIGNMENT is sent to the assignee. When a task is updated, the system evaluates three mutually exclusive cases:

• If the task just became done → ON_TASK_DONE

• If the assignee changed → ON_TASK_DELETION to the previous assignee + ON_TASK_ASSIGNMENT to the new assignee

• Otherwise → ON_TASK_EDIT

2. Event deduplication

Before creating a new event record, Jules checks whether there is already an unsent event for the same object. If one exists, it merges the new data into the existing event rather than creating a duplicate. This prevents notification floods when an entity is updated multiple times in quick succession (e.g., a trader updates an operation five times in a minute — the recipient gets one notification, not five).

3. Watcher cascade integrity

When a parent entity (operation, allocation, shipment) is unwatched, Jules checks whether any other watched parent still covers the child before removing the child watch. This prevents a user from accidentally losing notifications on a container when they unsubscribe from one of its operations while still watching the other.

4. Activity source auto-creation

Activity sources are created on first use with createIfNotExists logic. Users never need to pre-configure source values — typing a new source name when logging an activity is sufficient to register it permanently in the organization's list.

5. Audit log operation grouping

Every GraphQL mutation generates a logUid that groups all related database writes into a logical unit. This is critical for understanding compound mutations (e.g., "create operation + create two quality lines + create PO document") as a single event rather than scattered individual rows.

6. Stepper condition evaluation

Stepper configs can include a conditions JavaScript expression evaluated at runtime against the entity's data. This allows one stepper config catalog to serve many different entity configurations — a container in an export operation gets different steps than a container in a local truck operation — without requiring multiple separate configs.

7. External task visibility

The isExternal flag on tasks controls what portal users can see. Internal tasks (documentation reviews, margin approvals, pricing notes) are not visible to counterparties. Only tasks explicitly marked as external are surfaced in the portal, enabling selective collaboration without leaking internal process detail.

8. Manager-aware task filtering

When an authenticated user queries tasks, Jules checks whether they have any direct reports (ManagerToManagee relationship). If they do, the task filter applies ACL-based expansion — managers can see tasks assigned to their direct reports in addition to their own tasks.

---

Glossary