Sending notifications from Citeck BPMN (Camunda)

General Description

To send notifications from a BPMN process, the Send Task element is used — a special component of the Citeck platform.

Despite the name, Send Task in Citeck is not a standard BPMN Send Task: its behavior is entirely defined by Citeck extensions and implements sending notifications via the ecos-notifications microservice.

Notifications are sent via ecos-notifications.

Do not send notifications directly from microservice code or process scripts, bypassing ecos-notifications.

Important

Currently, only the EMAIL_NOTIFICATION notification type is supported in BPMN Send Task. Specifying any other type will cause an error when saving or publishing the process.

See the description of the Notifications component

XML Representation of Send Task

In the XML BPMN file, Send Task is described via the <bpmn:sendTask> element with attributes from the ecos: namespace (xmlns:ecos="http://www.citeck.ru/ecos/bpmn/1.0").

Example — notification with role-based recipients:

<bpmn:sendTask
  id="Activity_notify_initiator"
  name="Уведомление инициатору"
  ecos:notificationType="EMAIL_NOTIFICATION"
  ecos:notificationTemplate="notifications/template@ecos-contract-approval-notification-template"
  ecos:notificationLang="ru"
  ecos:notificationTo="[&quot;initiator&quot;]"
  ecos:notificationToExpression="[]"
  ecos:notificationCc="[]"
  ecos:notificationCcExpression="[]"
  ecos:notificationBcc="[]"
  ecos:notificationBccExpression="[]"
  ecos:notificationSendCalendarEvent="false"
  ecos:notificationAdditionalMeta="{}">
</bpmn:sendTask>

Example — notification with a dynamic recipient from a process variable:

<bpmn:sendTask
  id="Activity_notify_confirmer"
  name="Уведомление согласующему"
  ecos:notificationType="EMAIL_NOTIFICATION"
  ecos:notificationTemplate="notifications/template@ecos-contract-approval-notification-template"
  ecos:notificationLang="ru"
  ecos:notificationTo="[]"
  ecos:notificationToExpression="[&quot;${confirmer}&quot;]"
  ecos:notificationCc="[]"
  ecos:notificationCcExpression="[]"
  ecos:notificationBcc="[]"
  ecos:notificationBccExpression="[]"
  ecos:notificationSendCalendarEvent="false"
  ecos:notificationAdditionalMeta="{}">
</bpmn:sendTask>

Example — notification with an explicit sender specified from ecos-config:

<bpmn:sendTask
  id="Activity_notify_with_from"
  name="Уведомление инициатору о создании заявки"
  ecos:notificationType="EMAIL_NOTIFICATION"
  ecos:notificationTemplate="notifications/template@sd-request-create"
  ecos:notificationLang="ru"
  ecos:notificationFrom="${Config.getNotNull(&quot;app/service-desk$send-sd-email-from&quot;).asText()}"
  ecos:notificationTo="[&quot;initiator-role&quot;]"
  ecos:notificationToExpression="[]"
  ecos:notificationCc="[]"
  ecos:notificationCcExpression="[]"
  ecos:notificationBcc="[]"
  ecos:notificationBccExpression="[]"
  ecos:notificationSendCalendarEvent="false"
  ecos:notificationAdditionalMeta="{}">
</bpmn:sendTask>

Send Task Attributes

Main Attributes

Attribute

Description

ecos:notificationType

Notification type. Only EMAIL_NOTIFICATION is supported.

ecos:notificationTemplate

Reference to the notification template in the format notifications/template@<id>. Mutually exclusive with ecos:notificationTitle / ecos:notificationBody.

ecos:notificationTitle

Email subject directly (without a template). Static text only, no dynamic variables.

ecos:notificationBody

Email body directly (without a template). Static text only.

ecos:notificationLang

Template language: ru, en, etc. If not specified, the default language is used.

ecos:notificationFrom

Outgoing sender address. Can be specified directly or via an expression. If not specified, the default value from ecos-notifications settings is used. Supported formats:

  • someAddress@mail.com

  • "Some Name" <someAddress@mail.com>

  • ${someExpressionToGetAddress}

  • ${Config.getNotNull("app/your-app$your-key").asText()}

ecos:notificationAdditionalMeta

A JSON object with additional variables available in the template. A value starting with !str_ is passed as a string constant. Example: {"myKey": "!str_someConstant"} — available in the template as ${myKey} with the value someConstant.

Recipients

Recipients are defined as JSON arrays of strings. The *To, *Cc, *Bcc attributes accept role names of the document; the *ToExpression, *CcExpression, *BccExpression attributes accept expressions (username, email, recordRef, or ${variable}).

Attribute

Description

ecos:notificationTo

JSON array of recipient roles. The platform resolves the email of all users in the role. Example: ["initiator", "lead-tech-role"]

ecos:notificationToExpression

JSON array of expressions for recipients. Example: ["${confirmer}", "${assigneesOfCurrentLine}"]

ecos:notificationCc

JSON array of roles for carbon copy (CC).

ecos:notificationCcExpression

JSON array of expressions for carbon copy.

