Enmasse reference - GitOps for Zato configuration

The full reference of all options available in enmasse YAML configuration files.

This chapter is a reference for all the options available in enmasse YAML files, the platform's GitOps configuration format. For an overview of enmasse, see the enmasse overview page.

REST channels

Key: channel_rest


Name	Required	Description
`name`		Unique name of the REST channel
`service`		Name of the Zato service that the channel invokes
`url_path`		URL path that the channel listens on, e.g. `/api/v1/my-endpoint`
`security`		Name of a security definition to protect the channel with
`is_active`		Whether the channel accepts requests (default is `true`)
`method`		HTTP method the channel accepts, e.g. `GET` or `POST` (if omitted, all methods are accepted)
`data_format`		Expected data format of incoming requests, e.g. `json`
`content_type`		Content type that the channel expects in incoming requests
`timeout`		Request timeout in seconds
`groups`		List of security group names whose members are allowed to call this channel
`is_audit_log_active`		Whether the channel's traffic goes to the audit log (default is `true`, exported only when `false`)
`rate_limiting`		Rate limiting rules - see rate limiting on REST channels
`response_cache`		Response caching configuration - see response caching on REST channels
`is_deprecated`		Whether the channel is marked deprecated - it keeps serving but announces the deprecation in response headers (default is `false`)
`deprecation_sunset`		The retirement date announced in the `Sunset` response header, e.g. `2027-06-30`
`deprecation_successor`		URL of the replacement endpoint, announced in the `Link` response header
No matches

channel_rest:
  - name: enmasse.channel.rest.1
    service: demo.ping
    url_path: /enmasse.rest.1

  - name: enmasse.channel.rest.2
    service: demo.ping
    url_path: /enmasse.rest.2
    security: enmasse.basic_auth.1
    data_format: json

More details in the REST channels chapter.

Rate limiting on REST channels

Rate limiting is configured as a nested rate_limiting key inside each channel_rest entry. It is a list of rules, evaluated top to bottom. The first rule whose address list matches the client IP is used. Within each rule, time ranges are checked in order, and the all-day default applies when no specific time range matches.

Each rule contains:

Name	Required	Description
cidr_list	---	List of IP addresses or ranges, e.g. `10.0.0.0/8` or `192.168.1.10`. If empty, the rule matches all clients.
time_range	Yes	List of time range entries (see below). The first entry must be the all-day default (`is_all_day: true`).

Each time range entry contains:

Name	Required	Description
is_all_day	Yes	`true` for the all-day default, `false` for a specific time range
time_from	---	Start time in `HH:MM` format (required when `is_all_day` is `false`)
time_to	---	End time in `HH:MM` format (required when `is_all_day` is `false`)
disabled	Yes	If `true`, the time range is skipped during evaluation
disallowed	Yes	If `true`, matching requests are silently dropped at the TCP level
rate	Yes	Requests per second (sustained)
burst	Yes	Maximum burst size before throttling
limit	Yes	Hard cap on total requests within the time unit
limit_unit	Yes	Time unit for the hard cap - one of `second`, `minute`, `hour`, `day`, `month`

channel_rest:

  # Simple channel with 200 requests per minute, burst up to 50/s
  - name: crm.customer.get
    service: crm.customer.get-details
    url_path: /api/v1/customers
    rate_limiting:
      - cidr_list: []
        time_range:
          - is_all_day: true
            disabled: false
            disallowed: false
            rate: 50
            burst: 50
            limit: 200
            limit_unit: minute

  # Internal IPs get generous limits, everything else is silently dropped
  - name: billing.internal.sync
    service: billing.sync
    url_path: /internal/billing/sync
    rate_limiting:
      - cidr_list:
          - 10.0.0.0/8
          - 172.16.0.0/12
        time_range:
          - is_all_day: true
            disabled: false
            disallowed: false
            rate: 100
            burst: 200
            limit: 50000
            limit_unit: hour
      - cidr_list: []
        time_range:
          - is_all_day: true
            disabled: false
            disallowed: true
            rate: 0
            burst: 0
            limit: 0
            limit_unit: minute

  # Higher limits during the nightly batch window, stricter during the day
  - name: warehouse.inventory.update
    service: warehouse.inventory.bulk-update
    url_path: /api/v1/inventory
    rate_limiting:
      - cidr_list: []
        time_range:
          - is_all_day: true
            disabled: false
            disallowed: false
            rate: 20
            burst: 50
            limit: 5000
            limit_unit: hour
          - is_all_day: false
            time_from: "01:00"
            time_to: "03:00"
            disabled: false
            disallowed: false
            rate: 200
            burst: 500
            limit: 100000
            limit_unit: hour

  # Block a specific range, allow everyone else at 100/minute
  - name: public.search
    service: search.query
    url_path: /api/v1/search
    rate_limiting:
      - cidr_list:
          - 198.51.100.0/24
        time_range:
          - is_all_day: true
            disabled: false
            disallowed: true
            rate: 0
            burst: 0
            limit: 0
            limit_unit: minute
      - cidr_list: []
        time_range:
          - is_all_day: true
            disabled: false
            disallowed: false
            rate: 20
            burst: 40
            limit: 100
            limit_unit: minute

  # Strict daily budget - 10,000 requests per day, 10/s sustained
  - name: reports.generate
    service: reports.generate-pdf
    url_path: /api/v1/reports
    rate_limiting:
      - cidr_list: []
        time_range:
          - is_all_day: true
            disabled: false
            disallowed: false
            rate: 10
            burst: 20
            limit: 10000
            limit_unit: day

For a full explanation of all rate limiting concepts, see the Rate limiting and firewall chapter.

Response caching on REST channels

Response caching is configured as a nested response_cache key inside a channel_rest entry. On export, only the fields that differ from their defaults are written out.

Name	Required	Description
is_enabled	---	Whether the channel caches responses at all (default is `false`)
ttl	---	How long a cached response lives (default is `5`)
ttl_unit	---	Unit for the TTL - one of `seconds`, `minutes` or `hours` (default is `minutes`)
is_shared_across_callers	---	Whether all the callers share one cache entry or each caller has its own (default is `false`)
vary_by_headers	---	List of request headers whose values become part of the cache key
ignored_query_parameters	---	List of query parameters left out of the cache key
include_body_in_key	---	Whether the request body becomes part of the cache key (default is `false`)
max_body_size	---	The biggest response cached, in bytes (default is `1000000`)
cache_on_second_request	---	Whether a response is cached only once the same request repeats (default is `true`)
needs_etag	---	Whether cached responses include an `ETag` header (default is `false`)
coalesce_timeout	---	How long concurrent identical requests wait for the first one's response, in seconds (default is `15`)

channel_rest:

  - name: crm.customer.get
    service: crm.customer.get-details
    url_path: /api/v1/customers
    response_cache:
      is_enabled: true
      ttl: 10
      ttl_unit: minutes
      vary_by_headers:
        - X-Tenant-Id

The Response caching chapter explains all the fields in detail.

SOAP channels

Key: channel_soap

Name	Required	Description
name	Yes	Unique name of the SOAP channel
service	Yes	Name of the Zato service that the channel invokes
url_path	Yes	URL path that the channel listens on
security	---	Name of a security definition to protect the channel with
soap_action	---	SOAP action the channel responds to
soap_version	---	SOAP protocol version (default is `1.1`)
use_mtom	---	Whether the channel accepts MTOM attachments (default is `false`)
method	---	HTTP method the channel accepts (if omitted, all methods are accepted)
content_type	---	Content type that the channel expects in incoming requests
timeout	---	Request timeout in seconds
groups	---	List of security group names whose members are allowed to call this channel
is_audit_log_active	---	Whether the channel's traffic goes to the audit log (default is `true`, exported only when `false`)
rate_limiting	---	Rate limiting rules, in the same shape as on REST channels
response_cache	---	Response caching configuration, in the same shape as on REST channels

channel_soap:

  - name: enmasse.channel.soap.1
    service: demo.soap-input
    url_path: /soap/orders
    security: enmasse.basic_auth.1
    soap_action: urn:example:orders:create

  - name: enmasse.channel.soap.2
    service: demo.soap-attachments
    url_path: /soap/documents
    soap_version: "1.2"
    use_mtom: true

Outgoing REST connections

Key: outgoing_rest

Name	Required	Description
name	Yes	Unique name of the outgoing connection
host	Yes	Base host URL of the remote endpoint, e.g. `https://api.example.com`
url_path	Yes	URL path appended to the host when making requests, e.g. `/v1/endpoint`
security	---	Name of a security definition to use when connecting
data_format	---	Data format of outgoing requests, e.g. `json`
timeout	---	Request timeout in seconds (default is `60`)
ping_method	---	HTTP method used to ping the connection (default is `GET`)
pool_size	---	Size of the connection pool (default is `20`)
tls_verify	---	Whether to verify the remote TLS certificate (default is `true`)
content_type	---	Content type header sent with outgoing requests
is_audit_log_active	---	Whether the connection's traffic goes to the audit log (default is `true`, exported only when `false`)
max_retries	---	How many times a failed invocation is retried after a timeout, a connection error or an HTTP 429 response (default is `0`, i.e. no retries)
retry_sleep_time	---	How many seconds to sleep before the first retry (default is `2`)
retry_backoff_multiplier	---	Each retry sleeps this many times longer than the previous one, up to 8 seconds per a single sleep (default is `2`)
retry_backoff_threshold	---	A cap on the total time spent sleeping between retries, in seconds - once reached, no more retries take place (default is `60`)

