Skip to main content

Part 3 — WorkflowManager (WFM)

All endpoints in this section are served by WFM. Most are accessed through FM as a proxy — see the FM Proxy Table for the full mapping.

Table of Contents​

Context​

POST /context​

The main entry point for opening a workflow. This endpoint serves two distinct purposes depending on whether a processInstanceId is provided:

Starting a new process (no processInstanceId): The system validates the provided input against the workflow model's input schema, creates a new process instance, locks the first task for the initiating user, and sends a "Created" notification. The full session response with form context is returned so the UI can render the first form.

Retrieving an existing process (with processInstanceId): The existing process is loaded and authorization is verified. If skipToForm is true, the system bypasses any pre-forms, directly opens the main form, and acquires a lock on the task. A "display" activity is logged to record that the process was viewed. The context is then prepared for form rendering.

Request Body:

{
    appId: string;                  // Auto-injected by FM client
    processId: string;              // Required — the workflow definition identifier
    businessKey?: string;
    taskId?: string;                // Specific task to open
    skipToForm?: boolean | string;  // If true, skip pre-forms and acquire a task lock
    processInstanceId?: string;     // Omit to start new; provide to retrieve existing
    actionType?: ActionType;
    customType?: CustomType;
    input?: Record<string, any>;    // Initial data for new process (validated against model schema)
}
FieldRequiredDescription
appIdYesApplication identifier. If not in body, FM client auto-injects. If still missing, server resolves from processId.
processIdYesIdentifies which workflow definition to use.
processInstanceIdNoOmit to create a new process. Provide to open an existing one.
skipToFormNoWhen true, bypasses pre-forms, directly opens the main form, and acquires a lock on the task.
inputNoInitial data payload for new process creation. Validated against the workflow model's input schema — returns 400 on validation failure.

Response:

{
    context: {
        dataInstance: DataInstance;
        processInstance: IProcessInstance;
        action?: IAction;
    };
    formContext: {
        task?: ITask;
        swimlanes?: Record<string, string[]>;
    };
    swimlanes?: Record<string, string[]>;
}

Errors:

  • 400: Missing processId, unresolvable appId, or invalid input schema.
  • 404: Process instance not found.

POST /context/activity​

Retrieves the full activity log (audit trail) for a process instance. Activities are returned in reverse chronological order (newest first). Each activity represents a user action such as completing a task, saving data, uploading a file, adding a note, viewing the process, etc.

Request Body:

{ processInstanceId: string }

Response: IActivity[] — sorted by timeStamp descending.

Actions​

POST /action/complete​

Completes a user task in a workflow process instance, advancing the process to the next step. This is one of the most critical operations in the system.

The endpoint persists the submitted form data, marks the current task as ended, releases the lock on the completed task, advances the process via the workflow engine, executes post-completion hooks (userTaskActivity named function), and sends a notification. If the process has finished after this completion, the notification type changes to "Finished".

Key behaviors:

  • Context rollback on failure: If the workflow engine fails to advance the process, the system performs an automatic context rollback by restoring the previous state from a backup.
  • Auto-note creation: If additionalInfo.activityDescription is provided, a note is automatically created with that text.
  • Next task lock: After completing the current task, the system checks authorization for the next task and acquires a lock on it if the user is the original form owner.

Request Body:

{
    processId?: string;
    processInstanceId: string;       // Required
    businessKey?: string;
    taskId: string;                  // Required
    actionType: ActionType;          // Required — e.g., "complete", "cancel", "return"
    customType?: CustomType;
    dataInstance: DataInstance;       // Required — the form data to persist
    additionalInfo?: IAdditionalInfo;
}
FieldRequiredDescription
processInstanceIdYesThe process instance to complete a task in.
taskIdYesThe specific task to complete.
actionTypeYesThe completion action type (e.g., "complete", "cancel", "return"). Determines how the process advances.
dataInstanceYesThe current form data to persist before advancing.
additionalInfoNoIf activityDescription is set, a note is automatically created with that text.

Response: Session object with updated context, form context for the next task, and swimlane descriptions.

Errors:

  • 400: Missing processInstanceId, taskId, actionType, or dataInstance.
  • 500: Workflow engine failure (with automatic context rollback attempt).

POST /action/save​

Saves the current form data for a task without completing it (intermediate save / draft). Unlike complete, this endpoint does not advance the process, does not release or acquire any locks, and the task remains in its current state with updated data. It is purely a data persistence operation.

The updated dataInstance is persisted to the context, a "save" activity is logged, the userTaskActivity named function is executed, and an "Updated" notification is sent.