ecos:notificationBcc

JSON array of roles for blind carbon copy (BCC).

ecos:notificationBccExpression

JSON array of expressions for blind carbon copy.

Roles and expressions can be combined: static roles in *To, dynamic ones in *ToExpression.

Recipient formats in *Expression attributes:

  • ivan.petrov — username

  • ivan.petrov@company.com — email address directly

  • GROUP_company_accountant — group (the first email is selected)

  • emodel/authority-group@company_accountant — group recordRef

  • emodel/person@ivan — user recordRef

  • ${someVariable} — a process variable containing any of the above values

  • ${someService.getEmails()},petya.voks — multiple values separated by a comma

Calendar Invitation (iCal)

Send Task supports sending an iCal attachment (calendar invitation) together with the email.

<bpmn:sendTask
  id="Activity_meeting_invite"
  name="Приглашение на встречу по согласованию"
  ecos:notificationType="EMAIL_NOTIFICATION"
  ecos:notificationTemplate="notifications/template@contract-meeting-notification"
  ecos:notificationTo="[&quot;initiator&quot;]"
  ecos:notificationToExpression="[]"
  ecos:notificationCc="[]"
  ecos:notificationCcExpression="[]"
  ecos:notificationBcc="[]"
  ecos:notificationBccExpression="[]"
  ecos:notificationLang="ru"
  ecos:notificationSendCalendarEvent="true"
  ecos:notificationCalendarEventSummary="Встреча по согласованию договора"
  ecos:notificationCalendarEventDescription="Необходимо согласовать договор №${docNum}"
  ecos:notificationCalendarEventOrganizer="{&quot;role&quot;:&quot;initiator&quot;}"
  ecos:notificationCalendarEventDate="${meetingDate}"
  ecos:notificationCalendarEventDuration="PT1H"
  ecos:notificationAdditionalMeta="{}">
</bpmn:sendTask>

Attribute

Description

ecos:notificationSendCalendarEvent

Enable sending a calendar invite: true / false.

ecos:notificationCalendarEventSummary

Calendar event title. Supports expressions: ${someVar}.

ecos:notificationCalendarEventDescription

Event description. Supports expressions: ${someVar}.

ecos:notificationCalendarEventOrganizer

Organizer. A JSON object with a role or expression field.

  • By role: {"role": "initiator"}

  • By expression: {"expression": "ivan.petrov@company.com"}

If the role contains multiple users, the first email is used.

ecos:notificationCalendarEventDate

Event start date. A process variable of type Instant or an ISO 8601 string. Example: ${meetingDate} or 2025-12-01T10:00:00Z. The organizer’s time zone is used when creating the event.

ecos:notificationCalendarEventDateExpression

An alternative to ecos:notificationCalendarEventDate — an expression for computing the date. Must return java.util.Date, String (ISO 8601), or null.

ecos:notificationCalendarEventDuration

Event duration in ISO 8601 format. Examples: PT15S, PT1H30M, P14D.

ecos:notificationCalendarEventDurationExpression

An alternative to ecos:notificationCalendarEventDuration — an expression for computing the duration.

Notification Template

The template reference is specified in the ecos:notificationTemplate attribute in the format:

notifications/template@<template-id>

Where <template-id> is the template identifier matching the artifact directory name.

For details on creating templates, see Notification Templates.

Template Variables

The following are available in the template:

  1. Document attributes — resolved via the model field of the template meta file.

  2. Process variables — via $process.<variable name> in model.

  3. Event variables (for event sub-processes) — via $process.event.<attribute>.

  4. Contextual variables:

    Expression in model

    Description

    $now

    Current date and time.

    $user

    Current system user.

    $process.webUrl

    Process URL.

    $process.someVar

    Process variable someVar.

    $process.event.text

    Attribute of the event that triggered the notification. For example, the comment text.

    $process.event._meta.id

    Event ID.

    $process.event._meta.type

    Event type.

    $process.currentRunAsUser

    The user on whose behalf the process is running.

    $str.<CONSTANT>

    A string constant without evaluation. Example: $str.APPROVED → "APPROVED".

Example model for a notification triggered by a comment-added event:

{
  "documentDisp":    ".disp",
  "documentCreated": "_created",
  "now":             "$now",
  "user":            "$user",
  "commentText":     "$process.event.text",
  "eventType":       "$process.event._meta.type",
  "currentRunAsUser": "$process.currentRunAsUser"
}

To attach attachments from the event (e.g., files from a comment):

{
  "_attachments": "$process.event.attachments[]._as.ref._content{bytes,meta:?json}"
}

Additional Model (additional meta)

Via ecos:notificationAdditionalMeta, additional data can be passed to the template without extracting it from the document or process via model.

  • The key is the name of the variable available in the template.

  • Value:

    • If it starts with !str_, the characters after the prefix are passed as a string constant.

    • Otherwise, the string is treated as a recordRef, and the platform attempts to load attributes by this ref.

Example:

{
  "myConstant": "!str_someValue",
  "relatedDoc":  "emodel/some-type@some-id"
}

In the template, ${myConstant} will return someValue.