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.

Activity Notifications

Jules automatically sends notifications when an activity is created or updated. 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 automatically 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:

How notification delivery works

Jules uses a smart deduplication approach: if multiple changes happen to the same record in quick succession, recipients receive a single consolidated notification rather than a flood of individual alerts.

Each notification record carries:

• Recipient — who receives it
• Channel — email, push, or in-app
• Schedule — when to send it (supports delayed/scheduled delivery)
• Status — whether it has been sent
• CC — carbon copy recipients

Notification Config

Each user's notification preferences are configured from their profile settings — users can opt in or out of specific notification types.

---

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.

Updating Watchers

Watchers can be added or removed individually or in bulk. When updated in bulk, Jules applies only the necessary changes — it doesn't re-send notifications for users who were already watching.

---

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

The stepper is configured at the organization level with named steps, valid values, and display order. When a relevant event occurs (e.g., a booking is confirmed), Jules evaluates which steps apply to the entity's current state and links them accordingly. This ensures each entity only shows the steps that are relevant to it.

Supported Entity Types

The Stepper currently writes values to:

Progress is stored directly on the entity record alongside its other data. This means step state is available alongside other entity data in a single query — no join required.

Updating Stepper Values

Stepper updates are incremental — updating one step's progress does not reset others.

---

Audit Logs

The Audit Log is a comprehensive, tamper-evident record of every write operation performed on the platform. Every create, update, and delete action on tracked records is captured automatically.

What Gets Logged

The audit log captures changes to all major entities: operations, containers, invoices, payments, activities, shipments, tasks, companies, sites, and more.

Audit Log Fields

Log Groups

Every action in Jules generates a unique identifier that groups all related database changes into a logical unit. For example, creating an operation with two quality lines will generate one identifier 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 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 action in Jules generates a unique identifier that groups all related database changes 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 configurations can include conditions evaluated against the entity's current 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. If they do, the task filter automatically expands to include their team members' tasks — managers can see tasks assigned to their direct reports in addition to their own tasks.

---

Glossary