Article published on the 9th of February, 2023.
In some circumstances it can be helpful to be able to change the stage of multiple entities such as projects or cases in a single action.
This process is referred to as "Batch changing stages".
Using the "Batch change stage" WorkPoint Automate step, it is possible to create a process which can change the stage of multiple entities.
In this article we will give an example of how such a process could be configured. We will use two steps; a Stage form and a Batch Change Stage step. The stage form is used to select the target stage for the entities and the Batch Change Stage step is then used to change the stage of each entity.
Note that batch stage change requires that the selected entities are currently in the same stage
There are no requirements associated with the use of the Batch Change Stage-related steps which make up the Batch Change Stage process.
3.1. Process configuration
For this example, we will first use a Stage form. This form will allow users to select the target stage to which the selected entities should transition. We are configuring the process specifically to change the stage of entities on the Projects business module. We will select which projects to change the stage of from the Express panel using a Search Setting.
The general options for the Stage form are configured as follows:
The options in the "Properties" tab are configured as follows:
The combination of the "Business module" and "Entity" fields makes it possible for the system to identify which stages are eligible for transition. By selecting the Projects business module and any of the entities selected for stage change, the form is able to show the user options for selecting a target stage.
In the "Entity" field specifically, we use the following adaptive expression to select the first entity selected for stage change:
The entities we select in the Express panel when starting the Batch Change Stage process are stored in the "Items" context array. This expression grabs the ID property of the first element in the array of projects and passes that into the "Entity" field.
Lastly, we disallow stage model transitioning.
Next, we add the "Batch Change Stage" step to the process:
The general settings for the Batch Change Stage step are kept default as follows:
The options in the "Options" tab are configured as follows:
The "Business module" and "Entities" fields are used for letting the system know which entities we want to change the stage of. In this instance we select the Projects business module, and in the "Entities" field we pass in the entire array of entities we have selected in the Express panel via the "Items" array from the Context of the process.
The "Stage model ID" and "Stage ID" fields are used to let the system know the target stage of the entities we have selected. In this instance, we pass in the stage model and target stage from the previous Stage form step. The Projects module does not use sub-stages, so we leave the "Sub-stage ID" field blank. If the module used sub-stages, we would pass in the selected sub-stage form the Stage form step.
In the "Run the action as" field we can select to run the Batch Change Stage in Synchronous- or Asynchronous mode:
- Synchronous: change stage is performed directly by the WorkPoint API.
- Asynchronous: a web job is started which handles the stage changes. This is useful if you expect that the process will be used to change the stage of many entities - so many that the WorkPoint API might time out during the process.
The rest of the options in the other tabs are kept at default.
This concludes the configuration of the Batch Change Stage process. In the next section, we will set the button up to be used in the Express panel.
3.2. Setting up process for the Express panel
For the purpose of this example, we have created a Search Setting called "Projects".
This Search Setting is configured as follows:
For this article, the most important setting on the Search Setting is the "Process configurations" field. Here we can configure which processes should be available for execution from the Express panel when this search setting is active. In this example, we have selected the Batch change stage process. When one or more processes are set in this field, the Search Setting in the Express panel will display checkers next to search results, making it possible to select one or more element. The processes selected in this field are then available in the "Send to"-menu, as we will see in a moment.
3.3. Executing the Batch Change Stage process
In this section, we will execute the Batch Change Stage process and change the stage of two projects at the same time.
First, we open the Express panel in our WorkPoint solution and navigate to the "Projects" search setting:
We can now select the projects for which we want to change stages:
- We click the checkers to select the two projects we want to change the stages of.
- To execute the Batch Change Stage process, we now click the "Send to" button.
- In the "Send to"-menu, we click the "Batch change stage" process. This menu would display any process set in the "Process configurations" field of the search setting.
This opens the "Batch Change Stage" process:
- In the stage form, we select the "Closed" stage.
- To proceed to the next step and change the stages of the projects, we click "Continue".
- Progress of the stage changes can be followed in the main process window.
Once the process is completed, it should display the "Process succeeded" finish step:
The projects we selected should now be in the "Closed" stage: