Use workflow conversions to:
- Add a workflow definition to tables with existing business data.
- Convert the workflow type on a set of records based on filter criteria you provide. This makes workflow changes backwards compatible.
- Update the workflow state of existing business records to another state and state type.
Data transform logic blocks update table records so they can operate with a changed application. Learn more in Data transforms.
Within a data transform, there are multiple ways to build a workflow conversion, such as:
Update Workflow action—Allows you to set workflow state and workflow state type on a set of records defined in the Fetch Record action. Use this action when you need to change existing workflow on a set of records to a new state or state type. This action is the preferred approach for workflow conversions since the system reevaluates the workflow type of records, including any workflow types added by partners or customers in downstream development. This action is only intended for workflows without subflows enabled.
Bulk Update action—Allows you to set workflow state, workflow state type, and workflow type on a set of records defined in the Bulk Update action. This is helpful when you want new workflow on a table that already has data within it. This action should only be used if you are adding or removing workflow from a table. This includes converting a Header Detail workflow definition to separate Header and Detail workflow definitions. Learn more in Bulk Update action.
For configuration information, see Data transform configuration for application developers.
Data transform configuration for application developers
Application developers configure data transforms using the Logic Block Builder application, Data Transform Definitions application, temporary tenant applications, and Data Transform Execution Plan application to update business data so that the data can operate with a changed application.
Logic Blocks
In the Logic Block Builder application, create a logic block of type Data Transform, then:
- Use the Bulk Update action for records to be uniformly altered. It is the most efficient way to alter a collection of records where all the records need to be updated to the same set of values.
- Use an Update Record action when records need to be individually queried and altered. In these cases, the records need to be fetched with an applicable fetch logic block action and then updated.
- The Table Name or Inputs and Outputs are not needed unless the logic block is a child logic block that is called from another data transform logic block that is using a Chunk Fetch.
If you want to log messages during the run of a logic block, in the Set Message action select the message type Data Transform Message. To ensure the user running the data transform is aware of the status of the data transform operation, select either Background Task Progress or Background Task Summary type for the Set Message action.
A Set Message action of type Data Transform Message does not interrupt the processing of subsequent records. Even if an error occurs and the Message Severity is Error, the data transform continues to execute logic actions and any successfully altered records remain when the transform is complete.
To interrupt the processing of the data transform in case of an error and prevent any records from remaining, a Set Message action with message type Alert and Message Severity Error can be used.
For more information see Data transform logic blocks.
Data Transform Definitions
After you have built your data transform logic block, add the logic block record to the Data Transform Definitions application. You must enter your logic block record in the application to run or test the data transform.
In the Data Transform Definitions application, you must:
- Enter the name of the data transform logic block you have created. Only a data transform type logic block can be used in the Data Transform Definitions application.
- Enter the name of the initial data transform in the Dependency field if your data transform is dependent upon another data transform executing first.
- Test your data transform in a personal tenant. You must also test your data transform in the same lifecycle as the lifecycle the data transform logic block is located in.
- Select Test Transform from the row actions menu in the Data Transform Definitions application to initiate your data transform test.
- Add the name of each table modified by the data transform in the Tables Altered section. The table modified by the data transform logic block is automatically populated into this section when the data transform record is saved. However, any other tables modified by the data transform must be manually added this section.
For more information see Data Transform Definitions application.
Temporary tenants applications
Create a temporary tenant to test your data transform.
In either the Temporary Tenants - Test or Temporary Tenants - Server applications, you must:
- Create or import several records to test your data transform if the seed environment specified in the temporary tenant template does not have sufficient data to test the data transform.
- Select Renew in the row actions menu for the personal tent to extend the expiration date two weeks if you need to use the personal tenant beyond the specified expiration date.
- Select Clean in the row actions menu if you want to regenerate the environment as it existed in your personal tenant before you tested your data transform.
Data Transform Execution Plan
Data Transform Definitions application
Use the Data Transform Definitions application to test your data transform logic block. This type of logic block can only be run when connected to a record in the Data Transform Definitions application.
When configuring a data transform to test a data transform logic block, keep in mind the following:
- Data transforms generally run against only one table. However, they can run against more than one table (such as a Header table and then a Detail table), by using loops within the data transform logic block running the transform.
- A data transform cannot be used for table types involving multiple tables such as Join or Header Detail table types.
- Additionally, data transforms cannot modify tables that are used to hold transitory or temporary data. These table types include:
- Work Tables
- Report flat tables
- Cube tables
- Data transforms use only one type of logic block—data transform logic block.
- Each data transform is associated with only one logic block.
- The name of each table modified by the data transform must be added to the Tables Altered section. The table modified by the data transform logic block is automatically populated into this section when the data transform record is saved. However, any other tables modified by the data transform must be manually added this section.
- If a target release is provided in the Release field of the Data Transform application, your data transform runs when a tenant/zone is upgrading to the indicated release. If the field is empty, your transform does not run during an upgrade.
- Leave the Release field empty for data transforms associated with a patch action or with the activation of specializations to Nextworld metadata objects.
- Solution Partners cannot build a data transform over a base object, but they can build a data transform over a specialization that they have built for a base object.
Transform dependencies
A data transform may be dependent upon another data transform to run first. If your data transform is dependent upon another data transform running first, the Dependency field of the application displays the initial data transform.
Test the data transform
Select Test Transform from the row actions menu for the applicable record in the Data Transform application to test your data transform.
Note the following requirements for testing a data transform:
- Test your data transform in your temporary tenant that is populated with the appropriate business data.
- Once your testing is complete and you've determined that the data transform runs as expected, transfer the data transform to the designated testing/QA personnel for inclusion in a data transform execution plan so it can be run in the appropriate environments.
For more information see Data transforms and Data transform logic blocks.
Bulk Update action
The Bulk Update action allows you to update a group of specified records simultaneously. This is used in data transforms, such as workflow conversions, to update field values.
There are several operations you can perform with bulk update, such as:
- Add or subtract a field value by any number, or multiply by a whole number. The field can have only one math operation designated.
- Set a field with a new value.
- Clear a field to be empty.
The Bulk Update action performs the operation you configure on every record that matches the filter criteria.
Configuration
In the Logic Builder, application developers must:
- Select the Bulk Update action in their logic block.
- Specify the filter criteria for how the records should be selected.
- Designate the math operation, or value, which they want to use on the fields.
Workflow conversions
Use the Workflow Mappings section in the Bulk Update action to set the workflow state, workflow state type, and workflow type on records. This enables you to add or remove workflow support on a table which already has business data, since you can add or remove the znwWorkflowInstance field from records.
While bulk updates are generally more efficient than fetching and updating individual records, the bulk update does not take into account any workflow types added in downstream development. If workflow is newly added to a table, the production environments likely do not have any owned or customized workflow types, so it is safe to hardcode a workflow type in your workflow conversion.