WorkFusion REST API

important

For WorkFusion public REST API, refer to Swagger.

The WorkFusion API lets you launch, post data to, and receive results from the WorkFusion platform automatically. Using it, you can manage simple tasks and more complex Business Processes (BPs) representing a workflow of various manual and automated tasks.

Business Processes and Manual Tasks have a specific lifecycle within WorkFusion. There are a number of states: draft, processing, paused, completed, and so on. The API lets you manage the operations by providing unique actions applicable to various states—create, start, pause, stop, and so on.

API security

All API postings are made over a Secure Sockets Layer (SSL) connection encrypting communications between the user and web server to ensure data privacy.

note

All requests must be preceded by https://.

Form-based authentication

WorkFusion REST API employs form-based (login and password) authentication to ensure that APIs are only accessible to users with proper credentials.

Note that CSRF protection is added to REST endpoints. To make a REST call, add a CSRF token to the request header.

Before executing REST API requests, you have to log in using the form URL:

POST method
```
POST /workfusion/api/dologin
Content-Type: application/x-www-form-urlencoded
j_username=usernamej_password=password
```
where:
- j_username is your username in Control Tower.
- j_password is your password in Control Tower.

A successful request body from the server looks like this:

{
    "success": true,
    "csrfToken": <csrftoken>,
    "csrfHeaderName": <csrftokenname>
}

Get JSESSIONID from the Set-Cookie response header.
When creating REST API requests:
1. Set this JSESSIONID to the Cookie header.
2. Set application/x-www-form-urlencoded as the Content-Type header.
3. Set the received <csrftoken> as the <csrftokenname> header.

Here is a Postman login request example:

Sample login with HttpClient

package org.example;

import com.google.gson.Gson;
import org.apache.commons.lang.StringUtils;
import org.apache.http.HttpResponse;
import org.apache.http.NameValuePair;
import org.apache.http.client.HttpClient;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.AbstractHttpEntity;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.message.BasicNameValuePair;

import java.io.IOException;
import java.io.InputStream;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;

//Not a production-grade implementation use as an example only
public class ApiLogin {

    public static final String USERNAME = "ct_user_name";
    public static final String PASSWORD = "ct_user_password";
    public static final String LOGIN_URL = "https://instance.workfusion.com/workfusion/api/dologin";

    public static void main(String... args) throws IOException {
        String token = new ApiLogin().login();
        System.out.println("Auth token: " + token);
    }

    public String post(String addressURL, AbstractHttpEntity body, String csrfToken) throws IOException {

        HttpPost httpPost = new HttpPost(addressURL);
        System.out.println("POST -> " + addressURL);
        httpPost.setEntity(body);
        // add token if necessary
        if (!StringUtils.isEmpty(csrfToken)) {
            httpPost.addHeader("X-CSRF-TOKEN",csrfToken);
            httpPost.getParams().setParameter("_csrf",csrfToken);
        }
        HttpClient httpClient = HttpClients.createDefault();
        HttpResponse response = httpClient.execute(httpPost);

        //Read the Set-Cookie header from the response
        String cookies = response.getHeaders("Set-Cookie")[0].getValue();
        System.out.println("Set-Cookie header: " + cookies);

        String stringResponse = convertStreamToString(response.getEntity().getContent());
        System.out.println(stringResponse);

        return stringResponse;
    }


    public String login() throws IOException {

        List<NameValuePair> nvp = new ArrayList<>();
        nvp.add(new BasicNameValuePair("j_username", USERNAME));
        nvp.add(new BasicNameValuePair("j_password", PASSWORD));

        //post the username and password to the server to log in
        //re-use the httpClient instance to make sure the same JSESSIONID cookie is used

        //UrlEncodedFormEntity sets Content-Type=application/x-www-form-urlencoded
        // no token is required for login
        String loginResponse = post(LOGIN_URL, new UrlEncodedFormEntity(nvp),"");

        Map jsonResponse = new Gson().fromJson(loginResponse, Map.class);

        String csrfToken = (String) jsonResponse.get("csrfToken");

        String csrfHeader = (String) jsonResponse.get("csrfHeaderName");
        return csrfToken;
        // then use csrfHeader and csrfToken for REST API calls, return it.

    }

    private String convertStreamToString(InputStream is) {
        java.util.Scanner s = new java.util.Scanner(is).useDelimiter("\\A");
        return s.hasNext() ? s.next() : "";
    }
}

