Using the Workflow REST API in JavaScript

This topic provides some samples that demonstrate how to interact with the Workflow REST API through JavaScript.

Retrieve a list of Workflows you have rights to access
Return the metadata definition for a Workflow
Create and start an instance of a Workflow
Get a list of Tasks for the current user
Action a Task and update datafields

In the code samples below, you will need to replace values in square brackets with the appropriate values for your environment. For example, the value [K2RESTSERVICEBASEURL] refers to the location of the Site where the service is hosted. You can determine the REST service's URL for you environment through the Management Site by navigating to Integration > APIs > Workflow REST, the URL will be displayed in the Base URL property. The URL may look something like this, of course the value would be different for your environment: https://k2serverprod:4444/api/workflow/v1

Copy

Retrieve a list of Workflows you have rights to access

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
/*
 * Returns a list of Workflows either owned or startable for the user credentials supplied.
 */
$(document).on("click", "#listwfs", function () {
    $.ajax({
        type: 'GET',
        // Your URL is different to the one below. Enter your server address in the placeholder.
        // Use the Swagger descriptor from the Workflow REST API Configuration page on the K2 Management site
        // to get your base URL for the url: line.
        // The optional 'type' parameter returns either 'startable' or 'owned' workflows.
        // If no 'type' parameter is set, 'startable' workflows are returned. The URL with 'type' set:
        // [K2RESTSERVICEBASEURL]/workflows?type=Owned
        url: '[K2RESTSERVICEBASEURL]/workflows/',
        dataType: 'json',
        // As CORS is used, this must be set to true
        crossDomain: false,
        // Basic authentication is set in the header, enter your user name and password in the placeholders.
        // The xhr (XMLHttpRequest) function below sends authorization details to the server.
        //
        // This line creates a hash of the user name and password:
        // window.btoa(unescape(encodeURIComponent("[USERNAME]" + ':' + "[PASSWORD]")))
        beforeSend: function (xhr) {
            xhr.setRequestHeader('Authorization', 'Basic ' + window.btoa(unescape(encodeURIComponent("[USERNAME]" + ':' + "[PASSWORD]"))));
            xhr.setRequestHeader("Content-Type", "application/json; charset=UTF-8");
        },
        // On success, we write a 'success' message to the console and stringify the returned JSON to display, 
        // for example, in the <div id="wfs"><div> tag on a web page 
        success: function (json_data) {
            console.log('success');
            $("#wfs").html(JSON.stringify(json_data));
        },
        // In case of error, show an alert
        error: function () {
            alert('Failed!');
        },
    });
});

Copy

Return the metadata definition for a Workflow

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
/*
 * Returns a workflow metadata definition for a particular Workflow ID 
 */
$(document).on("click", "#listwfid", function () {
    $.ajax({
        type: 'GET',
        // your URL would be different. Enter your server address in the placeholder
        // use the Swagger descriptor from the Workflow REST API Configuration page on the K2 Management site
        // to get your base URL for the url: line 
        // Replace the Workflow ID number [WFID] placeholder with your Workflow ID.
        // You can get the ID by using the "Return a list of Workflows" snippet or with the
        // Swagger descriptor from the Workflow REST API Configuration page on the K2 Management site.
        url: '[K2RESTSERVICEBASEURL]/workflows/[WFID]',
        dataType: 'json',
        // As CORS is used, this must be set to true
        crossDomain: false,
        // Basic authentication is set in the header, enter your user name and password in the placeholders
        // The xhr (XMLHttpRequest) function below sends authorization details to the server
        //
        // The following line creates a hash of the user name and password:
        // window.btoa(unescape(encodeURIComponent("[USERNAME]" + ':' + "[PASSWORD]")))
        beforeSend: function (xhr) {
            xhr.setRequestHeader('Authorization', 'Basic ' + window.btoa(unescape(encodeURIComponent("[USERNAME]" + ':' + "[PASSWORD]"))));
            xhr.setRequestHeader("Content-Type", "application/json; charset=UTF-8");
        },
        // On success, we write a 'success' message to the console and stringify the returned JSON to display 
        // in the <div id="wfid"><div> tag on a web page for example
        success: function (json_data) {
            console.log('success');
            $("#wfid").html(JSON.stringify(json_data));
        },
        // In case of error, show an alert
        error: function () {
            alert('Failed!');
        },
    });
});

Copy

Create and start an instance of a Workflow

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
/*
 * Start a Workflow instance. 
 * Send values for folio and datafields etc. in JSON notation.
 * The Workflow REST API accepts string data in JSON notation.
 */