The retry fields are exported only when they differ from their defaults.

outgoing_rest:
  - name: enmasse.outgoing.rest.1
    host: https://example.com
    url_path: /api/v1
    data_format: json
    timeout: 60

  - name: enmasse.outgoing.rest.2
    host: https://example.com
    url_path: /api/v2
    security: enmasse.bearer_token.1
    tls_verify: false

  # A connection that retries failed invocations - with these settings, a call that keeps failing
  # sleeps 2s, 4s, 8s, 8s and 8s between attempts before giving up, about 30 seconds in total.
  - name: enmasse.outgoing.rest.3
    host: https://example.com
    url_path: /api/v3
    max_retries: 5
    retry_sleep_time: 2
    retry_backoff_multiplier: 2
    retry_backoff_threshold: 60

Outgoing SOAP connections

Key: outgoing_soap

Name	Required	Description
name	Yes	Unique name of the outgoing connection
host	Yes	Base host URL of the remote endpoint, e.g. `https://api.example.com`
url_path	Yes	URL path appended to the host when making requests, e.g. `/v1/endpoint`
security	---	Name of a security definition to use when connecting
soap_action	---	SOAP action header sent with requests
soap_version	---	SOAP protocol version (default is `1.1`)
data_format	---	Data format of outgoing requests
timeout	---	Request timeout in seconds (default is `60`)
ping_method	---	HTTP method used to ping the connection (default is `GET`)
pool_size	---	Size of the connection pool (default is `20`)
tls_verify	---	Whether to verify the remote TLS certificate (default is `true`)
content_type	---	Content type header sent with outgoing requests
is_audit_log_active	---	Whether the connection's traffic goes to the audit log (default is `true`, exported only when `false`)
max_retries	---	How many times a failed invocation is retried after a timeout, a connection error or an HTTP 429 response (default is `0`, i.e. no retries)
retry_sleep_time	---	How many seconds to sleep before the first retry (default is `2`)
retry_backoff_multiplier	---	Each retry sleeps this many times longer than the previous one, up to 8 seconds per a single sleep (default is `2`)
retry_backoff_threshold	---	A cap on the total time spent sleeping between retries, in seconds - once reached, no more retries take place (default is `60`)

The retry fields are exported only when they differ from their defaults.

outgoing_soap:
  - name: enmasse.outgoing.soap.1
    host: https://example.com
    url_path: /SOAP
    security: enmasse.ntlm.1
    soap_action: urn:microsoft-dynamics-schemas/page/example:Create
    soap_version: "1.1"
    tls_verify: false
    timeout: 20

  # A connection that retries failed invocations - three retries with 1s, 2s and 4s sleeps between them
  - name: enmasse.outgoing.soap.2
    host: https://example.com
    url_path: /SOAP
    soap_action: urn:example:submit
    soap_version: "1.2"
    max_retries: 3
    retry_sleep_time: 1

More details in the Python SOAP chapter.

Security definitions

Key: security

basic_auth

Name	Required	Description
name	Yes	Unique name of the security definition
type	Yes	Must be `basic_auth`
username	Yes	Username
password	---	Password - can be set via an environment variable
realm	---	HTTP Basic Auth realm (default is `zato`)
is_active	---	Whether the definition is active (default is `true`)

security:
  - name: enmasse.basic_auth.1
    type: basic_auth
    username: enmasse.1
    password: Zato_Enmasse_Env.BasicAuth1

apikey

Name	Required	Description
name	Yes	Unique name of the security definition
type	Yes	Must be `apikey`
password	---	The API key value - can be set via an environment variable
header	---	Name of the HTTP header that holds the API key (default is `X-API-Key`)
is_active	---	Whether the definition is active (default is `true`)

security:
  - name: enmasse.apikey.1
    type: apikey
    username: enmasse.1
    password: Zato_Enmasse_Env.EnmasseApiKey1

ntlm

Name	Required	Description
name	Yes	Unique name of the security definition
type	Yes	Must be `ntlm`
username	Yes	Username, typically in `DOMAIN\user` format
password	---	Password - can be set via an environment variable
is_active	---	Whether the definition is active (default is `true`)

security:
  - name: enmasse.ntlm.1
    type: ntlm
    username: enmasse\\user
    password: Zato_Enmasse_Env.NTLMPassword

mtls

mTLS definitions are asymmetric - the path fields drive outgoing connections while the match criteria drive channels. One definition uses one set or the other. More details in the mTLS chapter.

Name	Required	Description
name	Yes	Unique name of the security definition
type	Yes	Must be `mtls`
cert_path	---	Path to the client certificate in PEM format, for outgoing connections
key_path	---	Path to the certificate's private key in PEM format - not needed when the certificate file contains the key
ca_certs_path	---	Path to a CA bundle the remote server's certificate must chain up to
client_cert_fingerprint	---	Expected SHA256 fingerprint of an inbound client certificate, for channels
client_cert_subject_dn	---	Expected subject DN of an inbound client certificate, for channels
is_active	---	Whether the definition is active (default is `true`)

security:
  - name: enmasse.mtls.1
    type: mtls
    cert_path: /opt/hot-deploy/ssl/client-cert.pem
    key_path: /opt/hot-deploy/ssl/client-key.pem
    ca_certs_path: /opt/hot-deploy/ssl/remote-ca.pem

  - name: enmasse.mtls.2
    type: mtls
    client_cert_fingerprint: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
    client_cert_subject_dn: CN=client,O=Example,C=US

spnego

Kerberos definitions are used with outgoing connections - the keytab is the credential, so there is no password. More details in the Kerberos (SPNEGO) chapter.

Name	Required	Description
name	Yes	Unique name of the security definition
type	Yes	Must be `spnego`
principal	Yes	The Kerberos principal to authenticate as
keytab_path	Yes	Path to the principal's keytab file, as mounted into the container
target_spn	---	Service principal name of the remote API, e.g. `HTTP@api.example.com` - derived from the target host name when absent
needs_delegation	---	Whether to delegate credentials to the remote service (default is `false`)
is_active	---	Whether the definition is active (default is `true`)

security:
  - name: enmasse.spnego.1
    type: spnego
    principal: enmasse@EXAMPLE.COM
    keytab_path: /opt/hot-deploy/krb5/enmasse.keytab
    target_spn: HTTP@api.example.com

bearer_token

A bearer token definition is either dynamic - Zato obtains and refreshes the token from a token endpoint - or static, with a fixed token that never changes. The presence of any of the static_* fields makes the definition static.

Fields of dynamic definitions:

Name	Required	Description
name	Yes	Unique name of the security definition
type	Yes	Must be `bearer_token`
username	Yes	Client ID used to obtain the token
auth_endpoint	Yes	URL of the token endpoint
password	---	Client secret - can be set via an environment variable
grant_type	---	OAuth grant type (default is `client_credentials`)
client_id_field	---	Name of the client ID field sent to the token endpoint (default is `client_id`)
client_secret_field	---	Name of the client secret field sent to the token endpoint (default is `client_secret`)
data_format	---	Format of the token request (default is `form`)
extra_fields	---	List of additional fields to include in the token request, e.g. `audience=https://api.example.com`
is_active	---	Whether the definition is active (default is `true`)

Fields of static definitions:

Name	Required	Description
name	Yes	Unique name of the security definition
type	Yes	Must be `bearer_token`
static_token	Yes	The token itself - can be set via an environment variable, is never exported
static_header	---	The header the token is sent in (default is `Authorization`)
static_prefix	---	The prefix before the token in the header (default is `bearer`)
is_active	---	Whether the definition is active (default is `true`)

security:
  - name: enmasse.bearer_token.1
    type: bearer_token
    username: enmasse.1
    password: Zato_Enmasse_Env.EnmasseBearerToken1
    auth_endpoint: https://example.com/oauth/token
    client_id_field: username
    client_secret_field: password
    grant_type: password
    data_format: form

  - name: enmasse.bearer_token.2
    type: bearer_token
    username: enmasse.2
    password: Zato_Enmasse_Env.EnmasseBearerToken2
    auth_endpoint: https://example.com/oauth/token
    extra_fields:
      - audience=https://api.example.com

  # A static token sent as-is with each request
  - name: enmasse.bearer_token.3
    type: bearer_token
    static_token: Zato_Enmasse_Env.EnmasseStaticToken
    static_header: X-Auth-Token
    static_prefix: Token

