Workflows API

The workflow APIs are designed to handle the creation and processing of workflows.

Available URLs

URL Description
GET /api/v1/workflowModels Returns an array of workflow models for a given a tenant
POST /api/v1/workflowModels/bulk Returns an array of workflow models for a collection of tenants
POST /api/v1/workflowInstances Creates a new workflow instance and starts execution of the instance
GET /api/v1/workflowInstances Returns an array of workflow instances
GET /api/v1/workflowInstances/{wfInstanceId}/variables Returns a JSON object whose properties are workflow instance variables
GET /api/v1/user/{emailAddress}/tasks Returns an array of user tasks

Workflow Models

GET /workflowModels

Gets an array of workflow models for the dtm-accusoft-tenant header value. The query parameters taskAssignee and expand set to instanceCount will return workflow instance information. See details below.

Request
Request Headers
Name Description
Content-Type Must be application/json
Authorization The API token supplied by OnTask
accusoft-dtm-tenant The unique identifier of the owning tenant
URL parameters
Parameter Description
taskAssignee Optional query string parameter that is the email of the user who may be the assignee for workflow instances owned by the workflow model. When this property is set, the assignedWorkflowInstancesCount property will be returned in the response.
expand Optional query string parameter which can be set to instanceCount. When this property is set, the runningInstances and totalInstances properties will be returned in the response.

Successful Response

Response Body

An array of JSON objects with the following properties or an empty array if no workflow models were found.

  • tenantId (String) Unique identifier of the owning tenant
  • wfModelId (String) Unique identifier of the workflow model
  • name (String) Name of the workflow model
  • state (String) The state of the workflow model. Can be active (can be executed) or unpublished (cannot be executed).
  • permissions (Object Array) An array of JSON objects with the following properties which help define the workflow model security:
    • allowedTenantId (String) Unique identifier of the tenant that the requiredPermission property below applies to. Value will be public if there are no restrictions on who can start a workflow instance.
    • requiredPermission (String) The permission required to start a workflow instance
  • runningInstances (Number) The number of running workflow instances for the workflow model
  • totalInstances (Number) The total number of running, completed and canceled workflow instances for the workflow model
  • assignedWorkflowInstancesCount (Number) The total number of workflow instances for the workflow model assigned to the user set to the taskAssignee query string parameter

Error Responses

Status Code JSON errorCode Description
401 Unauthorized Insufficient permissions
480 MissingInput A required accusoft-dtm-tenant header was not provided

Example

Request

GET /workflowModels?taskAssignee=ksmith@acme.com&expand=instanceCount
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5kk6IkpXVACO.eyJzdWIiOiJhNmIxNTdjZS0yMzIzLTQ0MjMtYTJmZS1jYzE3M2JjZWY5YzAiLCJpYXQiOjE0OTA2MTYwMDQsImV4cCI6MTQ5MDc4ODgwNCwiaXNzIjoiaHR0cHM6Ly9kZXYub250YXNrLmlvIn0.hFdDUqu1rcG1bsNzKNK1_sMSNkGLgR31oooMIwjGCo
accusoft-dtm-tenant: f3ca20bf-db4d-43e3-9478-4c0qpve58c46

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "tenantId": "f3ca20bf-db4d-43e3-9478-4c0qpve58c46",
    "wfModelId": "0b7b7f5c-41d3-4a87-8609-fe0be0a8098d",
    "name": "Credit Application",
    "state": "active",
    "permissions": [
      {
        "allowedTenantId": "706498c7-28ee-4b1f-9921-45f6a23de796",
        "requiredPermission": "can-administer-workflows"
      }
    ],
    "runningInstances": 7,
    "totalInstances": 9,
    "assignedWorkflowInstancesCount": 1
  },
  {
    "tenantId": "f3ca20bf-db4d-43e3-9478-4c0qpve58c46",
    "wfModelId": "d353d594-4dr9-4e50-bca7-f78g47e6a467",
    "name": "Employee Survey",
    "state": "unpublished",
    "permissions": [
      {
        "allowedTenantId": "public",
        "requiredPermission": null
      }
    ],
    "runningInstances": 0,
    "totalInstances": 0,
    "assignedWorkflowInstancesCount": 0
  }
]

POST /workflowModels/bulk

Gets an array of workflow models for the tenantIds property supplied in the body of the request. The query parameters taskAssignee and expand set to instanceCount will return workflow instance information. See details below.