Use REST API with SSO

Starting from IA Cloud v.10.2, you can authenticate REST requests with your Keycloak credentials without making Control Tower changes. Note that you must have the password assigned for your user. This condition is mandatory because, when using SSO, a user appears in Keycloak only after their first login via the interface, while Keycloak won't have the user's password.

For more information, read the Configure Identity Providers and REST API authentication with enabled IDP topics.

Use REST API with LDAP

Starting from IA Cloud v.10.2, LDAP access is configured via Keycloak. So, you can authenticate REST requests with your Keycloak credentials. For more information, read the Configure LDAP topic.

URLs

All URLs begin with the following pattern:

https://%HOSTNAME%/workfusion/api/

Obtain end-user IP address

To obtain a real end-user IP address, do as follows:

Add the following snippet to nginx/sites/workfusion.com to each Master server:

location /echo {
   default_type text/plain;
   return 200 '{"X-Forwarded-For": "$http_x_forwarded_for"}';
}

Restart Nginx respectively:
```
wfmanager restart nginx
```
Enable the Proxy Protocol on HAProxy by changing group_vars/all/vars.yml. Set the use_proxy_protocol variable to true:
```
# use proxy protocol for forwarding user ip
use_proxy_protocol: true
```
To reconfigure HAProxy, on the Master server, run the following command:
```
./install.sh configure haproxy
```

The Proxy Protocol should be enabled on Load Balancer and used to carry connection information from the source requesting a connection. For more details, refer to Enable Proxy Protocol on F5.

The example output is as follows:

[wfuser@ip-10-100-9-111 ~]$ curl https://core-35330-wfan-10024-workfusion-lb1.wflab.io/echo
{"X-Forwarded-For": "10.100.9.111"}

UUID

Each operation, such as a task, Business Process, or workforce, have a unique identifier called UUID. It is used as a unique reference to invoke the WorkFusion API and identify those entities. The UUID looks similar to this: db1cf0a8-1be4-4842-aec9-4ab0196bc9f1.

Once you receive the required UUID, you can use it to manage BPs or workforces via API. For example:

To get JSON with detailed information on a BP, such as status, executor, and so on, send the POST request to the endpoint: https://HOSTNAME/workfusion/api/v1/bp-instances/BP_UUID?scope=STRUCTURE&scope=BP_DETAILS&scope=CHILDREN_DETAILS.
To receive snapshots for a BP, send the POST request to the endpoint: https://HOSTNAME/workfusion/api/v1/bp-instances/BP_UUID/snapshots/final?lastSnapshotCount=50.
To receive CSV with BP results, send the POST request to the endpoint: https://HOSTNAME/workfusion/api/v1/snapshots/BP_UUID.

For more information on each endpoint and its parameters, see the Swagger UI.

Obtain Business Process UUID

To obtain Business Process UUID, follow the instruction below:

In Control Tower, go to the Business Process list.
Click Open Process Definition In New Tab.

The Business Process Definition opens in a new tab. The UUID is displayed as shown in the image below.

Obtain Workforce UUID

To get a Workforce UUID:

In Control Tower, go to Workers > Workforces.
Copy the UUID of the required Workforce from the table.

Document processing

This section provides details on Intelligent Document Processing designed to:

Accept files from a customer’s system.
Use these files for an Intelligent Document Processing Business Process.
Classify and extract information in the context of the BP.
Route documents that require human-in-the-loop for exception handling.
Send the results of the process to the customer's system.

Get data files for screening

The input data is an Excel file with the buyer or seller data used by Use Cases. A sample file format is provided below:

This data can be delivered from a file storage:

MinIO S3 within IA Cloud platform
Any outside the IA Cloud platform

IA Cloud MinIO S3

The MinIO client for interacting with WorkFusion MinIO S3 can be written in Java, Go, Python, JS, .NET, and other languages.

WorkFusion MinIO is available at https://HOSTNAME-minio-lb1.workfusion.com/minio/. Remember to insert your URI instead of the placeholder.

The WorkFusion MinIO URL is outside the Intelligent Automation Cloud platform. Therefore, use the access key and secret key authentication:

Access key: HHVDVFJFT3GHHJKJ43FG
Secret Key: KNJkljJHGJHgjhJGHKjgy666RryfrftFk6589890

