Straatos Adapter Service API

This articles describes Straatos Adapter Service API

The Adapter Service is an extension of the Straatos Workflow, designed to enhance script service APIs and Interact APIs by providing built-in functionalities. This eliminates the need for developers to implement certain features manually, allowing for a more efficient development process.

Key Features:

• Enhances API capabilities without additional development effort.

• Provides pre-built methods that can be used in Interact APIs and Script APIs.

• Simplifies workflow integration by handling complex operations within Straatos.

How It Works:

• Developers can access adapter service methods within their script APIs or interact API.

• These methods can be used for data transformation, external system communication, and automation.

• The adapter service helps streamline workflow automation and integration with minimal coding.

---

Methods

Below is a list of functionalities provided by Straatos platform.

Method	Description
Get Document Info	Retrieves the information about the document or task.
Magick	This method incorporates an ImageMagick wrapper into the straatos data architecture. ImageMagick allows you to generate, edit, compose and convert digital photos. To learn more about the services that ImageMagick can provide, refer to https://imagemagick.org/.
Add Document Comment	Use this method to add a comment to the specific document identified by the documentId. DocumentId is the unique identifier for a document. The current Document ID is used as the default value.
Image Detect	Determine the presence of the Swiss flag and human faces on images/identity cards.
Add Additional Data	Add additional files to an existing document.
Add Additional Data With URL	Add additional files to an existing document from a specified path.
Remove Additional Data	Remove additional data from a document.
Detect Barcodes	Detect barcodes on specific document page identified by the documentId.
Detect Barcodes V2	Detect barcodes in a document, using a newer and faster engine (optionally specified by documentId)
Get Account	Retrieves account information for specific account id.
List Accounts For Organisation	Retrieves all account information in an organisation.
List Accounts For Manager	Retrieves information about all accounts managed by a specific manager.
Face Detection	Determines whether an image contains a face, which can be useful when processing passports or identification cards.
Split Document	Divide a single document into two separate documents.
Merge Document	Combine two documents into a single document.
Delete Document Page	Deletes a page from a document permanently. Once deleted, there is no method to recover a document!
Html To Pdf	Converts an HTML input to a PDF file. It is possible to generate an Audit Report and attach it to a document.
Zip	It generates a zip archive.
Unzip	Unzips a zipped document associated with a task and adds the zip file's contents as additional data.
Pdf To Image	Convert a PDF document to a multipage TIFF or a collection of JPG images and add as additional data. This function returns a URL that points to the first image.
Create Searchable Pdf	Create a searchable pdf file containing the results of a JSON file. This provided URL is: Local URL: It only contains the filename and retrieved from the CumuluPpro storage. Full URL: It contains the entire URL, beginning with HTTP.
Create Merge PDF	Create a PDF document from a collection of PDF files and/or images. Provides a URL to the generated PDF.
Set Error	Configure a Straatos Error. Once configured, the Straatos Task generates an Error Event and displays the Error Message in the Monitor.
Set Document Restriction	Access to a document stored within Straatos is granted using one of two methods: Time-based restriction. Access count restriction.
Create Account	Create a new user account.
Get Account	Retrieve information about an existing account.
Update Account	Update a user's account information.
Delete Account	Delete a user account.
Start Workflow	Start a new task in a workflow.
Get File As String - Get File As Base64 - Get File As ByteArray	Retrieves a file either as a string or as a Base64 file based on a provided URL to the file.
List Roles For Organisation	List all of the roles and functions of the current organisation.

---

Get Document Info

Input Parameters

Name	Required/Optional	Description
DocumentId	Optional	DocumentId is the unique identifier for a document. The current Document ID is used as the default value.

Sample Request Body

var documentInfo = straatos.adapter.getDocumentInfo();

Response Parameters

Name	Description
id	The unique identifier to obtain information about a document.
region	The S3 region is used for storage.
originalURL	When available, the original URL of the uploaded document will be displayed.
documentPages	A list of documentPages. This list contains the following fields:
lastModifiedDateTime	DateTime when the document was last updated.
Comments	A list of comments. This list contains the following fields:
timestamp	When the comment was entered.
comment	The actual comment.
additionalData	A list of all the additional data. This list contains the following fields:
width	The width of the original document. Set the value of GetDimensions to true.
height	The height of the original document. Set the value of GetDimensions to true.

---

Magick

Input Parameters

Name	Description
DocumentId	documentId is the unique identifier for a document. This is an optional parameter. (default: _documentId)
Command	The imageMagick command to execute; by default, convert is used.
InputAdditionalDataKey	If not null then the input file will be the additional file identified by the data key to use. If empty, then use the original URL (or if empty, preview URL) on a page level.
OutputAdditionalDataKey	Do not return the output URL but store the output as additional data. If this additional data key already exists, the new version will overwrite it.
OutputFormat	If the information is true, the result will contain the redirected output of the command rather than the URL of the output image. Another possible value is JSON, which results in the return of a JSON document containing all processed parameters.
ReturnOutput	if true and OutputFormat is not info, then '-' is appended.
OutputExtension
PageIndex	Indicates the page number to be used (zero-based).
Parameters	Parameters to pass to the imageMagick call.

Sample Code

try {
    var magickDetect = {
        OutputFormat: 'json',
        ReturnOutput: true,
        PageIndex: 0,
        Parameters:
            //'-gravity ' + gravity +
            ' -crop 50%x50%! ' +
            '-normalize ' +
            '-fuzz 30% -fill white +opaque red ' +
            '-monochrome ' +
            '-morphology close disk:3 ' +
            '-trim ' +
            '-resize 250x250 ' +
            '-shave 14x5 ' +
            '-moments'
    };
    var output = straatos.adapter.magick(magickDetect);
    console.log(output);
    MagickStatus = "OK";
}
catch (err) {
    console.log('error:' + err);
}

Sample Response

The following response is snippet of the actual result. It can either be JSON with output of imageMagick, or URL of resulting image.

