Skip to end of metadata
Go to start of metadata

Expand/Collapse All


A custom workflow is made by creating a workflow definition in a BPMN model in Enterprise Studio, and then uploading this definition to HoriZZon. After that, the custom workflow is available for use in HoriZZon.

Required roles

Designer or Lead Designer: Create workflow definitions.

Lead Designer: Upload workflow definition to HoriZZon.

On this page:

Custom workflow configuration

A workflow definition always consists of the following diagram types, which specify the different aspects for a custom workflow:

  • Workflow diagram (or process diagram) for defining the order of the tasks in the workflow.
  • Forms diagram for defining the workflow data. In the Forms diagram you define the fields that must be available when a workflow task is performed.
  • Resources diagram for defining the participants of the workflow.

After defining the above and uploading the workflow definition, the custom workflow will be available in all sites, based on any model package or project, and on any diagram, view, object, or relation in the site. If you do not want the workflow to be generally available, you can set a scope. With a scope, you can define what the workflow is about, for example applications or a specific type of view. With a scope, the workflow will only be available on the object type or relation type, or view/diagram type that you have specified. To set the scope of a workflow, the following diagram also needs to be created:

  • Metadata diagram for defining the workflow data.

Way of working

There is no prescribed order in which the different diagrams need to be defined. Depending on the purpose of your workflow, you can define the aspect that is most relevant to you at first. For example, if you want to create a multi-level approval of a new architectural model you can start by defining the roles that are involved in that approval (Resources diagram), then create a lane for each role in the process model and define user tasks in the appropriate lanes (Workflow diagram). Finally, you define the data for the workflow (Forms diagram and Metadata diagram).

On the other hand, if the goal of the workflow is to collect information about objects in a model from across the organization you might want to start with defining the data form fields (Forms diagram and Metadata diagram), then think about the different tasks to collect that information (Workflow diagram) and only then define the roles that should provide that information (Resources diagram).

In any case, defining a custom workflow involves some going back and forth between the different aspects and diagrams.

To illustrate the procedure to create a custom workflow, the following example is used.


We want to create a custom workflow Application Survey. In this workflow application owners are requested to fill in the quarterly costs of applications, their business value, technical value, and risk. After that the survey needs to be approved by a portfolio manager. Finally, after approval the survey results need to be processed by an architect. The workflow looks as follows:

The workflow definition created in Enterprise Studio for this custom workflow is shown in the following figure.

In the following procedures, the workflow definition containing the above files is created, resulting in a custom workflow. The existing example model package "Archisurance & portfolios" is used as basis for the workflow definition.

Creating a BPMN model with a workflow diagram

  1. Go to File > New > BPMN, select 4. Empty model with workflow diagram, and name the model.

    Instead of creating a new BPMN model package, you can also choose to open an existing model package (of any metamodel), and then add a BPMN model with a workflow diagram to it. That may be useful if you want to use data from the existing model package for defining the data for your workflow (in the Metadata diagram).

  2. Right-click the newly created BPMN model, select New > Metadata diagram, and name the diagram.

  3. Repeat step 2 for the Forms diagram and Resources diagram.

  4. Save the model package on HoriZZon.

    If you do not save the model package on HoriZZon, you will not be able to define the participants for the workflow and upload the workflow definition to HoriZZon.

Your BPMN model now includes all four diagram types.


Following the example workflow, the result can be as follows:

Defining the workflow data

The workflow data is defined in the Metadata diagram and Forms diagram. The first is for specifying what the workflow is about (the subject or scope), the latter for the fields that must be available in the workflow events and the tasks that are performed. Specifying the scope of the workflow is optional. It is only needed if the tasks of the workflow should be limited to a specific diagram/view type, object type or relation type.

Defining the workflow subject in the Metadata diagram (optional)

