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,
};
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
Name | Type | Description |
---|
name | string | A unique name used as the key to generate the ID. |
padding | number | (Optional) The number of digits to pad the result with (e.g., 6 → 000001). |
Returns
Type | Description |
---|
Promise | A Promise that resolves to the generated ID. |
Examples
let id = await SF.utils.nextValue("leave_request");
let id = await SF.utils.nextValue("leave_request",5);
shellExecLocal
Is a function that executes a local shell command and returns the trimmed output.
Parameters
Name | Type | Description |
---|
cmd | string | The shell command to be executed. |
Returns
Type | Description |
---|
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');
let result = await SF.utils.shellExecLocal('pwd');
shellExecRemote
Is a function that executes a shell command on a remote server.
Parameters
Name | Type | Description |
---|
cdm | string | The shell command to be executed remotely. |
options | object | SSH connection options (host, port, username, password/privateKey, etc.). |
Returns
Type | Description |
---|
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'
});
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) {
console.log(response);
}).catch(function (error) {
console.log(error);
});
2 - Collection
insertMany
Allow to insert an array of json in to a collection
Parameters
Name | Type | Description |
---|
collection | string | Collection name in SoftyFlow. |
data | array | Array of data to be inserted into the collection. |
Returns
Type | Description |
---|
Promise | A 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
Name | Type | Description |
---|
collection | string | Collection name in SoftyFlow. |
data | object | JSON object representing a single value to be inserted into the collection. |
Returns
Type | Description |
---|
Promise | A 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
Name | Type | Description |
---|
collection | string | Collection name in Softyflow. |
query | object | JSON object of values to be matched in the collection. |
Returns
Type | Description |
---|
Promise | Return promise |
Examples
await SF.collection.findOne("cost-centers",{value : "it"})
find
Returns all the documents that satisfies the specified query criteria .
Parameters
Name | Type | Description |
---|
collection | string | Collection name in SoftyFlow. |
query | object | JSON object representing the criteria to match documents in the collection. |
Returns
Type | Description |
---|
Promise | A 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
Name | Type | Description |
---|
collection | string | Collection name in SoftyFlow. |
query | object | JSON object representing the criteria to match documents in the collection. |
body | object | JSON object representing the fields and values to update. |
Returns
Type | Description |
---|
Promise | A 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
Name | Type | Description |
---|
collection | string | Collection name in SoftyFlow. |
query | object | JSON object representing the value to match in the collection. |
body | object | JSON object representing the value to update in the collection. |
Returns
Type | Description |
---|
Promise | Returns a promise. |
Examples
await SF.collection.update("cost-centers",{value : "it"})
count
Returns the count of documents in the collection.
Parameters
Name | Type | Description |
---|
collection | string | Collection name in SoftyFlow. |
Returns
Type | Description |
---|
Promise | Returns a promise. |
Examples
await SF.collection.count("cost-centers")
deleteOne
Allow to delete a document from collection.
Parameters
Name | Type | Description |
---|
collection | string | Collection name in SoftyFlow. |
query | object | JSON object representing the value to match in the collection. |
Returns
Type | Description |
---|
Promise | Returns a promise. |
Examples
await SF.collection.deleteOne("cost-centers")
delete
Allow to delete multiple documents from collection.
Parameters
Name | Type | Description |
---|
collection | string | Collection name in SoftyFlow. |
query | object | JSON object representing the value to match in the collection. |
Returns
Type | Description |
---|
Promise | Returns a promise. |
Examples
await SF.collection.delete("cost-centers")
aggregate
Aggregation operations process data records and return computed results
Parameters
Name | Type | Description |
---|
collection | string | Collection name in SoftyFlow. |
aggregation | array | Aggregation array. |
Returns
Type | Description |
---|
Promise | Returns 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
Name | Type | Description |
---|
collection | string | Collection name in SoftyFlow. |
Returns
Type | Description |
---|
Promise | Returns 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
Name | Type | Description |
---|
col | string | The name of the collection (without suffix). |
bulkOps | Array | An array of bulk write operations (insertOne , updateOne , deleteOne , etc.). |
Returns
Type | Description |
---|
Promise | Returns 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);
3 - Users
getUsersinGroup
Get all users in a given group
Parameters
Name | Type | Description |
---|
group | string | Group ID. |
Returns
Type | Description |
---|
Promise | Returns a promise. |
Examples
await SF.user.getUsersinGroup("6042551d231e8c8ade19bc09")
getUsersInGroupList
get the users who exist in certain groups.
Parameters
Name | Type | Description |
---|
groups | string[] | Array of groupID. |
Returns
Type | Description |
---|
Promise | Return 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
Name | Type | Description |
---|
id | string | The ID of the group to be retrieved. |
Returns
Type | Description |
---|
`Promise<object | null>` |
Examples
let group = await SF.utils.getGroupById("60c72b2f9f1b2c3c8f3b8b0b");
let group = await SF.utils.getGroupById("60c72b2f9f1b2c3c8f3b8b0c");
getUserById
Get user information using his id.
Parameters
Name | Type | Description |
---|
id | string | User ID. |
Returns
Type | Description |
---|
Promise | Return promise |
Examples
await SF.user.getUserById("6042551d231e8c8ade19bc09")
getUserByMail
Get user information using his email.
Parameters
Name | Type | Description |
---|
email | string | User email. |
Returns
Type | Description |
---|
Promise | Return promise |
Examples
await SF.user.getUserByMail("test@softydev.com")
updateUserById
Update user information using his ID.
Parameters
Name | Type | Description |
---|
id | string | User ID. |
data | object | JSON object of values to update. |
Returns
Type | Description |
---|
Promise | Return promise |
Examples
await SF.user.updateUserById("6042551d231e8c8ade19bc09",{firstName : "test"})
updateUsersEach
Update a list of users individualy : to each user their own payload.
Parameters
Name | Type | Description |
---|
Array | Array | Array of objects, each containing a user ID and a payload. |
Returns
Type | Description |
---|
Promise | Return promise |
Examples
await SF.user.updateUsersEach([{ _id: "6042551d231e8c8ade19bc09", payload: { firstName: 'firstUser' } }, { _id: "6042551d231e8c8ade19bc10", payload: { firstName: 'secondUser' } }])
Update user metadata using his ID.
Parameters
Name | Type | Description |
---|
id | string | User ID. |
field | object | JSON object of metadata to update. |
value | object | JSON object of values to be updated. |
Returns
Type | Description |
---|
Promise | Return promise |
Examples
await SF.user.updateUserMetadataById("6042551d231e8c8ade19bc09", "Manager", "test")
getUsers
Get users informations.
Returns
Type | Description |
---|
Promise | Return promise |
Examples
Get user metadata using his ID.
Parameters
Name | Type | Description |
---|
id | string | User ID. |
Returns
Type | Description |
---|
Promise | Return promise |
Examples
await SF.user.getUserMetadata("6042551d231e8c8ade19bc09")
addUserToGroup
Add user to a groupe using user ID & group ID.
Parameters
Name | Type | Description |
---|
userId | string | User ID. |
groupid | string | Group ID. |
Returns
Type | Description |
---|
Promise | Return promise |
Examples
await SF.user.addUserToGroup("6042551d231e8c8ade19bc09", "62c2b6f74d16c2a2c19dcdb7")
removeUserfromGroup
Remove user from group using user ID & group ID.
Parameters
Name | Type | Description |
---|
userId | string | User ID. |
groupid | string | Group ID. |
Returns
Type | Description |
---|
Promise | Return promise |
Examples
await SF.user.removeUserfromGroup("6042551d231e8c8ade19bc09", "62c2b6f74d16c2a2c19dcdb7")
createUser
Allow to create new user.
Parameters
Name | Type | Description |
---|
data | object | JSON content user data |
Returns
Type | Description |
---|
Promise | Return promise |
Data
This is the allowed user data:
field | Description |
---|
email | Required and Unique. The user email (string) |
lastName | Required. The user last name (string) |
firstName | Required. The user first name (string) |
group | Required. The user groups ids (array) |
metadata | optional. The user metadata (json) |
ideAccess | Required. IDE access right (boolean) |
blocked | optional. 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
Name | Type | Description |
---|
id | string | File ObjectId |
encoding | string | Encoding to use (default: 'utf8' ) |
Returns
Type | Description |
---|
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
Name | Type | Description |
---|
id | string | File ObjectId |
Returns
Type | Description |
---|
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
Name | Type | Description |
---|
dump_var | any | Not used |
fid | string | Template file ID |
context | object | PDF generation context |
Returns
Type | Description |
---|
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
Name | Type | Description |
---|
fileMetadata | object | Metadata (filename, contentType, etc.) |
bufferContent | Buffer | Binary content of the file |
Returns
Type | Description |
---|
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
Name | Type | Description |
---|
id | string | The ID of the file to be deleted. |
Returns
Type | Description |
---|
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");
let result = await SF.utils.deleteFileById("60c72b2f9f1b2c3c8f3b8b0c");
5 - Sql
insertOne
Insert a row into your SQL Table
Parameters
Name | Type | Description |
---|
id | string | Database ID. |
data | object | Data to insert into database. |
Returns
Type | Description |
---|
object | Return object |
Examples
await SF.sql.insertOne("610c0343f6ebc7ddcb49cc3b", "client", {
code: 'MMA',
codepostal: 225
})
insertMany
Insert an array of rows into your SQL Table
Parameters
Name | Type | Description |
---|
id | string | Database ID. |
data | array | Data to insert into database. |
Returns
Type | Description |
---|
object | Return object |
Examples
await SF.sql.insertMany("610c0343f6ebc7ddcb49cc3b", "client", [{
code: 'MMA',
codepostal: 225
}])
findOne
Find data in your SQL table.
Parameters
Name | Type | Description |
---|
id | string | Database ID. |
name | string | Table name. |
data | string | Criteria to query database. |
Returns
Type | Description |
---|
object | Return object |
Examples
await SF.sql.findOne("610c0343f6ebc7ddcb49cc3b", "client", "code='MGMT'")
find
Find all rows in your SQL table that match a certain criteria.
Parameters
Name | Type | Description |
---|
id | string | Database ID. |
name | string | Table name. |
data | string | Criteria to query database. |
Returns
Type | Description |
---|
object | Return object |
Examples
await SF.sql.find("610c0343f6ebc7ddcb49cc3b", "client", "code='MGMT'")
update
Update data in your database.
Parameters
Name | Type | Description |
---|
id | string | Database ID. |
name | string | Table name. |
data | string | Criteria to query database. |
newData | object | Updated data. |
Returns
Type | Description |
---|
object | Return object |
Examples
await SF.sql.update("610c0343f6ebc7ddcb49cc3b", "client", "code='MDMS'", {
code: 'CLEA'
})
delete
Delete rows from your database.
Parameters
Name | Type | Description |
---|
id | string | Database ID. |
name | string | Table name. |
data | string | Criteria to query database. |
Returns
Type | Description |
---|
object | Return object |
Examples
await SF.sql.delete("610c0343f6ebc7ddcb49cc3b", "client", "code='CLEA'")
count
count rows in your database.
Parameters
Name | Type | Description |
---|
id | string | Database ID. |
name | string | Table name. |
data | string | Criteria to query database. |
Returns
Type | Description |
---|
object | Return object |
Examples
await SF.sql.count("610c0343f6ebc7ddcb49cc3b", "client", "code='CLEA'")
execute
Execute custom/complex statements on your database.
Parameters
Name | Type | Description |
---|
id | string | Database ID. |
query | string | SQL statement. |
Returns
Type | Description |
---|
object | Return object |
Examples
await SF.sql.execute('610c0343f6ebc7ddcb49cc3b', "DELETE FROM client WHERE code='KL'")
6 - Instance
launchProcess
Initiate an existing process.
Parameters
Name | Type | Description |
---|
processId | string | Process ID. |
Returns
Type | Description |
---|
object | Return object |
Examples
await SF.instance.launchProcess('610c0343f6ebc7ddcb49cc3b')
pendingTask
Get Instance latest Pending Task
Parameters
Name | Type | Description |
---|
instanceId | string | Instance ID. |
Returns
Type | Description |
---|
object | Return object |
Examples
await SF.instance.pendingTask('610c0343f6ebc7ddcb49cc3b')
getMeasures
Get Instance Measures
Parameters
Name | Type | Description |
---|
instanceId | string | Instance ID. |
Returns
Type | Description |
---|
object | Return object |
Examples
await SF.instance.getMeasures('610c0343f6ebc7ddcb49cc3b')
validateTask
Validate Task.
Parameters
Name | Type | Description |
---|
taskId | string | Task ID. |
variables | object | JSON of variables. |
Returns
Type | Description |
---|
object | Return object |
Examples
let variables = {
"variable1": "value1",
"variable2": 1,
"variable3": true
}
await SF.instance.validateTask('610c0343f6ebc7ddcb49cc3b',variables)
updateVariablesById
Update variables using instance ID.
Parameters
Name | Type | Description |
---|
Id | string | Instance ID. |
data | object | JSON of variables data. |
Returns
Type | Description |
---|
object | Return 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
Name | Type | Description |
---|
fatherId | string | The ID of the father instance. |
childId | string | The ID of the child instance to be attached. |
stepId | string | The step ID representing the activity in the father instance. |
Returns
Type | Description |
---|
Promise<object> | Resolves to { done: true } if the attachment is successful. |
Examples
let result = await SF.utils.attachChildInstance(
"661e9d8a1a2b2f7f8d3c4e1f",
"661e9d9b2b5e2f8f8d3c5f0a",
"step123"
);
getVariablesById
Is a function that retrieves an instance document by its ID, with an optional projection to select specific fields.
Parameters
Name | Type | Description |
---|
instanceId | string | The ID of the instance to retrieve. |
projection | object | (Optional) MongoDB projection to specify which fields to return. |
Returns
Type | Description |
---|
Promise<object \| null> | Resolves to the instance document if found, or null if not found. |
Examples
let instance = await SF.utils.getVariablesById("661e9d8a1a2b2f7f8d3c4e1f");
let instance = await SF.utils.getVariablesById("661e9d8a1a2b2f7f8d3c4e1f", { variables: 1 });
deleteInstanceById
Is a function that deletes an instance by its ID, and also removes all related histories and tasks associated with that instance.
Parameters
Name | Type | Description |
---|
id | string | The ID of the instance to be deleted. |
Returns
Type | Description |
---|
Promise<object> | Resolves to the result of the instance deletion operation. |
Examples
let result = await SF.utils.deleteInstanceById("661e9d8a1a2b2f7f8d3c4e1f");
deleteManyInstances
Is a function that deletes multiple instances associated with a given process ID and an additional query.
Parameters
Name | Type | Description |
---|
processId | string | The ID of the process whose instances should be deleted. |
query | object | Additional query parameters to filter which instances to delete. |
Returns
Type | Description |
---|
Promise<object> | Resolves to the result of the deleteMany operation. |
Examples
let result = await SF.utils.deleteManyInstances("661e9d8a1a2b2f7f8d3c4e1f", { status: "completed" });
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
Name | Type | Description |
---|
id | string | The ID of the instance to update. |
data | object | Key-value pairs of variables to update inside the instance. |
Returns
Type | Description |
---|
Promise<object> | Resolves to { done: true } if the update succeeds. |
Examples
let result = await SF.utils.updateInstanceVariables("661e9d8a1a2b2f7f8d3c4e1f", {
amount: 1500,
dueDate: "2025-05-30"
});