wss

WS-Security definitions attach to SOAP channels and outgoing SOAP connections. Each definition has a mode - username_token, x509 or saml - and the mode decides which of the remaining fields apply.

Fields common to all modes:

Name	Required	Description
name	Yes	Unique name of the security definition
type	Yes	Must be `wss`
username	Yes	Username
mode	Yes	One of `username_token`, `x509` or `saml`
password	---	Password - can be set via an environment variable
is_active	---	Whether the definition is active (default is `true`)

Fields of the username_token mode:

Name	Required	Description
use_digest	---	Whether the password travels in digest form, with a nonce and timestamp, instead of as text (default is `false`)

Fields of the x509 mode:

Name	Required	Description
sign	---	Whether to sign messages with the signing key (default is `false`)
encrypt	---	Whether to encrypt message bodies to the peer certificate (default is `false`)
signing_key	---	Your own private key, PEM
signing_certificate_chain	---	Your own certificate and any intermediates, PEM - sent along so the receiver can verify the signature
decryption_key	---	The key that decrypts what arrives encrypted to you, PEM
peer_certificate	---	The other side's certificate, PEM - used both to encrypt to them and to pin their signatures
trust_anchors	---	CA certificates the other side's signing certificates may chain up to instead of pinning, PEM

Fields of the saml mode:

Name	Required	Description
issuer	---	Who vouches for the assertion
subject	---	The user or system the assertion is about
audience	---	Who the assertion is meant for
sign	---	Whether to sign the assertion (default is `false`) - uses `signing_key` and `signing_certificate_chain`, with `trust_anchors` validating incoming assertions

security:
  - name: enmasse.wss.token
    type: wss
    username: enmasse.1
    password: Zato_Enmasse_Env.EnmasseWSSToken
    mode: username_token
    use_digest: true

  - name: enmasse.wss.x509
    type: wss
    username: enmasse.2
    mode: x509
    sign: true
    encrypt: true
    signing_key: |-
      -----BEGIN PRIVATE KEY-----
      ...
      -----END PRIVATE KEY-----
    signing_certificate_chain: |-
      -----BEGIN CERTIFICATE-----
      ...
      -----END CERTIFICATE-----
    decryption_key: |-
      -----BEGIN PRIVATE KEY-----
      ...
      -----END PRIVATE KEY-----
    peer_certificate: |-
      -----BEGIN CERTIFICATE-----
      ...
      -----END CERTIFICATE-----
    trust_anchors: |-
      -----BEGIN CERTIFICATE-----
      ...
      -----END CERTIFICATE-----

  - name: enmasse.wss.saml
    type: wss
    username: enmasse.3
    mode: saml
    issuer: https://idp.example.com
    subject: CN=Example Subject
    audience: https://api.example.com
    sign: true
    signing_key: |-
      -----BEGIN PRIVATE KEY-----
      ...
      -----END PRIVATE KEY-----
    signing_certificate_chain: |-
      -----BEGIN CERTIFICATE-----
      ...
      -----END CERTIFICATE-----

Further reading: API authentication, SOAP security

Rate limiting on security definitions

Rate limiting on security definitions uses the same nested rate_limiting key inside each security entry. The rules apply to every channel that uses the definition - the limit follows the credential, not the endpoint. If a partner authenticates to five different channels, they all share one set of counters.

The rule and time range structure is identical to the channel rate limiting section above.

security:

  # Partner gets 1,000 requests per hour across all channels they call
  - name: partner-acme
    type: basic_auth
    username: acme
    password: Zato_Enmasse_Env.AcmePassword
    rate_limiting:
      - cidr_list: []
        time_range:
          - is_all_day: true
            disabled: false
            disallowed: false
            rate: 20
            burst: 40
            limit: 1000
            limit_unit: hour

  # External vendor limited to 500/day, only from their known IP range
  - name: vendor-logistics
    type: apikey
    password: Zato_Enmasse_Env.LogisticsApiKey
    rate_limiting:
      - cidr_list:
          - 198.51.100.0/24
        time_range:
          - is_all_day: true
            disabled: false
            disallowed: false
            rate: 5
            burst: 10
            limit: 500
            limit_unit: day
      - cidr_list: []
        time_range:
          - is_all_day: true
            disabled: false
            disallowed: true
            rate: 0
            burst: 0
            limit: 0
            limit_unit: minute

  # Gold tier partner - 50,000 per hour
  - name: partner-gold
    type: basic_auth
    username: gold
    password: Zato_Enmasse_Env.GoldPassword
    rate_limiting:
      - cidr_list: []
        time_range:
          - is_all_day: true
            disabled: false
            disallowed: false
            rate: 100
            burst: 200
            limit: 50000
            limit_unit: hour

  # Silver tier partner - 5,000 per hour
  - name: partner-silver
    type: basic_auth
    username: silver
    password: Zato_Enmasse_Env.SilverPassword
    rate_limiting:
      - cidr_list: []
        time_range:
          - is_all_day: true
            disabled: false
            disallowed: false
            rate: 10
            burst: 20
            limit: 5000
            limit_unit: hour

  # Deny all traffic for a retired API key
  - name: apikey-retired
    type: apikey
    password: Zato_Enmasse_Env.RetiredKey
    rate_limiting:
      - cidr_list: []
        time_range:
          - is_all_day: true
            disabled: false
            disallowed: true
            rate: 0
            burst: 0
            limit: 0
            limit_unit: minute

  # Internal service account - higher limits during nightly ETL, strict during the day
  - name: etl-service-account
    type: basic_auth
    username: etl
    password: Zato_Enmasse_Env.EtlPassword
    rate_limiting:
      - cidr_list: []
        time_range:
          - is_all_day: true
            disabled: false
            disallowed: false
            rate: 10
            burst: 20
            limit: 1000
            limit_unit: hour
          - is_all_day: false
            time_from: "00:00"
            time_to: "04:00"
            disabled: false
            disallowed: false
            rate: 200
            burst: 500
            limit: 200000
            limit_unit: hour

For a full explanation of all rate limiting concepts, see the Rate limiting and firewall chapter.

Quota tiers

Key: quota_tier

A quota tier is a named, reusable set of rate limiting rules. Instead of repeating the same rate_limiting block across many security definitions, define the rules once as a tier and reference it by name with a quota_tier key - on a security definition or on a security group.

Name	Required	Description
name	Yes	Unique name of the tier
description	---	Free-form description
rules	---	List of rate limiting rules, in the same shape as the rate limiting `rate_limiting` key

A security definition either references a tier or has its own rate_limiting rules, never both - when a YAML entry has one of the keys, the other is dropped.

quota_tier:

  - name: tier.gold
    description: Gold partners - 50,000 requests per hour
    rules:
      - cidr_list: []
        time_range:
          - is_all_day: true
            disabled: false
            disallowed: false
            rate: 100
            burst: 200
            limit: 50000
            limit_unit: hour

security:

  - name: partner-gold
    type: basic_auth
    username: gold
    password: Zato_Enmasse_Env.GoldPassword
    quota_tier: tier.gold

The Quota tiers chapter explains how tiers and direct rules interact.

Scheduler jobs

Key: scheduler

At least one interval field (weeks, days, hours, minutes or seconds) must be non-zero.

Name	Required	Description
name	Yes	Unique name of the scheduler job
service	Yes	Name of the Zato service that the job invokes
job_type	Yes	Type of the job - must be `interval_based`
start_date	Yes	Date and time when the job first becomes eligible to run, e.g. `2027-01-01 00:00:00`
is_active	---	Whether the job is active (default is `true`)
weeks	---	Number of weeks between runs (default is `0`)
days	---	Number of days between runs (default is `0`)
hours	---	Number of hours between runs (default is `0`)
minutes	---	Number of minutes between runs (default is `1`)
seconds	---	Number of seconds between runs (default is `0`)
repeats	---	How many times the job should run before stopping (default is unlimited)
extra	---	List of extra lines passed to the service as input

scheduler:
  - name: enmasse.scheduler.1
    service: demo.ping
    job_type: interval_based
    start_date: '2027-01-11 11:23:52'
    seconds: 2
    is_active: true

  - name: enmasse.scheduler.2
    service: demo.ping
    job_type: interval_based
    start_date: '2027-02-19 12:00:00'
    hours: 3

For Python scheduler examples, visit the scheduler examples page.

SQL connections

Key: sql

Name	Required	Description
name	Yes	Unique name of the connection
type	Yes	Database engine type - one of `mysql`, `oracle`, `postgresql`, `mssql`, `snowflake` or `redshift`
host	Yes	Database server host
port	Yes	Database server port
db_name	Yes	Name of the database to connect to
username	Yes	Database username
password	---	Database password - can be set via an environment variable
pool_size	---	Size of the connection pool (default is `5`)
timeout	---	Connection timeout in seconds
extra	---	List of extra connection parameters, e.g. `connect_timeout=10`
audit_log	---	What the audit log records for the connection - one of `off`, `statement`, `statement-params` or `full` (default is `off`)
ssl	---	Whether to connect over TLS (default is `false`)
ssl_ca_file	---	Path to a PEM file with the CA certificates that signed the server's certificate
ssl_cert_file	---	Path to the client certificate, for mutual TLS
ssl_key_file	---	Path to the client private key, for mutual TLS
ssl_verify	---	Whether to validate the server's TLS certificate (default is `true`)
is_active	---	Whether the connection is active (default is `true`)