You need to define one metaobject (or metarelation) for the workflow, and specify the object data you need. If you are creating multiple custom workflows, it is possible to place multiple metaobjects in one Metadata diagram, each metaobject having its own workflow.

  1. In the model browser, click the Metadata diagram to open it.

  2. Add a metaobject to the diagram.

    If you are working in an empty model package, use the Create pane or the quick-create pop-up window, and define the object type in the metaobject's properties. How?

    If you are working in a model package with data, select the model object of the type you want to add to the diagram in the model browser, and drag it onto the diagram. Example:

  3. Optional: If you are going to need specific properties from the metaobject that you want to use in fields in your workflow, then add one or more attributes, metrics, or tags to the metaobject. Select the metaobject, click the control of a property type, and select the desired property.


For the example workflow definition, the following properties are added:

Defining workflow fields in the Forms diagram

Simplest way is to just add all fields that are needed for the workflow tasks and events to one form in the diagram. You just create one form for all tasks and events in the workflow, and then add all fields used for these tasks and events to this form. However, you can also choose to add more structure by creating multiple forms, for example one form with fields for each task and event in the workflow.

You can define two types of fields:

  • entry fields in which users can add a value of the specified data type
  • selection fields with a closed list of values

It is not possible to retrieve single values from object properties into a workflow field.

