Skip to main content

Process modeler SDK

The process modeler SDK Description

The process modeler SDK is available in any input or output variables in the process modeler, It allows users access resources from process and execute complexe computational in the instance run time.

The SDK can be accessed trought the SF variable.

The SDK has the following attributs

var SF = {
collection : Object,
user : Object,
file : Object,
utils : Object,
sql : Object,
instance : Object,
task : Object,
process : Object,
mode : String, // The current Mode this is setted automatically
};

In the following sections we will explicit each attribute and the allowed methods.

1 - Utils


The utils object has the methods that will allow you to

nextValue

Generates an incremental number based on a unique string name. The resulting ID can be zero-padded to a specified length if desired.

Parameters

NameTypeDescription
namestringA unique name used as the key to generate the ID.
paddingnumber(Optional) The number of digits to pad the result with (e.g., 6 → 000001).

Returns

TypeDescription
PromiseA Promise that resolves to the generated ID.

Examples

let id = await SF.utils.nextValue("leave_request");
// return number 1
let id = await SF.utils.nextValue("leave_request",5);
// return string 00001

shellExecLocal

Is a function that executes a local shell command and returns the trimmed output.

Parameters

NameTypeDescription
cmdstringThe shell command to be executed.

Returns

TypeDescription
Promise<{data: string}>A Promise that resolves to an object containing the trimmed standard output.

Examples

let result = await SF.utils.shellExecLocal('echo Hello World');
// returns: { data: 'Hello World' }

let result = await SF.utils.shellExecLocal('pwd');
// returns: { data: '/home/user/project' }

shellExecRemote

Is a function that executes a shell command on a remote server.

Parameters

NameTypeDescription
cdmstringThe shell command to be executed remotely.
optionsobjectSSH connection options (host, port, username, password/privateKey, etc.).

Returns

TypeDescription
Promise<{data: string, code: number}>A Promise that resolves to an object containing:
data: The standard output result as a string.
code: The exit code of the remote command.

Examples

let result = await SF.utils.shellExecRemote('ls -l', {
host: '192.168.1.10',
port: 22,
username: 'user',
password: 'password'
});
// returns: { data: 'list of files and folders...', code: 0 }

axios

Axios is a Promise based HTTP client for the browser and node.js Lean more See the official documentation

Examples

let id = SF.utils.axios.get('/data/json/123')
.then(function (response) {
// handle success
console.log(response);
}).catch(function (error) {
// handle error
console.log(error);
});

2 - Collection


insertMany

Allow to insert an array of json in to a collection

Parameters

NameTypeDescription
collectionstringCollection name in SoftyFlow.
dataarrayArray of data to be inserted into the collection.

Returns

TypeDescription
PromiseA Promise indicating the result of the insert operation.

Examples

await SF.collection.insertMany("cost-centers",[{label : "IT", value : "it"}])

insertOne

Allow to insert a json in to a collection

Parameters

NameTypeDescription
collectionstringCollection name in SoftyFlow.
dataobjectJSON object representing a single value to be inserted into the collection.

Returns

TypeDescription
PromiseA Promise indicating the result of the insert operation.

Examples

await SF.collection.insertOne("cost-centers",{label : "IT", value : "it"})

findOne

Returns one document that satisfies the specified query criteria . If multiple documents satisfy the query, this method returns the first document.

Parameters

NameTypeDescription
collectionstringCollection name in Softyflow.
queryobjectJSON object of values to be matched in the collection.

Returns

TypeDescription
PromiseReturn promise

Examples

await SF.collection.findOne("cost-centers",{value : "it"})

find

Returns all the documents that satisfies the specified query criteria .

Parameters

NameTypeDescription
collectionstringCollection name in SoftyFlow.
queryobjectJSON object representing the criteria to match documents in the collection.

Returns

TypeDescription
PromiseA Promise indicating the result of the find operation.

Examples

await SF.collection.find("cost-centers",{value : "it"})

updateOne

update the first document that satisfies the specified query criteria .

Parameters

NameTypeDescription
collectionstringCollection name in SoftyFlow.
queryobjectJSON object representing the criteria to match documents in the collection.
bodyobjectJSON object representing the fields and values to update.

Returns