Request Body:

{
    processId: string;               // Required
    processInstanceId: string;       // Required
    businessKey: string;             // Required
    taskId: string;                  // Required
    dataInstance: DataInstance;       // Required — the form data to save
    customType?: CustomType;
    additionalInfo?: IAdditionalInfo;
}

Response: Session object with updated context.

POST /action/retry​

Retries a failed workflow thread by re-executing the step that errored. This allows recovery from transient failures without requiring manual intervention on the process instance.

Request Body:

{
    processInstanceId: string;       // Required
    threadId: string;                // Required — the specific failed thread to retry
    additionalInfo?: IAdditionalInfo;
}

Response: Session object with re-executed context.

Errors:

  • 400: Missing processInstanceId or threadId.
  • 404: Process instance not found.

POST /action/function​

Executes a function-type action on a task. This is triggered when a user clicks a function button on a form. The system locates the flow function associated with the action (matched by actionType="function" and the given customType), executes it with the current form data from the request (not from the database), and returns the updated context including any infoList output from the function.

After execution, the context is persisted and an "Updated" notification is sent.

Request Body:

{
    processId: string;               // Required
    processInstanceId: string;       // Required
    businessKey: string;             // Required
    taskId: string;                  // Required
    dataInstance: DataInstance;       // Required — current form data passed to the function
    customType?: CustomType;         // Used to identify which function action to execute
    additionalInfo?: IAdditionalInfo;
}

Response: Session object with updated context including infoList from the function execution.

Errors:

  • 500: Missing processInstanceId or taskId.
  • 401: Function not defined on the action, or function execution failure.

Process Management​

POST /process/start​

Starts a new workflow process instance. The input data is validated against the workflow model's input schema before the process is created. On success, a "Created" notification is sent and the essential process identifiers are returned.

Unlike POST /context (which also starts a process and returns a full session with form context), this endpoint returns a minimal response containing only the process identifiers — making it more suitable for headless/service-to-service process creation where no UI rendering is needed.

Request Body:

{
    appId: string;                   // Required
    processId: string;               // Required
    input: object;                   // Required — validated against workflow model schema
    customType?: CustomType;
    additionalInfo?: IAdditionalInfo;
    initiatorUserId?: string;        // Optional — override the initiating user
}

Response:

{
    context: {
        processInstance: {
            processInstanceId: string;
            processName: string;
            businessKey: string;
            processStart: Date;
        }
    }
}

Errors:

  • 400: Missing appId or invalid input schema.
  • 500: Missing processId.

POST /action/start​

Alternative path to start a new process. This FM endpoint is proxied to POST /process/start on WFM. Same request/response structure as above.

GET /process/:processInstanceId​

Returns a lightweight view of a process instance — only the task IDs and overall process status. This is a quick status-check endpoint for determining process state without loading the full context, data instance, or activity log.

Path Params:

ParamTypeDescription
processInstanceIdstringThe process instance to query.

Response:

{
    tasks: Array<{ taskId: string }>;
    processStatus: string;
}

External APIs​

These endpoints are designed for service-to-service (headless) communication. Unlike the action endpoints used by the UI, they do not manage task locks or prepare form contexts. They are intended for external systems that need to interact with workflow processes programmatically.

POST /external/task/:taskId/action/:actionType​

Completes a task from an external system. Supports complete, cancel, and return action types. The endpoint updates the context, advances the process, executes post-completion hooks, and sends a notification.

Key behavior: On workflow engine failure, the system performs an automatic context rollback to restore the previous state, preventing data corruption from partial completions.

Path Params:

ParamTypeDescription
taskIdstringThe task to complete.
actionType"complete" | "cancel" | "return"The completion action type.

Request Body:

{
    processInstanceId: string;       // Required
    dataInstance?: DataInstance;
    customType?: CustomType;
    additionalInfo?: IAdditionalInfo;
}

Required Headers: user

Response: { isSuccess: boolean }

Errors:

  • 400: Missing taskId, invalid actionType, or missing processInstanceId.
  • 500: Workflow engine failure (with context rollback).

POST /external/task/:taskId/assignToUser​

Reassigns a task to a specific user. The target user is resolved via the getUser named function, the task's ownership is updated in the context, an activity is logged, and a notification is sent. The target user is also added to the process's contributorUsers list.

Path Params:

ParamTypeDescription
taskIdstringThe task to reassign.

Request Body:

{
    processInstance: string;     // processInstanceId — Required
    targetUserId: string;        // Required — the userId to assign the task to
}