"image": {
    "name": "-",
    "baseName": "18625465-1135-4f7c-9806-0b8cd35f23c7.jpg",
    "format": "JPEG",
    "formatDescription": "JPEG",
    "mimeType": "image/jpeg",
    "class": "DirectClass",
    "geometry": {
        "width": 222,
        "height": 240,
        "x": 0,
        "y": 0
    },
    "resolution": {
        "x": 200,
        "y": 200
    },
    "printSize": {
        "x": 1.1100000000000001,
        "y": 1.2
    },
    "units": "PixelsPerInch",
    "type": "Bilevel",
    "baseType": "TrueColorAlpha",
    "endianess": "Undefined",
    "colorspace": "sRGB",
    "depth": 1,
    "baseDepth": 8,
    "channelDepth": {
        "alpha": 1,
        "gray": 1
    },
    "pixels": 53280,
    "channelStatistics": {
        "Alpha": {
            "min": "255",
            "max": "255",
            "mean": "255",
            "standardDeviation": "0",
            "kurtosis": "0",
            "skewness": "0"
        },
    }
}

---

Add Document Comment

Input Parameters

Name	Description
DocumentId	DocumentId is the unique identifier for a document. This is an optional parameter. (default: _documentId)
Comment	The text of the comment.
CommentTimestamp	The (optional) timestamp should be stored with the comment. If the date/time field is left blank, the current date/time will be used.
AuthAccountId	The id of the CumulusPro account.
LoginName	This information will be stored in the Comment table, with the LoginName displayed during Web validation.
Name	This information will be stored in the Comment table, with the row name displayed during Web validation.

Sample Code

var commentLines = 'This is a test comment';
try{
	var addCommentInput ={
		Comment: commentLines,
		AuthAccountId: '1234',
		LoginName: '[email protected]',
		Name: 'test account'
	};
	var documentInfoString = straatos.adapter.addDocumentComment(addCommentInput);
}
catch(err){
	console.log('error:' + err);
}

Sample Response

Upon success, response body contains an empty string (“”).

---

Image Detect

Input Parameters

Name	Description
DocumentId	DocumentId is the unique identifier for a document. This is an optional parameter. (default: _documentId)
InputAdditionalDataKey	When set, use an additionalData file as input, otherwise use OriginalUrl (or, if empty, the preview URL on page level)
PageIndex	0-based pageIndex of the page to use.
EnableFaceDetection	When returning the execution result, this parameter specifies whether or not face detection should be considered
EnableLandmarkDetection	Specifies whether face landmark detection should be performed to determine whether the face is forward/upright and to validate the result of the face detection.
MinimumMatchingScore	This value specifies the minimum matching score that should be used when identifying the flag pattern.

Output Status

Value	Description
-1	If there is an error while parsing command line arguments or any file fails to load/save
0	If there is a global negative match
1	If there is a global positive match

Sample Output JSON

{
	"FaceDetectionEnabled": true,
	"LandmarkDetectionEnabled": true,
	"FlagFound": true,
	"FaceFound": false,
	"FlagScore": 0.9959738254547119,
	"DocBottomLeftX": 43.44289779663086,
	"DocBottomLeftY": 1388.8232421875,
	"DocBottomRightX": 2211.49609375,
	"DocBottomRightY": 1394.5150146484375,
	"DocTopLeftX": -7.8344855308532715,
	"DocTopLeftY": 0.8703601360321045,
	"DocTopRightX": 2182.6748046875,
	"DocTopRightY": 2.0112831592559814,
	"FaceBottomLeftX": 244.07904052734375,
	"FaceBottomLeftY": 1130.546875,
	"FaceBottomRightX": 658.9694213867188,
	"FaceBottomRightY": 1131.473388671875,
	"FaceTopLeftX": 229.14334106445312,
	"FaceTopLeftY": 708.306396484375,
	"FaceTopRightX": 645.33544921875,
	"FaceTopRightY": 708.9693603515625,
	"FlagBottomLeftX": 133.9904022216797,
	"FlagBottomLeftY": 372.49267578125,
	"FlagBottomRightX": 411.7124328613281,
	"FlagBottomRightY": 372.79376220703125,
	"FlagTopLeftX": 123.77064514160156,
	"FlagTopLeftY": 88.54669189453125,
	"FlagTopRightX": 402.07513427734375,
	"FlagTopRightY": 88.7286148071289,
}

Name	Description
FaceDetectionEnabled	Indicates whether face detection was enabled.
LandmarkDetectionEnabled	Indicates whether landmark detection was enabled.
FaceFound	Indicates whether a face was discovered in the document's image.
FlagFound	Indicates whether or not the flag pattern was correctly identified.
FlagScore	The resulting score for identifying flag patterns.
Doc...	- 4 point coordinate for the document boundaries on the input image.
Face...	- 4 point coordinate for the face boundaries on the input image.
Flag...	- 4 point coordinate for the flag pattern boundaries on the input image.

Sample Code

var ImageInfo = {
    InputAdditionalDataKey: "attachment:image/jpeg:FrontID-RV (1).jpg",
    EnableFaceDetection: true
};

console.log(JSON.stringify(ImageInfo));

try {
    var outputJson = JSON.parse(
        JSON.parse(straatos.adapter.imageDetect(ImageInfo))
    );
    console.log(JSON.stringify(outputJson));
} catch (err) {
    console.log('error: ' + err);
}

Sample Response

{
	""DocBottomLeftX"": -13.175889015197754,
	""DocBottomLeftY"": 1418.9727783203125,
	""DocBottomRightX"": 2221.368408203125,
	""DocBottomRightY"": 1447.650390625,
	""DocTopLeftX"": 18.879119873046875,
	""DocTopLeftY"": -25.148832321166992,
	""DocTopRightX"": 2214.426025390625,
	""DocTopRightY"": 22.742834091186523,
	""FaceDetectionEnabled"": false,
	""FaceFound"": false,
	""FlagBottomLeftX"": 141.9219207763672,
	""FlagBottomLeftY"": 356.0522766113281,
	""FlagBottomRightX"": 425.9892578125,
	""FlagBottomRightY"": 361.57977294921875,
	""FlagFound"": true,
	""FlagScore"": 0.9895056486129761,
	""FlagTopLeftX"": 147.8835906982422,
	""FlagTopLeftY"": 66.41143035888672,
	""FlagTopRightX"": 430.9324645996094,
	""FlagTopRightY"": 72.42932891845703,
	""LandmarkDetectionEnabled"": false
}