TypeDescription
PromiseA Promise indicating the result of the update operation.

Examples

await SF.collection.updateOne("cost-centers",{value : "it"})

update

update all the documents that satisfies the specified query criteria .

Parameters

NameTypeDescription
collectionstringCollection name in SoftyFlow.
queryobjectJSON object representing the value to match in the collection.
bodyobjectJSON object representing the value to update in the collection.

Returns

TypeDescription
PromiseReturns a promise.

Examples

await SF.collection.update("cost-centers",{value : "it"})

count

Returns the count of documents in the collection.

Parameters

NameTypeDescription
collectionstringCollection name in SoftyFlow.

Returns

TypeDescription
PromiseReturns a promise.

Examples

await SF.collection.count("cost-centers")

deleteOne

Allow to delete a document from collection.

Parameters

NameTypeDescription
collectionstringCollection name in SoftyFlow.
queryobjectJSON object representing the value to match in the collection.

Returns

TypeDescription
PromiseReturns a promise.

Examples

await SF.collection.deleteOne("cost-centers")

delete

Allow to delete multiple documents from collection.

Parameters

NameTypeDescription
collectionstringCollection name in SoftyFlow.
queryobjectJSON object representing the value to match in the collection.

Returns

TypeDescription
PromiseReturns a promise.

Examples

await SF.collection.delete("cost-centers")

aggregate

Aggregation operations process data records and return computed results

Parameters

NameTypeDescription
collectionstringCollection name in SoftyFlow.
aggregationarrayAggregation array.

Returns

TypeDescription
PromiseReturns a promise.

Examples

let aggregation = [
{
"$match": { "type": "type1" }
},
{
"$project" : {
"_id": 1,
"name": 1
}
}
]
await SF.collection.aggregate("cost-centers",[aggregation]);

cleanCollection

Remove All Documents from a Collection.

Parameters

NameTypeDescription
collectionstringCollection name in SoftyFlow.

Returns

TypeDescription
PromiseReturns a promise.

Examples

await SF.collection.cleanCollection("cost-centers")

bulkWrite

Is a function that performs multiple write operations (insert, update, delete) in a single batch on a specified MongoDB collection.

Parameters

NameTypeDescription
colstringThe name of the collection (without suffix).
bulkOpsArrayAn array of bulk write operations (insertOne, updateOne, deleteOne, etc.).

Returns

TypeDescription
PromiseReturns a Promise that resolves once all bulk operations are complete.

Examples

let bulkOps = [
{ insertOne: { document: { name: 'John', age: 30 } } },
{ updateOne: { filter: { name: 'John' }, update: { $set: { age: 31 } } } },
{ deleteOne: { filter: { name: 'John' } } }
];

await SF.utils.bulkWrite('users', bulkOps);
// returns: Promise resolved when all operations are completed

3 - Users


getUsersinGroup

Get all users in a given group

Parameters

NameTypeDescription
groupstringGroup ID.

Returns

TypeDescription
PromiseReturns a promise.

Examples

await SF.user.getUsersinGroup("6042551d231e8c8ade19bc09")

getUsersInGroupList

get the users who exist in certain groups.

Parameters

NameTypeDescription
groupsstring[]Array of groupID.

Returns

TypeDescription
PromiseReturn promise

Examples

await SF.user.getUsersInGroupList(["6042551d231e8c8ade19bc09","6040e3679c81cf1b60b698f4"])

getGroupById

Is a function that retrieves a group document from the "groups" collection by its unique ID.

Parameters

NameTypeDescription
idstringThe ID of the group to be retrieved.

Returns

TypeDescription
`Promise<objectnull>`

Examples

let group = await SF.utils.getGroupById("60c72b2f9f1b2c3c8f3b8b0b");
// returns: { _id: ObjectId("60c72b2f9f1b2c3c8f3b8b0b"), name: 'Admin', members: [...] }

let group = await SF.utils.getGroupById("60c72b2f9f1b2c3c8f3b8b0c");
// returns: null (if group with this ID doesn't exist)

getUserById

Get user information using his id.

Parameters

NameTypeDescription
idstringUser ID.

Returns

TypeDescription
PromiseReturn promise

Examples

