State and state type
Common state and state types should be used throughout the system to maintain consistency.
Usage of the colors and icons should also be consistent across workflows.
A new workflow state list lookup should be created for each new workflow. This ensures that additional new states can be created without affecting other workflows.
A new workflow state type list lookup should be created for each new workflow. This ensures that additional new state types can be created without affecting other workflows. At a minimum, a new workflow state type list lookup should be created for each product family. This will allow each product family to make changes to the state types without affecting other families.
WorkflowStateTypes list lookup is a common list lookup shared by many workflows. The values in this list lookup should not be changed or extended without permission as it could impact several workflows that are sharing the list lookup.
All workflows should include the standard five state types. At a minimum, a standard list lookup for each family should be created with the standard five state types:
| List Lookup Value | Lookup Description | Lookup Icon | Text Color |
|---|---|---|---|
| INIT | Initial | ||
| ACTIVE | Active | ||
| INACTIVE | Inactive | ||
| CLOSED | Closed | ||
| PENDING | Pending |
The Pending state type can only be used for approvals. Pending is used when a workflow transition requires approval and is configured as the To State Type value alongside the To State value.
Workflow steps
The first step of every workflow must be configured with the From State List Lookup Value = NEW and From State Type List Lookup Value = INIT. However, the description of the NEW workflow state can be changed in the list lookup. For example, in the WorkOrderTransaction workflow the description for the NEW state type is 'Ready to Post'.
| From State | From State Type |
|---|---|
NEW | INIT |
Workflow steps should be sequenced in a logical order. Sequence the steps in increments of 10 or 100 to allow for room to insert additional steps. The sequencing of workflow steps does not affect processing, it is simply used for organization of steps in a logical order.
Transitions
If you use the Auto workflow transition with an Queue Immediately, Process Asynchronously duration, you must define an error state.
Do not have Post-transition Logic Blocks on Manuals. This works great for the delivered base application, but if a customer customizes the workflow and changes the Manual to an Auto, the end user will never see an error thrown by the Post-transition Logic Blocks. The record's workflow will be stuck in an error state. If a logic block on the Manual could fail, that transition needs to be either a Logic Block, or the validation should be moved to the Action Blocks or an Event Definition that has a Workflow State Change. This ensures the workflow of the record will not get stuck.
Minimize transaction processing and keep logic simple in any workflow transitions. Having large amounts of processing within workflow will slow the transition of the record.
Description Field on Transitions
All Logic Block Controlled Transitions should use this field to describe how and where those transitions are invoked. This includes listing the logic blocks that queue the transition. This is important for those that need to extend or customize our workflows. Do not add information to this field that provides no value or is just duplicating obvious information that can be found on the workflow transition. For example, a description is not needed to explain what a manual transition is doing, this just creates more noise. Focus on adding information to the description field that will help those who are extending or customizing the transition.
Approvals
A workflow with approvals should never be shipped because approvals should be entirely customizable for the customer. If there is an approval that you think should be delivered with a workflow, then the approval must be considered absolutely necessary to the workflow's definition. A notification that is separate from an approval can be configured and shipped with a workflow as long as they are tied to a role and not a user. The customer must configure the user list when the workflow is shipped to them, but the shipped roles stay the same.
Always include the SYS - Base User role in the Roles subtable of the approval definition.
Effective Date Transition Trigger Type
Effective date transitions will automatically retry 3 times back to back. However, a manual transition to allow the user to get out of the state where a failed effective date transition ended up should be delivered. For example, if there is an effective date transition from Pending Active to Active, but it fails, the record will stay at Pending Active (or an Error state if the workflow is setup that way). You need to give the end user a way to manually get out of Pending Active to Active or Error to Active (or Pending Active).
Informational status
The purpose of an informational status field is to track an additional status that is a sub-status to the workflow status. This is done with an additional field that is managed by the business logic and is not part of the workflow. It is simply another status field added to the table.
If an informational status field is added to a table that has workflow, the field should be qualified with a descriptive word before the word Status. This is needed so the field will not be confused with the workflow status field. For example, in the Supplier Invoices application, a transaction that can be Unpaid, Partially Paid, Paid in Full, Pending, Voided, or Payment Hold using the Payment Status field. The transaction record can be in its final state, Posted to GL, but multiple payments can be made against the supplier invoice record, so the Payment Status field is used to convey the status of the payment against the invoice. Using workflow to convey partial states can be difficult to manage and can cause a lot of back and forth in workflow.
Updating existing workflows
Avoid saving workflows in base lifecycles. If a workflow is saved in a base lifecycle, any customized workflows are automatically notified of a change, even if nothing was updated. This causes an update to be required in the customized workflow.
Active/Inactive workflow pattern best practices
These best practices ensure that all workflows used to identify Active and Inactive records follow a consistent workflow pattern.
Tables with Master, or core business, data must use workflow when a status of Active or Inactive must be applied to records. By using workflow, customers can add approvals to master data.
Use state and state type names and their associated icons and colors consistently so that they are that are similar to other Active/Inactive workflows.
The following table demonstrates the necessary state types you must use and the standard states to use alongside the state types in Active/Inactive workflows.
| State type | State |
|---|---|
| NON-STANDARD state type | |
(reserved for approvals) | |
Workflow steps delivered cannot be removed by the customer.
- Do not deliver pre-configured approvals.
- Deliver the smallest subset of steps for the business flow to allow customers to add their own steps
Sequence the workflow steps to order the flow according to the normal flow of events. Sequence numbers should initially skip by 100 to accommodate inserting new steps in the future.
Business process workflow pattern best practices
These best practices ensure that all workflows used to manage business processes follow a consistent workflow pattern.
Create new workflow state and state type list lookups for business processes since they are unique to the business process and likely to change over time.
Business process workflows must be unique to each business process, but should still maintain consistency by using common state, state types, icons, and colors.
The following table demonstrates the necessary state types you must use and the standard states to use alongside the state types in business processes workflows.
| State type | State |
|---|---|
| NON-STANDARD state type | |
(reserved for approvals) | |
Workflow steps delivered cannot be removed by the customer.
- Do not deliver pre-configured approvals.
- Deliver the smallest subset of steps for the business flow to allow customers to add their own steps
Sequence the workflow steps to order the flow according to the normal flow of events. Sequence numbers should initially skip by 100 to accommodate inserting new steps in the future.
Alternate Flows:
Workflow Type is used to transition a record differently than the normal flow based on a one or more values in a record. For example, both a sales order and a sale quote are stored in the SalesOrder table (header/detail). A sales quote has a different business flow than a sales order. The workflow type utilizes the field, SalesOrderType, to configure the different business flow.
- Name the workflow type to represent the intent of the flow. For example, SalesQuoteHeader.
- The name of the workflow should be in upper camel case.
- Do not add Workflow Type in the name.
Chosen by Decision option is used to set the To state to different states depending on various conditions.
- Use this option when the from state can transition to more than one state, based on the decision criteria.
- There is no error state. If an error state is required, use a conditional logic block.
Success/Error
- Use this option to determine if the transaction succeeded or failed. An error must be set in the logic block to set the record to an error state.
- Do not auto transition a error state to a non-error state.
GL transactions workflow pattern best practices
These best practices ensure that all workflows used to process transactions to the General Ledger follow a consistent workflow pattern.
GL Transaction workflow
Transactions writing to the General Ledger must use workflow to post to the GL. For example, a supplier invoice posts to the GL using a workflow transition from Ready to Post to Posted. This allows a customer to add approvals for a supplier invoice prior to posting to the GL.
Use state and state type names and their associated icons and colors consistently so that they are that are similar to other transaction workflows.
Transaction workflows that post to GL must contain a Ready to Post and Posted to GL states.
The following table demonstrates the necessary state types you must use and the standard states to use alongside the state types in transaction workflows.
| State type | State |
|---|---|
| NON-STANDARD state type | |
(reserved for approval) | |
Transaction Workflow - Immediate Post
Use this pattern when the transaction should be submitted for processing immediately. For example, WorkOrderTransactions workflow automatically triggers posting a transaction as soon as the record is created.
A transaction that results in an error should be discarded by moving it to Discard where it is processed and then Discarded.
Historical transactions are moved to Historical/Closed without processing the transaction.
The following table demonstrates the necessary state types you must use and the standard states to use alongside the state types in immediate post transaction workflows.
| State type | State |
|---|---|
| NON-STANDARD state type | |
(reserved for approvals) | |
Workflow list lookup best practices
These best practices ensure that all workflows list lookups follow a consistent workflow pattern.
For each workflow, define a unique workflow state list lookup and workflow state type list lookup. Do not share across workflow so customers can customize their workflows independently.
- Add the words 'Workflow Status' to the name of the State list lookup. For example, SalesOrderDetail Workflow Status
- Add the words 'Workflow State Type' to the name of the State Type list lookup. For example, SalesOrderDetailWorkflow State Types
Set both list lookups customization pattern to Allow Additions.
Workflow State list lookup:
- Include New as a standard value in the State list lookup. The user interface defaults to New on create.
Workflow State Type list lookup:
- Include the standard 6 values for a State Type list lookup: Initial, Active, Inactive, Closed, Pending, Exit Subflow.
- Create a unique state type value only if the original six values do not suffice and you need to uniquely identify a state type. For example, in manufacturing, the state type of Release has sufficient meaning to drive logic.
- Do not hard code in a logic block against the State Type values. You can only hard code against the State Type list lookup.
- Exception: In an integration, a logic block can set the value to a state type that is combined with a state type of Initial. This provides the ability to migrate data and set to a Historical/Initial status which auto transitions to a Historical/Closed status.
- Pending is reserved for approvals and cannot be used for any other purpose.
- Exit Subflow is reserved for use in subflows only.
Workflow standard icons and colors
In general, there needs to be consistency in the usage and meaning of an icon in workflow.
As much as possible, use the following set of icons to convey the stated meaning, presented in the standard color.
Never use a spinning icon for a workflow that may persist for a period of time, needs user interaction, or may have long processing time. For example, never use for a Closed state as the transaction may stay at this state indefinitely. However, that type of icon may be permitted if you need a Processing state that does not need user interaction and has a quick processing time.
When selecting the color be aware of when to use a spectrum color versus a semantic color. Semantic colors should be used if you want the color to show meaning and hold true to a theme. For example, in some locales the color red means bad or error, but in other places, that color may mean good or success. If your state is truly a bad state, choosing is better than . That means will be colored based on the theme or locale. While using will always be red regardless of the theme or locale. Learn more in Theme color types and Themes best practices.
| Icon | Meaning | Color |
|---|---|---|
| New | ||
| Draft | ||
| Review | ||
| Review | ||
| To Do | ||
| Pending | ||
| Ready (ASAP) | ||
| Ready (conditional move) | ||
| Pending | ||
| Pending Approval | ||
| Active | Automatic | |
| In progress | ||
| Done | Automatic | |
| Closed, Locked | Automatic | |
| Canceled | ||
| Inactive | ||
| History | ||
| Hold | ||
| Past Due | ||
| More Information | ||
| Error | ||
| Priority, Critical | ||
| Discarded |