---

Add Additional Data

Input Parameters

Name	Description
DocumentId	DocumentId is the unique identifier for a document. This is an optional parameter. (default: _documentId)
FormData	The actual content of the data file.
Extension	The extension (=filetype) of the file to store.
Key	AdditionalData is stored under this key.

Sample Code

var formData = straatos.newFormData();
var testXml = '<additionalData>Test</additionalData>';

formData.append(testXml);
addAdditionalDataStatus = 'False';

try {
    var output = straatos.adapter.addAdditionalData(
        docID,
        formData.getByteArray(),
        '.xml',
        testKey
    );
    console.log(JSON.stringify(output));
} catch (err) {
    console.log('error: ' + err);
}

Result

Upon success, response body contains an empty string (“”).

---

Add Additional Data with URL

This method is preferred over AddAdditionalData, because it does not load the whole file in memory.

Sample Code

try {
    straatos.adapter.addAdditionalDataWithUrl({
        DocumentId: straatos.documentId,
        AdditionalDataKey: 'UrlKey',
        Extension: '.jpeg',
        FileUrl: 'https://images.unsplash.com/photo-1509043759401-136742328bb3'
    });
} catch (err) {
    console.log('error: ' + err);
}

Result

On success, the response body contains an empty string (“”).

---

Remove Additional Data

Sample Code

try {
    // Remove additional data
    straatos.adapter.removeAdditionalData({
        AdditionalDataKey: 'HtmlToPDF2'
    });
} catch (err) {
    console.log('Err Remove Additional Data: ' + err);
}

---

Detect Barcodes

This is an older version of the Detect Barcodes. It is still recommend that you use Detect Barcodes V2.

In most cases, no additional parameters are needed. If no parameters are defined, the engine will try to detect all Barcodes on the Original Document of the current Document.

Input Parameters

Name	Description
DocumentId	DocumentId is the unique identifier for a document. This is an optional parameter. (default: _documentId)
Faster	When enabled, an algorithm makes additional attempts to locate a disable barcode. This is an optional value.
Formats	[Optional] The barcode format to look for. Possible values are: 2D Barcodes: QR. MicroQR. DATA_MATRIX. PDF417. 1D Barcodes. CODABAR. CODE_39. EAN8. EAN_13. ITF. UPC_A. UPC_E.
PdfMatchPattern	[Optional] Regular expression to match. Only works if the original document is a PDF. This is an optional value.
PageIndexes	The 0-based pageIndex(es) of the pdf document to which barcodes should be detected. To specify multiple pages, use a comma to separate indexes (,). This is an optional value.

The earlier version of barcode engine (pre July 2021) is still available and can be used with the following function straatos.adapter.detectBarcodes

Sample Code

var detectBarcodes = {
    Formats: ['QR']
    // PageIndexes: 0,
    // InputAdditionalDataKey: 'attachment:image/jpeg:QRCoded.jpg',
    // PdfMatchPattern: /[a-zA-Z]{4}-\d{4}-\d{6}$/
};

detectBarcodesStatus = 'False';

try {
    var barcodes = straatos.adapter.detectBarcodesV2(detectBarcodes);
    console.log(JSON.stringify(barcodes));
} catch (err) {
    console.log('error: ' + err);
}

Sample Response

{
    "NumberOfBarcodesDetected": 1,
    "Pages": [
        {
            "Barcodes": [
                {
                    "Coordinates": [
                        { "X": 60, "Y": 129 },
                        { "X": 60, "Y": 57 },
                        { "X": 132, "Y": 57 },
                        { "X": 120, "Y": 117 }
                    ],
                    "Type": "QR_CODE",
                    "Value": "This is a QR Code by CumulusPro"
                }
            ],
            "PageNumber": 1
        },
        {
            "Barcodes": [],
            "PageNumber": 2
        }
    ]
}

---

Detect Barcodes V2

Input Parameters

Name	Description
DocumentId	DocumentId is the unique identifier for a document. This is an optional parameter. (default: _documentId)
PageIndexes	An array of the page(s) that should be scanned. The pages should be defined as 0-based index numbers.
Formats	An array of barcode format(s) to look for. Possible values are: QR. MicroQR. DATA_MATRIX. PDF417. CODABAR. CODE_39. EAN_8. EAN_13. ITF. UPC_A. UPC_E. GdPicture options: Industrial2of5. Inverted2of5. Inverted2of5. Interleaved2of5. Iata2of5. Matrix2of5. Code39. Codeabar. BcdMatrix. DataLogic2of5. Code128. CODE93. EAN13. UPCA. EAN8. UPCE. ADD5. ADD2.

Sample Code

try {
    var barcodes = straatos.adapter.detectBarcodesV2({});
    console.log(JSON.stringify(barcodes));
} catch (err) {
    console.log('error: ' + err);
}

---

Get Account

Input Parameters

Name	Description
id	The id of the account (AuthAccount)

Response Parameters

The response body contains an object with the following properties:

Name	Description
Id	The id of the account
ManagerAuthAccountId	The (optional) id of the user's manager as configured in Admin Panel
LoginName	The login name (email address)
Name	The (optional) name as configured in Admin Panel
UserIdentifier	The (optional) user identifier as configured in Admin Panel
Roles	A array of roles, each with its own Id, Name, and Functions (array of functions containing Id, Name)

Sample Code

var input = {
    id: accountId
};

try {
    var output = straatos.adapter.getAccount(input);
    console.log(JSON.stringify(output));
} catch (err) {
    console.log('error: ' + err);
}

Sample Response

{
    "Id": 20283,
    "LoginName": "[email protected]",
    "ManagerAuthAccountId": 1234,
    "Name": "Test Account",
    "Roles": [
        {
            "Functions": [
                {
                    "Id": 3,
                    "Name": "My Home"
                }
            ],
            "Id": 11064,
            "Name": "Myhome test"
        }
    ],
    "UserIdentifier": ""
}

---

List Accounts For Organization

Sample Code

listAccountForOrganisationStatus = 'False';

