Managing files using variables
This feature is available from version 3.0 of the system and is exclusive to customers using the SoftExpert Suite cloud platform.
Prerequisites
- Access to the Process (PM063) menu.
- Previously created and modeled BPMN process.
- Process containing at least one user activity with an associated form and a system activity in its flowchart.
- Template in .docx format, containing variables in the {d.object.name} pattern.
- Access the SoftExpert Workflow > Configuration > General parameters (WF019) menu.
Introduction
Managing files through variables is a feature that allows the user to configure the automatic generation of documents from templates (.docx) that use variables from a process and from its associated form.
Variables work as reserved spaces replaced automatically by the system,thus preventing typing errors and ensuring consistency in documents.
The objective is to automate the creation, signing, and storage of customized files, reducing manual errors and increasing the productivity of the flow.
See how to use variables in contract templates:
Identifying available variables and inserting templates
To identify which variables are available for use and insert a template into a system activity, follow the steps below:
1. Access the Process (PM063) menu.
2. Locate the desired process and right-click on it.
3. Select the Open flowchart option.
4. In the flowchart, select the desired system activity and click on the Data toolbar option.
5. In the general data, expand the Integrations field and select the Generate electronic file with variables option.
6. Click on the Configure electronic file with variables option.
7. Click on the View available variables in the process field. At this point, a table will be presented with all the variables available for the process, such as form variables and workflow variables (instance data).
These variables are automatically detected based on properties configured in the process and linked form. See more details on using variables in the topic below.
8. After viewing the variables, click on the Add electronic file button to upload the template in .docx format that contains the variables in the {d.object.name} format.
9. Click on the Finish button. After the upload, the system will check for errors in the variables of the document that do not meet the standard required for the purpose.
10. If non-standard variables were identified, they will be presented as an error. In this case, use the Actions column to correct the variables directly on the screen, or edit the template and upload it again.
11. Click on the Next step button and perform the other necessary configurations:
Watermark
It is possible to configure a watermark for the generated document. This feature allows customizing the document according to the organization's internal policies or traceability needs.
It is recommended to use watermarks for internal documents that require version control or confidentiality.
The available types of watermark are:
- Text
- Image
- QR Code
Check the SoftExpert Document documentation for further details about watermark configuration.
Electronic signature
It is possible to configure digital signatures, linked to templates already created in the SoftExpert Administration > Configuration > Electronic file > Digital signature (AD077) menu.
Refer to the Configuring the digital signature of documents article for further details.
Storage
In the last step, define where and how the file will be stored.
Define if the file will be saved in PDF format or in the original format (.docx).
Indicate whether the file will be saved in a field of the File type of the form associated with the process, in the Attachment tab of the workflow, or whether a document from SoftExpert Document will be created and associated with the workflow.
Storage rules:
- If a watermark or digital signature has been set, the file will automatically be converted to PDF.
- If a digital signature has been configured, the file must be stored in SoftExpert Document, as the electronic signature requires a link with a record of the component.
- When the file is stored in a form field of the File type, it will not remain linked to the process instance. To check it later, it is necessary to access the form record.
Inserting variables in the template
1. After clicking on the View available variables option, find the information you wish to insert in the contract (e.g.: Title, ID #, Deadline, etc.).
2. Click on the Copy button of the variable corresponding to the information.
3. Open the contract template that will be used and paste the copied code to the area that will be replaced with the information of the variable.
4. Save the .docx file.
See the example below for a better understanding of how the text must be edited.
Suppose the contract contains this statement:
"This contract, identified by number ______, will start on ______, with the deadline being ______."
In the template, replace the spaces with the variables:
"This contract, identified by number {d.wf.identifier}, will start on {d.wf.dttm_start}, with the deadline being {d.wf.deadline}."
Once the workflow is executed, the contract will be generated and the system will automatically replace the variables with the actual data:
"This contract, identified by number 12345, will start on Sep/08/2025 10:30, with the deadline being Sep/15/2025."
Automatic repetition of information in the document
In some cases, the file needs to display information lists, such as several pieces of equipment, several steps of a process, or several people involved.
To this end, the system can automatically copy the same part of the file, filling in the data according to the information sent by the form or workflow.
There is no need to manually duplicate lines. Simply indicate in the document template where the sequence of information begins.
How the system understands that it must repeat a fragment:
Repetition happens when the document has:
- A field with the current position ([i]);
- A field just below with the next position ([i+1]).
The first line serves as a template and the second line serves only for the system to understand that there is a sequence. Therefore, this second line does not appear in the final document.
Only one field with [i+1] is enough to activate auto-repeat.
Example 1 — List completed by the form:
Workflow information:
| Equipment | Code |
| Laptop | EQ-01 |
| Monitor | EQ-02 |
| Keyboard | EQ-03 |
How to set up the file:
| Equipment | Code |
| {d.form.equipments[i].name} | {d.form.equipments[i].code} |
| {d.form.equipments[i+1].name} |
What happens in practice:
- The system uses the first line as default.
- It repeats this line for each item entered.
- The line with [i+1] serves only as an internal reference.
- The final document only shows correctly filled lines.
Generated result:
| Laptop | EQ-01 |
| Monitor | EQ-02 |
| Keyboard | EQ-03 |
Example 2 — Steps coming from the workflow:
Workflow information:
| Workflow | Step |
| Start | Requester |
| Analysis | Manager |
| Approval | Board |
How to set up the file:
Step: {d.workflow.steps[i].title}
Responsible: {d.workflow.steps[i].responsible}
{d.workflow.steps[i+1].title}
Generated result:
Step: Start
Responsible: Requester
Step: Analysis
Responsible: Manager
Step: Approval
Responsible: Board
Example 3 — Grouped information (lists within lists)
Some information is organized in groups, such as projects with several activities.
The system automatically understands when it needs to repeat each part.
Workflow information:
| Workflow | Projects |
| Name: Project Alpha | |
| Activities: | |
| Planning | 40 hours |
| Execution | 120 hours |
| Workflow | Projects |
| Name: Project Beta | |
| Activities: | |
| Survey | 32 hours |
| Delivery | 24 hours |
How to set up the file:
Project: {d.workflow.projects[i].name}
Activities:
{d.workflow.projects[i].activities[i].label} - {d.workflow.projects[i].activities[i].hours}h
{d.workflow.projects[i].activities[i+1].label}
{d.workflow.projects[i+1].name}
How the system interprets:
- First, it repeats the projects.
- Within each project, it repeats the activities.
- It is not necessary to copy everything again, just indicate the next information.
Example 4 — Table with automatic rows and columns
It is also possible to fill complete tables automatically.
Workflow information:
| Workflow | |
| Columns | |
| Name | Jan |
| Name | Feb |
| Name | Mar |
| Queues: | |
| Values: | 10, 20, 30 |
| Values: | 15, 25, 35 |
How to set up the file:
{d.workflow.columns[i].name} {d.workflow.columns[i+1].name}
{d.workflow.rows[i].values[i]} {d.workflow.rows[i].values[i+1]}
{d.workflow.rows[i+1].values[i]}
Important information:
- Always use [i] and [i+1] in the same set of information.
- Only one field with [i+1] is enough to activate the repetition.
- There is no need to manually duplicate texts or tables.
- The line with [i+1] does not appear in the final document.
To format date, date and time, and decimal fields:
Follow the example format below:
Date:
{d.form.table.datefield:formatD('DD/MM/YYYY')}
Other templates that can be used:
'20160131':formatD('L') // "01/31/2016"
'20160131':formatD('LL') // "January 31, 2016"
'20160131':formatD('LLLL') // "Sunday, January 31, 2016 12:00 AM"
'20160131':formatD('dddd') // "Sunday"
Date and time:
{d.form.table.datefield:formatD('DD/MM/YYYY HH:mm:ss')}
Other templates that can be used:
'2017-05-10T15:57:23.769561+03:00':formatD('LLLL') // "mercredi 10 mai 2017
14:57" '2017-05-10 15:57:23.769561+03:00':formatD('LLLL') // "mercredi 10 mai
2017 14:57" '20160131':formatD('LLLL') // "dimanche 31 janvier 2016 00:00"
'20160131':formatD('dddd') // "dimanche"
Decimal:
{d.form.table.fielddc'10,456.00':formatN()}
Important information:
- The contract template must necessarily be in .docx format.
- The variables displayed vary depending on the data of the instance and form associated with the process.
- Use the variables exactly how they appear in the list, including the curly brackets {}.
- Insert as many variables in the document as you wish, even if it is necessary to repeat them.
- If any variable does not have a value, the corresponding field will be empty in the document, displaying the variable exactly as configured, without performing the appropriate substitution.
- The Data type field helps understand the format of the information (text, date, icon + text, etc.).
- Variables of the Form type will always be provided in the following pattern:
◦ Table > Relationship > Field.
◦ Table > Relationship with the listing table > Listing column.
◦ For example, the {d.form.apr.file} variable represents a piece of data of the file type, with the file field, and the apr table.
Checking the job
Use the step-by-step instructions below to check if the job is running correctly:
1. Access the SoftExpert Workflow > Configuration > General parameters (WF019) menu.
2. Select the Jobs tab.
3. Click on the Test connection button.
If the system detects a connection error, contact the SoftExpert Engine team. The job not functioning prevents Carbone resources from being used by the system.
Conclusion
Variables are the most convenient and secure way to generate dynamic contracts in SoftExpert Suite, ensuring agility, standardization, and fewer errors in the day-to-day routine.
With all configurations set, when instantiating the process in SoftExpert Workflow, the file will be automatically generated using the variables.