Straatos Script Service API

This articles describes Straatos Scrip Service API

Straatos engine provides JavaScript activity. This document describes available calls for developers writing JavaScript activities.

Available Variables

Constants are declared and initialised by Straatos. They cannot be changed, just queried.

Constants are case sensitive.

Name	Description
workflowId	ID of workflow this workflowInstance is in. WorkflowId changes every time workflow is (re-)published.
workflowName	Name of workflow
workflowInstanceId	Unique ID of every workflowInstance. This will not change as long as the instance is in the workflow.
activityId	Uniquely identifies activity within current workflow.
activityName	Name of Script activity
activityInstanceId	Increasing sequence number representing logId of activity
activityInstanceDate	Date that activity execution started
workflowInstanceDate	Date the workflowInstance arrived in the workflow
console	Object with method log(String). Output will appear in efektif log.

---

Utility Methods

JavaScript activity provides “Straatos”-object containing several methods providing functionality. The following are description of these methods:

Generate a UUID

Generate a UUID (or GUID), please use:

var guid = straatos.uuid();

---

Sequence Number

The method nextSequenceNumber() generates sequence number that is unique for the workflow.

Identifier makes it possible to have several sequences in one process:

Name	Description
nextSequenceNumber()	Retrieves the next sequence number for the specified identifier
clearSequenceNumber()	Clears the sequence (ie it will start at 1 again)

Sample Code

var id = straatos.nextSequenceNumber('sequence1');

straatos.clearSequenceNumber('sequence1'); // clears the sequence

---

Getting Variables from Other WorkflowInstances in the Same Flow

Straatos provides two ways to get variables from other workflowInstances in the same workflow.

Name	Description
variablesByWorkflowInstanceId('')	Gets variables of workflowInstance defined by
variablesByDocumentId()	Gets variables of workflowInstance defined by (every workflowInstance also has unique documentId attached)

Sample Code

var DocumentId = 12345;

var frontVariables =
    JSON.parse(straatos.variabesByDocumentId(DocumentId));

function value(name) {
    var values = frontVariables.filter(function (entry) {
        return entry.variableId == name;
    });

    return values.length > 0 ? values[0].value : null;
}

var FirstName = value('FirstNameF');
var LastName = value('LastNameF');

---

Getting activityIds, documentId and workflowInstanceId

The ActivityId is used in multiple API methods, such as the message() method, to identify a specific activity within a workflow.

Getting ActivityId by Name

The method activityIdForName(activityName) allows you to retrieve the ActivityId when you provide an ActivityName.

Key Points:

• ActivityId is a unique identifier for an activity in a workflow.

• ActivityName is the user-defined name/description of an activity.

• The activityIdForName(activityName) method helps map the activity name to its corresponding ID.

Name	Description
activityIdForName()	Returns activityId for the given activityName (only works for the current workflow, ie workflow the workflowInstance is in)
getActivityIdsByDocumentId()	Returns list of activityIds where workflowInstance defined by DocumentId is in (there is a 1:1 relation between documentId and workflowInstanceId).
getWorkflowInstanceIdByDocumentId()	Get workflowInstanceId (a string) for specified documentId
documentIdsForFilter()	Perform search on all documents on given variables

Sample Code

var emailGroupId;

var documentIds = straatos.documentIdsForFilter({
    EmailUniqueId: emailGroupId
});

var activityId = straatos.activityIdForName('Wait for last Document');

var workflowInstances = [];

for (var i = 0; i < documentIds.length; i++) {
    var documentId = documentIds[i];
    if (documentId != _documentId) {
        workflowInstances.push({
            workflowInstanceId: straatos.getWorkflowInstanceIdByDocumentId(documentId)
        });
    }
}

var workflowMessageData = {
    workflowId: workflowId,
    activityId: activityId,
    workflowInstances: workflowInstances
};

console.log('workflowMessageData input: ' + JSON.stringify(workflowMessageData));

straatos.sendWorkflowMessage(workflowMessageData).fail (function (jqXHR, error) {
    straatos.SetError('Send Workflow Message: ' + error);
});

---

Getting Variable Values

It is possible to get variables from other workflowInstances in the same workflow using these methods:

Name	Description
variablesByDocumentId()	Gets JSON string containing all variables by documentId
variablesByWorkflowInstanceId()	Gets JSON string containing all variables by workflowInstanceId