sql:
  - name: enmasse.sql.1
    type: mysql
    host: 127.0.0.1
    port: 3306
    db_name: mydb
    username: enmasse.1
    password: Zato_Enmasse_Env.SQL_Password_1

  - name: enmasse.sql.2
    type: mssql
    host: 10.152.81.199
    port: 1433
    db_name: mydb
    username: enmasse.2
    password: Zato_Enmasse_Env.SQL_Password_2
    extra:
      - connect_timeout=10
    pool_size: 10
    audit_log: statement

  - name: enmasse.sql.3
    type: snowflake
    host: myorg-myaccount
    port: 443
    db_name: MYDB
    username: enmasse.3
    password: Zato_Enmasse_Env.SQL_Password_3
    extra:
      - warehouse=COMPUTE_WH
      - role=ANALYST
      - schema=PUBLIC

  - name: enmasse.sql.4
    type: redshift
    host: examplecluster.abc123xyz789.us-west-2.redshift.amazonaws.com
    port: 5439
    db_name: mydb
    username: enmasse.4
    password: Zato_Enmasse_Env.SQL_Password_4
    ssl: true
    ssl_ca_file: /path/to/ca.pem

With Snowflake, the host field is the account identifier, e.g. myorg-myaccount, not a hostname, and the port field is always 443.

Database-specific guides: MySQL · PostgreSQL · Oracle · Microsoft SQL Server · Snowflake · Amazon Redshift

MongoDB

Key: mongodb (alias: outgoing_mongodb)

Name	Required	Description
name	Yes	Unique name of the connection
server_list	Yes	One or more `host:port` entries, separated with newlines (default is `localhost:27017`)
username	---	Username to authenticate with
password	---	Password - can be set via an environment variable
auth_source	---	Database to authenticate against (default is `admin`)
replica_set	---	Name of the replica set to require, if any
app_name	---	Application name reported to the server (default is `Zato`)
pool_size_max	---	Maximum size of the connection pool (default is `10`)
connect_timeout	---	Connection timeout in seconds (default is `10`)
server_select_timeout	---	Server selection timeout in seconds (default is `5`)
is_tls_enabled	---	Whether to connect over TLS (default is `false`)
tls_ca_certs_file	---	Path to a PEM file with the CA certificates that signed the server's certificate
tls_cert_key_file	---	Path to a combined client certificate and private key PEM file, for mutual TLS
is_tls_validation_enabled	---	Whether to validate the server's TLS certificate (default is `true`)
is_active	---	Whether the connection is active (default is `true`)

mongodb:
  - name: enmasse.mongodb.1
    server_list: localhost:27017
    username: enmasse
    password: Zato_Enmasse_Env.Enmasse_MongoDB_Password

  - name: enmasse.mongodb.2
    server_list: |-
      mongodb1.example.com:27017
      mongodb2.example.com:27017
    username: enmasse
    password: Zato_Enmasse_Env.Enmasse_MongoDB_Password
    replica_set: rs0
    is_tls_enabled: true
    tls_ca_certs_file: /path/to/ca.pem
    tls_cert_key_file: /path/to/client.pem

More details in the MongoDB programming chapter.

Email - IMAP

Key: email_imap

Name	Required	Description
name	Yes	Unique name of the connection
host	Yes	IMAP server host
port	Yes	IMAP server port
username	Yes	Username
password	---	Password - can be set via an environment variable
mode	---	Connection mode, e.g. `ssl` or `plain` (default is `plain`)
timeout	---	Connection timeout in seconds (default is `30`)
debug_level	---	Debug level for the IMAP library (default is `0`)
get_criteria	---	Criteria used to fetch messages (default is `{}`)
is_active	---	Whether the connection is active (default is `true`)
scheduler_run_every	---	How often to poll the mailbox, e.g. `5` - requires the other scheduler fields too
scheduler_run_unit	---	Unit for `scheduler_run_every` - one of `seconds`, `minutes`, `hours` or `days`
scheduler_start_date	---	When to start polling, e.g. `2026-01-01T00:00:00`
scheduler_service	---	Service invoked for each message received from the mailbox
scheduler_invoke_with	---	What `scheduler_service` receives on input - `message` (default) or `each_attachment`
is_audit_log_active	---	Whether the connection's traffic goes to the audit log (default is `true`, exported only when `false`)

If the scheduler fields are given, a scheduler job is auto-created for the connection. The job polls the mailbox on the configured interval and invokes scheduler_service with each message received. With scheduler_invoke_with set to message, the service is invoked once per message, with the message object on input. With each_attachment, the message's body is ignored and the service is invoked once per each of the message's attachments, with an attachment object on input. Messages are marked as seen automatically once the service returns without an exception, otherwise they are received anew on the next run. The fields scheduler_run_every, scheduler_start_date and scheduler_service must be given together.

email_imap:
  - name: enmasse.email.imap.1
    host: imap.example.com
    port: 993
    username: enmasse@example.com
    password: Zato_Enmasse_Env.IMAPPassword

  - name: enmasse.email.imap.2
    host: imap.example.com
    port: 993
    username: enmasse@example.com
    password: Zato_Enmasse_Env.IMAPPassword
    scheduler_run_every: 5
    scheduler_run_unit: minutes
    scheduler_start_date: 2026-01-01T00:00:00
    scheduler_service: demo.ping
    scheduler_invoke_with: each_attachment

Read the Python IMAP email guide, including Microsoft 365 and OAuth2.

Email - SMTP

Key: email_smtp

Name	Required	Description
name	Yes	Unique name of the connection
host	Yes	SMTP server host
port	Yes	SMTP server port
username	---	Username
password	---	Password - can be set via an environment variable
mode	---	Connection mode, e.g. `starttls` or `plain` (default is `plain`)
timeout	---	Connection timeout in seconds (default is `60`)
ping_address	---	Email address used to ping the connection
is_debug	---	Whether to enable debug output (default is `false`)
is_active	---	Whether the connection is active (default is `true`)

email_smtp:
  - name: enmasse.email.smtp.1
    host: smtp.example.com
    port: 587
    username: enmasse@example.com
    password: Zato_Enmasse_Env.SMTPPassword

More details in the Python SMTP email chapter.

LDAP

Key: ldap

Name	Required	Description
name	Yes	Unique name of the connection
username	Yes	Distinguished name (DN) of the user to bind as
server_list	Yes	Comma-separated list of LDAP servers, e.g. `127.0.0.1:389`
auth_type	---	Authentication type, e.g. `NTLM` or `SIMPLE`
password	---	Password - can be set via an environment variable
is_active	---	Whether the connection is active (default is `true`)

ldap:
  - name: enmasse.ldap.1
    username: 'CN=enmasse,OU=testing,OU=Servers,DC=enmasse'
    auth_type: NTLM
    server_list: 127.0.0.1:389
    password: Zato_Enmasse_Env.Enmasse_LDAP_Password

See custom authentication for how to use LDAP credentials in services.

OData

Key: odata

Name	Required	Description
name	Yes	Unique name of the connection
address	Yes	Service root URL, e.g. `https://example.com/sap/opu/odata/sap/API_SALES_ORDER_SRV/`
odata_version	---	OData version, `2.0` or `4.0` (default is `4.0`)
auth_type	---	Authentication type, one of `no-auth`, `basic`, `bearer` or `oauth2` (default is `basic`)
username	---	Username, for Basic Auth
secret	---	Password or bearer token - can be set via an environment variable
token_url	---	OAuth2 token URL, e.g. `https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token`
tenant_id	---	OAuth2 tenant ID - when given, it is substituted into the token URL
client_id	---	OAuth2 client ID
client_secret	---	OAuth2 client secret - can be set via an environment variable
scopes	---	OAuth2 scopes, e.g. `https://api.businesscentral.dynamics.com/.default`
needs_csrf_token	---	Whether to exchange SAP X-CSRF-Token headers for write operations (default is `false`)
page_size	---	Server-driven page size requested via `Prefer: odata.maxpagesize` (default is `0`, meaning the server decides)
timeout	---	Connection timeout in seconds (default is `60`)
pool_size	---	Connection pool size (default is `1`)
is_active	---	Whether the connection is active (default is `true`)