await SF.user.getUserById("6042551d231e8c8ade19bc09")

getUserByMail

Get user information using his email.

Parameters

NameTypeDescription
emailstringUser email.

Returns

TypeDescription
PromiseReturn promise

Examples

await SF.user.getUserByMail("test@softydev.com")

updateUserById

Update user information using his ID.

Parameters

NameTypeDescription
idstringUser ID.
dataobjectJSON object of values to update.

Returns

TypeDescription
PromiseReturn promise

Examples

await SF.user.updateUserById("6042551d231e8c8ade19bc09",{firstName : "test"})

updateUsersEach

Update a list of users individualy : to each user their own payload.

Parameters

NameTypeDescription
ArrayArrayArray of objects, each containing a user ID and a payload.

Returns

TypeDescription
PromiseReturn promise

Examples

await SF.user.updateUsersEach([{ _id: "6042551d231e8c8ade19bc09", payload: { firstName: 'firstUser' } }, { _id: "6042551d231e8c8ade19bc10", payload: { firstName: 'secondUser' } }])

updateUserMetadataById

Update user metadata using his ID.

Parameters

NameTypeDescription
idstringUser ID.
fieldobjectJSON object of metadata to update.
valueobjectJSON object of values to be updated.

Returns

TypeDescription
PromiseReturn promise

Examples

await SF.user.updateUserMetadataById("6042551d231e8c8ade19bc09", "Manager",  "test")

getUsers

Get users informations.

Returns

TypeDescription
PromiseReturn promise

Examples

await SF.user.getUsers()

getUserMetadata

Get user metadata using his ID.

Parameters

NameTypeDescription
idstringUser ID.

Returns

TypeDescription
PromiseReturn promise

Examples

await SF.user.getUserMetadata("6042551d231e8c8ade19bc09")

addUserToGroup

Add user to a groupe using user ID & group ID.

Parameters

NameTypeDescription
userIdstringUser ID.
groupidstringGroup ID.

Returns

TypeDescription
PromiseReturn promise

Examples

await SF.user.addUserToGroup("6042551d231e8c8ade19bc09", "62c2b6f74d16c2a2c19dcdb7")

removeUserfromGroup

Remove user from group using user ID & group ID.

Parameters

NameTypeDescription
userIdstringUser ID.
groupidstringGroup ID.

Returns

TypeDescription
PromiseReturn promise

Examples

await SF.user.removeUserfromGroup("6042551d231e8c8ade19bc09", "62c2b6f74d16c2a2c19dcdb7")

createUser

Allow to create new user.

Parameters

NameTypeDescription
dataobjectJSON content user data

Returns

TypeDescription
PromiseReturn promise

Data

This is the allowed user data:

fieldDescription
emailRequired and Unique. The user email (string)
lastNameRequired. The user last name (string)
firstNameRequired. The user first name (string)
groupRequired. The user groups ids (array)
metadataoptional. The user metadata (json)
ideAccessRequired. IDE access right (boolean)
blockedoptional. User blocking (boolean)

Examples

let user = {
email: "email@softydev.com",
lastName : "last name",
firstName: "first name",
group: [],
metadata: {},
ideAccess: true,
blocked: false
}
await SF.users.createUser(user);

4 - Files


The File class manages files stored in MongoDB's GridFS system, providing methods to upload, retrieve, delete, and generate PDFs from EJS templates.

Usage

const file = new File(gridfsBucket);

getFileContentById

Retrieve the text content of a file by its ID.

Parameters

NameTypeDescription
idstringFile ObjectId
encodingstringEncoding to use (default: 'utf8')

Returns

TypeDescription
Promise<object>File metadata with content field

Example

let result = await file.getFileContentById("64bfa28cfabc123...", "utf8");
console.log(result.content);

getFileBufferById

Retrieve the binary content of a file as a Buffer.

Parameters

NameTypeDescription
idstringFile ObjectId

Returns

TypeDescription
Promise<Buffer>File data as Buffer

Example

let buffer = await file.getFileBufferById("64bfa28cfabc123...");

generatePDFFromTemplate

Generate a PDF from a stored EJS template file and save it back to GridFS.

Parameters

NameTypeDescription
dump_varanyNot used
fidstringTemplate file ID
contextobjectPDF generation context

