Documents, PDFs & Integrations in Jules

Product documentation — How Jules generates, stores, and distributes commercial documents (POs, SOs, invoices, and more), manages document templates and legal terms, handles Letter of Credit workflows, and connects with external systems through email and webhooks.

Table of Contents

1. Overview

2. Document Types (DocType)

3. PDF Templates

4. Document Terms (DocTerm)

5. Site-Level PDF Parameters

6. PDF Generation Workflow

7. Uploaded Documents & Manual Upload

8. Document Approval Workflow

9. AI Document Verification & Mismatch Detection

10. Document Receivables (DocReceivables)

11. Letter of Credit

12. Email Integration

13. Webhook System

14. Relationships with Other Modules

15. Key Business Rules

16. Glossary

Overview

Jules has a complete document management layer that covers the full lifecycle of commercial paperwork — from generating a Purchase Order the moment a deal is confirmed, to distributing it to a counterparty by email, to verifying a Bill of Lading uploaded by the supplier against Jules data using AI.

The document system is built on four interconnected concepts:

Document Types (DocType)

Every document in Jules belongs to a DocType — a fixed category that determines its purpose, how it is rendered, and which entities it can be attached to.

Note: RECOVERY_CERTIFICATE_EXCEL is generated client-side in the front-end and is not processed through the backend generation pipeline.

PDF Templates

A PdfTemplate is the configuration record that tells Jules how to render a document. Templates decouple the rendering logic from individual documents, so the same template can be reused across hundreds of operations.

Template fields

Supported output formats

Template scope by entity

Templates are scoped to a LinkedEntityEnum value, which controls which object type can use them:

All templates are fetched via filteredPdfTemplates with filters for linkedEntity, docType, and isDefault. The pdfTemplatesChoices query returns a dropdown-friendly list for the UI.

Document Terms (DocTerm)

DocTerms are the legal boilerplate paragraphs embedded in commercial documents — the standard terms and conditions, payment clauses, and legal notices printed at the bottom of POs, SOs, and invoices.

DocTerms can be filtered by docType and billingEntity, allowing organizations that operate under multiple billing entities to maintain distinct sets of legal terms per entity. Terms are updated via updateDocTerm.

Site-Level PDF Parameters

When a user opens the document generation dialog for a purchase or sale operation, Jules pre-fills several fields from site-level configuration — the PoSoParams. These defaults are stored per site and per quality, and are fetched by the getPoSoParams query.

These parameters reduce repetitive data entry when generating routine POs and SOs.

PDF Generation Workflow

How a document is generated

Generation steps in detail

1. Template selection: The user selects (or Jules auto-selects) a PdfTemplate for the document type.

2. Argument pre-fill (pdfArgs): Jules fetches and pre-fills the data payload for the template — operation details, quality lines, counterparty information, site parameters, and legal terms. The user can review and override fields in the UI.

3. Document creation: Jules calls the document generation service with the template ID, data payload, and output format. The service renders the document and returns a storage URL.

4. JSON snapshot: A JSON copy of the data used to render the document is stored alongside the PDF, for audit purposes.

5. PDF record creation: A Pdf record is created in Jules linking the document URL to the entity (operation, invoice, container, etc.) with the appropriate status.

Batch and aggregate generation

Jules supports batch generation — generating the same document for multiple entities in a single call. For example, generating delivery slips for all containers in a shipment at once.

It also supports aggregate generation (shouldGenerateAggregatePdf: true), which combines data from multiple entities into a single consolidated document. This is useful for multi-container shipment summaries.

Supported entities for generation

Asynchronous generation

For large-scale generation (e.g., generating documents for all containers in a shipment), Jules uses generateEntityDocs, which pushes a job to the RabbitMQ worker queue (generateEntityDocs queue). The generation happens asynchronously in the background, so the user's session is not blocked.

Uploaded Documents & Manual Upload

Not all documents are generated by Jules. Counterparties send back signed POs, Bills of Lading, weight certificates, and other documents that must be stored in Jules.