For more information on how to upload and download files, refer to the MinIO SDK guide.

You have to create a bucket in the following format in advance: https://HOSTNAME-minio-lb1.workfusion.com/minio/media_check/input_data/.

Verify that the file transfer is working by checking the following MinIO SDK methods (JavaScript Client API Reference):

bucketExists checks if a bucket exists: https://docs.min.io/docs/javascript-client-api-reference.html#bucketExists.
putObject uploads an object from a Stream or Buffer: https://docs.min.io/docs/javascript-client-api-reference.html#putObject.

In case of a successful file transfer, the response contains the etag and versionId strings of the uploaded object.

File storage outside of IA Cloud

A client's server can also host the files. However, WorkFusion IA Cloud needs to access the files via traditionally accepted methods—S3 Object Storage, HTTP, FTP.

S3 Object Storage

When using S3 Object Storage, WorkFusion IA Cloud can access stored files with the credentials provided by the user in the following format:

Access key: HHVDVFJFT3GHHJKJ43FG
Secret Key: KNJkljJHGJHgjhJGHKjgy666RryfrftFk6589890

HTTP

In case of HTTP links, WorkFusion IA Cloud can access stored files with the credentials provided by the user in the following format:

Username and password authentication:

headers: {
        username: USERNAME,
        password: PASSWORD
        }

Secret key in the HTTP headers:

headers: {
        secret-key: secretKey
        }

Secret key specified as a get-parameter in the link to the file:

https://client_domain.com/media_check_input_data/file1.xlsx?key=JKJH778sdfusdf678f678dfs78s^yjhhjwdkl754

HMAC-based one-time password:

API_KEY = c3b290df-d560-493c-86ca-0ab552f24490a
SECRET = 06d9BLvnPwpj/DFKJ6iGb5oiFO7wZK+dl+C9aflIu/9DIXMXqEyR0Qi1y5BjFi8NcSJl4b62vpK9v3JB1223339g==

headers: {
        authorisation: Signature keyId="${API_KEY}",algorithm="hmac-sha256",headers="(request-target) host date",signature="${HMAC_GENERATED_SIGNATURE_VIA_SECRET}"
        }

FTP

When you use an FTP server for storing input files, WorkFusion IA Cloud downloads these files with the following credentials provided by the user:

Protocol: FTP / SFTP
Port: 21
host: ftp://client_domain.com
remote root: /www/media_check_input_data/
username: USERNAME
password: PASSWORD

At the end of execution, the BP saves the updated files to the MinIO S3 storage at https://HOSTNAME-minio-lb1.workfusion.com/minio/media_check/output_data/.

The BP generates a final report with temporary links to these files. You can retrieve the report via API. For details, read Check BP for results.

Start Business Process

Once logged in, call the WorkFusion REST API to start the Business Process while passing a link to the CSV file with associated entities for screening.

The command to start a Business Process takes the following form:

Method: POST
URL: https://HOSTNAME/workfusion/api/v2/workfusion/task/file
Headers required:
- JSESSIONID: from the Auth API response, see Form-based authentication.
- X-CSRF-TOKEN: from the Auth API reponse, see Form-based authentication.
- Content-Type: application/json; charset=utf-8

Body:

JSON object

{
    "campaignUuid" : "UUID of the Combined UC Campaign",
    "mainData" : ".csv file in the text representation."
}

// An example of building mainData string
var main_data_example = "wf_screening_input\n" + // name of the column
    "file_s3_path_1\n" +
    "file_s3_path_2";

var mainData = JSON.stringify(main_data_example ));

Response: UUID of the started Business Process

Below is a Postman example:

The return of a UUID indicates a successful start of the Business Process with the provided CSV file.

Check BP status

Once the Business Process is underway, it is necessary to continually check its status to determine when it is completed.

It is recommended to ping the endpoint using the following structure every 3-5 minutes based on the expected execution duration:

Method: GET
URL: https://HOSTNAME/workfusion/api/v2/workfusion/task/{uuid}/steps
Headers required:
- JSESSIONID: from the Auth API response, see Form-based authentication
- X-CSRF-TOKEN: from the Auth API response, see Form-based authentication.
- Content-Type: application/json; charset=utf-8.

Response: an array of JSON objects that represents each step of the started BP.