Request
Request Headers
Name Description
Content-Type Must be application/json
Authorization The API token supplied by OnTask
URL parameters
Parameter Description
taskAssignee Optional query string parameter that is the email of the user who may be the assignee for workflow instances owned by the workflow model. When this property is set, the assignedWorkflowInstancesCount property will be returned in the response.
expand Optional query string parameter which can be set to instanceCount. When this property is set, the runningInstances and totalInstances properties will be returned in the response.
Request Body
  • tenantIds (String Array) Required unique identifier(s) of the owning tenant(s).

Successful Response

Response Body

An array of JSON objects with the following properties or an empty array if no workflow models were found.

  • tenantId (String) Unique identifier of the owning tenant.
  • wfModelId (String) Unique identifier of the workflow model.
  • name (String) Name of the workflow model.
  • state (String) The state of the workflow model. Can be active or unpublished.
  • permissions (Object Array) An array of JSON objects with the following properties which help define the workflow model security:
    • allowedTenantId (String) Unique identifier of the tenant that the requiredPermission property below applies to. Value will be public if there are no restrictions on who can start a workflow instance.
    • requiredPermission (String) The permission required to start a workflow instance.
  • runningInstances (Number) The number of running workflow instances for the workflow model.
  • totalInstances (Number) The total number of workflow instances for the workflow model.
  • assignedWorkflowInstancesCount (Number) The total number of workflow instances for the workflow model assigned to the user set to the taskAssignee query string parameter.

Error Responses

Status Code JSON errorCode Description
401 Unauthorized Insufficient permissions
480 MissingInput A required tenantIds property was not provided
480 InvalidInput tenantIds should be an array

Example

Request

GET //workflowModels?taskAssignee=ksmith@acme.com&expand=instanceCount
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5kk6IkpXVACO.eyJzdWIiOiJhNmIxNTdjZS0yMzIzLTQ0MjMtYTJmZS1jYzE3M2JjZWY5YzAiLCJpYXQiOjE0OTA2MTYwMDQsImV4cCI6MTQ5MDc4ODgwNCwiaXNzIjoiaHR0cHM6Ly9kZXYub250YXNrLmlvIn0.hFdDUqu1rcG1bsNzKNK1_sMSNkGLgR31oooMIwjGCo

{
    "tenantIds": ["f3ca20bf-db4d-43e3-9478-4c0qpve58c46", "c9so20bf-ak4d-43e3-1940-4c0qpve58c46"]
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "tenantId": "f3ca20bf-db4d-43e3-9478-4c0qpve58c46",
    "wfModelId": "0b7b7f5c-41d3-4a87-8609-fe0be0a8098d",
    "name": "Credit Application",
    "state": "active",
    "permissions": [
      {
        "allowedTenantId": "706498c7-28ee-4b1f-9921-45f6a23de796",
        "requiredPermission": "can-administer-workflows"
      }
    ],
    "runningInstances": 2,
    "totalInstances": 4,
    "assignedWorkflowInstancesCount": 2
  },
  {
    "tenantId": "c9so20bf-ak4d-43e3-1940-4c0qpve58c46",
    "wfModelId": "s294d594-4dr9-4e50-bca7-f78g47e6a467",
    "name": "Expense Report",
    "state": "unpublished",
    "permissions": [
      {
        "allowedTenantId": "public",
        "requiredPermission": null
      }
    ],
    "runningInstances": 0,
    "totalInstances": 0,
    "assignedWorkflowInstancesCount": 0
  }
]

Workflow Instances

POST /workflowInstances

Creates a new workflow instance and starts execution of the instance.

The workflow instance is created from the workflow model ID that is set to wfModelId in the request body.

The body of the request may also contain all of the data required to start the workflow instance set to wfData. This data is completely dependent on the workflow model that is being instantiated. If the workflow model contains a start form, then the data specified in the start form may be supplied. Data that is marked as required in the start form must be supplied.

Request
Request Headers
Name Description
Content-Type Must be application/json
Authorization The API token supplied by OnTask
Request Body
  • wfModelId (String) Required. Identifies the workflow model.
  • wfData (Object) Optional JSON object representing the data required to initiate the workflow.

Successful Response

Response Body

JSON with the following properties:

  • wfInstanceId (String) Unique identifier of the newly created workflow instance.
  • redirectUrl (String) A URL that can be used to access the initial user task in the workflow instance.

Error Responses