If you do not use a scope for the workflow, make sure to only define fields that are not object-related, like a username or registration date. Do not use fields with object properties.

  1. In the model browser, click the Forms diagram to open it.

  2. Add one or more forms to the diagram, and name them.


  3. Only if you use a workflow scope: Select the form, click  to open the form properties window, and set the created metaobject as the subject of the form.


  4. Define the fields for the form(s). Click  to add a field.


  5. Click the box  in front of the field to open the properties window, and define the field.


    1. In Label, specify the label for the field. It is the name of the field shown in the workflow when used in HoriZZon.

    2. In Category, select the data type for the field.

      If you want to define a data entry field, choose one of the following data types:

      String: Users can enter text and numbers.
      Integer: Users can enter a whole numerical number.
      Real: Users can enter a real number.
      Boolean: Users can enter Yes or No.
      Date: Users can enter a date.
      Money: User can enter an amount.
      Model object: Users can select an object from the models present in the model package.
      User: Users can select a user from the list of Team users, as defined in the Resources diagram.
      Group: Users can select a Team group from the list of Team groups, as defined in the Resources diagram

      If you want to define a selection field with a closed list of values, do one of the following:

      Define your own list: Select data type Enumeration, and in Options, add the labels and their associated values below Label and Value. The labels are shown in the field when used in the workflow in HoriZZon, the values can be used for condition expressions in the workflow process, if desired. When adding a label and then pressing the Tab key, an associated value is automatically added. You can adjust the value name if you wish to.

      Use an existing closed list of values from an object attribute or metric: Ignore Category, activate Is linked, and in Subject property, select an attribute or metric from the metaobject that has a closed list of values. Examples of objects in the ArchiMate metamodel that have an attribute with a closed list, are:

      Any ArchiMate object: 
      property "value" (via 'the "Asset" profile)
      Assessment: property "standard assessment type"
      Risk (risk object)property "risk factor"
      Vulnerability (risk object): property "vulnerability level"
      Control measure (risk object): property "control strength"

    3. Optional: In Value, you can set a default value for the field. It will be shown in the field when working with the workflow in HoriZZon. The value that can be entered depends on the selected data type.


Following the example workflow definition, the following forms are added:

Defining the workflow participants

Determine who will be performing the workflow tasks, and who should be able to see the workflow request (users and groups), and define their roles. A role represents the group of users or single user who will be able to see the request or perform a task.

Basically you can just add the roles, users and groups in one diagram, and link them together. However, if you want to reuse users and/or groups in multiple roles and workflows, then add the users and groups to a separate resources diagram, and link them from that diagram to the roles in other diagrams.

  1. In the model browser, click the Resources diagram to open it.

  2. Add a resource role to the diagram for each role that you want to define, and name each resource role.


  3. Add users and/or groups from Team Platform to the diagram. Easiest way to add them is by importing them. Click the import control in the diagram menu, and then in the selection window click  next to a user or group to import it.

    Only users and groups who have the Contributor role are available for selecting.


    Alternatively, you can manually add users and groups to the diagram, and then link them to the associated Team Platform users/groups in HoriZZon by in the selection window clicking  next to a user or group.


  4. Attach the users and/or rule to the right role. Select a resource role, click and select a user or group.


Following the example workflow definition, the following roles are defined:

Defining the workflow order

The order of the tasks in the workflow is defined in the Workflow diagram. The name of the Workflow diagram will be the name of the workflow in the menu in HoriZZon.

  1. In the model browser, click the Workflow diagram to open it.

  2. Model your workflow process by adding lanes, a start event, an end event, and one or more tasks. Name the tasks. If desired, you can include gateways and set condition expressions for them, as is shown in the figure below.

    If different tasks need to be performed by different roles, make sure these tasks are in different lanes, so that each role can be linked to the right task.


  3. Assign roles to the tasks by linking the roles to the lanes. Select a lane, click , and select a resource role. Do this for each lane that needs a role.


  4. Only if you use a workflow scope: Link the workflow process to the defined metadata.
    1. Select the start event, and click .

    2. On the Start event tab, in Subject, select the defined metaobject.

  5. Link the workflow process to the form containing the field(s) needed at the workflow start.

    1. On the Form tab, in Form definition, select the form that must be available at the start of the workflow.


    2. Specify which fields from the form need to be available at the workflow start. By default, all fields are visible, required to fill, and editable in the workflow request in HoriZZon. Make the desired changes by first clicking a field name and then clicking a  next to an option to deactivate it.

      Is required: When activated, the field must be filled when visible in the workflow in HoriZZon. Deactivate if the field should be optional to fill.
      Is editable: When activated, the field is editable when visible in the workflow in HoriZZon. Deactivate if the field should be read-only.
      Is included: When activated, the field is visible in the workflow in HoriZZon. Deactivate if the field is not needed and should therefore not be visible.


  6. For each task in the process, specify the form that must be available for that task, and specify which fields must be available.

    1. Select a task, and click .

    2. On the Form tab, in Form definition, select the form.

    3. For each field in the form specify whether it needs to be visible, editable and/or required by clicking a field name and then clicking a  next to an option to deactivate it.


  7. Optional: If a user must be notified by e-mail when assigned a task, click the  next to E-mail notification to activate it. Do this for each task the user needs to be notified by mail.

  8. Optional: If the performer of a task should be determined during execution of the process, determine the performer of the task.

    On the Task tab, in Form field, select a user field, or select a performer of a preceding task (or the start event for assigning the task to the requester of the process) in Preceding performer

  9. Set the workflow version. In the model browser, select the Workflow diagram, click the Properties tab of the diagram's Properties window, and in Workflow version, enter a version for the workflow definition.


  10. Validate the workflow definition to check for errors. Open the canvas menu of the Workflow diagram, and click .


  11. If validation is successful, it is shown in a dialog and in the Messages window. Close the dialog. The workflow definition is now ready to be uploaded to HoriZZon.

    If validation is not successful, errors are shown in the Messages window. Fix the errors, and revalidate the workflow when you are ready.

Uploading the workflow definition to HoriZZon

When your workflow definition is complete, it can be uploaded to HoriZZon. Once uploaded, the custom workflow is automatically available on the Workflows page in HoriZZon, and is ready to be used.

  1. Open the canvas menu of the Workflow diagram, and click .


  2. When upload is successful, it is shown in a dialog. Close the dialog.

The uploaded diagram now shows information about the status and version of the uploaded workflow definition.

In HoriZZon, the new workflow is available on the Workflows page:

Administrator users can manage the custom workflow in HoriZZon, like changing the workflow code and icon.

Making changes to an existing workflow definition

If you make any changes to an existing workflow definition, validate the changes, change the workflow definition version, and re-upload the updated definition to HoriZZon in order to make it available in HoriZZon. When updating workflows, please take note of the following:

  • New workflow requests in HoriZZon that are started after uploading the new version will run in the new version.
  • Running workflow requests will continue to run in the version they were started in.