odata:
  - name: enmasse.odata.1
    address: https://example.com/sap/opu/odata/sap/API_SALES_ORDER_SRV/
    odata_version: "2.0"
    auth_type: basic
    username: enmasse.odata.user.1
    needs_csrf_token: true
    secret: Zato_Enmasse_Env.Enmasse_OData_Secret

  - name: enmasse.odata.2
    address: https://api.businesscentral.dynamics.com/v2.0/my-tenant/sandbox/api/v2.0/
    odata_version: "4.0"
    auth_type: oauth2
    token_url: https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token
    tenant_id: my-tenant
    client_id: my-client-id
    scopes: https://api.businesscentral.dynamics.com/.default
    client_secret: Zato_Enmasse_Env.Enmasse_OData_Client_Secret

More details in the OData integrations chapter.

SMB

Key: smb (alias: outgoing_smb)

Name	Required	Description
name	Yes	Unique name of the connection
host	Yes	SMB server host
port	---	SMB server port (default is `445`)
username	---	Username for NTLM authentication
password	---	Password - can be set via an environment variable
is_active	---	Whether the connection is active (default is `true`)

smb:
  - name: enmasse.smb.1
    host: smb.example.com
    port: 445
    username: enmasse
    password: Zato_Enmasse_Env.Enmasse_SMB_Password

An SMB connection may also include a schedules list, each entry watching a directory and invoking a service once per file - see file transfer in enmasse for its fields, and the file transfer chapter for everything else.

SFTP

Key: sftp (alias: outgoing_sftp)

Name	Required	Description
name	Yes	Unique name of the connection
address	Yes	SFTP server address, optionally including a port, e.g. `example.com` or `example.com:22022` (default port is `22`)
username	---	Username to log in with
password	---	Password - can be set via an environment variable, and if the private key is encrypted, the password is its passphrase
private_key	---	Path to a private key file on the Zato server's filesystem, e.g. `/keys/id_ed25519` - the file is provided when the Zato container or server starts, typically through a mounted directory. If it is not given, system-level keys from `~/.ssh` are used.
strict_host_key_checking	---	Default is `true`, meaning the remote server's host key must already exist in `known_hosts` and connections to servers with unknown or changed keys are rejected. If `false`, keys of previously unknown hosts are accepted and recorded on first connection, while changed keys of known hosts are still rejected.
ignore_host_key_changes	---	Default is `false`. If `true`, any host key is accepted, known or changed, overriding `strict_host_key_checking` - meant for test servers and containers that regenerate their keys, never for production systems.
should_store_content	---	Default is `false`. If `true`, the audit log keeps the bytes of each transferred file, in addition to the always-recorded metadata.
is_active	---	Whether the connection is active (default is `true`)

sftp:
  - name: enmasse.sftp.1
    address: sftp.example.com:22
    username: enmasse
    password: Zato_Enmasse_Env.Enmasse_SFTP_Password
    private_key: /keys/id_ed25519
    strict_host_key_checking: true

An SFTP connection may also include a schedules list, each entry watching a directory and invoking a service once per file - see file transfer in enmasse for its fields, and the file transfer chapter for everything else.

Confluence

Key: confluence

Name	Required	Description
name	Yes	Unique name of the connection
address	Yes	URL of the Confluence instance, e.g. `https://example.atlassian.net`
username	Yes	Username or email address
password	---	API token or password - can be set via an environment variable
api_version	---	Confluence API version (default is `v1`)
is_active	---	Whether the connection is active (default is `true`)

confluence:
  - name: enmasse.confluence.1
    address: https://example.atlassian.net
    username: api_user@example.com
    password: Zato_Enmasse_Env.ConfluenceAPIToken

For calling external APIs in general, see calling external REST APIs.

Jira

Key: jira

Name	Required	Description
name	Yes	Unique name of the connection
address	Yes	URL of the Jira instance, e.g. `https://example.atlassian.net`
username	Yes	Username or email address
password	---	API token or password - can be set via an environment variable
api_version	---	Jira API version (default is `v1`)
is_active	---	Whether the connection is active (default is `true`)

jira:
  - name: enmasse.jira.1
    address: https://example.atlassian.net
    username: enmasse@example.com
    password: Zato_Enmasse_Env.JiraAPIToken

Practical examples are available in the Jira integration examples chapter.

Microsoft 365

Key: microsoft_cloud

Name	Required	Description
name	Yes	Unique name of the connection
client_id	Yes	Azure application (client) ID
tenant_id	Yes	Azure tenant ID
secret_value	Yes	Client secret - can be set via an environment variable
scopes	---	Space-separated list of OAuth scopes
is_active	---	Whether the connection is active (default is `true`)

microsoft_cloud:
  - name: enmasse.cloud.microsoft365.1
    client_id: 12345678-1234-1234-1234-123456789abc
    tenant_id: 87654321-4321-4321-4321-cba987654321
    secret_value: Zato_Enmasse_Env.Microsoft365SecretValue
    scopes: Mail.Read Mail.Send

Microsoft 365 IMAP connections are covered in the Python IMAP email guide.

Microsoft Teams

Key: microsoft_teams

Name	Required	Description
name	Yes	Unique name of the connection
client_id	Yes	Azure application (client) ID
tenant_id	Yes	Azure tenant ID
secret_value	Yes	Client secret - can be set via an environment variable
scopes	---	Space-separated list of OAuth scopes
is_active	---	Whether the connection is active (default is `true`)

microsoft_teams:
  - name: enmasse.chat.microsoft-teams.1
    client_id: 45678901-4567-4567-4567-4567890abcde
    tenant_id: 87654321-7654-7654-7654-fedcba987654
    secret_value: Zato_Enmasse_Env.MicrosoftTeamsSecretValue
    scopes: https://graph.microsoft.com/.default

Code examples are in the Microsoft Teams chapter.

Slack

Key: slack

Name	Required	Description
name	Yes	Unique name of the connection
token	Yes	Bot token - can be set via an environment variable
is_active	---	Whether the connection is active (default is `true`)

slack:
  - name: enmasse.chat.slack.1
    token: Zato_Enmasse_Env.SlackToken

Code examples are in the Slack chapter.

Odoo

Key: odoo

Name	Required	Description
name	Yes	Unique name of the connection
host	Yes	Odoo server host
user	Yes	Odoo username
database	Yes	Name of the Odoo database
port	---	Odoo server port (default is `8069`)
password	---	Password - can be set via an environment variable
protocol	---	Protocol to use (default is `jsonrpc`)
pool_size	---	Size of the connection pool (default is `10`)
is_active	---	Whether the connection is active (default is `true`)

odoo:
  - name: enmasse.odoo.1
    host: odoo.example.com
    port: 8069
    user: admin
    password: Zato_Enmasse_Env.OdooPassword
    database: enmasse_db

Code examples are in the Python Odoo integrations chapter.

ElasticSearch

Key: elastic_search

Name	Required	Description
name	Yes	Unique name of the connection
address_list	Yes	Full URL or list of URLs of ElasticSearch servers, e.g. `https://elasticsearch:9200` - the scheme of each URL decides whether TLS is used
username	---	Username to authenticate with, leave out if the server does not require authentication
password	---	Password matching the username
timeout	---	Request timeout in seconds (default is `90`)
is_tls_validation_enabled	---	Whether to verify the server's TLS certificate (default is `true`)
tls_ca_certs_file	---	Path to a PEM file with CA certificates to verify the server's certificate against
tls_cert_key_file	---	Path to a PEM file with a combined client certificate and private key, for mutual TLS
is_active	---	Whether the connection is active (default is `true`)

elastic_search:
  - name: enmasse.elastic.1
    address_list:
      - http://elasticsearch:9200
    timeout: 60

Usage examples: Python ElasticSearch

LLM connections

Key: llm

Name	Required	Description
name	Yes	Unique name of the connection - services look it up with `self.llm`
model	Yes	Model name from the catalog, e.g. `Sonnet 5`, or a wire id entered by hand
address	Yes	Base URL of the API to call, e.g. `https://api.openai.com/v1`
secret	---	API key - can be set via an environment variable, self-hosted endpoints may not need one
timeout	---	How many seconds to wait for the provider's response (default is `60`)
max_tokens	---	The most tokens the model may generate per reply (default is `1024`)
max_history_turns	---	How many past chat turns are sent to the provider (default is `20`)
chat_expiry	---	How many seconds a chat's history is kept after its last message (default is `86400`)
is_active	---	Whether the connection can be used (default is `true`)

llm:

  - name: My OpenAI
    model: gpt-4o-mini
    address: https://api.openai.com/v1
    secret: Zato_Enmasse_Env.My_OpenAI_API_Key
    timeout: 30

  - name: My Claude
    model: Sonnet 5
    address: https://api.anthropic.com
    secret: Zato_Enmasse_Env.My_Claude_API_Key

The AI enmasse chapter covers LLM connections in more detail.

Security groups

Key: groups

Each entry defines a named group of security definitions. Groups can then be referenced from REST channels to control access.

Name	Required	Description
name	Yes	Unique name of the group
members	---	List of security definition names that belong to this group
quota_tier	---	Name of a quota tier that every member of the group follows, unless a member has its own rules or its own tier