try {
    var output = straatos.adapter.listAccountsForOrganization({});
    console.log(JSON.stringify(output));
} catch (err) {
    console.log('error: ' + err);
}

Sample Response

Response body contains an array of objects with properties as detailed under Get Account section.

{
    "Id": 20283,
    "LoginName": "[email protected]",
    "ManagerAuthAccountId": 1234,
    "Name": "Test Account",
    "Roles": [
        {
            "Functions": [
                {
                    "Id": 3,
                    "Name": "My Home"
                }
            ],
            "Id": 11064,
            "Name": "Myhome test"
        }
    ],
    "UserIdentifier": ""
}

---

List Accounts For Manager

Input Parameters

Name	Description
managerId	The id of the manager's account

Sample Code

var input = {
    managerId: managerId
};

try {
    var output = straatos.adapter.listAccountsForManager(input);
    console.log(JSON.stringify(output));
} catch (err) {
    console.log('error: ' + err);
}

Sample Response

Response body contains an array of objects with properties as detailed under Get Account.

{
    "Id": 20283,
    "LoginName": "[email protected]",
    "ManagerAuthAccountId": 1234,
    "Name": "Test Account",
    "Roles": [
        {
            "Functions": [
                {
                    "Id": 3,
                    "Name": "My Home"
                }
            ],
            "Id": 11064,
            "Name": "Myhome test"
        }
    ],
    "UserIdentifier": ""
}

---

Face Detection

This method detects whether image contains face, for example, processing of passports and identification cards. Also able to rotate image to an upright posture in relation to the image and crop the document if the background is white.

The FaceDetection module requires a jpg as an input image.

Input Parameters

Name	Description
DocumentId	DocumentId is the unique identifier for a document. This is an optional parameter. (default: _documentId)
InputAdditionalDataKey	When set, an additionalData file is used as input; otherwise, OriginalUrl is used (or, if empty, the preview URL on page level)
CroppingMargin	Specifies the margin which is to be left for cropping
Threshold	Threshold value
EdgeRatio	Ratio of the edges
NoiseRatio	Noise Ratio

Sample Code

var docID = _documentId;

var documentInfoInput = {
    DocumentId: docID,
    InputAdditionalDataKey: "attachment:image/jpeg:image.jpg",
    CroppingMargin: 5,
    Threshold: 90,
    EdgeRatio: 1,
    NoiseRatio: 15
};

try {
    var output = JSON.parse(
        JSON.parse(straatos.adapter.orientationFinder(documentInfoInput))
    );
    console.log(JSON.stringify(output));
} catch (err) {
    console.log('error: ' + err);
}

Sample Response

The result is a processed image (turned upright and cropped) as well as JSON containing whether face was found, document was detected, coordinates where document was detected, coordinates where face was detected as well as score of the face:

{
	""URL"": ""https://effektif-connector-cpro-	ch.cumuluspro.net/ConnectorService.svc/json/Storage/ae1666df-d7b8-47d5-	b1b4-f1d4143a088d.jpg"",
	""DocBottomLeftX"": 10.062535285949707,
	""DocBottomLeftY"": 1416.6976318359375,
	""DocBottomRightX"": 2282.43701171875,
	""DocBottomRightY"": 1416.6976318359375,
	""DocDetected"": true,
	""DocTopLeftX"": 10.062535285949707,
	""DocTopLeftY"": -19.61455535888672,
	""DocTopRightX"": 2282.43701171875,
	""DocTopRightY"": -19.614511489868164,
	""FaceBottomLeftX"": 260.82867431640625,
	""FaceBottomLeftY"": 1112.6834716796875,
	""FaceBottomRightX"": 644.717529296875,
	""FaceBottomRightY"": 1112.6834716796875,
	""FaceFound"": true,
	""FaceScore"": 0.6723385453224182,
	""FaceTopLeftX"": 260.82867431640625,
	""FaceTopLeftY"": 728.0123291015625,
	""FaceTopRightX"": 644.717529296875,
	""FaceTopRightY"": 728.0123291015625
}

---

Split Document

Split a document into two documents. Original documents will contain first pages, newly created second document will contain all documents have pageIndex >= specified PageIndex. After document is split, MessageWorkflow call to newly created document should be done to allow further processing of document by the Straatos engine.

Input Parameters

Name	Description
WorkflowInstanceId	The effective workflowInstanceId belonging to the documentId
PageIndex	0-based index on where to split the document. All pages >= PageIndex will be part of the new documentId
CopyFieldValues	When true, the new document will have variable values of the original document.

Upon success, a JSON with the following fields is returned:

WorkflowInstanceId	The effective workflowInstanceId belongs to the new document.
DocumentId	The DocumentId belonging to the newly created document.

Sample Code

var docID = _documentId;

