Skip to content
Support
  • There are no suggestions because the search field is empty.

Workflows

The Variable API securely creates, retrieves, updates, and deletes user variables, encrypting and decrypting confidential data as needed via REST endpoints.

Introduction

Interacting with workflows in Vince Live can be done from two different perspectives, namely

Management

Where you create, maintain, update and delete workflows.

Execution

Where you run, check status, return data, list results, etc on workflows

Workflow Name vs Alias

All workflows has both a workflowName and workflowAlias . The name is immutable, but the alias is not.

That means the first time, you create a workflow, both of these properties are the set to the same value.

If you rename a workflow, only the alias is changed (and displayed in UI).

Note! Please consider using workflowAlias as the de-facto name of the workflow when integrating with the workflow endpoints.

API Versions

Currently there are two different API versions.

Management endpoints are available at

GET /workflows # List workflows
GET /workflows/{workflowId} # Get a workflow
PATCH /workflows # Update a workflow (workflowId in body)
POST /workflows # Create a workflow
PUT /workflows # Overwrite a workflow (workflowId in body)
DELETE /workflows/{workflowId} # Delete a workflow

Execution endpoints are available at

GET /live/worfklows/stats # List statistics for all workflows
GET /live/worfklows/{workflowId}/results # List results for a workflow
GET /live/worfklows/{workflowId}/results/{executionId} # Get details about an execution
GET /live/worfklows/{workflowId}/download-url # Get a URL to download workflow files
GET /live/worfklows/{workflowId}/upload-url # Get a URL to upload workflow trigger
POST /live/worfklows/{workflowId} # Async execution of workflow
POST /live/worfklows/{workflowId}/sync # Syncronous execution of workflow (wait for result)

Version 1

Management and execution endpoints are combined at the same base path /v1/workflows/

GET /v1/workflows/ # List workflows
GET /v1/workflows/stats # List statistics for all workflows
GET /v1/workflows/{workflowId} # Get a workflow
GET /v1/worfklows/{workflowId}/download-url # Get a URL to download workflow files
GET /v1/worfklows/{workflowId}/upload-url # Get a URL to upload workflow trigger
GET /v1/workflows/{workflowId}/stats # Get statistics for a workflow
GET /v1/worfklows/{workflowId}/results # List results for a workflow
GET /v1/worfklows/{workflowId}/results/{executionId} # Get details about an execution
GET /v1/worfklows/{workflowId}/results/{executionId}/data # Get result data from an execution

Listing workflows

Only workflows you have access to are returned when listing or search workflows.

Searching workflows

The following List endpoints support searching via search query string parameter

GET /v1/workflows/ # List workflows
GET /v1/worfklows/{workflowId}/results # List results for a workflow

Examples

Search for workflows starting with Finance

GET /v1/workflows/?search=workflowAlias:Finance*

Search for workflow executions in a time range

GET /v1/workflows/WORKFLOW-123/results/?search=startTime:[2023-03-12 to 2023-03-13]

Running workflows

A workflow is triggered by either

  • POST /workflows/{workflowId} (old version) for asynchronous execution, where only an executionId is returned
    • You can use the executionId to check for the workflow status using the Results endpoint.
  • POST /workflows/{workflowId}/sync (old version) for synchronous execution, where either the execution details or the result data is returned

Request structure

Body

The body is your raw data input.

It needs to be one of the following mime types if passed as raw request body:

  • application/json
  • application/json;charset=UTF-8
  • application/xml
  • text/xml
  • text/plain

Note that the content-type header needs to be set accordingly.

Note! Request size limitation is 6MB. If your payload is larger than that, use the triggerFile property to reference a file uploaded via /v1/workflows/{workflowId}/upload-url endpoint.

There is no limitation on mime type for the file when passed as triggerFile

Header

The header takes quite a few parameters, please see Execution controls below.

Execution controls

Controlling workflow execution and behaviour can be done by header parameters

