Type = How-tos, ; Topic = OPUS Solution Environment,;Persona = Solution Designer,; Orchestration = Manufacturing, Logistics, Commerce, Transportation, Clinical Supply,; Function = Supply Chain, IT, Operations, Regulatory Affairs, Quality, Commercial, Pharmacy, Project Management, Finance, Procurement, Spare 2,

Configure workflows

A workflow defines the sequence of states that an object (e.g. a business transaction object) moves through during its lifecycle. Each state (e.g. Draft, In Review, or Approved) represents a stage of progress, and transitions occur based on specific actions or conditions.

Solution Designers can search for, view, and configure workflows in a Company Solution. Workflows enhance business process management by ensuring efficiency and consistency, guaranteeing that objects of the same type move through the same base states and transitions without users needing to configure separate workflows for each object. At the same time, configuring workflows also provides flexibility, allowing the workflows in a Company Solution to continue to evolve in conjunction with the company's processes and business needs.

A typical workflow consists of the following components:

States – Represents the current position of an object within the workflow. They include base states and can incorporate sub states if needed. Base states are the primary states that an object can occupy. Base states are defined by the application developer and cannot be customized by solution users.
Sub state – Define substate within each base state to provide more detailed tracking of the process.
Transitions – Defines the permissible paths between states and guides the object through the workflow.
Post-Transition Actions – These actions execute when a transition occurs, allowing for additional logic to be applied during the workflow.

There are two types of workflows:

Standard workflow – Includes a predefined sequence of states and transitions for an object type. These workflows are commonly used across various business processes.
Business object workflow – Extends a standard workflow to support unique requirements. It provides configuration options and flexibility to adapt the standard workflow model to specific business needs.

Before performing any actions on the workflow, ensure the following:

If you have access to multiple companies, make sure you have the correct company selected in the TraceLink Account menu.
The company solution is in the Edit state.

Add and edit a sub state

Solution Designers add sub states within a base state to modularize existing workflow logic and tailor it to meet specific business needs. For example, a base workflow includes a state called Pending Approval, while sub states such as Pending Approval by Product Architect or Pending Approval by CTO can be added to enable scalable and reusable approval processes. Only add substates when they are relevant and necessary for the business context.

Add a new sub state

Select the Main Menu icon.
Select Opus Solution Environment.
Select Solution in the side menu.
Select Workflows in the side menu.
The Search Workflows screen appears.
Select Filter.
In the Filters push panel, fill in one or more of the following fields:
- Solution type-ahead field – The name of the desired solution.
- Business Object Type type-ahead field – The name of the desired business object associated with the solution.
Select Apply.
The Filters panel closes and the main content area displays the results according to filters applied by the user.
In the Business Object Workflow column, select the desired workflow link to open it.
The Workflow Details screen appears.
Select the Edit button.
In the Workflow States and Transitions table, under the Base State column, select the desired base state, and then select the add new sub state icon.
The Add Sub State push panel appears.
Fill in the following fields:
- Base State type-ahead field – Required. The primary state of the workflow from a predefined list.
- Sub State field – The sub state to add more granular states within a base state.
- State Display Name field – Required. The name for the sub state to display it in the workflow.
- Start State switch – Designate a specific sub state as the starting point of the workflow. Setting this switch to Yes enables the sub state to be the initial state when the workflow is initiated.
Select Apply.
Verify that the added sub state now appears under the selected base state in the Workflow States and Transitions table.
Select the Save button.

Tips

Every added sub state must have at least one incoming transition. It is recommended to include one outgoing transistion unless the substate is the last state in the workflow.

Edit a sub state

