Straatos Interact API

Overview

The Straatos Interact API enables 3rd party applications and web services to interact with Straatos to create new tasks, upload documents, update existing tasks, return values of tasks to the 3rd party application.

To know more about how two programs connect using web services, refer to FAQs.

Click highlighted areas for more information.

How does it work?

The Straatos Interact API allows you (or the CumulusPro Professional Services team) to define your own Straatos API in a simple JavaScript. The hosting of that API is done on the Straatos Platform and the API can be accessed through the Admin Panel.

Web service URL

Every organisation in Straatos has its own URL. The URL is unique to a specific organisation and can't be changed. For example: https://effektifconnector.cumuluspro.net/ConnectorService.svc/json/Interact/<YourOrganisationId>

Configuration of the web service

JavaScript is used to define the web service. To define a new web service, go to Admin Panel > Organisation > Interact Script.

How to create a new task in a Straatos process:

Sample Code

if (request.pathSegments[1] == 'createTask') {
    // Create a new Task in the workflow named 'Test QA Workflow' at the Start Event 'Start' 
    // and returns the documentId of the newly created task
    var documentId = straatos.addDocument('Test QA Workflow', 'Start');

    // response of the webservice with the DocumentID
    response.body = "Finished request of type " + request.pathSegments[1] + " DocumentID: " + documentId;
}

For easier development and troubleshooting, the Admin Panel provides a Log where a ‘console.log' command can write to get logging data.

To call this web service from a 3rd party application, the following URL can be used: https://effektif-connector.cumuluspro.net/ConnectorService.svc/json/Interact/<your organisation id>/createTask

API Documentation

This section describes how to use Straatos interact API to create new tasks, upload documents, update existing tasks, return values of tasks to the 3rd party application.

API Server and Base URL

To know more about Organisation ID, refer to FAQs.

Request and Response parameter

The request and response contain the information sent to the webservice and the response sent by the webservice to webservice call. Refer to Sample Code section for more details. 

Request

Response

Straatos Functions

Straatos contains functions to interact with the platform.

XML

XML Document (JsXmlDocument)

To create an XML Document, use the following straatos methods:

• newXMLDocument, 
• prseXML and,
• transformXSL.

XML Element (JsXmlElement)

XML Elements can be accessed throught the documentElement property of the XML Document and the XML Element methods selectElements, selectSingleElement and created with addElement.

AJAX Utility Function

Sample Code

Simple process flow in Straatos as follows:

Start Event: It must have a name. For example, in the above case 'Start'.

Wait: Once a task is formed in the system, we use a 'Message Receive' task called 'Wait' to wait for some input.

Sample Code 1 - Create a new Task in Straatos

In this sample, a webservice is created that adds a new task in the workflow.

Sample

if (request.pathSegments[1] == 'createTask') {
    // Create a new Task in the workflow named 'Test QA Workflow' at the Start Event 'Start'; 
    // and returns the documentId of the newly created task
    var documentId = straatos.addDocument('Test QA Workflow', 'Start');

    straatos.startWorkflow(documentId, {});

    // response of the webservice with the DocumentID
    response.body = "Finished request of type " + request.pathSegments[1] + " DocumentID: " + documentId;
}

Sample Code 2 - Create a new Task in Straatos with Index fields

In this sample, the indexfield values are submitted as part of the webservice. This script is builds on top of Sample code 1.

We can also add values that are submitted as URI parameters, Headers, and body.

Sample

if (request.pathSegments[1] == 'createTask') {
    // Create a new Task in the workflow named 'Test QA Workflow' at the Start Event 'Start' 
    // and returns the documentId of the newly created task
    var documentId = straatos.addDocument('Test QA Workflow', 'Start');
    
    // Adding Index fields values
    straatos.startWorkflow(documentId, {
        'FirstName': request.multipart.parameters.FirstName, // value from body, note this only works if the body is a multipart.
        'LastName': request.headers.LastName, // value from header
        'InvoiceNumber': request.queryParameters.InvoiceNumber // value from URI parameters
    });
        
    // response of the webservice with the DocumentID
    response.body = "Finished request of type " + request.pathSegments[1] + " DocumentID: " + documentId;   
}

Sample Code 3 - Create a new Task in Straatos with Index fields and JPG Files / Pages

In this sample, a PDF Document is attached in the new Straatos Task. This script is built on top of Sample code 1 and Sample code 2.