groups:
  - name: enmasse.group.1
    members:
      - enmasse.basic_auth.1
      - enmasse.basic_auth.2
      - enmasse.apikey.1

  - name: enmasse.group.2
    quota_tier: tier.gold
    members:
      - enmasse.apikey.1
      - enmasse.apikey.2

Groups are used together with REST channels - see REST channels for details.

MCP gateways

Key: mcp_gateway

Each entry defines an MCP gateway that exposes services as tools for AI agents.

Name	Required	Description
name	Yes	Unique name of the gateway
url_path	---	URL path the MCP endpoint is exposed under, e.g. `/mcp/billing` (default is `/mcp`)
services	---	List of service names exposed as tools
security_groups	---	List of security group names whose members may call the gateway - see MCP gateway security
is_active	---	Whether the gateway accepts requests (default is `true`)
is_audit_log_active	---	Whether the MCP audit log records the gateway's traffic (default is `false` when absent)
skills	---	List of skills served as MCP prompts
session_ttl	---	Idle session TTL in seconds - `0`, the default, keeps the built-in 30 minutes
invoke_timeout	---	How many seconds one `tools/call` invocation may run for - `0`, the default, keeps the built-in 90
validate_input	---	Whether tool arguments are validated against each tool's schema (default is `false`)
allow_agent_filters	---	Whether agents may attach per-call JSONata response filters (default is `false`)
should_delete	---	An entry with `should_delete: true` removes the gateway instead of creating or updating it

A gateway also accepts the response controls family - the max_response_size, size_cap_mode, min_size_threshold and characters_per_token response shaping fields plus all the safeguards_* fields for compaction, PII removal, secrets removal and content safety. The AI enmasse chapter lists every one of them with its default.

mcp_gateway:
  - name: enmasse.mcp.gateway.1
    is_active: true
    is_audit_log_active: true
    url_path: /mcp/enmasse-1
    services:
      - crm.get-customer
      - crm.update-customer
    security_groups:
      - enmasse.group.1
    validate_input: true
    max_response_size: 2000
    safeguards_pii_enabled: true

Rule engine API

Key: rule_engine_api

Each entry exposes rule engine rulesets over a REST endpoint.

Name	Required	Description
name	Yes	Unique name of the API endpoint
url_path	---	URL path the endpoint is exposed under (default is `/api/rules`)
rulesets	---	List of ruleset names the endpoint serves
security_groups	---	List of security group names whose members may call the endpoint
is_active	---	Whether the endpoint accepts requests (default is `true`)

rule_engine_api:
  - name: enmasse.rules.1
    url_path: /api/rules/pricing
    rulesets:
      - pricing
      - discounts
    security_groups:
      - enmasse.group.1

OpenAPI channels

Key: channel_openapi

Name	Required	Description
name	Yes	Unique name of the OpenAPI channel
url_path	Yes	URL path where the OpenAPI specification is served, e.g. `/openapi/my-api`
rest_channel_list	---	List of REST channel names to include in the specification
is_active	---	Whether the channel is active (default is `true`)

channel_openapi:
  - name: enmasse.channel.openapi.1
    url_path: /openapi/enmasse-1
    rest_channel_list:
      - enmasse.channel.rest.1
      - enmasse.channel.rest.2

The OpenAPI specifications chapter explains how OpenAPI channels work.

HL7 MLLP channels

Key: channel_mllp

Name	Required	Description
name	Yes	Unique channel name
service	Yes	Service invoked for each incoming message
is_active	---	Whether the channel accepts connections (default `true`)
should_validate	---	Validate parsed messages against the HL7 schema (default `false`)
should_parse_on_input	---	Parse raw ER7 into structured objects before the service is invoked (default `true`)
should_log_messages	---	Log incoming messages (default `false`)
should_return_errors	---	Include error details in NAK responses (default `false`)
normalize_line_endings	---	Convert CRLF/LF to CR (default `true`)
force_standard_delimiters	---	Rewrite non-standard delimiters to `^~\&` (default `true`)
restore_truncated_msh	---	Pad short MSH segments (default `true`)
split_concatenated_messages	---	Split multi-MSH payloads into separate messages (default `true`)
use_msh18_encoding	---	Use MSH-18 for character encoding (default `true`)
normalize_obx2_value_type	---	Fill empty OBX-2 with ST (default `true`)
replace_invalid_obx2_value_type	---	Replace invalid OBX-2 with ST (default `true`)
normalize_invalid_escape_sequences	---	Strip unmatched escapes (default `true`)
normalize_obx8_abnormal_flags	---	Clear OBX-8 literal null (default `true`)
normalize_quadruple_quoted_empty	---	Strip multi-quote sequences (default `true`)
allow_short_encoding_characters	---	Pad short MSH-2 (default `true`)
fix_off_by_one_field_index	---	Remove spurious leading field (default `false`)
msh9_message_type	---	Routing filter on MSH-9.1
msh9_trigger_event	---	Routing filter on MSH-9.2
default_character_encoding	---	Default encoding (default `utf-8`)
dedup_ttl_value	---	Deduplication window value
dedup_ttl_unit	---	Deduplication window unit (minutes, hours, or days)
is_audit_log_active	---	Whether the channel's traffic goes to the audit log (default `true`)

channel_mllp:

  - name: enmasse.hl7.lab-results
    service: hl7.process-lab-results
    should_validate: true
    normalize_line_endings: true
    msh9_message_type: ORU

  - name: enmasse.hl7.admissions
    service: hl7.process-admissions
    msh9_message_type: ADT
    msh9_trigger_event: A01
    dedup_ttl_value: 60
    dedup_ttl_unit: minutes

  - name: enmasse.hl7.default
    service: hl7.catch-all
    is_default: true
    fix_off_by_one_field_index: true

For the full description of every field, see the MLLP channel configuration reference.

HL7 MLLP outgoing connections

Key: outgoing_mllp

Name	Required	Description
name	Yes	Unique connection name - services use it with `self.mllp`
address	Yes	Remote endpoint as `host:port`, e.g. `10.20.30.40:2575`
is_active	---	Whether the connection can be used (default `true`)
pool_size	---	How many connections the pool keeps open (default `10`)
start_seq	---	MLLP frame start bytes in hex (default `0b`)
end_seq	---	MLLP frame end bytes in hex (default `1c 0d`)
recv_timeout	---	How long to wait for the acknowledgment, in milliseconds (default `250`)
max_msg_size	---	The biggest acknowledgment accepted, in bytes (default `2097152`, i.e. 2 MB)
read_buffer_size	---	Socket read buffer, in bytes (default `32768`)
max_wait_time	---	Default timeout for the dashboard invoke screen, in seconds (default `5`)
max_retries	---	How many times a failed send is retried (default `5`)
backoff_base_seconds	---	Delay before the first retry, in seconds, doubling with each attempt (default `1`)
backoff_cap_seconds	---	The longest delay between retries, in seconds (default `300`)
backoff_jitter_percent	---	Random percentage applied to each retry delay (default `10`)
circuit_breaker_threshold_percent	---	Failure percentage within the window that pauses sending (default `50`)
circuit_breaker_window_seconds	---	Length of the rolling window the failure percentage is computed over, in seconds (default `60`)
circuit_breaker_reset_seconds	---	How long sending stays paused before a trial message goes through, in seconds (default `60`)
should_log_messages	---	Log outgoing traffic (default `false`)
logging_level	---	Log level for this connection (default `INFO`)
is_audit_log_active	---	Whether the connection's traffic goes to the audit log (default `true`)
tls_ca_path	---	Path to the CA bundle used to verify the remote server - setting it turns TLS on
tls_cert_path	---	Path to the client certificate, for mTLS
tls_key_path	---	Path to the client private key, for mTLS

outgoing_mllp:

  - name: adt-outbound
    address: 10.20.30.40:2575

  - name: lab-outbound
    address: lab.example.com:2575
    recv_timeout: 500
    tls_ca_path: /path/to/ca.pem
    tls_cert_path: /path/to/client.pem
    tls_key_path: /path/to/client.key

The Sending HL7v2 over MLLP chapter explains how outgoing connections work.

HL7 FHIR outgoing connections

Key: outgoing_fhir

Name	Required	Description
name	Yes	Unique connection name - services use it with `self.fhir`
address	Yes	URL of the FHIR server, including its base path, e.g. `https://fhir.example.com/r4`
security	---	Name of a Basic Auth or OAuth security definition the requests go out with - without one they are unauthenticated
is_active	---	Whether the connection can be used (default `true`)
pool_size	---	How many clients to keep open to the server (default `10`)
is_audit_log_active	---	Whether the connection's traffic goes to the audit log (default `true`)

outgoing_fhir:

  - name: FHIR.Sample
    address: https://fhir.example.com/r4

  - name: FHIR.Secured
    address: https://fhir.partner.example.com/r4
    security: enmasse.basic_auth.1
    pool_size: 20

The HL7 FHIR integrations chapter explains how outgoing FHIR connections are used from a service.

Kafka channels