---

Converting to-and-from Byte Arrays

Several convenience methods are provided to convert to and from byte arrays.

Name	Description
getBytes(inputString)	Converts inputString to byte array, using UTF-8 encoding.
getString(byte[])	Converts byte array to a string, using utf-8 character set.
getString(<byte[]>, )	Convert byte array to a string, using specified character set.

---

Base64 Encoding and Decoding

Name	Description
decodeBase64()	Returns (possibly binary) byteArray of base64 encoded string.
encodeBase64()	Returns base64 encoded string representation of (binary-) byteArray.

Sample Code

try {
    var dataAcceptingSystemUrl = "https://<someDataAcceptingSystems URL>/documentimportsrv";

    // variables need to be defined before call to multiString
    ReferenceNumber103 = straatos.getWorkflowData('some.ref.number.' + EmailUniqueId);

    var base64String;
    var documentBase = AttachmentFileName.replace('.pdf','');
    var documentInfo = straatos.adapter.getDocumentInfo();

    straatos.ajax({
        url: documentInfo.originalURL + '?w=' + straatos.webServiceKey,
        dataType: 'binary'
    }).done(function (pdf) {
        base64String = straatos.encodeBase64(pdf);

        var documentData = multiString(function() {/** 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:doc="http://nsServer.net/documentimportsrv">
<soapenv:Header/>
<soapenv:Body>
<doc:ImportDoc>
<doc:documentImportReq>
<doc:Docs>
<doc:Doc>
<doc:Content>#base64String#</doc:Content>
<doc:FileExt>pdf</doc:FileExt>
<doc:Filename>#AttachmentFileName#</doc:Filename>
<doc:FilenameBase>#documentBase#</doc:FilenameBase>
</doc:Doc>
</doc:Docs>
<doc:IdentifierNr>#ReferenceNumber103#</doc:IdentifierNr>
<doc:Type>DOCTYPE</doc:Type>
</doc:documentImportReq>
</doc:ImportDoc>
</soapenv:Body>
</soapenv:Envelope>
        **/});

        straatos.ajax({
            url: dataAcceptingSystemUrl,
            data: documentData,
            method: 'POST',
            contentType: 'text/xml; charset=UTF-8',
            dataType: 'text/xml',
            headers: {
                SOAPAction: 'dataAcceptingSystemUrl + /IDocumentImportSrv/ImportDoc"'
            }
        }).done(function (responseString) {
            console.log('Document Import Response: ' + responseString);
            if (responseString != '<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"><s:Body><ImportDocumentResponse xmlns="http://nsServer.net/documentimportsrv"/></s:Body></s:Envelope>') {
                straatos.SetError('Response from document import service: ' + responseString);
            }
        }).fail(function (jqXHR, error) {
            straatos.SetError('document import service: ' + error);
            console.log('Document Import Service: ' + error);
        });

    }).fail(function (jqXHR, error) {
        straatos.SetError('Get original: ' + error);
    });

} catch(err) {
    straatos.SetError('error: ' + error);
    console.log('error: ' + err);
}

// Hack that converts multi line comment to multi line string
function multiString(f) {
    var result = f.toString().replace('function() {/**', '').replace('**/}', '');
    result = result.replace(/#([^#]+)#/g, function (match, variable) {
        // console.log('replacing ' + match + ', variable: ' + variable + ', value: ' + eval(variable));
        return eval(variable);
    });
    return result;
}

---

Workflow Data

Functionality is provided to store and retrieve data on workflow level. This data remains available when the workflow is re-published.

Name	Description
setWorkflowData(, )	Sets workflow data.
getWorkflowData()	Gets workflow data for specified key
removeWorkflowData()	Removes workflow data for specified key
clearAllWorkflowData()	Removes all workflow data for current workflow

Example:

straatos.getWorkflowData('reference-' + EmailUniqueId);

---

Messaging Other WorkflowInstances

Send other (waiting) workflowInstances a message that they can continue the workflow.

Name	Description
sendWorkflowMessage({})	Sends a message to workflowInstance. Message should contain workflowId, activityId and an array of workflowInstances to message. Optionally variables per workflowInstance. See example below.

Parameters:

• workflowId:

  • ID (a guid) of current workflow.

• activityId:

  • ID (a string) of activity. See activityForName() method to get activityId via activityName.