Status Code JSON errorCode Description
404 ResourceNotFound The specified workflow model does not exist
480 MissingInput A required wfModelId was not provided
480 MissingInput A required wfData property was not provided
480 InvalidInput A wfData property with invalid syntax was provided
480 InvalidToken An invalid Authorization header token was provided

Example

Request

POST /api/v1/workflowInstances
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5kk6IkpXVCJ9.eyJzdWIiOiJhNmIxNTdjZS0yMzIzLTQ0MjMtYTJmZS1jYzE3M2JjZWY5YzAiLCJpYXQiOjE0OTA2MTYwMDQsImV4cCI6MTQ5MDc4ODgwNCwiaXNzIjoiaHR0cHM6Ly9kZXYub250YXNrLmlvIn0.hFdDUqu1rcG1bsNzKNK1_sMSNkGLgR31oooMIwjGCo

{
  "wfModelId": "561ad350-97b3-40c8-ac75-d88f94d5466c",
  "wfData": {
    "email": "someWorkflowUser@acme.com"
  }
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "wfInstanceId": "f3ca91bf-db4d-43e3-9478-4c0abde58c46",
  "redirectUrl": "https://app.ontask.io/workflows/dff861fb-148c-11ej-b1de-0242554088ce/tasks/current?token=eyJhbGciOiJIUzI1NiIsInRMzII6IkpXVCJ9.eyJzdWIiOiI0NzhhMzUxMS0xODY2LTExZTctYjdmYi0wMjQyYWMxMjAwMDMiLCJpc3MiOiJzb2x1dGlvbnMuYWNjdXNvZnQuY29tIiwiYWNjdXNvZnQuc29sdXRpb25zLnVzZXIiOnsiZW1haWwiOiJzb2x1dGlvbnMuYWNjdXNvZnQuY29tLnVzZXJBbm9uIn0sImlhdCI6MTQ5MTIyMTMyM30.tQa3uD8DkUlUXBiF-zf9MdhQ6OwZFlLXYNqAnqt2uRY"

}

GET /workflowInstances

Gets an array of workflow instances of the wfModelId query parameter. The query parameters participant and status will filter the workflow instances accordingly. Only running workflow instances are returned by default if no status is specified.

Request
Request Headers
Name Description
Content-Type Must be application/json
Authorization The API token supplied by OnTask
URL parameters
Parameter Description
wfModelId Required query string parameter that is the unique identifier of the owning workflow model
participant Optional query string parameter that is the email address of the user who participated in the workflow
status Optional query string parameter that is status of the task. Can be running, completed or cancelled.

Successful Response

Response Body

An array of JSON objects with the following properties or an empty array if no instances were found.

  • wfInstanceId (String) Unique identifier of the workflow instance.
  • wfInstanceName (String) Name of the workflow instance.
  • isRunning (Boolean) Indicates if the workflow instance is running.
  • wasCanceled (Boolean) Indicates if the workflow instance was canceled.
  • fatalErrorEncountered (Boolean) Indicates if a fatal error was encountered during execution of the workflow instance.
  • endEventName (String) Name of the end event.
  • startDateTime (Date) Date the workflow instance was started.
  • endDateTime (String) Date the workflow instance was completed or canceled.
  • wfModelId (String) Unique identifier of the workflow model.
  • wfModelName (String) Name of the workflow model.
  • currentActivities (Object Array) An array of JSON objects with the following properties:
    • activityType (String) The type of activity.
    • activityName (String) The name of activity.
    • dateStarted (Date) The date the activity started.
    • userTaskAssignee (String) The user email assigned to the user task.
    • userTaskAssigneeDisplayName (String) The task assignee display name.

Note: currentActivities will only be returned for running workflow instances.

Error Responses

Status Code JSON errorCode Description
401 Unauthorized Insufficient permissions
404 ResourceNotFound The specified workflow model does not exist
480 MissingInput A required wfModelId was not provided
480 InvalidToken An invalid Authorization header token was provided

Example

Request