Sample

if (request.pathSegments[1] == 'createTask') {
    // Create a new Task in the workflow named 'Test QA Workflow' at the Start Event 'Start' 
    // and returns the documentId of the newly created task
    var documentId = straatos.addDocument('Test QA Workflow', 'Start');
    
    // Adding a document (multipart form post should contain JPG files)
    var files = request.multipart.files.map(function (file) { return file.content; }); 
    straatos.setDocumentContent(documentId, files, 'jpg', true, false);    

    // Adding Indexfields values
    straatos.startWorkflow(documentId, {
        'FirstName': request.multipart.parameters.FirstName, // value from body
        'LastName': request.headers.LastName, // value from header
        'InvoiceNumber': request.queryParameters.InvoiceNumber // value from URI parameters
    });
    
    // response of the webservice with the DocumentID
    response.body = "Finished request of type " + request.pathSegments[1] + " DocumentID: " + documentId;    
}

Sample Code 4 - Forward a Task in the workflow and update field values

Documents are now created and flow to the process step 'Wait'.

In this code example, we will now find specific documents in the 'Wait' step and forward it in the workflow to the next step (in our case end).

Sample

if (request.pathSegments[1] == 'forwardTask') {
    var documentIds = straatos.findDocuments('Test QA Workflow', 'Wait', {
        'InvoiceNumber': request.headers.InvoiceNumber
    });

    straatos.messageWorkflow('Test QA Workflow', 'Wait', documentIds, {
        'PaymentStatus': 'paid'
    });

    response.body = "Finished request of type " + request.pathSegments[1];
}

Sample Code 5 - Upload a PDF File

In this sample, PDF is uploaded as part of the body, while JPG files are expected to be uploaded as a multipart.

Sample

if (request.pathSegments[1] == 'createTask') {
    var documentId = straatos.addDocument('Test QA Workflow', 'Start');

    if (typeof(request.multipart) == 'undefined') {
        // assumes the body to contain a PDF file
        straatos.setDocumentContent(documentId, [request.body], 'pdf', true, false);
    } else {
        // assumes the multi part files to be JPG
        var files = request.multipart.files.map(function (file) { return file.content; });
        straatos.setDocumentContent(documentId, files, 'jpg', true, false);
        
        straatos.startWorkflow(documentId, {});
    }
}

Sample Code 6 - Polling

3rd party application may reject a push API call from the workflow. In this case, the 3rd party application may want to poll for information.

The code below looks for a document with a LastName workflow index field that matches the header 'Name.' If one or more documents are identified, it polls the indexfield values for the first document and returns the field value pairs as part of the body.

Sample

if (request.pathSegments[1] == 'poll') {  

    var documentIds = straatos.findDocuments('Test QA Workflow', 'Wait', {
        'LastName': request.headers.Name
    });

    if (documentIds.length > 0) {
        // console.log('Get variables: ' + JSON.stringify(straatos.getVariables(documentIds[0])));
        response.body = JSON.stringify(straatos.getVariables(documentIds[0]));
    } else {
        response.body = 'Sorry, no documents found';
    }
}

Sample Code 7 - Usage of getDocumentInfo

The script below uses the getDocumentInfo method on the Adapter and outputs the contents to the console.

Sample

try {
   var documentInfo = straatos.getDocumentInfo(straatos.documentId);
   console.log(documentInfo);
   response.body = 'Ok!';
} catch(err) {
   response.body = 'Error: ' + err;
   console.log('error: ' + err);
}

Sample Code 8 - to get additional stored documents

The following script gets the merge-pages-pdf additional data (the result of a Merge PDF pages activity) of a certain document and returns that pdf to the browser.

Sample

try {
    var documentInfo = straatos.getDocumentInfo(straatos.documentId);

    // Return only the additionData objects with a merge-pages-pdf key
    var additionalDataObj = documentInfo.additionalData.filter(function(additionalData) {
        return additionalData.key == 'merge-pages-pdf';
    });
    
    if (additionalDataObj && additionalDataObj.length > 0) {
        var mergeUrl = additionalDataObj[0].url + '?w=' + straatos.webServiceKey;
        straatos.ajax({
            url : mergeUrl,
            dataType : 'binary'
        }).done(function(pdfRes) {
            response.body = pdfRes;
            response.headers['Content-Type'] = 'application/pdf';
        });
    } else {
        response.body = 'No merge-pages-pdf data found';
    }
} catch(err) {
    response.body = 'Error: ' + err;
    console.log('error: ' + err);   
}