Key: channel_kafka

Name	Required	Description
name	Yes	Unique name of the Kafka channel
address	Yes	Kafka broker address, e.g. `localhost:9092`
topic	---	Kafka topic to consume from
group_id	---	Consumer group ID
service	---	Name of the Zato service invoked for each message
is_active	---	Whether the channel is active (default is `true`)
ssl	---	Whether to use SSL (default is `false`)
ssl_ca_file	---	Path to the CA certificate file
ssl_cert_file	---	Path to the client certificate file
ssl_key_file	---	Path to the client key file

channel_kafka:
  - name: enmasse.kafka.channel.1
    address: localhost:9092
    topic: incoming-events
    group_id: zato-consumers
    service: kafka.process-event

  - name: enmasse.kafka.channel.2
    address: broker1:9093
    topic: secure-events
    group_id: zato-secure
    service: kafka.process-secure
    ssl: true
    ssl_ca_file: /path/to/ca.pem
    ssl_cert_file: /path/to/cert.pem
    ssl_key_file: /path/to/key.pem

See Kafka examples for Python code.

Kafka outgoing connections

Key: outgoing_kafka

Name	Required	Description
name	Yes	Unique name of the outgoing connection
address	Yes	Kafka broker address, e.g. `localhost:9092`
topic	---	Default Kafka topic to publish to
is_active	---	Whether the connection is active (default is `true`)
ssl	---	Whether to use SSL (default is `false`)
ssl_ca_file	---	Path to the CA certificate file
ssl_cert_file	---	Path to the client certificate file
ssl_key_file	---	Path to the client key file

outgoing_kafka:
  - name: enmasse.kafka.outgoing.1
    address: localhost:9092
    topic: outgoing-events

  - name: enmasse.kafka.outgoing.2
    address: broker2:9093
    topic: secure-outgoing
    ssl: true
    ssl_ca_file: /path/to/ca.pem
    ssl_cert_file: /path/to/cert.pem
    ssl_key_file: /path/to/key.pem

See Kafka examples for Python code.

IBM MQ channels

Key: channel_ibm_mq

Name	Required	Description
name	Yes	Unique name of the channel
address	Yes	Address of the queue manager as host:port, e.g. `mq.example.com:1414`
queue_manager	---	Name of the queue manager to connect to
mq_channel_name	---	Name of the MQ server-connection channel, e.g. `DEV.APP.SVRCONN`
queue	---	Queue to consume messages from
service	---	Name of the Zato service invoked for each message
username	---	Username the channel authenticates with
password	---	Password - can be set via an environment variable
remove_jms_headers	---	Whether JMS headers are stripped from incoming messages (default is `true`)
ssl	---	Whether to connect over TLS (default is `false`)
cipher_spec	---	The MQ CipherSpec to use when TLS is on, e.g. `TLS_RSA_WITH_AES_256_CBC_SHA256`
ssl_ca_file	---	Path to a PEM file with the CA certificates that signed the queue manager's certificate
ssl_cert_file	---	Path to the client certificate, for mutual TLS
ssl_key_file	---	Path to the client private key, for mutual TLS
is_active	---	Whether the channel is active (default is `true`)

channel_ibm_mq:
  - name: enmasse.ibm-mq.channel.1
    address: mq.example.com:1414
    queue_manager: QM1
    mq_channel_name: DEV.APP.SVRCONN
    queue: ORDERS.IN
    service: orders.process-order
    username: app
    password: Zato_Enmasse_Env.IBMMQPassword

IBM MQ outgoing connections

Key: outgoing_ibm_mq

Name	Required	Description
name	Yes	Unique name of the connection
address	Yes	Address of the queue manager as host:port, e.g. `mq.example.com:1414`
queue_manager	---	Name of the queue manager to connect to
mq_channel_name	---	Name of the MQ server-connection channel, e.g. `DEV.APP.SVRCONN`
queue	---	Default queue to send messages to
username	---	Username the connection authenticates with
password	---	Password - can be set via an environment variable
ssl	---	Whether to connect over TLS (default is `false`)
cipher_spec	---	The MQ CipherSpec to use when TLS is on
ssl_ca_file	---	Path to a PEM file with the CA certificates that signed the queue manager's certificate
ssl_cert_file	---	Path to the client certificate, for mutual TLS
ssl_key_file	---	Path to the client private key, for mutual TLS
is_active	---	Whether the connection is active (default is `true`)

outgoing_ibm_mq:
  - name: enmasse.ibm-mq.outgoing.1
    address: mq.example.com:1414
    queue_manager: QM1
    mq_channel_name: DEV.APP.SVRCONN
    queue: ORDERS.OUT
    username: app
    password: Zato_Enmasse_Env.IBMMQPassword

See IBM MQ examples for Python code.

AMQP channels

Key: channel_amqp

Name	Required	Description
name	Yes	Unique name of the AMQP channel
address	Yes	Address of the broker as host:port, e.g. `localhost:5672`
queue	Yes	Queue to consume messages from
service	Yes	Name of the Zato service invoked for each message
username	---	Username the channel authenticates with
password	---	Password for the username above
is_active	---	Whether the channel is active (default is `true`)
consumer_tag_prefix	---	Prefix of the consumer tag the channel identifies itself with
pool_size	---	How many connections to the broker to keep open (default is `10`)
ack_mode	---	What to tell the broker about each message, `ack` or `reject` (default is `ack`)
prefetch_count	---	How many messages to prefetch, `0` means no limit (default is `0`)
data_format	---	Format of incoming message bodies, e.g. `json`

channel_amqp:
  - name: enmasse.amqp.channel.1
    address: localhost:5672
    queue: orders
    service: orders.process-order
    username: zato
    password: Zato_Enmasse_Env.AMQPPassword

  - name: enmasse.amqp.channel.2
    address: broker1:5672
    queue: invoices
    service: invoices.process-invoice
    username: zato
    password: Zato_Enmasse_Env.AMQPPassword
    data_format: json
    pool_size: 20

See AMQP examples for Python code.

AMQP outgoing connections

Key: outgoing_amqp

Name	Required	Description
name	Yes	Unique name of the outgoing connection
address	Yes	Address of the broker as host:port, e.g. `localhost:5672`
username	---	Username the connection authenticates with
password	---	Password for the username above
is_active	---	Whether the connection is active (default is `true`)
delivery_mode	---	`persistent` or `non_persistent` (default is `persistent`)
priority	---	Priority stamped on published messages, 0-9 (default is `5`)
content_type	---	MIME type stamped on published messages, e.g. `application/json`
content_encoding	---	Content encoding property of published messages, e.g. `utf-8`
expiration	---	Message expiration in milliseconds
pool_size	---	How many connections to the broker to keep open (default is `10`)
user_id	---	User ID stamped on published messages
app_id	---	Application ID stamped on published messages

outgoing_amqp:
  - name: enmasse.amqp.outgoing.1
    address: localhost:5672
    username: zato
    password: Zato_Enmasse_Env.AMQPPassword

  - name: enmasse.amqp.outgoing.2
    address: broker2:5672
    username: zato
    password: Zato_Enmasse_Env.AMQPPassword
    content_type: application/json
    priority: 7

See AMQP examples for Python code.

Azure Service Bus channels

Key: channel_azure_service_bus

Azure Service Bus channels accept the same fields as AMQP channels - the address is your namespace hostname with port 5671 and the username is your Shared Access Policy name.

channel_azure_service_bus:
  - name: enmasse.azure.channel.1
    address: mycompany-dev.servicebus.windows.net:5671
    queue: flight-updates
    service: flights.process-update
    username: MyPolicyName
    password: Zato_Enmasse_Env.AzureServiceBusPassword

See Azure Service Bus examples for Python code.

Azure Service Bus outgoing connections

Key: outgoing_azure_service_bus

Azure Service Bus outgoing connections accept the same fields as AMQP outgoing connections - the address is your namespace hostname with port 5671 and the username is your Shared Access Policy name.

outgoing_azure_service_bus:
  - name: enmasse.azure.outgoing.1
    address: mycompany-dev.servicebus.windows.net:5671
    username: MyPolicyName
    password: Zato_Enmasse_Env.AzureServiceBusPassword

See Azure Service Bus examples for Python code.

GraphQL outgoing connections

Key: outgoing_graphql

Name	Required	Description
name	Yes	Unique name of the outgoing connection
address	Yes	URL of the GraphQL endpoint, e.g. `https://graph.microsoft.com/v1.0`
is_active	---	Whether the connection is active (default is `true`)
security	---	Name of a security definition (Basic Auth, API key or OAuth)
default_query_timeout	---	Query timeout in seconds (default is `60`)
extra	---	JSON object of custom HTTP headers, e.g. `{"X-Tenant": "acme"}`

outgoing_graphql:
  - name: ms365-graph
    address: https://graph.microsoft.com/v1.0
    security: ms365-oauth
    default_query_timeout: 30

  - name: github-api
    address: https://api.github.com/graphql
    security: github-token
    default_query_timeout: 60