[
    {
        "title": "Step 1",
        "stepIndex": 1,
        "runUuid": "uuid",
        "runStatus": "COMPLETED",
        "campaignUuid": "uuid",
        "type": "MACHINE",
        "finalStep": false,
        "stepPosition": "START",
        "componentUuid": "uuid",
        "versionUuid": "uuid",
        "workforceUuid": null
    },
    ...,
    {
        "title": "Step 5",
        "stepIndex": 5,
        "runUuid": "uuid",
        "runStatus": "COMPLETED",
        "campaignUuid": "uuid",
        "type": "MACHINE",
        "finalStep": true,
        "stepPosition": "END",
        "componentUuid": "uuid",
        "versionUuid": "uuid",
        "workforceUuid": null
    }
]

The Business Process indicates the completion when the final step has been reached with the completed status.

"finalStep": true
"runStatus": "COMPLETED"

If you receive "runStatus": null in a response, this means the Business Process failed with an error, and additional investigation is needed.

If the BP fails, log in to Control Tower and investigate the problem, including analyzing logs.

Check BP for results

To pull the results of a Business Process or look at its snapshot with a specific UUID in the CSV or XLSX format, use the following structure:

Method: GET
URL: https://HOSTNAME/workfusion/api/v2/workfusion/task/{uuid}/snapshot/CSV
Headers required:
- JSESSIONID: from the Auth API reponse, see Form-based authentication.
- X-CSRF-TOKEN: from the Auth API response, see Form-based authentication.
- Content-Type: application/json; charset=utf-8.

Response: returns a binary object that can be converted into an Excel table or a CSV file.

{
    "content": "...",
    "contentType": "text/csv"
}

// An example how you can do it in JS
function retrieveSnapshot(processUuid) {
   retriveSnapshotUrl= instanceBaseUrl + "/api/v2/workfusion/task/{uuid}/snapshot/CSV";
   var startProcessPromise = $.ajax({
     type: "GET",
     url: retriveSnapshotUrl.replace("{uuid}", processUuid),
     contentType: 'text',
     headers: {...},
     dataType: 'text',
     cache:false,
     async: true
   });
 startProcessPromise.then(snapshotRetrieveSuccess, snapshotRetrieveError);
};

function snapshotRetrieveSuccess (response){
   var decodedResponseString = atob(JSON.parse(response).content);
};

The resulting file contains links to the initial files updated with the resolutions and justifications for acceptance or rejection from the WorkFusion Media Check BP processing.

Process results

The updated files have to be uploaded to your system based on the business and process requirements so that relevant Analysts can process alerts.

Sample implementation

Refer to the API sample below to see how you can implement the login, launching, and getting a BP status with Apache HttpClient.

API sample

import com.google.gson.Gson;
import com.google.gson.annotations.SerializedName;
import org.apache.http.Header;
import org.apache.http.HttpResponse;
import org.apache.http.NameValuePair;
import org.apache.http.client.HttpClient;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.AbstractHttpEntity;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.*;
import org.apache.http.message.BasicHeader;
import org.apache.http.message.BasicNameValuePair;

import java.io.IOException;
import java.io.Serializable;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

//Not a production-grade implementation, use as an example only
public class APISample {

    public static String BASE_URL = "https://instance.workfusion.com/workfusion";
    public static String START_BP_URL = BASE_URL + "/api/v2/workfusion/task/file";
    public static String STATUS_BP_URL = BASE_URL + "/api/v2/workfusion/task/";
    public static String LOGIN_URL = BASE_URL + "/api/dologin";


    public static String UUID = "4632e14b-86af-4fa8-8bc3-21ed709a0cb1";
    public static String USERNAME = "ct_user_name";
    public static String PASSWORD = "ct_user_password";

    private HttpClient httpClient;
    private List<Header> defaultHeaders;

    public APISample() {
        this.httpClient = HttpClients.createDefault();
        this.defaultHeaders = new ArrayList<>(2);
    }

    public static void main(String... args) throws IOException {
        APISample apiSample = new APISample();
        apiSample.login();

        //get version details and alike
        //apiSample.get(BASE_URL + "/api/v2/workfusion/service/info");

        //launch new Business Process
        String uuid = apiSample.startBusinessProcess(UUID);

        System.out.println(apiSample.getBusinessProcessStatus(uuid));
    }