Response: { isSuccess: boolean }

Errors:

  • 400: Missing taskId, targetUserId, or processInstanceId.
  • 404: Target user not found, or task not found in the process instance.

POST /external/task/:taskId/assignToSwimlane​

Reassigns a task to a different swimlane (group/pool). Important business rule: When assigning to a swimlane, the task's userId and userName are cleared — the task becomes unassigned to any specific user and goes back to the pool for any user in that swimlane to pick up.

Path Params:

ParamTypeDescription
taskIdstringThe task to reassign.

Request Body:

{
    processInstance: string;     // processInstanceId — Required
    swimlane: string;            // Required — the target swimlane name
    additionalInfo?: IAdditionalInfo;
}

Response: { isSuccess: boolean }

POST /external/function/:functionId/execute​

Executes a named flow function from an external system. Supports two modes of execution:

  1. With processInstanceId (process-context mode): The function runs within the context of a specific process instance. Input parameters from the request are mapped to the flow's store, and after execution, output parameters are mapped back to the process's data instance.

  2. With only appId (standalone mode): The function runs without any workflow context. No authorization checks are performed, no context is loaded. Input/output parameters are passed directly.

Path Params:

ParamTypeDescription
functionIdstringThe flow function identifier to execute.

Request Body:

{
    processInstanceId?: string;         // For process-context execution
    appId?: string;                     // For standalone execution
    processId?: string;                 // Required with processInstanceId
    taskId?: string;                    // Required with processInstanceId
    businessKey?: string;               // Required with processInstanceId
    inputParams?: Record<string, any>;  // Input parameters mapped to the flow's store
    additionalInfo?: IAdditionalInfo;
}

Required Headers (process-context mode): user

Response:

{
    dataInstance?: DataInstance;      // Updated data instance (only in process-context mode)
    output: Record<string, any>;     // Output parameters from the flow execution
}

Errors:

  • 400: Missing functionId, or missing both processInstanceId and appId, or missing required fields for process-context mode.

POST /external/process/start​

External API to start a new process instance. Identical behavior to POST /process/start, exposed under the /external/ path for external service consumers.

POST /external/process/changeStep​

Forces a process instance to a specific workflow step. This is an administrative endpoint used for process corrections or rerouting — for example, moving a stuck process to a different step or resetting it to an earlier state.

The process instance can be identified either by processInstanceId directly, or by the combination of processId + businessKey.

Request Body:

{
    processInstanceId?: string;      // Provide this OR (processId + businessKey)
    processId?: string;
    businessKey?: string;
    dataInstance?: DataInstance;      // Optional — data to set on the new step
    status?: StatusType;             // Optional — new process status
    stepId: string;                  // Required — the target step to jump to
    additionalInfo?: IAdditionalInfo;
}

Response: { isSuccess: boolean }

Errors:

  • 400: Missing stepId, or missing both processInstanceId and processId+businessKey, or process not found.

POST /external/data/search/:collection​

Searches workflow data across a specified collection. A thin passthrough to the data search engine, allowing external systems to query process data without needing direct database access.

Path Params:

ParamTypeDescription
collectionstringThe collection name to search in (human-readable name).

Request Body: Search parameters (conforms to IDataSearchParams without the collection field).

Response: IDataSearchResult — the search results.

DELETE /external/locks/:userId​

Releases all locks held by a specific user. This is a bulk operation — it releases every lock associated with the given userId, not just a specific task lock. Useful for administrative cleanup or when a user's session is forcefully terminated and their locks need to be freed so other users can pick up the tasks.

Path Params:

ParamTypeDescription
userIdstringThe user whose locks should be released.

Response: { status: "OK" }

File Operations​

All file operations execute workflow-defined flow functions configured in the workflow model (fileUploadFunction, fileDownloadFunction, fileDeleteFunction). The workflow model must have these functions configured for the respective operations to work. If the function is missing, the endpoint returns an error.

Timeout: 300 seconds (5 minutes) for all file operations.

POST /file/upload​

Uploads a file to a process instance. The request is multipart — file metadata is sent as JSON fields and the file content as a binary part. The system validates that the workflow model has a fileUploadFunction defined with the correct input/output schema, executes the upload flow function, adds the uploaded file to the process instance's files array, and records a "fileUpload" activity.

Request Body (multipart/form-data):

PartTypeDescription
fieldsJSON{ processId, processInstanceId, businessKey, taskDefinitionKey, taskId, label, fileName, body }
fileBodyBinaryThe raw file content as a Buffer.