The savePdfInfo mutation handles manual uploads:

PO/SO status auto-update on upload

When a signed document is uploaded back into Jules:

• Uploading a PURCHASE_ORDER automatically updates the parent operation's poStatus to SIGNED_AND_UPLOADED

• Uploading a SALES_ORDER automatically updates the parent operation's soStatus to SIGNED_AND_UPLOADED

This tracks the commercial document lifecycle without any manual status update.

PO/SO document lifecycle

Merging documents

Multiple PDF documents can be merged into a single file using the mergePdfs mutation. Jules calls the document service to combine the files (in the exact order of IDs provided) and creates a new Pdf record of type MERGED_DOCUMENTS linked to the same entities.

Marking documents complete

markAllAsComplete flags all documents attached to an entity as complete in a single operation. Useful when finalizing a shipment where multiple documents have been collected.

Document Approval Workflow

Some documents require internal review before being shared externally. Jules supports a structured approval workflow on PDFs.

How it works

1. After generating a document, a user submits it for approval with insertPdfsToApprovers, specifying which users should review it. An optional requestComment can be included.

2. Reviewers are notified (via RabbitMQ sendNotification queue, trigger ON_REQUEST_FOR_DOCUMENT_APPROVAL).

3. Each approver can either approvePdf or rejectPdf (with a rejectComment explaining the issue).

4. The reviewStatus field reflects the outcome: PENDING, APPROVED, or REJECTED.

5. When the review is complete, a ON_DOCUMENT_REVIEWED notification is sent.

Approval-related fields on a PDF

AI Document Verification & Mismatch Detection

Jules includes an AI-powered document verification capability that compares uploaded documents against the data stored in Jules, highlighting discrepancies.

This is currently used for two verification types:

How AI verification works

The Mismatch record

Each detected discrepancy is stored as a Mismatch:

Reviewer actions on mismatches

Reviewers can:

• Approve a mismatch (status: APPROVED) — acknowledging the discrepancy as acceptable

• Reject a mismatch (status: REJECTED) — flagging it as a genuine error requiring correction

• Update a mismatch — adding issue text, improvement suggestions, or correcting the Jules value

This workflow gives trade operations teams a structured way to review and sign off on incoming shipping documents before funds are released or goods cleared.

Document Receivables (DocReceivables)

DocReceivables defines which documents a counterparty (supplier or customer) is expected to provide for a given document type. It is a configuration table that maps associatedObjectType + docType combinations to required receivable items.

This is used to power the document checklist feature — showing operations teams which documents they are still waiting to receive from a counterparty, for example:

• Bill of Lading from the shipping line

• Weight certificate from the inspection company

• Phytosanitary certificate from the supplier

The getByDocTypeAndAssociatedObjects query is used internally to look up what documents are expected for a given entity type and document category.

Letter of Credit

A Letter of Credit (LC) is a bank-issued financial guarantee commonly used in international commodity trade to ensure payment upon presentation of shipping documents.

Jules models Letters of Credit as first-class entities that can be created, managed, and linked to operations — particularly export sales where the buyer's bank issues an LC as payment security.

Letter of Credit fields

LC and operations

An LC is typically attached to an export sale operation. The LC covers the payment obligation for that shipment — the customer's bank commits to paying once the seller presents the required documents (BL, invoice, packing list, etc.) within the periodPresentation window.

AI verification for LCs

When the aiApi field on the linked PdfTemplate is set to LC_VERIFICATION, Jules can use AI to verify an uploaded LC document against the terms recorded in Jules — checking that the bank-issued document matches what was agreed. Discrepancies are surfaced as Mismatch records (see AI Document Verification).

Email Integration

Jules has a built-in email integration that allows users to send commercial documents directly from the platform. Sent emails are stored as Email records linked to their parent entity.

Sending an email

The sendEmail mutation accepts:

Email storage

Each sent email is stored as an Email record with:

• Full header information (to, from, cc, bcc)

• Subject and body

• Links to the attached Pdf records

• Reference to the linked Jules entity

