For Developers - how to integrate an external system with Workflowsoft using API

Each process in Workflowsoft is defined as a diagram that has a name (ProcessDiagramName) and an ID (ProcessDiagramID). In the Process editor, you can edit the diagram and add Integration steps to the diagram (IntegrationDiagramName and IntegrationDiagramID).

After starting the process, all steps are automatically created according to the links in the diagram. Each Integration step created from the process has an unique ID (IntegrationInstanceID), which is different from IntegrationDiagramID (constant ID for this Integration step in the diagram).

How to work with an Integration step - get fields, update fields, and complete the step

To use API, you have to get an API token

Login to Workflowsoft as administrator, then request API token:

GET https://api.workflowsoft.com/api/v2/app/apitoken?lifeTimeInSec=3600

lifeTimeInSec - API token lifetime in seconds

This token is referred as access_token in the examples below.

Get a list of Process diagrams

  const options = {
    url: `https://api.workflowsoft.com/api/v2/workflows`,
    method: 'GET',
    headers: {
      Accept: 'application/json',
      Authorization: `Bearer ${access_token}`,
    },
    params: {
      searchTerm: searchTerm, // optional - use this parameter if you need to get only process diagrams with names that match searchTerm
      mode: 'view',
      limit: 100,
    },
  };

Returns an array of Process diagram objects:

    [{
      Id: 1,  // ProcessDiagramID
      Title: 'Process name'  // ProcessDiagramName
    }]

Get a list of Integration steps in the process diagram

    const options = {
      url: `https://api.workflowsoft.com/api/v2/workflows/${ProcessDiagramID}/tasks`,  // ProcessDiagramID from "Get a list of Process diagrams"
      method: 'GET',
      headers: {
        Accept: 'application/json',
        Authorization: `Bearer ${access_token}`,
      },
      params: {
        integration: true
      },
    };

Returns an array of Integration step objects:

    [{
      Id: 1,  // IntegrationDiagramID
      Title: 'Integration step name'  // IntegrationDiagramName
    }]

Poll for a new Integration instance

You need to poll every n minutes to find out if a new Integration step (instance) was automatically created from the process

  const options = {
    url: `https://api.workflowsoft.com/api/v2/workflows/instances/new-integrations`,
    method: 'GET',
    headers: {
      Accept: 'application/json',
      Authorization: `Bearer ${access_token}`,
    },
    params: {
      id: IntegrationDiagramID  // IntegrationDiagramID from "Get a list of Integration steps in the process diagram"
    },
  };

Returns an Integration instance object

    {
      IntegrationInstanceId: 2  // IntegrationInstanceID
      ProcessInstanceId: 2  // ProcessInstanceID
    }

Get fields from the Integration instance

    const options = {
      url: `https://api.workflowsoft.com/api/v2/workflows/instances/tasks/${IntegrationInstanceID}/variables`, // IntegrationInstanceID from "Poll for a new Integration instance"
      method: 'GET',
      headers: {
        Accept: 'application/json',
        Authorization: `Bearer ${access_token}`,
      },
      params: {
      },
    };

Returns fields in the Integration instance

  [
    {
      label: 'Event name',
      type: 'String',
      key: '9aae87b4-2b01-43eb-be17-d0080a225f54',
      options: null,
      valueJson: '"Event Test"',
      isReadonly: false,
      isRequired: false
    },
    {
      label: 'Event exists',
      type: 'Boolean?',
      key: '3db9d864-d2ea-43f5-8907-2a350c5708d5',
      options: null,
      valueJson: 'true',
      isReadonly: false,
      isRequired: false
    },
    {
      label: 'Event start',
      type: 'DateTime?',
      key: 'cdb815a3-0c60-4cd6-88b2-ef3f9becddc7',
      options: null,
      valueJson: '"2021-08-24T21:00:00Z"',
      isReadonly: false,
      isRequired: false
    },
    {
      label: 'Event duration',
      type: 'Decimal?',
      key: '4dc8a917-da0c-4cf7-a43e-064785e42785',
      options: null,
      valueJson: '1640.0',
      isReadonly: false,
      isRequired: false
    }
  ]