Returns

TypeDescription
Promise<object>Metadata of saved PDF file
  • context.variables: Variables injected into the template.
  • context.SF_pdfName: Optional name for the generated PDF.

Example

await file.generatePDFFromTemplate(null, 'templateId', {
variables: { name: "John" },
SF_pdfName: "user-report.pdf"
});

createFileFromBuffer

Create and upload a file from a Buffer.

Parameters

NameTypeDescription
fileMetadataobjectMetadata (filename, contentType, etc.)
bufferContentBufferBinary content of the file

Returns

TypeDescription
Promise<object>Metadata of saved file

Example

await file.createFileFromBuffer({ filename: "doc.txt", contentType: "text/plain" }, Buffer.from("Hello"));

deleteFileById

Is a function that deletes a file from the database by its unique ID.

Parameters

NameTypeDescription
idstringThe ID of the file to be deleted.

Returns

TypeDescription
Promise<object>Resolves to an object indicating deletion status: { deleted: 1 } if successful, { deleted: 0 } if failed.

Examples

let result = await SF.utils.deleteFileById("60c72b2f9f1b2c3c8f3b8b0b");
// returns: { deleted: 1 } (if file was deleted)

let result = await SF.utils.deleteFileById("60c72b2f9f1b2c3c8f3b8b0c");
// returns: { deleted: 0 } (if there was an error or file not found)

5 - Sql


insertOne

Insert a row into your SQL Table

Parameters

NameTypeDescription
idstringDatabase ID.
dataobjectData to insert into database.

Returns

TypeDescription
objectReturn object

Examples

await SF.sql.insertOne("610c0343f6ebc7ddcb49cc3b", "client", {
code: 'MMA',
codepostal: 225
})

insertMany

Insert an array of rows into your SQL Table

Parameters

NameTypeDescription
idstringDatabase ID.
dataarrayData to insert into database.

Returns

TypeDescription
objectReturn object

Examples

await SF.sql.insertMany("610c0343f6ebc7ddcb49cc3b", "client", [{
code: 'MMA',
codepostal: 225
}])

findOne

Find data in your SQL table.

Parameters

NameTypeDescription
idstringDatabase ID.
namestringTable name.
datastringCriteria to query database.

Returns

TypeDescription
objectReturn object

Examples

await SF.sql.findOne("610c0343f6ebc7ddcb49cc3b", "client", "code='MGMT'")

find

Find all rows in your SQL table that match a certain criteria.

Parameters

NameTypeDescription
idstringDatabase ID.
namestringTable name.
datastringCriteria to query database.

Returns

TypeDescription
objectReturn object

Examples

await SF.sql.find("610c0343f6ebc7ddcb49cc3b", "client", "code='MGMT'")

update

Update data in your database.

Parameters

NameTypeDescription
idstringDatabase ID.
namestringTable name.
datastringCriteria to query database.
newDataobjectUpdated data.

Returns

TypeDescription
objectReturn object

Examples

await SF.sql.update("610c0343f6ebc7ddcb49cc3b", "client", "code='MDMS'", {
code: 'CLEA'
})

delete

Delete rows from your database.

Parameters

NameTypeDescription
idstringDatabase ID.
namestringTable name.
datastringCriteria to query database.

Returns

TypeDescription
objectReturn object

Examples

 await SF.sql.delete("610c0343f6ebc7ddcb49cc3b", "client", "code='CLEA'")

count

count rows in your database.

Parameters

NameTypeDescription
idstringDatabase ID.
namestringTable name.
datastringCriteria to query database.

Returns

TypeDescription
objectReturn object

Examples

 await SF.sql.count("610c0343f6ebc7ddcb49cc3b", "client", "code='CLEA'")

execute

Execute custom/complex statements on your database.

Parameters

NameTypeDescription
idstringDatabase ID.
querystringSQL statement.

Returns

TypeDescription
objectReturn object

Examples

await SF.sql.execute('610c0343f6ebc7ddcb49cc3b', "DELETE FROM client WHERE code='KL'")

6 - Instance


launchProcess

Initiate an existing process.

Parameters

NameTypeDescription
processIdstringProcess ID.

Returns

TypeDescription
objectReturn object