Sample Code 9 - Uploading a PDF as 'additional data'

This Script does not show the pdf in the browser, but it uploads the pdf as additional data with a different key, in this case, binary-test-pdf.

Sample

try {
    var documentInfo = straatos.getDocumentInfo(straatos.documentId);
    var additionalDataObj = documentInfo.additionalData.filter(function(additionalData) {
        return additionalData.key == 'merge-pages-pdf';
    });

    if (additionalDataObj && additionalDataObj.length > 0) {
        var mergeUrl = additionalDataObj[0].url + '?w=' + straatos.webServiceKey;
        straatos.ajax({
            url : mergeUrl,
            dataType : 'binary'
        }).done(function(pdfRes) {
            // Add the document as Additional Data
            var output = straatos.addAdditionalData(_documentId, pdfRes, '.pdf','binary-test-pdf');
            console.log('uploaded document link: ' + JSON.stringify(output));
            response.body = 'File uploaded!';
            
        }).fail(function(jqXHR, error){
            response.body = 'An error occurred: ' + error;
        });
    } else {
        response.body = 'No merge-pages-pdf data found';
    }
} catch (err) {
    response.body = 'error: ' + err;
    console.log('error: ' + err);   
}

Sample Code 10 - XML without namespaces

This Script shows how to create a simple XML document.

Sample

var xmlDocument = straatos.newXMLDocument('root');

var rootElement = xmlDocument.documentElement;

rootElement.addAttribute('attr', 'attribute value');

var element1 = rootElement.addElement('element');
element1.text = 'element value 1';

var element2 = rootElement.addElement('element');
element2.addAttribute('elementAttr', '25');
element2.text = 'element value 2';

console.log(xmlDocument.xml);

console.log('xpath string attr: ' + rootElement.stringValue('@attr'));
console.log('xpath string query by attr: ' + rootElement.stringValue('element[@elementAttr = "25"]'));

var elements = rootElement.selectElements('/root/element');

elements.forEach(function (element, index) {
  console.log('element at index ' + index + ': ' + element);
});

var xmlDocument = straatos.newXMLDocument('ns:root', 'https://www.cumuluspro.com/api/1.0');

var rootElement = xmlDocument.documentElement;

rootElement.addAttribute('ns:attr', 'attribute value', 'https://www.cumuluspro.com/api/1.0');

var element1 = rootElement.addElement('ns:element', 'https://www.cumuluspro.com/api/1.0');
element1.text = 'element value 1';

var element2 = rootElement.addElement('ns:element', 'https://www.cumuluspro.com/api/1.0');
element2.addAttribute('ns:elementAttr', '25', 'https://www.cumuluspro.com/api/1.0');
element2.text = 'element value 2';

console.log(xmlDocument.xml);

console.log('xpath string attr: ' + rootElement.stringValue('@ns:attr', { 'ns': 'https://www.cumuluspro.com/api/1.0' }));
console.log('xpath string query by attr: ' + rootElement.stringValue('ns:element[@ns:elementAttr = "25"]', { 'ns': 'https://www.cumuluspro.com/api/1.0' }));

var elements = rootElement.selectElements('/ns:root/ns:element', { 'ns': 'https://www.cumuluspro.com/api/1.0' });

elements.forEach(function (element, index) {
  console.log('element at index ' + index + ': ' + element);
});

//The interact API is looking for the 'submitTask'
if (activityName == 'submitTask') {
    
    try{

        var userId = straatos.validateSession(request.headers['X-Session-Id']); //Validating the Session we received as part of the headers and assigning the result to userId
        
        if (userId > 0) { //if it is a valid session, the returned number is bigger than 0. If no valid session, then the return is 0. hence, we only want to execute the code if it is a valid session.
            var reqBody = JSON.parse(straatos.getString(request.body));
            
            var authRoles = straatos.adapter.getAccount({id: userId}).Roles; //get the roles for the user account that has a valid session
            var authOk = false; //set the authentication 'authOk' to false as a start.
            
            // check if any of the roles the user has match the 'startevent' that was submitted. If true, the user has the role and hence is authorised to create the Job.
            authOk = authRoles.some(function(record){
                return record.Name === reqBody.wfstep;
            });
            
            if(authOk == true) { //only if the role is for which step the user wants to update a task we will attempt to update the task. If the user is not authorised, we will not update the task
                       
                straatos.messageWorkflow('Production Line Process', reqBody.wfstep, [reqBody.taskId], {
                    //'taskListData': 'test',
                    'taskListData': JSON.stringify(reqBody.taskListData),
                    'taskDetails': JSON.stringify(reqBody.taskDetails),
                    'action': reqBody.action
                });
            }
            else{
                response.body = '';
                response.status = 401; //respond with 401 for issues with Authorisation
            }
        }
        else{
            response.body = '';
            response.status = 401; //respond with 401 for issues with Authorisation
        }
    }
    catch(err){
        console.log('Error: ' & err.message);
        response.status = 501;
        response.body = err;
    }
}