Response: IFile — the uploaded file metadata including id, storageHandle, label, fileName, fileType.

Errors:

  • 500: Missing processInstanceId/processId, missing fileUploadFunction in workflow model, or incorrect function schema.

POST /file/download​

Downloads a file from a process instance by executing the workflow model's file download flow function. The file is identified by its storageHandle. A "fileDownload" activity is recorded, but no context changes are persisted.

Request Body:

{
    processId: string;               // Required
    processInstanceId: string;       // Required
    businessKey: string;
    taskDefinitionKey: string;
    taskId: string;
    storageHandle: string;           // The storage handle identifying the file
    additionalInfo?: IAdditionalInfo;
}

Response: Buffer — raw file content.

POST /file/delete​

Deletes a file from a process instance by executing the workflow model's file delete flow function. The file is removed from the process instance's files array, a "fileDelete" activity is recorded, and the updated context is persisted.

Request Body:

{
    processId: string;               // Required
    processInstanceId: string;       // Required
    businessKey: string;
    taskDefinitionKey: string;
    taskId: string;
    storageHandle: string;           // The storage handle identifying the file to delete
    additionalInfo?: IAdditionalInfo;
}

Response: { isSuccess: boolean }

Notes​

Note operations allow adding, updating, and deleting notes (comments) on process instances. Notes are stored in the processInstance.notes array in reverse chronological order (newest first). All update and delete operations enforce ownership-based authorization — only the original author of a note can modify or remove it.

POST /note/add​

Adds a new note to a process instance. Creates a note object with a UUID, the note text, the current user as author, and a timestamp. The note is prepended to the notes array (newest first). The user is added to contributorUsers, a "noteAdded" activity is recorded, and an "Updated" notification is sent.

Request Body:

{
    processId: string;               // Required
    processInstanceId: string;       // Required
    businessKey: string;             // Required
    taskId: string;                  // Required
    note: string;                    // Required — the note text content
}

Response: Session object with updated context including the new note.

POST /note/update​

Updates an existing note's text. The note is located by its ID, and the system verifies that the current user is the original author before allowing the update. The note's updateDate is refreshed.

Request Body:

{
    processId: string;
    processInstanceId: string;       // Required
    businessKey: string;
    taskId: string;
    note: {                          // Required
        id: string;                  // The note ID to update
        note: string;                // The new note text
    };
}

Response: Session object with updated context.

Errors:

  • 404 (wm3090): Note not found by ID.
  • 404 (wm3091): User is not the author of the note — update denied.

POST /note/delete​

Deletes a note from a process instance. Verifies ownership before deletion — only the original author can delete their note.

Request Body:

{
    processInstanceId: string;       // Required
    noteId: string;                  // Required — the ID of the note to delete
}

Response: Session object with updated context.

Task Functions​

POST /task/:taskId/run/:functionId​

Runs a specific flow function within a task context. This is typically called from the UI when a form needs to execute a backend operation such as a data lookup, calculation, or validation. The system maps input parameters from the request into the function's store model, executes the flow function, and maps output parameters back to the data instance.

If a dataInstance is provided in the request body, the context's data instance is updated with it before execution — ensuring the function operates on the latest form data.

Path Params:

ParamTypeDescription
taskIdstringThe task context to run the function in.
functionIdstringThe flow function identifier to execute.

Request Body:

{
    processId: string;               // Required
    processInstanceId: string;       // Required
    businessKey: string;             // Required
    dataInstance?: DataInstance;      // Optional — updates context before execution
    inputParams?: Record<string, any>; // Optional — input parameters for the function
    additionalInfo?: IAdditionalInfo;
}

Required Headers: user

Response:

{
    dataInstance: DataInstance;       // Updated data instance after function execution
    output: Record<string, any>;     // Output parameters from the function
}

POST /task/:taskId/commit​

Persists a data instance update for a task without executing any functions or completing the task. This is the most lightweight persistence operation available — no activity logging, no flow function execution, no lock operations. It simply replaces the dataInstance in the process instance record and sends an "Updated" notification.

Use this endpoint for intermediate form data persistence where you need the data saved but don't want the overhead of a full save operation.

Path Params:

ParamTypeDescription
taskIdstringThe task to commit data for.

Request Body:

{
    processId: string;               // Required
    processInstanceId: string;       // Required
    businessKey: string;             // Required
    dataInstance: DataInstance;       // Required — the data to persist
}

Required Headers: user

Response: { success: boolean }

Notifications (WFM)​

GET /notifications/:appId​

