Skip to main content

3.11. Server Scripts

Server scripts are a mechanism for executing custom JS code on the server. Typically, they contain business logic that does not depend on the current model version and does not require creating separate UB domain models.

Since scripts are executed on the server, they can be used to implement many different scenarios:

  • custom business logic, such as validations or aggregations;
  • database operations, such as querying/inserting/updating/deleting data;
  • file operations;
  • external API calls;
  • email sending;
  • and more.

Each form script must be a CommonJS module, meaning it must export an object or function and can require other modules.

Server scripts can use the entire server-side API of the UB platform.

3.11.1. Server Module Library​

A server module is a function or group of functions created as a separate record that can be reused in other server scripts or modules. Server modules can be exported to other environments using configuration packages, making it easy to share implemented business logic.

To create a group of performers, in the navigation pane, open the Studio workspace, then open Server Module Library, and click Add.

3.11.1.1. Server Modules​

Fill in the fields described in the table below, then click Save or Save and Close.

3.11.1.2. Create a Server Module​

Field NameDescription
Code*Unique module code. Used to call the module from other server scripts.
Name*Server module name. Different values can be configured for different locales
DescriptionServer module description
Script*JavaScript code of the server module
Note:

Fields marked with the "*" symbol are required.

After saving the server module, the Script to Include This Module field is displayed. It contains the code that should be used to call this module from other server scripts or modules. To copy the code, click the corresponding button.

In the server module dictionary, users with the Admin role can perform standard grid actions (Sorting, Filtering, Adding, Deleting).

You cannot delete a server module if it is used in server scripts or other server modules.

Script examples are provided in Appendix 2 of the guide.

3.11.2. "Script" Handler​

Using the Script handler in document type events, you can execute server scripts. Scripts can be added directly to the handler, and you can also call scripts from the server module library.

When creating a Script handler, the code required to execute the module is added automatically.

3.11.2.1. Script Handler​

The server script receives an event object depending on the context. For example, if the script is executed from a document, the following event parameters are available:

{"event":"actionExec_new_s3","eventType":"actionExec","docID":3000006583316,"docTypeID":3000005759706,"stateID":3000002278725,"stateCode":"new","actionCode":"s3","actionID":3000005892174,"store":{}}

For example, to get the current document number in the script, you can use the event.docID value.

If the script is executed on a process completion event, the following event parameters are available:

{"eventType":"processComplete","event":"processComplete_main","docID":3000006583316,"docTypeID":3000005759706,"processInstanceID":3000006583721,"processCode":"main"}

For example, to get the process ID, you can use the event.processInstanceID value.

To use scripts from the server module library in the Script handler, add a module reference using the following format:

const myModule = require('#LDOC3326_01')

Where:

  • myModule — the module name used in the script code
  • LDOC3326_01 — the server module code from the library

To call a function from the server module, use the following code:

myModule.clear(event.docID, event)

Where:

  • myModule — the module name
  • clear — the function name
  • event.docID, event — parameters passed to the function

Script examples are provided in Appendix 2 of the guide.

3.11.2.2. Example of Calling a Server Module in a Script Handler​

3.11.3. Call a Server Script from a Business Process​

The system allows calling a script from the server module library in a business process using a service task. If the script in the server module is updated, the changes are applied immediately after saving, without requiring changes to the business process.

Example of calling a script from the server module library without calling a function:

JSON.stringify({
  entity: 'bpm_ExtTaskService',
  method: 'callServerModule',
  execParams: {
    code: 'deleteDocumentLink', // server module code
    params: {
      docID: $ID
    }
  }
})

3.12.3.1. Example of Calling a Script from the Server Module Library Without Calling a Function​

Example of calling a script from the server module library with a function call:

JSON.stringify({
  entity: 'bpm_ExtTaskService',
  method: 'callServerModule',
  execParams: {
    code: 'documentUtils', // server module code
    method: 'deleteDocumentLinks', // function name from the server module
    params: {
      docID: $ID
    }
  }
})

3.11.3.2. Server Module Without a Function Called from a Business Process​

Example of calling a script from the server module library with a function call:

3.11.3.3. Example of Calling a Script from the Server Module Library with a Function Call​

3.11.4. In a Document Template​

A server script in a document template is executed when the document is generated and allows performing any operations with attributes, such as generating the current document generation date and time, replacing attribute values, generating indexes (sequential numbers) for tables, and more.

To create a server script in a document template, open the Studio workspace, then open the Document Type Settings folder and the Document Templates shortcut. Open the required document template, and then click Enable Server Logic.

A Server Logic tab will be added to the template, containing example scripts.

Example of a script for generating a table index:

module.exports = {
  transformTemplateData({dataEntityName, dataID, templateData}) {
    // ms16 - table attribute code
    templateData['attrValues.ms16'].forEach(function(item, index) {
      item.index = index;
      item['attrValues.index'] = index + 1;
    })
  }
}

In document template server scripts, you can use scripts from the server module library by adding the appropriate require reference.

Script examples are provided in Appendix 2 of the guide.

3.11.5. In an IDP Template (available when the dfx-idp package is installed)​

A server script in an IDP template is executed when recognition results are saved and allows performing any operations with attributes.

To create a server script in an IDP template, open the Studio workspace, then open the Document Type Settings folder and the IDP Templates shortcut. Open the required IDP template, and then click Enable Server Logic.

In IDP template server scripts, you can use scripts from the server module library by adding the appropriate require reference.

A Server Logic tab will be added to the template, containing example scripts.

Script examples are provided in Appendix 2 of the guide.