GET /workflowInstances?workflowModel=7e57191b-5cfe-431e-8cc8-f4b1uzw4bab4&status=running
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5kk6IkpXVCJ9.eyJzdWIiOiJhNmIxNTdjZS0yMzIzLTQ0MjMtYTJmZS1jYzE3M2JjZWY5YzAiLCJpYXQiOjE0OTA2MTYwMDQsImV4cCI6MTQ5MDc4ODgwNCwiaXNzIjoiaHR0cHM6Ly9kZXYub250YXNrLmlvIn0.hFdDUqu1rcG1bsNzKNK1_sMSNkGLgR31oooMIwjGCo

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "wfInstanceId": "01b2a8e0-103b-11po-bdfc-0242ac120003",
    "wfInstanceName": "Time-Off Request for Jane Smith",
    "isRunning": true,
    "wasCanceled": false,
    "fatalErrorEncountered": false,
    "endEventName": null,
    "startDateTime": "2017-03-24T02:38:47.000Z",
    "endDateTime": "",
    "wfModelName": "Time-Off Request",
    "wfModelId": "7e57191b-5cfe-431e-8cc8-f4b1uzw4bab4",
    "currentActivities": [
      {
        "activityType": "userTask",
        "activityName": "Time-Off Information",
        "dateStarted": "2017-03-24T02:39:21.000Z",
        "userTaskAssignee": "jsmith@acme.com",
        "userTaskAssigneeDisplayName": "Jane Smith"
      }
    ]
  },
  {
    "wfInstanceId": "01b2a8e0-103b-11po-bdfc-0242ac120003",
    "wfInstanceName": "Time-Off Request for John Doe",
    "isRunning": true,
    "wasCanceled": false,
    "fatalErrorEncountered": false,
    "endEventName": null,
    "startDateTime": "2017-03-22T02:38:47.000Z",
    "endDateTime": "",
    "wfModelName": "Time-Off Request",
    "wfModelId": "7e57191b-5cfe-431e-8cc8-f4b1uzw4bab4",
    "currentActivities": [
      {
        "activityType": "userTask",
        "activityName": "Time-Off Information",
        "dateStarted": "2017-03-22T02:39:21.000Z",
        "userTaskAssignee": "jdoe@acme.com",
        "userTaskAssigneeDisplayName": "John Doe"
      }
    ]
  }
]

GET /workflowInstances/{wfInstanceId}/variables

Gets a wfVariables object whose properties are the variables for the workflow instance. The query parameter expand can be set to documents or internal to include document or internal variables of the workflow instance in the response.

Request
Request Headers
Name Description
Content-Type Must be application/json
Authorization The API token supplied by OnTask
URL parameters
Parameter Description
wfInstanceId Required workflow instance id for which the variables are retrieved

Successful Response

Response Body

A JSON object.

  • wfVariables (Object) Object whose properties are the variables of the workflow instance.

Error Responses

Status Code JSON errorCode Description
480 InvalidToken An invalid Authorization header token was provided

Example

Request

GET /workflowInstances/2vp650d9-ff7c-11e6-a18d-0242ac120003/variables
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5kk6IkpXVCJ9.eyJzdWIiOiJhNmIxNTdjZS0yMzIzLTQ0MjMtYTJmZS1jYzE3M2JjZWY5YzAiLCJpYXQiOjE0OTA2MTYwMDQsImV4cCI6MTQ5MDc4ODgwNCwiaXNzIjoiaHR0cHM6Ly9kZXYub250YXNrLmlvIn0.hFdDUqu1rcG1bsNzKNK1_sMSNkGLgR31oooMIwjGCo

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "wfVariables": {
    "accusoft_solutions_workflowInitiator": "Jane Smith",
    "originatorName": "Jane Smith",
    "recipientCompany": "Acme Corp.",
    "recipientName": "Bob Jones",
    "originatorEmail": "jsmith@acme.com",
    "recipientEmail": "bjones@fastcars.com",
    "recipientTitle": "CEO",
    "signByDate": "2017-03-04T00:00:00",
    "expirationDate": "2017-03-05T04:59:59.000Z",
    "serviceSuccess": true,
    "variableAssignment": null
  }
}

GET /api/v1/user/{emailAddress}/tasks

Gets an array of user tasks (and their corresponding workflow instance and model data) where URL parameter emailAddress is equal to the assignee of the task. The query string parameters wfModelId, tenantId, organizationId and status will filter the user tasks accordingly. Only current user tasks are returned by default if no status is specified.

Request
Request Headers
Name Description
Content-Type Must be application/json
Authorization The API token supplied by OnTask
URL parameters
Parameter Description
emailAddress Required email address of the user for which the user tasks are retrieved
wfModelId Optional query string parameter that is the unique identifier of the owning workflow model
tenantId Optional query string parameter that is the unique identifier of the owning tenant
organizationId Optional query string parameter that is the unique identifier of the owning organization
status Optional query string parameter that is status of the task. Can be all, completed or current

