🧱Building blocks
What are building blocks?
Building blocks let you package a reusable subprocess with its own data model and version it separately from cases. This allows them to use their own data and configuration. You can use the same building block in multiple case definitions and across environments, while keeping a clear input and output contract.
Building blocks are isolated by design. They should not directly read or write case data. Instead, you define the inputs and outputs when you link them to a case. This isolation ensures that building blocks remain reusable and maintainable across different contexts.
The building block lifecycle follows these steps:
Create a building block definition (name, version, description).
Define the data it needs and the data it produces.
Add the processes and choose the main process.
Link the building block to a Call activity in a case process.
Map inputs and outputs, and choose when outputs are synced.
When to use building blocks
Building blocks are useful when:
The same subprocess is needed in multiple cases.
You want one place to update a shared step.
You want a consistent way to pass data in and get results back.
Example: A "Household verification" building block can be used in both subsidy and permit cases. Each case passes in the citizen data, the building block runs the checks, and the outcome is synced back to the case.
This feature is different from the Process Exchange building blocks that you download and copy into projects. For those, see Process Exchange building blocks.
Creating a building block
1. Create the definition
Go to Admin in the left sidebar.
Select Building blocks.
Click Create.
Enter a Name, Version, and (optional) Description.
Click Save.
2. Add general information
Open the General tab.
Optionally upload Artwork.
Review the list of Plugins used so you know which plugin types must be configured later. Initially, the list will be empty. This will be updated as you add plugins or other building blocks to the processes of your building block.
3. Define the data fields
Open the Document tab.
Add the fields the building block needs (inputs) and may return (outputs) and any other data the building block will need to use internally.
Mark fields as required if the case must provide them when using the building block. Required fields must be mapped in the input mapping when linking the building block to a case.
Click Save.
4. Add processes
Open the Processes tab.
Either Upload a BPMN file or Create a new process.
Select which process should be the Main process for the building block, or use the process that has been created with the building block.
You can use plugins in these processes just like in case processes, but you select the plugin type instead of a specific configuration.
When a building block has multiple processes, you can create call activities from one process to another. Set the process definition key (the Key value shown in the processes list) and include a reference to the current building block in the Version tag field. The version tag has the format
BB:<building-block-key>:<building-block-version>.
User tasks are not yet supported in building blocks. This means form, form flow, and custom UI component process links cannot be used. Only plugin and building block process links are available.
5. Finalize the version
Building blocks use draft and final versions, similar to case definitions.
Before you finalize, test the building block thoroughly. Final versions cannot be changed.
In the More menu, choose Make version final to lock the version.
To make changes later, create a new draft from a final version.
Only final building blocks can be used when finalizing a case definition.
Using a building block in a case
1. Add a Call activity
Open the case process where you want to use the building block.
Add a Call activity to the process model.
2. Link the building block
Open the Process link for the Call activity.
Choose Building block as the link type.
Choose the Building block you want to use.
3. Configure plugin mappings
Select the building block Version you want to use.
If this version uses plugins, you must map each plugin type to a plugin configuration that already exists in your environment.
Select the saved plugin configuration for each plugin type.
4. Map inputs and sync outputs
Map Inputs from the case data to the building block fields.
All required fields (marked as required in the building block document definition) are listed by default and must be mapped.
Any optional inputs can be added manually by clicking Add input.
Map Outputs from the building block back to the case.
Fields can be added for syncing by clicking Add sync.
When the building block completes, the specified fields are written from the building block back to the case document.
This is one way. Any changes to the case document will not be automatically synced to the building block instance.
5. Save and deploy
Click Complete to save the process link.
Save and deploy the updated case process.
Import and export building blocks
Building blocks are automatically included in case definition exports. You can also export or import a building block separately when you want to move or reuse it on its own.
Import
Before importing, make sure any required process definitions or plugin configurations already exist in your environment.
Go to Admin → Building blocks.
Click Upload.
Select a
.zipexport file.Confirm the overwrite warning. This will replace all existing resources (document definition, processes, and settings) for this building block version if it already exists in your environment.
Follow the steps in the wizard.
Export
Open a building block.
Click More → Export.
Related
Cases - Building blocks are used within case processes
Plugins - Building blocks can use plugin types
Processes - Understanding process links and call activities
Process Exchange building blocks - Different type of building blocks
Last updated