Emails are queryable via filteredEmails filtered by linkedEntity + linkedEntityIds, allowing the activity feed of an operation or invoice to display the full communication history.

Permission model

The EMAILS resource is governed by Permit.io:

• SEND — controlled at the linked entity level (users can only send from entities they have access to)

• VIEW — can view sent emails for accessible entities

Webhook System

Jules provides a webhook system that automates the distribution of data and documents to external recipients when specific events occur. Webhooks are pre-configured notification channels, typically used to:

• Share operation summaries with counterparties or internal stakeholders

• Notify logistics partners when containers are ready to ship

• Push shipment data to external systems

• Share invoices with finance teams

Webhook triggers

Webhook fields

Running a webhook manually

In addition to automatic triggers, users can manually fire a webhook for an operation using runOperationWebhook:

runOperationWebhook(operationId, webhookId, type)

This is useful for re-sending a notification, or sending to a new recipient who joined after the original send.

Associating webhooks with operations

The upsertWebhookToOperation mutation creates a persistent link between a webhook configuration and an operation, so that future events on the operation automatically use the configured webhook.

External webhook choices

Before sending, Jules builds a filtered list of applicable webhook configurations for the user via externalWebhookChoices. This query:

1. Fetches all EXTERNAL webhooks matching the trigger type

2. Enriches them with entity-specific data (e.g., container details for ON_SHARE_CONTAINERS)

3. Returns a dropdown-ready list with pre-populated recipient suggestions

Relationships with Other Modules

The document and integration layer connects to virtually every other Jules module:

Key Business Rules

1. Template selection priority

When multiple templates exist for the same docType + linkedEntity combination, Jules uses the priorityConfig field to determine which template to use. The isDefault flag marks the fallback template for cases where no priority rule matches.

2. Signed document upload auto-updates operation status

When a user uploads a signed PO back into Jules (savePdfInfo with docType: PURCHASE_ORDER), Jules automatically advances the operation's poStatus to SIGNED_AND_UPLOADED. The same applies for SALES_ORDER → soStatus. This keeps the document lifecycle in sync with the operation status without manual updates.

3. Documents notify via worker queue

All document upload events (manual uploads, approval requests, approval decisions) fire asynchronous notifications through the RabbitMQ worker queue. This means document-related notifications (e.g., "Your document has been approved") are delivered without blocking the API response.

4. AI verification is non-destructive

Mismatch records produced by AI verification are proposals, not automatic corrections. A human reviewer must explicitly approve or reject each mismatch. Jules never auto-corrects data based on AI output — the AI highlights discrepancies, the user decides.

5. Webhooks respect operation type

When running runOperationWebhook, the type parameter (BUY or SELL) controls which version of the data is sent. This is important because an allocation links a purchase and a sale — the webhook must know which side to represent to the external recipient.

6. Email threads are preserved

Emails sent from Jules can be associated with an existing threadId, allowing replies to be grouped in the email client. This is important when multiple emails are sent about the same shipment — they appear as a conversation thread, not isolated messages.

7. Public templates are accessible to portal users

Templates flagged isPublic: true are accessible to external counterparty users on the Jules portal. This allows, for example, a supplier to download their delivery slip directly from the portal, without needing a full Jules account.

8. Letter of Credit shipping line restrictions are enforced at the booking stage

The authorizedShippingLines and restrictedShippingLines fields on an LC carry commercial restrictions from the buyer's bank. Operations teams use these to ensure the freight booking uses a compliant carrier, since using a restricted shipping line could result in the bank refusing to honor the LC.

9. PDF merging preserves document order

When using mergePdfs, Jules strictly respects the order of ids provided. The final merged document presents pages in the exact sequence requested — typically: BL first, then packing list, then invoice, etc. — matching the order required by the bank for LC presentation.

10. DocReceivables vs uploaded PDFs

DocReceivables tracks what documents are expected from a counterparty. Actual received documents are stored as isUploaded: true PDF records. Together, these two tables power the "documents pending" checklist visible on an operation — showing what has been received and what is still outstanding.

Glossary