Documenting a Flow¶
Frequently, a flow implements a business logic that is anything but trivial. It is therefore very useful to be able to trace and document all the steps computed by the flow in various tasks or to provide more information about data and operations performed behind the pure flow topology.
In Rulex Factory, the Documentation tab performs this functionality. For more information on this tab, see section: Documentation tab.
This page introduces the various procedures that allow the user to edit flow and task documentation.
In this tab, it is possible to associate documentation with the entire flow as well as with each individual task within it. As a rule, you associate documentation with the flow when you want to keep track of the flow logic or if you want to have an overview about the problem solved by the current procedure.
To edit the flow documentation, follow the steps below:
Procedure
Click on the Documentation tab at the left-hand side of the stage window.
Click on the pencil icon at the upper right side of the left panel.
Insert and customize the documentation for the flow overview in the Documentation Editor.
Click on Save to make your modifications persistent or on Discard to erase your editing.
whereas for single tasks follow this procedure:
Procedure
Click on the Documentation tab at the left-hand side of the stage window.
Double-click on the line of the task you want to document.
Insert and customize the documentation for the selected task in the Documentation Editor.
Click on Save to make your modifications persistent or on Discard to erase your editing.
Documentation Editor¶
The Documentation Editor can be used to insert and customize your documentation for the entire flow or for any single task.
In this editor you can write plain text and change its formatting options like font, size and color and many others.
The Documentation Editor is divided into a menu bar and a text area where you can freely write your own notes and logic.
The menu bar allows you to customize your text. Available options are:
Bold
Italic
Underline
Strikethrough
Subscript
Superscript
Font family
Font size
Font color
Background color
Left Alignment
Center Alignment
Right Alignment
Justify
Bullet list
Number list
Tables
Autofill (see below to know more about autofill operations)
As in any other standard text editor you can apply these customizations to the whole text or to a part of it. Moreover, it is possible to select the text of the documentation and to right-click on it to open the context menu, which contains the following options:
Undo
Redo
Copy
Cut
Paste
Select all
Tables in documentation
When clicking on the Tables icon in the Flow documentation window, the Insert table context menu opens. Here, users can specify:
Rows: the number of rows in the table.
Columns: the number of columns in the table.
Cell padding: the distance between each single cell of the table.
Border width: the width of the table’s border.
With header row: if selected, an header row is added to the table.
It is possible to select with the pointer both the text or the cells of the table. If a cell has been selected, it is possible to open the table context menu, where the following options are available:
Add row before
Add row after
Add column before
Add column after
Delete row
Delete column
Delete table
Merge cells
Split cell
Toggle header column
Toggle header row
Tip
It is possible to work on the documentation editor using specific keyboard shortcuts:
- Ctrl+F: this shortcut opens a finder, whose interface contains the following features:
a text field, where users can type the string(s) they are looking for. The searched string then highlights in the text, to identify its position in the documentation.
the arrow located on the left of the find text field opens another text field located under the find one, where users can type the text which will replace the searched one.
the results, which indicates the currently selected result of the research and the total of the results.
the previous result and next result arrows, which allow respectively to browse to the previous or next result of the research.
the close button, which allows to close the finder.
the Case Sensitive button, which enables the case sensitive research.
the replace current selection button, which allows to replace the current selected string with the new one.
the replace all button, which allows to replace the current results with the new text.
Ctrl+H: replace.
Ctrl+C: copy the underlying HTML code. If the text is pasted to another documentation window, the HTML code is not visible, while if it is pasted externally, the full HTML code is pasted.
Ctrl+V: paste the underlying HTML code.
Ctrl+X: cut the underlying HTML code.
Ctrl+Z: undo last operation.
Ctrl+Y: redo last operation.
Ctrl+A: select all.
Autofilling a task¶
Rulex Factory offers users the possibility to automatically document any task by describing its most common operations and position in the flow. The position of tasks in a flow will be shown to users by means of a parent-child task hierarchy within the relative exported documentation file. You can also use this auto-documentation feature as a starting point for future customization.
The autofill functionality can be applied to a set of tasks rows from the Documentation tab by selecting them and then by right-clicking and choosing the Autofill option from the corresponding context menu.
You can also automatically autofill all the still empty task entries directly during exportation to file phase of your documentation, by selecting the desired value in the Autofill empty spaces drop-down list within the Export documentation dialog box.
The Autofill option will generate automatic documentation by inserting your option values or your history in the selected task into a pre-defined sentence. If needed also information about input / output task names is used.
To autofill a task or a set of tasks, follow these step-by-step instructions:
Procedure
Click on the Documentation tab at the left-hand side of the stage window.
Select the task rows you want to autofill by pressing the Ctrl+click to select multiple and far apart task lines or press Shift+click to select all documentation rows at the same time.
Right-click on one of the selected lines to open the context menu, then click on the Autofill option to autofill documentation rows.
Exporting the documentation¶
Once you have written down your notes and logic, to share with your colleagues or leaders, this needs to be exported as a file. In particular Rulex Factory exports flow documentation to a PDF file format.
To export documentation, click on the Export documentation icon in the upper right side of the Documentation tab.
Like in many other Export dialog boxes in Rulex Platform, you now have to configure the Filesystem connection and select the folder where you want to export your documentation file. For more information about how to configure a Filesystem connection, please see section: Configuring a Filesystem connection.
The file name will be generated automatically as follows: RulexDocumentation_<date>_<hour>.pdf with date and time of the export process.
Use the text field Insert the desired file name to define a custom file name.
The other option available in the documentation Export dialog box is the Autofill empty spaces option. This functionality manages the auto-documentation feature for all task entries for which no specific documentation has been defined. It can take three possible values:
None: no autofill operation is performed.
Only flow: all the documentation free tasks of the selected flow will be autofilled in the PDF file. When dealing with module tasks, if this option has been selected, the documentation of the module only will be added, and the documentation on the module’s flow tasks will be added as an appendix.
Both flow and module: all the documentation free tasks of the selected flow will be autofilled, as well as all the documentation free tasks of all the modules contained in the selected flow will be autofilled in the PDF file. For more information about module tasks, see section: Module Tasks.
To export flow documentation as a PDF, follow the guidelines listed below:
Procedure
Click on the Documentation tab at the left-hand side of the stage window.
Click on the Export documentation icon at the upper right side of the left panel.
Select from the DESTINATION slider, whether you want to export your documentation to a previously saved location, or to a custom one.
Choose from the drop-down list, whether you want to export the documentation file to your computer or to a remote connection (see filesystem description). If you are exporting to a remote connection, choose it from the list, and then click on the pencil icon to set the connection information required.
Click the SELECT button and browse to the location of the folder where you want to export.
Write the file name in the Insert the desired file name field and choose the Autofill empty spaces policy.
Click Export. When the progress bar reaches 100%, your exported documentation will be saved in the previously specified location.
Exported documentation format¶
Documentation is exported to PDF file formats. PDF files are divided into the following parts:
Header: it contains the Rulex Platform logo image.
Flow name
Flow documentation overview
Image of the stage: it shows the flow topology. This image is replaced by a placeholder if the stage size exceeds 2000 px in width or height.
- Initial Flow’s configuration: divided into:
Code Variables: displayed as a table with Name/Source/Value columns.
Vault Variables: displayed as a table with Name/Source/Value columns.
- Task Description: filled with only documented or autofilled tasks; each of them having
Task icon: describing the category of the task.
Task name: the task label on the stage.
Parents: name of input tasks. By clicking on the task name, the user will be automatically redirected to the corresponding task’s description.
Children: name of output tasks. By clicking on the task name, the user will be automatically redirected to the corresponding task’s description.
Task documentation: documentation on the task, which has been previously written by the user or automatically filled.
Appendix: one for each documented module, they own the same form of a complete flow documentation just presented but referred to the flow pointed by the module task.