Note: The tenantId and organizationId parameters cannot both be used in a single request. Doing so will result in a 480 error. The more specific wfModelId parameter will override a tenantId or organizationId parameter.

Successful Response

Response Body

An array of JSON objects with the following properties or an empty array if no tasks were found.

  • assignee (String) Email address of the user who is assigned the task.
  • taskId (String) Unique identifier of the task.
  • taskName (String) Name of the task.
  • wfInstanceId (String) Unique identifier of the workflow instance.
  • wfInstanceName (String) Name of the workflow instance.
  • wfModelId (String) Unique identifier of the workflow model.
  • wfModelName (String) Name of the workflow model.
  • url (String) URL to the task.
  • created (String) Date the task was created.

Error Responses

Status Code JSON errorCode Description
480 OnlyTenantIdOrOrganizationIdAllowed Both tenantId and organizationId were provided
480 InvalidToken An invalid Authorization header token was provided

Example

Request

GET /api/v1/user/someUser@acme.com/tasks?organizationId=bfbc97ea-4e19-4d9a-821e-967a20141f4e
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5kk6IkpXVCJ9.eyJzdWIiOiJhNmIxNTdjZS0yMzIzLTQ0MjMtYTJmZS1jYzE3M2JjZWY5YzAiLCJpYXQiOjE0OTA2MTYwMDQsImV4cCI6MTQ5MDc4ODgwNCwiaXNzIjoiaHR0cHM6Ly9kZXYub250YXNrLmlvIn0.hFdDUqu1rcG1bsNzKNK1_sMSNkGLgR31oooMIwjGCo

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "assignee": "someUser@acme.com",
    "taskId": "123bob80-e4c5-11e6-b4d8-0242ac120003",
    "taskName": "Complete Form",
    "wfInstanceId": "0pmecx2d-e4c5-11e6-b4d8-0242ac120003",
    "wfInstanceName": "Time-Off Request for Jane Smith",
    "wfModelId": "739f8049-afac-4f44-bc35-071bd04fd944",
    "wfModelName": "Time-Off Request",
    "url": "https://app.ontask.io/workflows/0pmecx2d-e4c5-11e6-b4d8-0242ac120003/tasks/current?token=eyJhbGciOixatzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIwYTZlMjcyZC1lNGM1LTExZTYtYjRkOC0wMjQyYWMxMjAwMDMiLCJpc3MiOiJzb2x1dGlvbnMuYWNjdXNvZnQuY29tIiwiYWNjdXNvZnQuc29sdXRpb25zLnVzZXIiOnsiZW1haWwiOiJkaG1hcnRpbjI3QGhvdG1haWwuY29tIn0sImlhdCI6MTQ5MDgxNjA0NH0.tGQO3Hq9XywiH_NadsIVvTd4rWMi-hmhTgVNH_UrF28",
    "tenantId": "d5af7c28-8680-4979-8d25-ab6b5173e7a2",
    "created": "2017-01-27T19:16:14"
  },
  {
    "assignee": "someUser@acme.com",
    "taskId": "c2d1f04a-e4c4-11e6-b4d8-0242ac120003",
    "taskName": "Complete Form",
    "wfInstanceId": "b9eba5ze-e4c4-11e6-b4d8-0242ac120003",
    "wfInstanceName": "Credit Application for John Smith",
    "wfModelId": "739f8049-afac-4f44-bc35-071bd04fd944",
    "wfModelName": "Credit Application",
    "url": "https://app.ontask.io/workflows/b9eba5ze-e4c4-11e6-b4d8-0242ac120003/tasks/current?token=eyJhbGciOixatzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIwYTZlMjcyZC1lNGM1LTExZTYtYjRkOC0wMjQyYWMxMjAwMDMiLCJpc3MiOiJzb2x1dGlvbnMuYWNjdXNvZnQuY29tIiwiYWNjdXNvZnQuc29sdXRpb25zLnVzZXIiOnsiZW1haWwiOiJkaG1hcnRpbjI3QGhvdG1haWwuY29tIn0sImlhdCI6MTQ5MDgxNjA0NH0.tGQO3Hq9XywiH_NadsIVvTd4rWMi-hmhTgVNH_UrF28",
    "tenantId": "d5af7c28-8680-4979-8d25-ab6b5173e7a2",
    "created": "2017-01-27T19:14:01"
  }
]