$(document).on("click", "#startwf", function () {
    // Create your JSON data object that is stringified as part of your POST.
    var data = {
        "folio": "Tuesday Folio",
        "expectedDuration": 26000,
        "priority": 1,
        "dataFields": {
            "TextDataField": "This is Tuesday data",
            "DateDataField": Date.now().toString
        }
    }
    $.ajax({
        type: 'POST',
        // your URL would be different. Enter your server address in the placeholder
        // use the Swagger descriptor from the Workflow REST API Configuration page on the K2 Management site
        // to get your base URL for the url: line 
        // Replace the Workflow ID number [WFID] placeholder with your Workflow ID.
        // You can get the ID by using the "Return a list of Workflows" snippet or with the
        // Swagger descriptor from the Workflow REST API Configuration page on the K2 Management site.
        url: '[K2RESTSERVICEBASEURL]/workflows/[WFID]',
        // The data to POST is declared as a variable (var data) and stringified here when sent to the server.
        data: JSON.stringify(data),
        processData: false,
        dataType: 'json',
        // As CORS is used, this must be set to true
        crossDomain: true,
        // Basic authentication is set in the header, enter your user name and password in the placeholders
        // The xhr (XMLHttpRequest) function below sends authorization details to the server
        //
        // The following line creates a hash of the user name and password:
        // window.btoa(unescape(encodeURIComponent("[USERNAME]" + ':' + "[PASSWORD]")))
        beforeSend: function (xhr) {
            xhr.setRequestHeader('Authorization', 'Basic ' + window.btoa(unescape(encodeURIComponent("[USERNAME]" + ':' + "[PASSWORD]"))));
            xhr.setRequestHeader("Content-Type", "application/json; charset=UTF-8");
        },
        // On success, we write a 'success' message to the console and stringify the returned JSON to display 
        // in the <div id="wfid"><div> tag on a web page for example
        success: function (json_data) {
            console.log('success');
            $("#swf").html("Instance started and new folio sent. Data sent: " + JSON.stringify(data));
        },
        // In case of error, show an alert
        error: function (error) {
            alert('Failed! ' + error);
            console.log(request.responseText);
        }
    });
});

Copy

Get a list of Tasks for the current user

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
/*
 * Get a list of tasks for the current user.
 */
$(document).on("click", "#GetWorklist", function () {
    $.ajax({
        type: 'GET',
        // Your URL is different to the one below. Enter your server address in the placeholder.
        // Use the Swagger descriptor from the Workflow REST API Configuration page on the K2 Management site
        // to get your base URL for the url: line.
        // The optional 'type' parameter returns either 'startable' or 'owned' workflows.
        // If no 'type' parameter is set, 'startable' workflows are returned. The URL with 'type' set:
        // [K2RESTSERVICEBASEURL]/workflows?type=Owned
        url: '[K2RESTSERVICEBASEURL]/tasks',
        dataType: 'json',
        // As CORS is used, this must be set to true
        crossDomain: false,
        // Basic authentication is set in the header, enter your user name and password in the placeholders.
        // The xhr (XMLHttpRequest) function below sends authorization details to the server.
        //
        // This line creates a hash of the user name and password:
        // window.btoa(unescape(encodeURIComponent("[USERNAME]" + ':' + "[PASSWORD]")))
        beforeSend: function (xhr) {
            xhr.setRequestHeader('Authorization', 'Basic ' + window.btoa(unescape(encodeURIComponent("[USERNAME]" + ':' + "[PASSWORD]"))));
            xhr.setRequestHeader("Content-Type", "application/json; charset=UTF-8");
        },
        // On success, we write a 'success' message to the console and stringify the returned JSON to display, 
        // for example, in the <div id="wfs"><div> tag on a web page 
        success: function (json_data) {
            console.log('success');
            $("#tl").html(JSON.stringify(json_data));
        },
        // In case of error, show an alert
        error: function () {
            alert('Failed!');
        },
    });
});

Copy

Action a Task and update datafields

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
/*
 * Action a task and update datafields.
 */
$(document).on("click", "#update", function () {
    // Create your JSON data object that is stringified as part of your POST.
    var data = {
        "dataFields": {
            "TextDataField": "instance complete",
            "DateDataField": Date.now().toString
        }
    }
    $.ajax({
        type: 'POST',
        // your URL would be different. Enter your server address in the placeholder
        // use the Swagger descriptor from the Workflow REST API Configuration page on the K2 Management site
        // to get your base URL for the url: line 
        // Replace the instance ID placeholder [IID} with your Workflow's instance ID and the 
        // [ACTION] placeholder with your action.
        url: '[K2RESTSERVICEBASEURL]/tasks/[IID]/actions/[ACTION]',
        data: JSON.stringify(data),
        processData: false,
        dataType: 'application/json',
        // As CORS is used, this must be set to true
        crossDomain: true,
        // Basic authentication is set in the header, enter your user name and password in the placeholders
        // The xhr (XMLHttpRequest) function below sends authorization details to the server
        //
        // The following line creates a hash of the user name and password:
        // window.btoa(unescape(encodeURIComponent("[USERNAME]" + ':' + "[PASSWORD]")))
        beforeSend: function (xhr) {
            xhr.setRequestHeader('Authorization', 'Basic ' + window.btoa(unescape(encodeURIComponent("[USERNAME]" + ':' + "[PASSWORD]"))));
            xhr.setRequestHeader("Content-Type", "application/json; charset=UTF-8");
        },
        // On success, we write a 'success' message to the console and stringify the returned JSON to display 
        // in the <div id="wfid"><div> tag on a web page for example
        success: function (json_data) {
            console.log('success');
            $("#upd").html("Instance started and new folio sent. Data sent: " + JSON.stringify(data));
        },
        // In case of error, show an alert
        error: function () {
            alert('Failed!');
        },
    });
});