To get a field value, you need to parse valueJson

  let fieldValue = JSON.parse(field.valueJson)

Update fields in the Integration instance

Note - If a field has the isReadonly property set to true and you try to update that field, an exception will be thrown.

      const options = {
        url: `https://api.workflowsoft.com/api/v2/workflows/instances/variables`,
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Accept': 'application/json',
          'Authorization': `Bearer ${access_token}`,
          'X-OnBehalfOf-Id': 'system'
        },
        params: {
      
        },
        body: {
          TaskId: IntegrationInstanceID,  // IntegrationInstanceID from "Poll for a new Integration instance"
          Fields: {
            'field_9aae87b4_2b01_43eb_be17_d0080a225f54': 'Value'
          }
        }
      }

Fields is a hashmap from the Key of the field in the Integration instance (see Get fields from the Integration instance )

Key: 9aae87b4-2b01-43eb-be17-d0080a225f54 => field_9aae87b4_2b01_43eb_be17_d0080a225f54

Value: parsed field value

Example:

  let key = 'field_' + field.key.replace(/\-/g, '_')
  let value = JSON.parse(field.valueJson)

Complete the Integration instance

Note - If the Integration instance has fields that have the isRequired property set to true, and at least one of these fields is empty, an exception will be thrown.

  const options = {
    url: `https://api.workflowsoft.com/api/v2/tasks/${IntegrationInstanceID}/action`,  // IntegrationInstanceID from "Poll for a new Integration instance"
    method: 'PATCH',
    headers: {
      'Content-Type': 'application/json',
      'Accept': 'application/json',
      'Authorization': `Bearer ${access_token}`,
      'X-OnBehalfOf-Id': 'system'
    },
    params: {
  
    },
    body: {
      Action: 'Complete',
      CustomAction: '__AUTO__'
    }
  }

How to start a process or create a task

First you need to get a user ID

    const options = {
      url: `https://api.workflowsoft.com/api/users/search`,
      method: 'GET',
      headers: {
        Accept: 'application/json',
        Authorization: `Bearer ${access_token}`,
      },
      params: {
        Query: Query,  // user name or email //
        entityType: 'users',
        limit: Limit || 15,  // limit the list to the specified number of users
      },
    };

Returns an array of users

    [{
      Id: 1,
      FullName: 'John Doe',
      Email: 'user@mail.com',      
    }]

Start a new process

      const options = {
        url: `https://api.workflowsoft.com/api/v2/workflows/start`,
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Accept': 'application/json',
          'Authorization': `Bearer ${access_token}`,
          'X-OnBehalfOf-Id': UserID  // start a process on behalf of the user with UserID from "First you need to get a user ID"
        },
        params: {
      
        },
        body: {
          TemplateId: ProcessDiagramID,  // ProcessDiagramID from "Get a list of Process diagrams"
          Fields: {}
        }
      };

Returns a Process instance object

    {
      Id: 1,  // ProcessInstanceID
      Title: 'Process title'  // ProcessInstanceName
    }

Create a new task

      const options = {
        url: `https://api.workflowsoft.com/api/v2/tasks`,
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Accept': 'application/json',
          'Authorization': `Bearer ${access_token}`,
          'X-OnBehalfOf-Id': UserID  // create a task on behalf of the user with UserID from "First you need to get a user ID"
        },
        params: {
      
        },
        body: {
          Title: TaskName,  // mandatory - name of the new task
          AssignedUserId: UserID  // optional - assign the task to the user with UserID from "First you need to get a user ID". If not specified, then the task will be assigned to the user in 'X-OnBehalfOf-Id'
          Description: TaskDescription,  // optional - description of the new task
          Files: Files  // optional - files attached to the new task
        }
      }

Returns a Task object

    {
      Id: 1,
      Title: 'Task name',
      Description: 'Task Description'
    }