Allowed headers are:

  • vl-wf-control- prefix used for the following properties
    • return-data use with /sync endpoint to ensure data from last step is returned in your request
      • Allowed values: true false
    • log-level log level detail
    • trigger-file reference to file uploaded using /v1/workflows/{workflowId}/upload-url endpoint
    • notify-on-error whether to notify email defined in notification-email on any errors
    • notification-email email for recipient of any errors, if notify-on-error is set to true
  • vl-wf-control as a standalone property with a stringified object as value, containing camelCase key/values, e.g. { returnData: true, logLevel: 10 }
  • vl-wf-header- prefix used for any key / values that should go into the workflow trigger header
    • Note that casing is not considered for keys provided this way
  • vl-wf-header as a standalone property with a stringified or a Base64 encoded object as value
    • Note that HTTP protocol does not support non-UTF8 characters in header values, so use Base64 encoding if you expet non-UTF8 charactes as keys or values.
  • vl-wf-execution- prefix used for any Execution key in the range key1 to key9

Defining execution keys

A workflow can be configured to automatically index key data when storing the result of the workflow. This can be useful to index for instance:

  • order numbers
  • customer names
  • external transaction IDs
  • etc

…that you might want to search for later.

There are a total of 10 available keys you can use freely.

When defined on a workflow, you can set the a name for each key, e.g. key1 is Order number which can be used in relevant places in Vince Live UI.

Every definition must be a valid JSONata expression, which also allows for constant values.

Note that all values stored under each key will be indexed as text, which means that only text or an array of strings (text) is intended to be used as execution key values.

Execution keys will be evaluated and indexed as soon as data is available

Default execution keys

Default key values for a workflow can be configured on workflow level.

In a workflow with the following steps:

Trigger => Rest API (get) => Transform => Rest API (send) keys could be defined as such:

{
  "executionKeys": {
    "key1": {
			"expression": $context.data.all.rest_api_1.orderHeader.orderNumber,
      "name": "Order number"
		},
    "key2": {
      "expression": $context.data.trigger.header.country,
      "name": "Country code"
		},
    "key3": {
      "expression": $context.data.all.transform_1.numOrderLines,
      "name": "Order lines"
		},
    "key4": {
      "expression": $context.data.all.rest_api_2.transactionStatus,
      "name": "Send status"
		},
		"key5": {
      "expression": "PROCESSED", // static value
      "name": "Manual status"
		},
		"key6": {
      "expression": $context.env.api.domain, // environment value
      "name": "Vince Live Environment"
		}
}

In the above example, key2 would be available to search directly after workflow has started, while key4 only would be searchable after workflow has finished.

Configuring default execution keys

You can configure default execution keys via REST API endpoint. This is currently only available in old version

PATCH /workflows

body:

{
    "executionKeys": {
        "key1": {
            "expression": "$context.data.all.transform_1.store",
            "name": "Store"
        },
        "key2": {
            "expression": "$context.data.all.transform_1.item",
            "name": "Item number"
        }
    },
    "workflowId": "WORKFLOW-a87ce5b4d73a4a02906e867eaf019b74",
    "tenantId": "TENANT-aaecd4b277ad4e62be2447c03fa54a98"
}

Runtime execution keys

If you have not yet defined any default execution keys on your workflow, you can still pass keys to be indexed during runtime, when triggering a workflow.

Keys are then defined in the header of the API call as such:

POST /v1/workflows/WORKFLOW-123
header:
  vl-wf-execution-key1: $context.data.all.rest_api_1.orderHeader.orderNumber
  vl-wf-execution-key2: $context.data.trigger.header.country
  vl-wf-execution-key3: $context.data.all.transform_1.numOrderLines
  vl-wf-execution-key4: $context.data.all.rest_api_2.transactionStatus

Note! When defining runtime execution keys, you can override whatever is defined as default execution keys.

Searching for execution key values

GET /v1/workflows/WORKFLOW-123/results/?search=startTime:[2023-03-12 TO 2023-03-13] AND key1="ORDER-123"