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);
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"
});