Workflow Versioning
- Hannah.Dela
- Casper Badenhorst
- Grant Slinger
- Vu Nguyen
Summary
Prior FAB version 3.3, deploying a new workflow in production automatically update all in-progress and new form instances to adhere to the new workflow. This could lead to issues arising from discrepancies in task configurations.
FAB version 3.3 introduces Workflow Versioning, providing control over the workflow definition utilized by each form instance. Each Workflow Version corresponds to a single configured workflow definition and records changes while displaying the currently active workflow in the system.
By default, in-progress form instances retain their original workflow definition, preventing interruptions. while new instances adopt the latest workflow definition, ensuring consistency.
In this documentation, the terms "Non-breakable Workflow" and "Durable Workflow" also refer to the logic of Workflow Versioning.
Revised Workflow Versioning (FAB version 3.3.1 and higher)
With the introduction of Workflow Versioning in FAB version 3.3, auto-versioning ensures version control but complicates development and testing due to the creation of numerous workflow instances. It has also become difficult to track the specific workflow version used by each form instance.
To resolve these issues, we enhanced the workflow versioning logic and introduced a new API. This API collects detailed versioning data, which determines whether a new Workflow Instance ID will be generated. It also helps in managing workflow versions for in-progress form instances.
Below is the relational structure from the FAB Form App level to the Workflow Version level.
Starting FAB version 3.3.1, the combined values of Project Form Name, WF Iteration, WF Pattern, and WF Version triggers the creation of new Workflow Instance ID (field WF_INSTANCE).
API Component | Description | Related Table Fields | Release Notes |
|---|---|---|---|
Project Form App | Also known as the FAB Form App Name. In every Project Form App, there may exist multiple Form Iterations. | /IQX_FORMHD_INST-ZFORM_NAME /IQX/FAB_WF-ZFORM_NAME /IQX/FAB_WF_INST-ZFORM_NAME | AS-IS before FAB 3.3 |
Project Form Iteration / Workflow Iteration | Form Iteration value increments whenever user saves the form app via 'Save (new iteration)' button or form is transported through systems. Each Form Iteration can accommodate multiple Workflow IDs. | /IQX_FORMHD_INST-WF_ITERATION /IQX/FAB_WF-ZITERATION_NO /IQX/FAB_WF_INST-ZITERATION_NO | AS-IS before FAB 3.3 |
Workflow ID / Workflow Pattern ID | This field is intended to be used for future Alternate Workflows. Since the Alternate Workflow functionality has not been released yet, Workflow IDs as of FAB released v3.3.2 will always be set to '1'. Within each Workflow ID, numerous Workflow Versions can be found. | /IQX_FORMHD_INST-WF_PATTERN_ID /IQX/FAB_WF-ID /IQX/FAB_WF_INST-ID | Added on FAB 3.3.1 |
Workflow Version ID | Each Workflow Version ID represents a specific Workflow Definition configured for the Form App. All workflow versions available can now be easily viewed in the Workflow Version List within process designer version 2. A Workflow Version or Workflow Definition can be either in Editable or Active/Locked status. | /IQX_FORMHD_INST-WF_VERSION_ID /IQX/FAB_WF-VERSION_ID /IQX/FAB_WF_INST-VERSION_ID | Added on FAB 3.3.1 |
Auto-Versioning (FAB version 3.3)
Saving new changes in the Workflow Definition automatically creates a new workflow version, represented by the Workflow Instance ID (WF_INSTANCE) in the table /IQX/FAB_WF_INST. At the same time, it updates the table /IQX/FAB_WF and directly links the new Workflow Instance ID to the table /IQX/FAB_WF via the MD5_CHECKSUM field.
Upon submission, the FAB Form Instance records the Workflow Definition used in the table /IQX/FORMHD_INST, field WF_INSTANCE.
If you are using FAB version 3.3 and wish to deactivate this feature, please follow these steps: How To Bypass WF Instance ID Generation.
For FAB version 3.3, Workflow Version and Workflow Instance are used interchangeably since each WF version automatically creates new WF Instance.
Related Tables
/IQX/FORMHD_INST - FAB Form Header Instance Data (run-time values)
Run-time values of created Form App Instances
Notable Fields:
ZFORM_NAME - Form App
ZINSTANCE - Form Instance
WF_INSTANCE
added in FAB version 3.3
A MD5 checksum value representing the Workflow Instance on which a submitted form instance is currently running on
Unique identifier for single configured Workflow Definition with details that can be check on tables /IQX/FAB_WF and /IQX/FAB_WF_INST via fields MD5_CHECKSUM and WF_INSTANCE, respectively
CHECKSUM
added in FAB version 3.3.2
Unique identifier for OneList task checksum for syncing tasks via event
/IQX/FAB_WF - FAB Enhanced Workflow Definition
Contains the latest workflow definition for each Project Form App iteration
Change Date and Timestamps are recorded in the fields with pattern MODIFIED_*
Notable Fields:
ZFORM_NAME - Form App
ZITERATION_NO - Form Iteration
ID - Workflow Pattern ID (Always set to '1' as of FAB v3.3.2)
MD5_CHECKSUM - Workflow Instance ID, Unique character identifier for Workflow Version
VERSION_ID - incrementing number of Workflow Version (populated only for FAB version 3.3.1 and higher)
Description Fields:
ITERATION_DESC - Form Iteration Description
ZID - Workflow ID Description
VERSION_DESC - Workflow Version Description (editable via new workflow designer)
DESCRIPTION - Project Form App Description
Status Fields (populated only for FAB version 3.3.1 and higher):
IS_ACTIVE - Sets to 'X' (TRUE) when WF Version is in Active or Locked status
IS_RELEASED - Sets to 'X' (TRUE) when WF Version is released and transported
When no Workflow Version is activated yet, Workflow Instance ID (MD5_CHECKSUM) will contain the concatenated fallback value:
/IQX/FAB_WF-MD5_CHECKSUM = FormName + IterationNo+ WF Pattern ID + WF Version_ID
For FAB version 3.3, each workflow version is considered activated so Workflow Instance ID (MD5_CHECKSUM) will always contain a hash value.
/IQX/FAB_WF_INST - FAB - Enhanced Workflow Instance (Table released in FAB v3.3)
As of FAB v3.3.1, this table captures a snapshot of the workflow definition each time the corresponding workflow version is saved and activated.
As of FAB v3.3, this table captures a snapshot of the workflow definition whenever its changes are saved.
Notable Fields:
WF_INSTANCE - Workflow Instance ID, Unique character identifier for Workflow Version
ZFORM_NAME - Form App
ZITERATION_NO - Form Iteration
ID - Workflow Pattern ID (Always set to '1' as of FAB v3.3.2)
Description Fields:
VERSION_DESC - Workflow Version Description (editable via new workflow designer)
Workflow Data Comparison Across FAB Versions
| Fields | Prior FAB version 3.3 | FAB version 3.3 | FAB version 3.3.1 | FAB version 3.3.2 |
|---|---|---|---|---|---|
Table /IQX/FORMHD_INST | WF_INSTANCE | Not populated | Contains the WF Instance (MD5 checksum value) in which the form instance is currently running on. Check table fields: /IQX/FAB_WF-MD5_CHECKSUM or /IQX/FAB_WF_INST-WF_INSTANCE | Same as FAB 3.3 | Same as FAB 3.3.1 |
WF_ITERATION | Not populated | Not populated | Same value as Form Iteration | Same as FAB 3.3.1 | |
WF_PATTERN_ID | Not populated | Not populated | Always “1” | Same as FAB 3.3.1 | |
WF_VERSION_ID | Not populated | Not populated | Increments for every activated & saved WF Definition | Same as FAB 3.3.1 | |
CHECKSUM | Not populated | Not populated | Not populated | Contains the OneList Hash checksum for syncing tasks via event | |
Table /IQX/FAB_WF | MD5_CHECKSUM | Not populated | Contains the latest WF Instance in which new submitted form instances will run on. On FAB 3.3, new hash value will be generated every time the WF Definition is changed and saved. Therefore, MD5_CHECKSUM will always contain the hash value for latest WF Definition. | Contains the latest WF Instance in which new submitted form instances will run on. | Same as FAB 3.3.1 |
MODIFIED_* | Not populated | Contains details of WF Definition change (date & time) | Same as FAB 3.3 | Same as FAB 3.3.1 | |
VERSION_ID | Not populated | Not populated | Increments for every activated & saved WF Definition | Same as FAB 3.3.1 | |
VERSION_DESCRIPTION | Not populated | Not populated | Contains the value entered by user in Process Designer or the default concatenated value of date and timestamp | Same as FAB 3.3.1 | |
IS_ACTIVE | Not populated | Not populated | Same as FAB 3.3.1 | ||
IS_RELEASED | Not populated | Not populated | Set to 'X' when WF Definition is in Locked status in Process Designer | Same as FAB 3.3.1 | |
WF_ID_* | Not populated | Not populated | Contains details of WF Definition creation (date & time) | Same as FAB 3.3.1 | |
MC_* | Not populated | Not populated | Contains match code values for Revised WF Versioning | Same as FAB 3.3.1 | |
Table /IQX/FAB_WF_INST | WF_INSTANCE | No table entry | Contains the hash value for WF Definition. New table entry is added each time the WF Definition is changed and saved.
| Contains the hash value for WF Definition. New table entry is only added for new value combination of Project Form Name, WF Iteration, WF Pattern, and WF Version and WF Definition is saved and activated. | Same as FAB 3.3.1 |
VERSION_ID | No table entry | Not populated | Increments for every saved & activated WF Definition | Same as FAB 3.3.1 | |
VERSION_DESCRIPTION | No table entry | Not populated | Contains the value entered by user in Process Designer or the default concatenated value of date and timestamp | Same as FAB 3.3.1 | |
MC_* | No table entry | Not populated | Contains match code values for Revised WF Versioning | Same as FAB 3.3.1 | |
MODIFIED_* | No table entry | Contains details of WF Definition change (date & time) | Contains details of WF Definition change (date & time) | Same as FAB 3.3.1 |
Sample Screenshots Workflow Data Across FAB Versions
Prior FAB version 3.3
Table /IQX/FORMHD_INST
Table /IQX/FAB_WF
No Table /IQX/FAB_WF_INST
FAB version 3.3
Table /IQX/FORMHD_INST
Table /IQX/FAB_WF
Table /IQX/FAB_WF_INST
FAB version 3.3.1 and higher
Table /IQX/FORMHD_INST
Table /IQX/FAB_WF
Table /IQX/FAB_WF_INST
More Information
To know more on workflow differences between different FAB released versions, please check FAB Process Flow Version Comparison.