See GraphQL examples for Python code.

gRPC outgoing connections

Key: outgoing_grpc

Name	Required	Description
name	Yes	Unique name of the outgoing connection
address	Yes	Host and port of the gRPC server, e.g. `billing.example.com:50051`
is_active	---	Whether the connection is active (default is `true`)
security	---	Name of a security definition (Basic Auth, API key or OAuth) whose credentials are sent as call metadata
is_tls	---	Whether to connect over TLS (default is `true`)
tls_ca_certs_file	---	Path to a PEM file with CA certificates to verify the server's certificate against
proto_path	---	Path to a `.proto` file on the server - client code is generated out of it automatically
stub_module	---	Alternatively, the Python module with a pre-generated stub, e.g. `billing_pb2_grpc`
stub_class	---	Name of the stub class in `stub_module`, needed only when the module has more than one
ping_timeout	---	How many seconds to wait for the server when pinging (default is `10`)
max_send_message_size	---	The biggest message that can be sent, in bytes (default is `104857600`)
max_recv_message_size	---	The biggest message that can be received, in bytes (default is `104857600`)

outgoing_grpc:
  - name: billing
    address: billing.example.com:50051
    security: billing-api-key
    proto_path: /opt/zato/proto/billing.proto

  - name: inventory
    address: inventory.internal:50051
    is_tls: false
    stub_module: inventory_pb2_grpc

See gRPC examples for Python code.

Pub/sub topics

Key: pubsub_topic

Name	Required	Description
name	Yes	Unique name of the topic
description	---	Optional description of the topic
is_active	---	Whether the topic is active (default is `true`)
is_audit_log_active	---	Whether the topic's traffic goes to the audit log (default is `true`, exported only when `false`)

pubsub_topic:
  - name: enmasse.topic.1
    description: Optional description for topic 1
  - name: enmasse.topic.2

Topics are part of the pub/sub system - the pub/sub API page has more.

Pub/sub permissions

Key: pubsub_permission

Name	Required	Description
security	Yes	Name of the security definition to grant permissions to
pub	---	List of topic name patterns the security definition is allowed to publish to
sub	---	List of topic name patterns the security definition is allowed to subscribe to

pubsub_permission:
  - security: enmasse.basic_auth.1
    pub:
      - enmasse.topic.1
      - enmasse.topic.2
    sub:
      - enmasse.topic.2
      - enmasse.topic.3

  - security: enmasse.basic_auth.2
    pub:
      - enmasse.topic.*
    sub:
      - enmasse.#

For background on pub/sub security, visit pub/sub security.

Pub/sub subscriptions

Key: pubsub_subscription

Name	Required	Description
security	Yes	Name of the security definition that owns the subscription
delivery_type	Yes	How messages are delivered - either `pull` or `push`
topic_list	Yes	List of topic names to subscribe to
push_rest_endpoint	---	Name of an outgoing REST connection to push messages to (required when `delivery_type` is `push` and pushing to a REST endpoint)
push_service	---	Name of a Zato service to push messages to (required when `delivery_type` is `push` and pushing to a service)
max_retry_time	---	How long to retry delivery before giving up, e.g. `365d`, `48h` or `30m`
is_delivery_active	---	Whether delivery is active (default is `true`)

pubsub_subscription:
  - security: enmasse.basic_auth.1
    delivery_type: pull
    max_retry_time: 365d
    topic_list:
      - enmasse.topic.1
      - enmasse.topic.2

  - security: enmasse.basic_auth.2
    delivery_type: push
    push_rest_endpoint: enmasse.outgoing.rest.1
    max_retry_time: 48h
    topic_list:
      - enmasse.topic.1

  - security: enmasse.basic_auth.3
    delivery_type: push
    push_service: demo.input-logger
    max_retry_time: 30m
    topic_list:
      - enmasse.topic.3

Endpoints and subscriptions are explained in the pub/sub endpoints chapter.

Custom connectors

Key: custom_*

Connection types built with the Connector SDK get a top-level key of their own, named after the type - a connector of type crm is configured under custom_crm.

Name	Required	Description
name	Yes	Unique name of the connection
is_active	---	Whether the connection can be used (default is `true`)

Every other field is whatever the connector class declares - the fields are written to the YAML and read back exactly as the connector defines them.

custom_crm:
  - name: enmasse.custom.crm.1
    address: https://crm.example.com
    username: api
    api_key: Zato_Enmasse_Env.CRMAPIKey

Alert rules

Key: alert_rules

Each entry configures the alert rules of one connection type. The values are the same numbers, in the same units, that the alert rules config screen shows - percentages as whole numbers, latencies in milliseconds. Importing an entry updates the live rules in place, so an import that changes nothing is a no-op.

Name	Required	Description
type	Yes	Connection type the entry configures - one of `rest`, `sql`, `llm`, `mcp`, `microsoft`, `email`, `odoo`, `file_transfer`, `scheduler`, `channels` or `common`
is_active	---	Whether the type's alert rules are active as a whole
consecutive_failures	---	How many consecutive failures mean a connection is down (all types except `scheduler`, `channels` and `common`)
error_rate	---	Error share of recent traffic, in percent, that raises an alert (all types except `common`)
alert_threshold	---	Error share, in percent, above which an alert is diagnosed (`rest`, `sql`, `mcp`, `email` and `scheduler`)
max_latency	---	Average response time, in milliseconds, above which responses count as slow (`rest` only)
use_llm	---	Whether alerts above the alert threshold are diagnosed by the LLM (all types except `channels` and `common`)
max_query_time	---	Average query time, in milliseconds, above which queries count as slow (`sql` only)
warning_latency	---	Average completion time, in milliseconds, that raises a warning (`llm` only)
critical_latency	---	Average completion time, in milliseconds, that raises a critical alert (`llm` only)
max_tool_call_time	---	Average tool call time, in milliseconds, above which calls count as slow (`mcp` only)
health_alerts	---	Whether Microsoft service health alerts are raised (`microsoft` only)
max_call_time	---	Average call time, in milliseconds, above which calls count as slow (`microsoft` and `odoo`)
auth_failures	---	How many authentication failures raise an alert (`email` and `odoo`)
warning_failures	---	How many transfer failures raise a warning (`file_transfer` only)
critical_failures	---	How many transfer failures raise a critical alert (`file_transfer` only)
test_transfers	---	Whether periodic test transfers run to confirm connections work (`file_transfer` only)
arrival_overdue	---	How many arrival windows may pass without a file before an alert (`file_transfer` only)
overdue_multiplier	---	How many missed intervals mean a job's run was missed (`scheduler` only)
start_delay	---	Start delay, in milliseconds, above which a job's start counts as delayed (`scheduler` only)
certificate_warning	---	How many days before a certificate expires an alert is raised (`common` only)
outstanding_backlog	---	How many outstanding messages raise an alert (`common` only)
feed_silence	---	How many seconds of silence from a feed raise an alert (`common` only)

alert_rules:
  - type: rest
    is_active: true
    consecutive_failures: 3
    error_rate: 10
    alert_threshold: 25
    max_latency: 5000
    use_llm: true

  - type: file_transfer
    is_active: true
    consecutive_failures: 3
    warning_failures: 10
    critical_failures: 20
    test_transfers: false

Alert notifications

Key: alert_notifications

One mapping, not a list - the default notification targets alerts go to when a rule names none of its own. Email, Slack and Teams deliver through the connections named default.alerts.notifications - these keys hold the addressing only.

Name	Required	Description
webhook_url	---	Webhook alerts are delivered to, e.g. a Jira automation webhook
email_to	---	Addresses alert emails go to, comma-separated
email_from	---	Address alert emails are sent from
dashboard_url	---	Dashboard address the links in notifications point to

alert_notifications:
  webhook_url: https://example.atlassian.net/automation/webhooks/abc
  email_to: ops@example.com
  email_from: zato@example.com
  dashboard_url: https://dashboard.example.com

Audit retention policies

Key: audit_retention

Named audit log retention policies. Each policy says how long events and their payloads are kept and, optionally, where they are archived before deletion.

Name	Required	Description
name	Yes	Unique name of the policy
retention_days	Yes	How many days events are kept
content_retention_days	---	How many days payloads are kept - `0`, the default, means payloads live exactly as long as their events
archive_dir	---	Directory events are archived to before they are deleted

audit_retention:
  - name: enmasse.retention.1
    retention_days: 90
    content_retention_days: 7
    archive_dir: /opt/zato/audit-archive

Attribute extraction rules

Key: audit_extraction

Named sets of rules describing which searchable attributes to pull out of the messages the audit log records - an order ID in a JSON body, a correlation header, a match of a regular expression.

Name	Required	Description
name	Yes	Unique name of the rule set, after the channel or connection it applies to
source	---	The audit source the set applies to, e.g. `rest-channel`
rules	Yes	List of extraction rules - each with `attr_name`, `rule_type` and `expression`