Select the Main Menu icon.
Select Opus Solution Environment.
Select Solution in the side menu.
Select Workflows in the side menu.
The Search Workflows screen appears.
Select Filter.
In the Filters push panel, fill in one or more of the following fields:
- Solution type-ahead field – The name of the desired solution.
- Business Object Type type-ahead field – The name of the desired business object associated with the solution.
Select Apply.
The Filters panel closes and the main content area displays the results according to filters applied by the user.
In the Business Object Workflow column, select the desired workflow link to open it.
The Workflow Details screen appears.
Select the Edit button.
In the Workflow States and Transitions table, under the Base State column, select the desired sub state, and then select the edit sub state icon.
The Edit Sub State push panel appears.
Update the following fields:
- Sub State field – Required. The sub state to add more granular states within a base state.
- State Display Name field – Required. The name for the sub state to display it in the workflow.
- Start State switch – Designate a specific sub state as the starting point of the workflow. Setting this switch to Yes enables the sub state to be the initial state when the workflow is initiated.
Select Apply.
View the updated Sub State in the Workflow States and Transitions table.
Select the Save button.

Add, edit, and remove a transition

A transition defines how an object moves from one workflow state to another. Each transition represents a single step in the workflow, such as moving an object from Draft PO to Pending approval or from In progress to Done.

Transition conditions control whether a transition is allowed to occur. A condition is a JavaScript expression evaluated at runtime. The transition proceeds only when the expression returns true. Conditions are typically used to enforce business rules (for example, blocking a transition when a required attribute is empty or exceeds a limit). Transition conditions are implemented as pre-transition conditions and must be written as a single line of code. Multi-line expressions are not supported and fail at runtime.

Transition actions are often called post-transition actions and they run automatically after a transition completes successfully. Actions allow the workflow to perform follow-up logic, such as creating related objects or updating attributes. Together, transitions, transition conditions, and transition actions provide fine-grained control over both the path an object takes through its workflow and the business logic executed before and after each step. This enables robust workflow automation, including sub states, conditional routing, and post-transition processing.

Add a transition

Select the Main Menu icon.
Select Opus Solution Environment.
Select Solution in the side menu.
Select Workflows in the side menu.
The Search Workflows screen appears.
Select Filter.
In the Filters push panel, fill in one or more of the following fields:
- Solution type-ahead field – The name of the desired solution.
- Business Object Type type-ahead field – The name of the desired business object associated with the solution.
Select Apply.
The Filters panel closes and the main content area displays the results according to filters applied by the user.
In the Business Object Workflow column, select the desired workflow link to open it.
Select the Edit button.
Select the desired Sub State in the Workflow States and Transitions table.
This is the desired transition From State.
Select the add new transition icon.
The New Transition push panel appears.
Fill in the following fields:

To State field – Select the desired transition.
Transition Conditions field – A rule or requirement that must be met in order for a workflow to move from one state to the next.
See example, for more details.
Transition Actions field – The thing that happens automatically when a condition is met and the transition occurs.
See example, for more details.

Select Apply.
View the new Sub State Transition in the Workflow States and Transitions table.
Select the Save button.

Edit transition conditions and actions

Select the Main Menu icon.
Select Opus Solution Environment.
Select Solution in the side menu.
Select Workflows in the side menu.
The Search Workflows screen appears.
Select Filter.
In the Filters push panel, fill in one or more of the following fields:
- Solution type-ahead field – The name of the desired solution.
- Business Object Type type-ahead field – The name of the desired business object associated with the solution.
Select Apply.
The Filters panel closes and the main content area displays the results according to filters applied by the user.
In the Business Object Workflow column, select the desired workflow link to open it.
Select the Edit button.
Select the desired Sub State in the Workflow States and Transitions table.
This is the desired transition From State.
Select the desired Transition To State.
Select the edit transition condition and action icon.

The Edit Transition Condition and Action push panel appears.
Insert the required JavaScript code in one or both of the following fields:

Transition Conditions field – A rule or requirement that must be met in order for a workflow to move from one state to the next.
See example, for more details.
Transition Actions field – The thing that happens automatically when a condition is met and the transition occurs.
See example, for more details.

Select Apply.
View the Transition Condition and Transition Action columns in the Workflow States and Transitions table to confirm the presence or absence of Transition Conditions and Transition Actions.
Select the Save button.

