Starting a Process

A process instance can be started manually or automatically. Manual start is triggered by an employee from the Tasks page. Automatic start is triggered by an entity lifecycle event — for example, when a deal is created or a document is updated.

Manual start

An employee opens the Tasks page and chooses Start Process. The dialog lists the active processes that the employee is allowed to launch.

If the process has a start form, the employee fills it in before starting. The form values become process variables available to the first step.

Who can launch a process

Launch permissions are controlled per process through the Roles & Access tab on the process detail page.

Each employee role can be granted or denied the right to launch a specific process. An employee can launch a process only if at least one of their roles has been granted launch access to that process.

Launch access is independent of the read, update, and delete permissions on the process record itself. An employee who can view a process definition cannot necessarily launch it.

Automatic start on entity events

CityScreen Deals fires a signal event whenever certain entities are created, updated, or change state. A process can listen for these signals by modeling a Signal Start Event with a matching signal name.

Signal naming convention

The signal name follows the pattern:

entity_<entityType>_<eventType>

Where:

  • <entityType> is the machine name of the entity type. For built-in types, use the lowercase name (for example, deal). For administrator-defined types (documents, proposals, directories, counterparties), use the machine name assigned when the entity type was created.

  • <eventType> is the lifecycle event: create, update, or state (for deal stage changes).

Examples:

  • entity_deal_create — fires when a new deal is created.

  • entity_deal_state — fires when a deal changes stage.

  • entity_PRINTED_INVENTORY_PROPOSAL_create — fires when a new proposal of the type with machine name PRINTED_INVENTORY_PROPOSAL is created.

  • entity_contract_update — fires when a document of the type with machine name contract is updated.

The signal name must match exactly, including capitalization. A typo in the signal name means the process does not start.

How to model an automatic start

  1. Add a Signal Start Event to the diagram (replacing or alongside the plain start event).

  2. Open the generic properties panel for the signal event.

  3. Set the signal name to the exact entity_<entityType>_<eventType> string.

Signal variables

When a signal fires, the event data is passed to the new process instance as process variables. The available variables depend on the entity type and the event type. These variables can be read by subsequent tasks and scripts in the process.

Catching signals in a running process

A signal can also be caught by a running process instance using a Signal Intermediate Catch Event or a Signal Boundary Event. This lets a process wait for a specific entity event before continuing.

The same naming convention applies — the signal name on the catch event must match the pattern exactly.

Process automation prerequisites

The process automation module must be enabled for the organization by CityScreen staff before processes can be started. Entity lifecycle signals are not fired unless the module is enabled, so automatic starts will not trigger even if the diagram is correctly configured.