Skip to main content

Running Workflows

The Workflow Engine API provides two main endpoints for operation and are called with properly formatted POST requests.

  • /init
  • /message

These endpoints allow you to start a new workflow instance and process messages to resume an existing workflow.

POST /init​

The /init endpoint is used to initialize a new workflow instance.

It accepts a payload that specifies the workflow type, correlation ID, and other relevant information.

Init Request​

The request payload for the /init endpoint should include the following properties:

{
  "messages": [
    {
      "typeWithVersion": "ExampleWorkflow@2.0",
      "correlationId": "123",
      "invocationPoint": "",
      "instanceId": "123"
    }
  ],
  "payload": {
    "payloadType": "json",
    "userId": "user@123",
    "email": "sample@email.com"
  }
}
  • messages: An array of message objects, each containing:
    • typeWithVersion: The type and version of the workflow to be initiated.
    • correlationId: A unique identifier to correlate messages.
    • invocationPoint: The point at which the workflow is invoked.
    • instanceId: A unique identifier for the workflow instance.
  • payload: An object containing the payload data for the workflow, including:
    • payloadType: The type of the payload (e.g., "json").
    • userId: The user ID associated with the workflow.
    • email: The email address associated with the workflow.

Init Response​

The response from the /init endpoint will indicate whether the workflow initialization request was successful.

{
  "success": true,
  "message": "Workflow initialization request sent."
}

Init Sequence​

  1. Receive Request: The server receives a POST request to the /init endpoint with the specified payload.
  2. Validate Payload: The server validates the payload to ensure all required properties are present.
  3. Initialize Workflow: The server initializes a new workflow instance based on the typeWithVersion specified in the payload.
  4. Send Response: The server sends a response indicating whether the workflow initialization request was successful.
  5. Workflow Response: If the workflow completes and has a response, it is sent back to the client directly from the worker workflow process.

POST /message​

The /message endpoint is used to process a workflow message.

It accepts a payload that specifies the workflow type, correlation ID, and other relevant information.

Message Request​

The request payload for the /message endpoint should include the following properties:

{
  "messages": [
    {
      "typeWithVersion": "ExampleWorkflow@2.0",
      "correlationId": "123",
      "invocationPoint": "",
      "instanceId": "123"
    }
  ],
  "payload": {
    "payloadType": "json",
    "userId": "user@123",
    "email": "sample@email.com"
  }
}
  • messages: An array of message objects, each containing:
    • typeWithVersion: The type and version of the workflow to be resumed.
    • correlationId: A unique identifier to correlate messages.
    • invocationPoint: The point at which the workflow is invoked.
    • instanceId: A unique identifier for the workflow instance.
  • payload: An object containing the payload data for the workflow, including:
    • payloadType: The type of the payload (e.g., "json").
    • userId: The user ID associated with the workflow.
    • email: The email address associated with the workflow.

Message Response​

The response from the /message endpoint will indicate whether the workflow message processing request was successful.

{
  "success": true,
  "message": "Workflow message processing request sent."
}

Message Sequence​

  1. Receive Request: The server receives a POST request to the /message endpoint with the specified payload.
  2. Validate Payload: The server validates the payload to ensure all required properties are present.
  3. Process Message: The server processes the workflow message based on the typeWithVersion specified in the payload.
  4. Resume Workflow: If the workflow instance is found, the server resumes the workflow from the specified invocationPoint.
  5. Send Response: The server sends a response indicating whether the workflow message processing request was successful.
  6. Workflow Response: If the workflow has a response, it is sent back to the client directly from the worker workflow process.

Considerations​

When using the Workflow Engine API to run workflows, consider the following:

  • Payload Data: Ensure that the payload data provided in the request is properly formatted and contains all required information.
  • Workflow Type: Specify the correct workflow type and version to ensure that the correct workflow is initialized or resumed.
  • Correlation ID: Use a unique correlation ID to correlate messages and workflow instances.
  • Invocation Point: Provide the correct invocation point to resume the workflow from the desired point.
  • Instance ID: Use a unique instance ID to identify the workflow instance.
  • Response Handling: Handle the workflow response data appropriately based on the requirements of your application. This includes making sure the network security is properly configured to allow the response to be sent back to the client.
X

Graph View