• workflowInstances:

  • List of one or more workflowInstances that should receive the message.

Each workflowInstance should contain workflowInstanceId and optionally list named variables of id-value pairs.

Sample Code

var workflowInstanceId = '';

var messageInput = {
    workflowId: workflowId,
    activityId: activityId,
    workflowInstances: [{
        workflowInstanceId: workflowInstanceId,
        variables: [
            {'id' : 'Variable1', 'value' : 'string123'},
            {'id' : 'Var2', 'value' : 123 }
        ]
    }]
};

straatos.sendWorkflowMessage(messageInput)
.done(function () {
    console.log('Ok');
}).fail(function (jqXHR, error) {
    straatos.SetError('Message error: ' + error);
});

---

Calling Web Services (Ajax Support)

Straatos provides an api to call web services. The way it can be used is similar to a jQuery Ajax call, however, it supports a subset of the functionality.

This Ajax call can also be used to call additional functionality the Straatos REST API provides. For more information, please open the link below.

https://docs.google.com/document/d/1ui5UhztqodEmLn6rY36AQ00rUsiLKfwNNvXdzLw6CJ0/edit?ts=5829c792#bookmark=id.fccwvtqnhhu3

Name	Description
ajax()	Performs the call. See table below for the request options

Request specification:

Name	Description
url	Required: Complete url to call. Calls to urls containing localhost are not allowed.
data	Data you want to pass, or the multipart object from straatos.newFormData call
method	Possible values are GET, POST, PUT, DELETE and OPTIONS. When not specified, it defaults to GET
contentType	Optional contentType of data to be sent, default is 'application/json'
dataType	Optional contentType of expected data for example: 'binary' or 'text/html'
headers	Optional array with headers that will be passed to the call
timeout	Optional timeout in milliseconds. The default is 60 seconds. This one parameter specifies connectTimout, requestTimeout and socketTimeout.

Sample Code

try {
    straatos.ajax({
        url: externalAPIURL,
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        data: JSON.stringify({'client_id': '', 'client_secret': ''})
    }).done(function (output) {
        var response = JSON.parse(output);
        console.log('++ response: ' + JSON.stringify(response));
        token = response.access_token;
    }).fail(function (jqXHR, error) {
        straatos.setError('Access Token Error: ' + error);
        console.log('Access Token Error: ' + error);
    });
} catch(err) {
    console.log('Get Access Token Error: ' + err);
}

---

Multipart Support

Multipart support is available to create multipart messages. If boundaries are needed between parts, they should be added manually by the developer.

To get a new Multipart object, call straatos.newFormData().

Adding Data

To add data to multipart objects, call one of these methods:

Name	Description
append()	Adds a string, this string will be utf-8 encoded
append(, )	Adds a string with a custom character set. Values used can be ‘utf-8’, or any of the character sets from the table below.
append(<byte []>)	Appends a byte array to multipart object

Getting Data

To get the data from the multipart object, call one of these methods:

Name	Description
getByteArray()	Returns byte array (byte[]) representing multipart data
toString()	Returns utf-8 decoded string of multipart data

Sample Code

var multipart = straatos.newFormData();

multipart.append('This is string 1');

var boundaryName = 'Straatos-' + straatos.uuid(); //The Boundary Name must be unique as part of the entire post. Hence in this case we use 'Straatos- and a unique ID' to make it unique.

var boundary = '--' + boundaryName + '\r\n';

var multipart = straatos.newFormData();

multipart.append(boundary);

multipart.append('Content-Type: ' + mimeType + '\r\n');

multipart.append('Content-Disposition: document; name="' + documentName + '"; filename="' + fileName + '"\r\n');

multipart.append('\r\n');

multipart.append(fileContents);

multipart.append('\r\n');

multipart.append(boundary);

multipart.append('Content-Type: application/json; charset=UTF-8\r\n');

multipart.append('Content-Disposition: meta\r\n');

multipart.append('\r\n');

multipart.append(JSON.stringify(metadata) + '\r\n');

multipart.append('--' + boundaryName + '--\r\n'); //The last Boundary must have the two dashes (--) at the end.