Remove a transition

Select the Main Menu icon.
Select Opus Solution Environment.
Select Solution in the side menu.
Select Workflows in the side menu.
The Search Workflows screen appears.
Select Filter.
In the Filters push panel, fill in one or more of the following fields:
- Solution type-ahead field – The name of the desired solution.
- Business Object Type type-ahead field – The name of the desired business object associated with the solution.
Select Apply.
The Filters panel closes and the main content area displays the results according to filters applied by the user.
In the Business Object Workflow column, select the desired workflow link to open it.
Select the Edit button.
Select the desired Sub State in the Workflow States and Transitions table.
This is the desired transition From State.
Select the desired Transition To State.
Select the remove transition table icon.

The Remove transition push panel appears.
Read the confirmation message and select Apply.
View the Transition Condition and Transition Action columns in the Workflow States and Transitions table to confirm the removal of the Transition.
Select the Save button.

Example: Restrict transition access and automate object creation

In this example, only authorized users can perform a transition. When a transition occurs, the post–transition logic automatically creates a new object.

Before you begin

Identify the permission required to perform the transition.

Identify the target workflow state and the object type you want to create in the post–transition action.

Step 2: Add the transition condition and transition action

Open the workflow configuration.
Select the Edit button.
Select the desired State in the Workflow States and Transitions table. (For example, from Draft to Pending Approval).
Select the add new transition icon.
The New Transition push panel appears.

fill in the following fields:

To State drop-down – Select the desired transition state.
Transition Conditions field – A rule or requirement that must be met in order for a workflow to move from one state to the next.
Add the entire function as a single line and replace the PERMISSION_NAME with the required permission key to perform this transition.

Copy

1
2
3
4
5
6
7
8
function evaluateCondition(dnpContext, commonConditionObject) { 
let isTransitionSuccessful = 'true'; const payload = JSON.parse(commonConditionObject.data.payloadRef); 
if (!role.permissions().includes("PERMISSION_NAME"))
 { 
 dnpContext.log().info("User does not have required permission for this transition.");
 isTransitionSuccessful = 'false'; 
 } return isTransitionSuccessful; 
 }

Transition Actions field – The function that runs automatically when the transition occurs and its condition is met.
Add the entire function and modify the payload fields (for example, schema ID) as needed for this use case.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
async function triggerTransition(dnpContext, commonTransitionObject) {
  const sourcePayload = JSON.parse(commonTransitionObject.data.payloadRef);

  const newItemPayload = {
    item: {
      objectAction: "new",
      payload: {
        id: "",
        schemaId: "agile-process-teams:item",
        schemaVersion: 1,
        objectType: "agile-process-teams:item",
        subType: "",
        data: {
          itemTitle: "Follow-up for " + (sourcePayload.data.workItemTitle || "workflow item")
        }
      }
    }
  };

  return await dnpContext.transport().events().send(
    "agile-process-teams:item-new:v2",
    "agile-process-teams",
    newItemPayload
  );
}

Select Apply.
Select the Save button.
Ensure the transition condition and transition action have been added properly and changes are saved.

Understanding funtions and objects used in the example

commonConditionObject and commonTransitionObject objects

In the context of the evaluateCondition function, the dnpContext, commonConditionObject and commonTransitionObject serve specific roles:

commonConditionObject – contains contextual information about the object undergoing a state transition. It includes metadata, workflow states, user information, and business data. The data.payloadRef property is parsed to access specific details, such as lastUpdatedByUserId, which is used in the condition check in the evaluateCondition function. This check determines whether the user attempting the transition is the same user who last updated the object.
commonTransitionObject – a standard context payload object that is passed to post-transition actions (i.e, transition action scripts) when an object moves from one workflow state to another. Use commonTransitionObject in your JavaScript transition action to access details about the transition and the object being transitioned, including:
- The from state
- The to state
- The object type
- The object’s business data, referenced through payloadRef
This payload structure is the same concept used for pre-transition conditions, where it is typically referenced as commonConditionObject. For transition actions, however, the parameter name used in the example is commonTransitionObject.