Examples

await SF.instance.launchProcess('610c0343f6ebc7ddcb49cc3b')

pendingTask

Get Instance latest Pending Task

Parameters

NameTypeDescription
instanceIdstringInstance ID.

Returns

TypeDescription
objectReturn object

Examples

await SF.instance.pendingTask('610c0343f6ebc7ddcb49cc3b')

getMeasures

Get Instance Measures

Parameters

NameTypeDescription
instanceIdstringInstance ID.

Returns

TypeDescription
objectReturn object

Examples

await SF.instance.getMeasures('610c0343f6ebc7ddcb49cc3b')

validateTask

Validate Task.

Parameters

NameTypeDescription
taskIdstringTask ID.
variablesobjectJSON of variables.

Returns

TypeDescription
objectReturn object

Examples

let variables = {
"variable1": "value1",
"variable2": 1,
"variable3": true
}
await SF.instance.validateTask('610c0343f6ebc7ddcb49cc3b',variables)

updateVariablesById

Update variables using instance ID.

Parameters

NameTypeDescription
IdstringInstance ID.
dataobjectJSON of variables data.

Returns

TypeDescription
objectReturn object

Examples

let data = {
"variable1": "value1",
"variable2": 1,
"variable3": true
}
await SF.instance.updateVariablesById('610c0343f6ebc7ddcb49cc3b',data)

attachChildInstance

Is a function that links a child instance to a father instance in the "instances" collection, based on a specific activity step.

Parameters

NameTypeDescription
fatherIdstringThe ID of the father instance.
childIdstringThe ID of the child instance to be attached.
stepIdstringThe step ID representing the activity in the father instance.

Returns

TypeDescription
Promise<object>Resolves to { done: true } if the attachment is successful.

Examples

let result = await SF.utils.attachChildInstance(
"661e9d8a1a2b2f7f8d3c4e1f",
"661e9d9b2b5e2f8f8d3c5f0a",
"step123"
);
// returns: { done: true }

getVariablesById

Is a function that retrieves an instance document by its ID, with an optional projection to select specific fields.

Parameters

NameTypeDescription
instanceIdstringThe ID of the instance to retrieve.
projectionobject(Optional) MongoDB projection to specify which fields to return.

Returns

TypeDescription
Promise<object \| null>Resolves to the instance document if found, or null if not found.

Examples

let instance = await SF.utils.getVariablesById("661e9d8a1a2b2f7f8d3c4e1f");
// returns: Full instance document

let instance = await SF.utils.getVariablesById("661e9d8a1a2b2f7f8d3c4e1f", { variables: 1 });
// returns: { variables: {...} }

deleteInstanceById

Is a function that deletes an instance by its ID, and also removes all related histories and tasks associated with that instance.

Parameters

NameTypeDescription
idstringThe ID of the instance to be deleted.

Returns

TypeDescription
Promise<object>Resolves to the result of the instance deletion operation.

Examples

let result = await SF.utils.deleteInstanceById("661e9d8a1a2b2f7f8d3c4e1f");
// returns: { acknowledged: true, deletedCount: 1 }

deleteManyInstances

Is a function that deletes multiple instances associated with a given process ID and an additional query.

Parameters

NameTypeDescription
processIdstringThe ID of the process whose instances should be deleted.
queryobjectAdditional query parameters to filter which instances to delete.

Returns

TypeDescription
Promise<object>Resolves to the result of the deleteMany operation.

Examples

let result = await SF.utils.deleteManyInstances("661e9d8a1a2b2f7f8d3c4e1f", { status: "completed" });
// returns: { acknowledged: true, deletedCount: 5 }

updateInstanceVariables

Is a function that updates the variables of an instance, recalculates related measures based on the process definition, and updates them both in the instance and the last related task.

Parameters

NameTypeDescription
idstringThe ID of the instance to update.
dataobjectKey-value pairs of variables to update inside the instance.

Returns

TypeDescription
Promise<object>Resolves to { done: true } if the update succeeds.

Examples

let result = await SF.utils.updateInstanceVariables("661e9d8a1a2b2f7f8d3c4e1f", {
amount: 1500,
dueDate: "2025-05-30"
});
// returns: { done: true }