try {
    var splitInput = {
        WorkflowInstanceId: straatos.getWorkflowInstanceIdByDocumentId(docID),
        PageIndex: 1
    };

    var splitOutput = straatos.adapter.splitDocument(splitInput);
    console.log(JSON.stringify(splitOutput));

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

Sample Response

{
	"DocumentId": 946919,
	"WorkflowInstanceId": "59c21481b3ac1616f09fe22c"
}

---

Merge Documents

Input Parameters

Name	Description
DocumentId1	The documentId of the first document
DocumentId2	The documentId of the second document
WorkflowInstanceId2	The WorkflowInstanceId was known by the straatos engine of the second documentId

Sample Code

try {
    var mergeRequest = {
        DocumentId1: docID1,
        DocumentId2: docID2,
        WorkflowInstanceId2: WorkflowInstanceId2
    };

    var mergeResult = straatos.adapter.mergeDocuments(mergeRequest);
    console.log(JSON.stringify(mergeResult));

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

Result

If successful, response body will contain “ok”, and “error” when not successful.

---

Delete Document Page

Name	Description
DocumentId	DocumentId is the unique identifier for a document. This is an optional parameter. (default: _documentId)
PageIndex	0-based index of the page to delete.

Sample Code

try {
    var deleteInput = {
        PageIndex: 0
    };

    console.log(JSON.stringify(deleteInput));

    var deleteOutput = straatos.adapter.deleteDocumentPage(deleteInput);
    console.log(JSON.stringify(deleteOutput));

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

Result

If successful, the response body contains an empty string (“”).

---

Html To Pdf

Input Parameters

Name	Description
DocumentId	The unique identifier of the document for which the PDF should be created.
PageSize	The PDF page size (for example A4).
OutputAdditionalDataKey	The Additional Data Key in which the document can be found. For example 'pdf-audit'.
PrependPDFUrl	You can specify either PrependPDFUrl or PrependPDFAdditionalData (key). This field must point to an existing PDF file. The PDF will be prepended with the new HTML-generated PDF. Intended for use in creating cover pages for pre-existing documents.
PrependPDFAdditionalData	You can specify either PrependPDFUrl or PrependPDFAdditionalData (key). This field must point to an existing PDF file. The PDF will be prepended with the new HTML-generated PDF. Intended for use in creating cover pages for pre-existing documents.
AppendPDFUrl	You can specify either AppendPDFUrl or AppendPDFAdditionalData (key). This field must point to an existing PDF file. The PDF will be appended to the new HTML-based PDF. Ideal for creating audit trails and exporting documents that are attached to an existing document.
AppendPDFAdditionalData	You can specify either AppendPDFUrl or AppendPDFAdditionalData (key). This field must point to an existing PDF file. The PDF will be appended to the new HTML-based PDF. Ideal for creating audit trails and exporting documents that are attached to an existing document.
AppendPDFAdditionalData	You can specify either AppendPDFUrl or AppendPDFAdditionalData (key). This field must point to an existing PDF file. The PDF will be appended to the new HTML-based PDF. Ideal for creating audit trails and exporting documents that are attached to an existing document.
Landscape	Boolean, If the value is not set or is false, the value is Portrait.
HTML	The HTML code of the file.
Margin	If empty, the default value is 36.

The Example code below fetches users who have participated in User Task (for example, Approval). It then generates HTML code that includes a table with the date, username, and process step information. Finally, HTMLtoPDF function produces PDF and adds extra Data to Task. The code returns the document’s URL.

Output PDF looks like this:

Sample Code

var accountsString = straatos.adapter.listAccountsForOrganization({});

var accountLookup = {};

if (accountsString.length > 0) {
    accountsString.forEach(function (account) {
        accountLookup[account.Id] = account.Name ? account.Name : account.LoginName;
    });
}

var lines = '';

var history = JSON.parse(straatos.history());

history.activityInstances.forEach(function (activityInstance) {
    if (activityInstance.activityName) {
        if (esc(accountLookup[activityInstance.triggerUserId]).length != 0) {
            lines +=
                '<tr>' +
                '<td>' + moment(activityInstance.end).lang('de').format('LLL') + '</td>' +
                '<td>' + esc(accountLookup[activityInstance.triggerUserId]) + '</td>' +
                '<td>' + activityInstance.activityName + '</td>' +
                '</tr>';
        }
    }
});

var htmlToPdf = {
    DocumentId: _documentId,
    PageSize: 'A4',
    OutputAdditionalDataKey: 'new-pdf-audit',
    PrependPDFAdditionalData: 'abbyy-pdf-searchable',
    HTML: html()
        .replace(/#tablelines#/, lines)
        .replace(/#DocumentID#/, _documentId)
};

var outputHTMLtoPDF = straatos.adapter.htmlToPDF(htmlToPdf);
console.log('outputPDF URL: ' + outputHTMLtoPDF);

function esc(value) {
    if (typeof value === 'undefined') return '';
    return value;
}

function hereDoc(f) {
    return f.toString()
        .replace(/^[^\/]+\/\*!?/, '')
        .replace(/\*\/[^\/]+$/, '');
}

function html() {
    return hereDoc(function () { /*!
    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
    <html xmlns="http://www.w3.org/1999/xhtml">
    <head>
    <title>HTML Table Layout with CSS Style - 3 Column</title>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <link href="https://fonts.googleapis.com/css?family=Lato" rel="stylesheet">
    <style type="text/css">

    html, body {
      height: 100%;
    }

    body {
      margin: 0;
      font-family: 'Lato', sans-serif;
      font-size: 1.2rem;
      font-size: 12px;
      line-height: 16px;
      margin: 30px;
    }

    svg {
      width: 20%;
      vertical-align: middle;
      position: absolute;
      top: 50%;
      -webkit-transform: translateY(-50%);
      transform: translateY(-50%);
      display: inline-block;
      float: left;
    }

    .table {
      margin: 30px;
    }

    table.layout {
      border: 1px #ddd solid;
      width: 100%;
    }

    tr {
      height: 20px;
      border: 1px #ddd solid;
    }

    tr:nth-child(even) {
      background-color: rgba(17,76,143,0.2);
    }

    td {
      padding: 2px 5px;
    }

    th.header {
      color: white;
      background: #114C8F;
      text-align: left;
      padding: 2px 5px;
    }

    </style>
    </head>
    <body>

    <header>
      <div style="position: relative; display: block; border-bottom: 2px #114C8F solid; height: 75px;">
        <svg xmlns="http://www.w3.org/2000/svg" version="1.1" x="0" y="0" width="808.6" height="127.3" viewBox="0 0 808.6 127.3" enable-background="new 0 0 808.611 127.312" xml:space="preserve"><path fill="#114C8F" d="M281.1 118.5c-3.1 1.5-10.6 3.4-20 3.4 -27.1 0-41.1-17-41.1-39.4 0-26.8 19.1-41.6 42.9-41.6 9.2 0 16.2 1.7 19.3 3.5l-3.7 14c-3.5-1.5-8.5-2.9-14.9-2.9 -14 0-24.9 8.5-24.9 26 0 15.7 9.3 25.6 25 25.6 5.5 0 11.3-1 14.9-2.6L281.1 118.5zM340.7 102.3c0 7.5 0.2 13.5 0.5 18.3h-15.4l-0.8-8h-0.3c-2.2 3.5-7.6 9.3-17.8 9.3 -11.6 0-20-7.2-20-24.8V63.7h17.7v30.6c0 8.3 2.7 13.3 9 13.3 4.9 0 7.8-3.4 8.9-6.2 0.5-1 0.7-2.3 0.7-3.8V63.7h17.7V102.3zM514.2 37.9h17.7v82.7h-17.7V37.9zM596.9 102.3c0 7.5 0.2 13.5 0.5 18.3h-15.4l-0.8-8h-0.3c-2.2 3.5-7.6 9.3-17.8 9.3 -11.6 0-20-7.2-20-24.8V63.7h17.7v30.6c0 8.3 2.7 13.3 9 13.3 4.9 0 7.8-3.4 8.9-6.2 0.5-1 0.7-2.3 0.7-3.8V63.7h17.7V102.3zM608.1 105.2c3.3 2 10 4.2 15.2 4.2 5.4 0 7.6-1.7 7.6-4.7 0-3-1.8-4.4-8.3-6.6C610.8 94.2 606.2 87.8 606.4 81c0-10.7 9.1-18.7 23.2-18.7 6.6 0 12.5 1.6 16 3.4l-3 12.2c-2.6-1.4-7.6-3.3-12.3-3.3 -4.3 0-6.8 1.7-6.8 4.5s2.2 4.2 9.2 6.6c10.8 3.7 15.3 9.3 15.4 17.6 0 10.7-8.3 18.5-24.6 18.5 -7.4 0-14.1-1.7-18.4-4.1L608.1 105.2zM657 43.2c5.2-0.9 12.3-1.6 21.9-1.6 10.5 0 18.1 2.2 23.1 6.4 4.7 3.8 7.7 10 7.7 17.4 0 7.5-2.3 13.5-6.6 17.7 -5.8 5.7-14.7 8.5-24.8 8.5 -2.7 0-5-0.1-7-0.6v29.7h-14.2V43.2zM671.2 79.6c1.9 0.6 4.1 0.7 7 0.7 10.7 0 17.2-5.4 17.2-14.4 0-8.7-6.1-13.3-16-13.3 -4 0-6.8 0.4-8.3 0.7V79.6zM717.2 82.2c0-7.7-0.1-13.3-0.5-18.3h12.3l0.6 10.7h0.3c2.8-7.9 9.4-12 15.6-12 1.4 0 2.2 0.1 3.4 0.4v13.4c-1.3-0.2-2.6-0.3-4.3-0.3 -6.7 0-11.5 4.3-12.8 10.8 -0.2 1.3-0.3 2.8-0.3 4.3v29.5h-14.3V82.2zM808.6 91.7c0 20.8-14.7 30.2-29.1 30.2 -16 0-28.4-10.9-28.4-29.2 0-18.6 12.2-30 29.3-30C797.3 62.6 808.6 74.5 808.6 91.7zM765.9 92.3c0 10.9 5.5 19.2 14.1 19.2 8.2 0 13.9-7.9 13.9-19.4 0-8.8-4-19.1-13.7-19.1C770 73 765.9 82.9 765.9 92.3z"></path><path fill="#114C8F" d="M163.5 127.3H49.8C22.3 127.3 0 105 0 77.5c0-22.8 15.7-42.6 37.3-48.2C46.9 11.3 65.6 0 86.3 0c21.1 0 40.3 12.1 49.7 30.6 15.8 3.5 28.9 14.8 34.6 29.8 15.2 3.3 26.7 16.9 26.7 33.1C197.4 112.1 182.2 127.3 163.5 127.3zM87.5 19.5c-14.2 0-27 8.5-32.4 21.7l-2.3 5.5 -5.9 0.8c-14.3 2-25.1 14.4-25.1 28.9 0 16.1 13.1 29.2 29.2 29.2h113.7c7.3 0 13.2-5.9 13.2-13.2 0-7.2-5.8-13.1-13-13.2 -0.2 0-0.4 0-0.6 0l-8.7 0.3 -1.7-8.5c-2.4-11.8-12.5-20.8-24.6-21.8l-6.6-0.5 -2.3-6.2C115.3 28.7 102.1 19.5 87.5 19.5z"></path></svg>
        <h1 style="position:absolute;width:75%;padding:10px;color:#555;margin-left: 25%;padding: 10px;border-left:2px #555 solid;bottom:0;">Audit Trail</h1>
      </div>
    </header>
    <article class="table">
      <h3>Invoice Approval</h3>
      <table class="layout">
        <tr>
          <th class="header datum">Date and Time</th>
          <th class="header benutzer">User</th>
          <th class="header prozess">Processstep</th>
        </tr>
        #tablelines#
        <!--
        <tr>
          <td>16. Mai 2017 19:49</td>
          <td>Stephan Wolf</td>
          <td>Visierung Stephan Wolf</td>
        </tr>
        -->
      </table>
    </article>
    </body>
    </html>
    */});
}

Result

PDF is attached as additional Data and URL to PDF.

---

Set Document Restriction

Input Parameters

Name	Description
Url	The URL to the document to grant access to.
MinutesFromNow	The duration of access to the document in minutes. The number of minutes that have passed since the script was run (not from the creation of the task).
AccessCount	You can specify either PrependPDFUrl or PrependPDFAdditionalData (key). This field must point to an existing PDF file. The PDF file will be prepended with the new HTML-based PDF. Intended for use in creating cover pages for pre-existing documents.

Sample Code

The following code shows how to test access toa document. In the first part, the URL for additionalData file 'test-xml' is retrieved. Then, script tries to access documents without granting access, resulting in 'Fail. Script then allows access to document once and then tests access again, indicating that access is now granted.

var documentInfo = straatos.adapter.getDocumentInfo();

var additionalDataUrl = documentInfo.additionalData
    .filter(function (additionalData) {
        return additionalData.key == 'test-xml';
    })[0].url;

// Assuming workflow-level "Documents Public Accessible" is set to Never
// Test if the file is accessible without webservice key or valid session ID.
straatos.ajax({
    url: additionalDataUrl
}).done(function (data) {
    // The access was successful, hence the test failed as we expected not to have access to the document.
    console.log('DocRestriction Failed: should not be accessible');
    DocumentRestrictions = 'False';
}).fail(function (response, error) {
    // The access was unsuccessful, which we expected, so the test was successful.
    console.log('DocRestriction Succeeded: could not access');
    if (DocumentRestrictions != 'False') DocumentRestrictions = 'OK';
});

// Set a one-time access to the document
straatos.adapter.setDocumentRestrictions({
    URL: additionalDataUrl,
    AccessCount: 1
});

// Test if the document can be accessed
straatos.ajax({
    url: additionalDataUrl
}).done(function (data) {
    console.log('Succeeded: could access once');
    if (DocumentRestrictions != 'False') DocumentRestrictions = 'OK';
}).fail(function (response, error) {
    console.log('Failed: should be accessible once');
    DocumentRestrictions = 'False';
});

---

Zip

Input Parameters

Name	Description
AdditionalDataKey	The additionalData is placed under this key (not the URL)
Files	A File array. Each object in the array should be a JSON object containing 2 (out of possible 3) keys: Filename - The name of the file that should be included in the zip. SourceURL - The URL to the document to be added. UTF8Content.
DocumentId	Optional, if not specified the current document will be used.
TimeOutMs	Optional timeout in Milliseconds, If no timeout value is specified, the default value of 90 seconds is used.

Sample Code

The following code adds file from additional Data to ZIP file named 'zip'

var returnURL = straatos.adapter.zip(zipParameters);

var zipParameters = {
    AdditionalDataKey:'zip',
    Files:[
        {SourceUrl: additionalDataUrl, FileName:'123.xml'}
    ]
};

---

Unzip

Input Parameters

Name	Description
AdditionalDataPrefix	Prefix for each additional data entry created from the zip file
AdditionalDataKey	The Key of the additionalData where the ZIP file is stored
DocumentId	Optional, if not specified the current document will be used.
IgnoreDirectoryInfo	Ignore the directory information in the ZIP file as an option. If it is true, all entries in the additional data key will be extracted without path information. The default value is false.
IncludeHiddenFiles	Optional option to include files that have a name string with '.'. The default value is false.
TimeoutMs	Optional timeout in Milliseconds, if no timeout value is specified, the default value of 90 seconds is used.

Sample Code

The following code extracts data from zip file and adds data as additional data with prefix 'Unzip-'.

straatos.adapter.unzip({AdditionalDataPrefix:'Unzip-',AdditionalDataKey:'zip'});

---

Pdf To Image

Input Parameters

Name	Description
EndpageNumber	End (1 based) page number. The default value is 0, which includes all pages. This is an optional parameter.
JPGQuality	An optional value between 0-100. Default is 40.
DocumentId	If not specified, the current document will be used. This is an optional parameter.
OutputAdditionalDataKeyPrefix	Optional prefix for the generated additional data keys (default is 'page' and will be suffixed by e.g. '-0001.jpg')
OutputTiff	If true, a multipage TIFF file will be generated, default is false (JPG).
PDFURL	URL pointing to the PDF file.
ResolutionDPI	Optional value in DPI, default is 150.
StartPageNumber	Optional, start (1 based) page number. The default value is 0, which includes all pages.
TimeoutMs	Optional timeout in Milliseconds, if no timeout value is specified, the default value of 90 seconds is used.
UserPassword	Optional, password to access password-protected PDF files.

Sample Code

The following code creates TIF file from PDF in 300dpi:

straatos.adapter.pdfToImage(
    {
    JPGQuality:'90', 
    OutputAdditionalDataKeyPrefix:'testTIF', 
    PDFURL:OriginalUrl, 
    ResolutionDPI:'300',
    OutputTiff:'true'
    }
);

---

Create Merge PDF

Input Parameters

Name	Description
CompressionLevel	Optional, compression level, default is 'normal'. Available options are: AboveNormal. BelowNormal. Best. BestSpeed. NoCompression. Normal.
Orientation	Optional page orientation. Available options are: Portrait. Landscape.
DocumentId	Optional, if not specified the current document will be used.
OutputAdditionalDataKey	Optional additional data key, default is 'merge.pdf'.
PageSize	Optional page size. Available options are: Letter. Note. Legal. A0. A10. B0. B5. ArchA. ArchE. Fisa. HalfLetter. Letter11x7. Ledger.
Files	An array of file descriptions, one entry for each PDF file or image to append. Each entry is formatted as follows: {RL:'https://...', StartIndex: 0, Length: 99, Password: '...'}. Only the URL is required and point to a PDF or image file.
TimeoutMs	Optional timeout in Milliseconds, if no timeout value is specified, the default value of 90 seconds is used.
Password	Optional, password to access password-protected PDF files.

Sample Code

The following code merges two PDF files.

// Create a MergePDF from two PDFs
var documentInfo = straatos.adapter.getDocumentInfo();

var secondPDFUrl = documentInfo.additionalData
    .filter(function (additionalData) {
        return additionalData.key == 'HtmlToPDF2';
    })[0].url;

straatos.adapter.createMergePDF({
    OutputAdditionalDataKey: 'createMergePDF.pdf',
    Files: [
        { URL: outputHTMLtoPDF },
        { URL: secondPDFUrl }
    ]
});

---

Create Searchable Pdf

Input Variables

{  
    DocumentId:'9223372036854775807',
    OutputAdditionalDataKey:'yourDataKey',
    InputImageFile: 'd75b5fad-cdb0-471c-8532-6a97d92727a3.pdf',
    InputJsonFile: '757db782-aaa3-4cef-884a-bd9c7e0d200b.json'
}

Sample Code

You can get InputImageFile and InputJsonFile from a call to GetDocumentInfo, or you can store the value that is returned when you add additional data with call to AddAdditionalData().

var documentInfo = straatos.adapter.getDocumentInfo();

var thePdfUrl = documentInfo.additionalData
    .filter(function (additionalData) {
        return additionalData.key == 'HtmlToPDF';
    })[0].url;

var jsonFile = documentInfo.additionalData
    .filter(function (additionalData) {
        return additionalData.key == 'HtmlToPDF';
    })[0].url;

var pfdFileName = straatos.adapter.createSearchablePdf({
    "DocumentId": 1234,
    "OutputAdditionalDataKey": "MyPDF",
    "InputImageFile": thePdfUrl,
    "InputJsonFile": jsonFile
});

---

Set Error

Straatos.setError is used to set an error to a task when a task has an error.

Sample Code

straatos.setError("Error Successfully Set");

---

Create Account

Input Parameters

Name	Description
LoginName	Login credentials.
Email Address	Login email address.
Name	Name of the person/account.
UserIdentifier	Similar to Login Name.
Password	Optional, password to create new user.
Roles	Defining the roles to be added to the account.

Sample Code

The following code creates a new user.

var newAccount = {
    LoginName: '[email protected]',
    EmailAddress: "",
    Name: 'Test Account',
    UserIdentifier: '[email protected]',
    Password: "<password>",
    Roles: []
};

console.log(JSON.stringify(newAccount));

try {
    straatos.adapter.createAccount(newAccount);
} catch (err) {
    straatos.setError(err);
}

---

Get Account

Input Parameters

Name	Description
Id	Account ID is associated with account for which information is required.

Sample Code

The following code fetches user account information.

var validInput = { Id: validAccountId };

try {
    var account = straatos.adapter.getAccount(invalidInput);
    console.log(JSON.stringify(account));
} catch (err) {
    straatos.setError(err);
}

Sample Response

Below is output from Get Account.

{
    "WebServiceKey": null,
    "EffektifWorkflowId": null,
    "Id": 4001,
    "ManagerAuthAccountId": null,
    "LoginName": "[email protected]",
    "EmailAddress": "",
    "Name": "Test Account",
    "UserIdentifier": null,
    "Password": null,
    "Roles": []
}

---

Update Account

Input Parameters

Name	Description
LoginName	Login credentials.
Email Address	Login email address.
Name	Name of the person/account.
UserIdentifier	Similar to Login Name.
Password	Optional, password to update user.
Roles	Defining the access to the roles for the account.

Sample Code

The following code updates user account information.

try {
    var accounts = straatos.adapter.updateAccount(newAccount);
    console.log('newAccount: ' + JSON.stringify(accounts));
} catch (err) {
    straatos.setError(err);
}

Sample Response

Below is output from updateAccount.

{
    "WebServiceKey": "<webserviceKey>",
    "EffektifWorkflowId": "<workflowid>",
    "Id": 4001,
    "ManagerAuthAccountId": null,
    "LoginName": "[email protected]",
    "EmailAddress": "",
    "Name": "Test Account Updated",
    "UserIdentifier": "[email protected]",
    "Password": null,
    "Roles": []
}

---

Delete Account

Input Parameters

Name	Description
ID	ID of account that needs to be deleted.

Sample Code

The following code deletes the user's account.

var input = { Id: newAccountId };

try {
    straatos.adapter.deleteAccount(input);
} catch (err) {
    straatos.setError(err);
}

---

Start Workflow

Input Parameters

Name	Description
workflowid	Workflow ID of workflow where new task should be started. If it is the same workflow, can be passed with straatos.workflowId.
startActivityId	Start activity ID of start event which should start the workflow.
Data	indexfielddata to be passed.
workflowconfiguration	Numeric (short) workflow ID which is also visible in Admin Panel. Alternative to specify workflowid.
webservice Key	(Optional, not needed to start a workflow in your own organisation). If you want to start a workflow in another organisation, enter that workflows webServiceKey here.
filetype	If original document is provided, provide filetype (pdf, tif, jpg).
documenturls	URL(s) to documents that need to be added as original document.

Sample Code for Interact API

var conf = {
    "workflowid": "59d39db00eb0834790670e8d",
    "data": {
        "AutoTest": "Jeroen",
        "SomethingElse": "No"
    },
    "documentUrls": [
        "https://yourdomain/s3fs-public/thumbnails/image/2018/12/11/17/gettyimages-1048042404.jpg"
    ],
    "startActivityId": "6851",
    "additionalDatas": [
        {
            "key": "jb",
            "index": 0,
            "url": "https://yourdomain/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png"
        }
    ],
    "filetype": "jpg",
    "webServiceKey": "199aa86e-c6f4-4901-b169-740dacd38dba"
};

straatos.adapter.startWorkflow(conf);

Sample Code for Script Task

var conf = {
    "workflowConfiguration": "1234",
    "data": {
        "AutoTest": "Jeroen",
        "SomethingElse": "No"
    },
    "documentUrls": [
        "https://yourdomain/s3fs-public/thumbnails/image/2018/12/11/17/gettyimages-1048042404.jpg"
    ],
    "startActivityId": "6851",
    "additionalDatas": [
        {
            "key": "jb",
            "index": 0,
            "url": "https://yourdomain/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png"
        }
    ],
    "filetype": "jpg",
    "webServiceKey": "199aa86e-c6f4-4901-b169-740dacd38dba"
};

straatos.startWorkflow(conf);

---

Get File As String / Get File As Base64 / Get File As ByteArray

Input Parameters

Name	Description
DocumentId	Straatos documentId of task from where to get file content. Required from interact API or when it is from different task.
FileUrl	URL to document to retrieve content from.
WebServiceKey	Only required if file is retrieve from workflow outside current workflow or if called from interact API.

Sample Code

var url = '7756d1cc-f0b7-456c-b862-fb62a62bf3fc.tif';

var base64 = straatos.adapter.getFileAsBase64({
    FileUrl: url,
    DocumentId: 6141667
});

---

List Roles for Organisation

Input Parameters

Name	Description
credentials	Login credentials
ID	ID of account holder
Functions	Function/role of account holder.

Sample Code

The following code fetches a list of roles available in organisation.

try {
    var output = straatos.adapter.listRolesForOrganization();
} catch (err) {
    straatos.setError(err);
}

Sample Response

Following code output from ListRolesFromOrganisation.

[
    {
        "Id": <ID>,
        "Name": "Admin",
        "Functions": 
        [{
            "Id": <ID>,
            "Name": "AdminPanel"
        }]
    },
    {
        "Id": <ID>,
        "Name": "Myhome test",
        "Functions":
        [{
            "Id": <ID>,
            "Name": "My Home"
        }]
    },
    {
        "Id": <ID>,
        "Name": "scan",
        "Functions":
        [
            {
                "Id": <ID>,
                "Name": "My Home"
            },
            {
                "Id": <ID>,
                "Name": "Scan+"
            }
        ]
    }
]