Both commonConditionObject and commonTransitionObject objects have the same structure. Each is a JSON object that includes the from state, to state, object type, and a payload reference string as shown in the following example.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "data": {
    "fromState": {
      "baseState": "State1",
      "subState": "state1sub2"
    },
    "toState": {
      "baseState": "State2"
    },
    "objectType": "test-application:test-object:v1",
    "payloadRef": "{\"id\":\"20260106-5555-8888-5555-314159265358\",\"data\":{\"baseAttribute1\":\"the year is 2026\",\"ext_customAttribute1\":\"today is a tuesday\",\"currentState\":\"state1sub2\"},\"currentBaseState\":\"State1\",\"currentSubState\":\"state1sub2\",\"objectType\":\"test-application:test-object\",\"schemaId\":\"test-application:test-object\",\"subType\":\"ext_testSubType\",\"ownerId\":\"00000000-0000-0000-0000-000000000000\",\"contextualOwnerId\":\"27c47d4d-23bc-4afe-aad5-ee5fa4bd7f11\",\"schemaVersion\":1,\"dataVersion\":5,\"lastUpdatedByUserId\":\"9e03b340-5ea9-11ed-bf9e-0242ac110010\",\"lastUpdatedDateTime\":1741616660462,\"createdByUserId\":\"7df38650-f882-11ea-9413-0242ac110006\",\"creationDateTime\":1731519199180}"
  }
}

The difference between the two objects is when the payload reference applies:

For a commonConditionObject, the payloadRef represents the state before the transition. In the example, the payload reference points to state1sub2.
For a commonTransitionObject, the payloadRef represents the state after the transition. For the same from and to states, the payload reference points to state2 instead of state1sub2.

dnpContext reference

dnpContext provides the context for the current operation within the TraceLink workflow. It allows access to various properties and methods related to the workflow execution environment. For example, dnpContext.headers().event().userId() retrieves the user ID of the event that triggered the workflow, which is essential for evaluating conditions based on user actions.

The following list includes various contexts:

Get user and membership information

dnpContext.headers().event().userId() – Returns the ID of the user that sent the request.
dnpContext.headers().event().userEmail() – Returns the email address of the user that sent the request.
dnpContext.headers().event().companyMemberships() – Returns the company memberships of the user that sent the request.
dnpContext.headers().event().applicationMemberships() – Returns the application memberships of the user that sent the request.
dnpContext.headers().event().processNetworkMemberships() – Returns the process network memberships of the user.
dnpContext.headers().event().contextualOwner() – Returns the owner in whose context the request is executing.

Get network and request context

dnpContext.headers().event() – Returns detailed metadata about the incoming event or request.
dnpContext.headers().event().processNetworkNodeId() – Returns the process network node ID of the request.

dnpContext.headers().event().partnerNetworkNodeId() – Returns the partner network node ID of the request.
dnpContext.headers().event().serviceId() – Returns the service ID used by the request.
dnpContext.headers().event().licensePlate() – Returns the license plate associated with the request.

Read configuration and values

dnpContext.configuration() – Returns a value from the application's configuration.
dnpContext.configuration().getString(keypath) – Returns a string at the given keypath.
dnpContext.configuration().getNumber(keypath) – Returns a number at the given keypath.
dnpContext.configuration().getBoolean(keypath) – Returns a boolean at the given keypath.

Log messages

dnpContext.log() – Generic logging entry point.
Log visibility order, from most visible to least visible,is error, warn, info, and debug.
dnpContext.log().error() – Writes an error log.
dnpContext.log().warn() – Writes a warning log.
dnpContext.log().info() – Writes an informational log.
dnpContext.log().debug() – Writes a debug log.

Send events and messages

dnpContext.transport() – Sends an event or message.
dnpContext.transport().events().send(endpoint, application, payload) – Sends a payload to another application at the specified endpoint.

Tag end