Retrieves all notifications for a given application, sorted by processInstance.lastUpdate in descending order (most recently updated first). Each notification represents the current state of a process instance and is continuously updated as the process progresses through its lifecycle.

Path Params:

ParamTypeDescription
appIdstringThe application identifier.

Response: INotificationObject[]

{
    eventType: NotificationEventTypes;   // "Created", "Updated", "TaskCompleted", "Finished", etc.
    informList: Array<{
        key?: string;
        label?: string;
        header: string;
        display?: boolean;
    }>;
    processInstance: IProcessInstance;
    onUs: boolean;
    task?: ITask;                        // Present when onUs = true
}

POST /notify/send​

Manually triggers a notification for a process instance. The system first fetches the current context from WFM, then sends the notification with the retrieved context data. This is useful when a notification needs to be re-sent or triggered outside the normal process flow.

Request Body:

{
    appId: string;                       // Required
    businessKey: string;                 // Required
    processId: string;                   // Required
    processInstanceId?: string;
    skipToForm?: boolean;
    eventType: NotificationEventTypes;   // Required — the notification event type
    completed?: boolean;
}

Response: { status: "OK" }

Errors:

  • 404 (C-3003): Context not found from WFM.

Queries​

All query endpoints require the user header. They return 400 if required fields are missing.

POST /query/activeProcessIds​

Queries for active (running) process instance IDs for a given workflow definition. Returns process identifiers and metadata for all instances that are currently in progress.

Request Body:

{ processId: string }   // Required — the workflow definition ID

Required Headers: user

Response: IActiveProcessInfo[]

POST /query/processIdsUpdatedBetween​

Queries for process instance IDs that were updated within a specified date range. Useful for reporting, monitoring, or data export scenarios. The upper bound (date2) is optional — if omitted, the query covers from date1 to the present.

Request Body:

{
    processId: string;       // Required
    date1: DateTime;         // Required — start of the date range
    date2?: DateTime;        // Optional — end of the date range (defaults to now)
}

Required Headers: user

Response: IProcessInfo[]

POST /query/processInstanceContextAndActivity​

Batch retrieval of context and activity data for multiple process instances in a single call. More efficient than making individual calls for each process instance — reduces network round trips when the caller needs data for many instances at once.

Request Body:

{
    processId: string;                   // Required
    processInstances: Array<{            // Required
        processInstanceId: string;
        businessKey: string;
    }>;
}

Required Headers: user

Response: Array<Record<string, any>> — context and activity data for each requested process instance.

Constants​

POST /getConstantValue​

Retrieves the value of a workflow constant by its composite ID. Constants are stored per-application and identified by a composite ID that embeds the app ID prefix. This allows workflow models to reference shared configuration values that can be changed without modifying the model itself.

Request Body:

{
    appId: string;               // Required
    processInstanceId: string;   // Required (validated but not used in lookup)
    constantId: string;          // Required — composite ID embedding app ID and constant identifier
}

Response:

{ result?: string }   // The constant value, or undefined if not found

App Lifecycle​

POST /appclose​

Releases a task lock when the user closes the application (browser/tab). This is a critical lifecycle hook that prevents tasks from being permanently locked when users leave without explicitly completing or releasing them. Without this mechanism, abandoned tasks would remain locked and inaccessible to other users.

Request Body:

{
    taskId: string;      // The task whose lock should be released
    userId: string;      // The user whose lock should be released
}

Response: { status: "OK" }

Batch Jobs​

POST /external/batchjob/retry​

Retries failed batch jobs. Batch jobs have a maximum retry count of 10 — once exhausted, they are marked as "failed". This endpoint provides a manual intervention mechanism to reset failed jobs back to "waiting" with tryCount: 0, giving them a fresh set of retries.

The nHours parameter scopes the retry to recent failures, preventing accidental retry of very old failed jobs that may no longer be relevant.

Request Body:

{ nHours?: number }   // Look back window in hours (default: 24)

Response: { message: string } — e.g., "3 jobs will be executed again." or "No job found."

Health (WFM)​

GET /liveness​

Health check for the WorkflowManager service. Unlike FM's simple liveness probe, the WFM version also reports the list of registered application IDs and version information. Errors from database queries or version reads are captured in the response rather than thrown, ensuring the endpoint remains available even if dependencies are down.

Response:

{
    time: Date;
    name: "workflowManager";
    appList: string;                // Stringified list of appIds or "no AppId found"
    versionInfo: {
        version: string;
        modify: Date;
    } | {
        error: string;
    };
}