straatos.ajax({
    url: APIBaseURL + '/api/v1/delivery',
    method: 'POST',
    data: multipart,
    contentType: 'multipart/related; boundary="' + boundaryName + '"', //Note: The Boundary Name needs to be in double quotes and must be defined here.
    headers: {
        'Authorization': 'Bearer ' + tokenResult.access_token
    }
}).done(function (response) {
    console.log('Peax response: ' + response);
    PeaxUploadId = JSON.parse(response).id;
}).fail(function (jqXHR, error) {
    straatos.setError('Peax upload: ' + error);
});

---

Getting History or Audit Trail Info

This API call returns JSON string containing history of the document. This will not include the currently executed step.

• straatos.history() returns json string containing history of the current workflowInstance (not including current running activity).

• straatos.history(number documentId) returns json string containing history of workflowInstance identified by documentId provided. This document must be part of the same workflow as the calling document.

Since a string is returned, JSON.parse() should be called on the string before accessing json objects within the returned data.

Sample Code

// Example:
var hist_str = straatos.history();
var hist = JSON.parse(hist_str);
console.log(JSON.stringify(hist)); // prints the whole history object
console.log('WorkflowInstance started at: ' + JSON.stringify(hist.start));
console.log('Nr of log entries: ' + hist.activityInstances.length);

// Example with documentId:
var hist_str2 = straatos.history(877603);
var hist2 = JSON.parse(hist_str2);
console.log(JSON.stringify(hist2)); // prints the whole history object
console.log(JSON.stringify(hist2.start));
console.log('Second: ' + hist2.activityInstances.length);

---

setSecret and getSecret

The Set Secret and Get Secret functions provided by the Script task or Interact API enable the secure storage of sensitive data such as passwords, tokens, API keys, and connection strings.

How It Works:

• setSecret:

  • This function securely stores the data in Straatos's vault.

• getSecret:

  • This function retrieves the stored data from the vault for use within the workflow.

Best Practices:

• It is crucial not to store secrets directly in script code. Instead, utilize the setSecret and getSecret functions to manage sensitive data securely.

Storing a Secret

var result = straatos.setSecret('mySecretName', 'mySecretValue');

The above code stores the return value in a variable. That variable will either contain a 'true' or 'false' value, depending on if the storing of the secret was successful. This result should be checked by the code.

Retrieving a Secret

var secret = straatos.getSecret('mySecretName');

---

Database (SQL) Queries

The straatos.data.query lets user connect to a database and execute SQL queries. This function can be used to read data from Database (Select), but also to update, truncate, drop databases (tables).

The sample code below shows how a database is updated.

var sqlUpdate = 'DECLARE @UNI UNIQUEIDENTIFIER ' +
'SET @UNI = NEWID() ' +
'INSERT INTO BBAuditLog (id,AuditLogRecordId,UserName, EventDate, WorkflowStep, BatchId, Area, RecordName, RecordValue) ' +
'OUTPUT @@RowCount as RowsAffected ' +
'VALUES (NewID(),@AuditLogRecordId,@UserName,@EventDate,@WorkflowStep,@BatchId,@Area,@RecordName,@RecordValue);';

var sqlParam = {
    '@AuditLogRecordId': AuditLogRecordId,
    '@UserName': LastSavedBy,
    '@EventDate': moment(LastSavedDateTime).format('YYYY-MM-DDThh:mm:ssZ'),// LastSavedDateTime,
    '@WorkflowStep': ReportType,
    '@BatchId':BatchId,
    '@Area':'Header'
};

var dbConnString = 'Server=<ServerName>,1433;Database=<DBName>;Trusted_Connection=False;Encrypt=True;Connection Timeout=30;TrustServerCertificate=False';
var dbUser = '<Username>';
var dbPassword = '<Password>';

var query = {
    ConnectionString: dbConnString,
    User: dbUser,
    Password: dbPassword,
    SqlQuery: sqlUpdate,
    Parameters: sqlParam
};

var sqlresult = straatos.data.query(query);

---

Supported Character Sets

Supported charsets (java might support more, but this is the minimum).

• US-ASCII Seven-bit ASCII, a.k.a. ISO646-US.

• ISO-8859-1 ISO Latin Alphabet No. 1, a.k.a. ISO-LATIN-1.

• UTF-8 Eight-bit UCS Transformation Format.

• UTF-16BE Sixteen-bit UCS Transformation Format, big-endian byte order.

• UTF-16LE Sixteen-bit UCS Transformation Format, little-endian byte order.

• UTF-16 Sixteen-bit UCS Transformation Format, byte order identified by an optional byte-order mark.