FAQs

What are the usual challenges when two applications try to interact via web services?

Each application has its own set of web services with its own parameters, headers, body requirements. The challenge is to make them talk to each other.

There are three ways to make that happen:

• 3rd party application makes changes to their push web service API calls

• Straatos makes changes to its API definitions.

• Use of a 3rd party web service (or Platform) that makes the two web service calls to talk to each other (example: Zapier, Mulesoft).

What are the challenges of traditional approaches?

• Knowledge & skills to change the API

  - Changes affect other users of the web service.
  - 3rd party product which can not be changed or requires the vendor to make changes.
  - Effort and cost to make the changes.

• Changes affect other users

  - Duration, cost, and effort to develop a customer-specific web service (days to weeks).
  - Agility to change the web services.
  - No customer self-service to change the web services.

• 3rd Party Platform (such as Zapier/Mulesoft)

  - Different geolocation

  - Not the feature set required

  - Additional subscription/cost

  - Additional service/company.

• Dedicated web service

  - Effort & cost to build an entire/independent web service.

  - Hosting & monitoring of the web service

  - Code maintenance

  - Extensive testing.

   

   

What incoming web service calls are supported?

The Straatos Interact API supports POST and GET calls.

All parameters, header, and body information are passed to the Interact Script and can be used in the script to determine what to do with the incoming call.

Can more than one web service call be defined?

Yes, there is no limit on the number of different web service calls that can be defined in a single Straatos Interact Script.

Here an example for 3 web service calls:

• CreateTask
• ForwardTask
• RetrieveTaskInfo

CreateTask

CreateTask will create a new Task in the Workflow. See Sample Code.

ForwardTask

ForwardTask will forward a specific task in the workflow to the next step.

RetrieveTaskInfo

RetrieveTaskInfo can return data from the workflow task to the 3rd party application, for example, a Name, Date of Birth, or a License Number that was extracted in the workflow from the AI Extraction engine.

Security, how does a web service call get authorised?

The security can be built right into the Straatos Interact Script. The approach may depend on the application used. For example:

• No authentication:  An open web service for everyone. Anyone with access to the URL can submit a new task to this Straatos Process. Refer to Sample Code for reference.
• Web service Key/API Key: A webservice key check is added to the web service call. If the web service key does not match, an error will be returned.
• OAuth2: The Straatos Interact Script uses ajax to interact with other web services. Hence an incoming authentication can authorise the Client Secret to an OAuth2 server. Security is handled outside of Straatos in this situation, and it can rely on existing technology or services.

In summary, Authentication can be as secure and restrictive as need to be for the process.

Is the data between the web service calls encrypted?

Yes, all communication will be using SSL encryption.

Can payload encryption be used?

Yes, the Straatos Interact Script allows for the data to be encrypted on top of SSL encryption. The incoming data can be decrypted within the Interact Script (if necessary, for processing the data) or the data can be passed encrypted to the Straatos process.
If required for processing, the data can then be decrypted within the process or passed straight through without decryption. The decryption requirements depend on what action the Straatos process has to take on the data.

What is Organisation ID?

The Organisation ID is a unique identifier that defines your organization and is also used as part of the request URL when consuming the API.

How to find your Organization ID?

1. Log in to the CumulusPro Admin Panel with your credentials. The CumulusPro Admin dashboard will appear.
2. In the dashboard, click Create Organisation.

3. Select the desired template. and click Next.

The new organisation will appear on the dashboard.

4. From the dashboard, click the newly created organisation. A new dashboard will appear.
5. Click the Organisation Settings to view the organisation details. The Organisation Settings page contains the Unique ID and all relevant information about the organisation.