    public void login() throws IOException {

        List<NameValuePair> nvp = new ArrayList<>();
        nvp.add(new BasicNameValuePair("j_username", USERNAME));
        nvp.add(new BasicNameValuePair("j_password", PASSWORD));

        //UrlEncodedFormEntity sets Content-Type=application/x-www-form-urlencoded
        loginPost(LOGIN_URL, new UrlEncodedFormEntity(nvp));
    }


    public String get(String addressURL) throws IOException {

        HttpGet httpGet = new HttpGet(addressURL);
        System.out.println("GET -> " + addressURL);

        HttpResponse response = httpClient.execute(httpGet);
        return convertStreamToString(response.getEntity().getContent());
    }

    public List<Header> loginPost(String addressURL, AbstractHttpEntity body) throws IOException {

        HttpPost httpPost = new HttpPost(addressURL);
        System.out.println("POST -> " + addressURL);
        httpPost.setEntity(body);

        HttpResponse response = httpClient.execute(httpPost);
        //
        String cookieHeader = response.getHeaders("Set-Cookie")[0].getValue();
        this.defaultHeaders.add(new BasicHeader("Cookie", cookieHeader));
        //
        String stringResponse = convertStreamToString(response.getEntity().getContent());
        //
        Map jsonResponse = new Gson().fromJson(stringResponse, Map.class);
        String csrfToken = (String) jsonResponse.get("csrfToken");
        String csrfHeader = (String) jsonResponse.get("csrfHeaderName");
        this.defaultHeaders.add(new BasicHeader(csrfHeader, csrfToken));
        return this.defaultHeaders;
    }

    public String post(String addressURL, AbstractHttpEntity body) throws IOException {

        HttpPost httpPost = new HttpPost(addressURL);
        System.out.println("POST -> " + addressURL);
        httpPost.setEntity(body);
        this.defaultHeaders.stream().forEach(httpPost::addHeader);

        HttpResponse response = httpClient.execute(httpPost);
        String stringResponse = convertStreamToString(response.getEntity().getContent());
        System.out.println(stringResponse);

        return stringResponse;
    }


    public String startBusinessProcess(String uuid) throws IOException {
        TaskStart taskStart = new TaskStart();
        taskStart.setCampaignUuid(uuid);

        //pass the CSV file content here to provide input for the Business Process
        taskStart.setMainData("loan_amt\n100000");

        StringEntity body = new StringEntity(new Gson().toJson(taskStart));

        //the server can return an error if it is not Content-Type=application/json
        body.setContentType("application/json");

        return post(START_BP_URL, body);
    }

    public String getBusinessProcessStatus(String uuid) throws IOException {
        return get(STATUS_BP_URL + uuid);
    }

    static String convertStreamToString(java.io.InputStream is) {
        java.util.Scanner s = new java.util.Scanner(is).useDelimiter("\\A");
        return s.hasNext() ? s.next() : "";
    }

    private static class TaskStart implements Serializable {

        @SerializedName("campaignUuid")
        private String campaignUuid;

        @SerializedName("mainData")
        private String mainData;

        @SerializedName("sandbox")
        private Boolean isSandbox;

        @SerializedName("tags")
        private String tags;

        public TaskStart() {

        }

        public String getCampaignUuid() {
            return campaignUuid;
        }

        public void setCampaignUuid(String campaignUuid) {
            this.campaignUuid = campaignUuid;
        }

        public String getMainData() {
            return mainData;
        }

        public void setMainData(String mainData) {
            this.mainData = mainData;
        }

        public Boolean isSandbox() {
            return isSandbox;
        }

        public void setSandbox(Boolean sandbox) {
            isSandbox = sandbox;
        }

        public String getTags() {
            return tags;
        }

        public Boolean getSandbox() {
            return isSandbox;
        }

        public void setTags(String tags) {
            this.tags = tags;
        }
        
    }

}

WorkFusion Documentation

10.2.7

Asset Bundle API

Robotics API

OCR API

important

API security

note

Form-based authentication

Use REST API with SSO

Use REST API with LDAP

URLs

Obtain end-user IP address

UUID

Obtain Business Process UUID

Obtain Workforce UUID

Document processing

Get data files for screening

IA Cloud MinIO S3

File storage outside of IA Cloud

S3 Object Storage

HTTP

FTP

Start Business Process

Check BP status

Check BP for results

Process results

Sample implementation