Enmasse reference (YAML export/import)

This chapter is a reference for all the options available in enmasse YAML files. For an overview of enmasse, see the enmasse overview page.

REST channels

Key: channel_rest

Name	Required	Description
name	Yes	Unique name of the REST channel
service	Yes	Name of the Zato service that the channel invokes
url_path	Yes	URL path that the channel listens on, e.g. `/api/v1/my-endpoint`
security	---	Name of a security definition to protect the channel with
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 (default is `json`)
content_type	---	Content type that the channel expects in incoming requests
content_encoding	---	Content encoding that the channel expects, e.g. `gzip`
timeout	---	Request timeout in seconds
groups	---	List of security group names whose members are allowed to call this channel

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.

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 (default is `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
content_encoding	---	Content encoding header sent with outgoing requests

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

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
content_encoding	---	Content encoding header sent with outgoing requests

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

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 carries 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

bearer_token

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`)

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

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` or `mssql`
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`)
extra	---	Extra connection parameters, e.g. `connect_timeout=10`
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

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

Cache

Key: cache

Name	Required	Description
name	Yes	Unique name of the cache
is_active	---	Whether the cache is active (default is `true`)
is_default	---	Whether this is the default cache (default is `false`)
max_size	---	Maximum number of items in the cache (default is `10000`)
max_item_size	---	Maximum size of a single item in bytes (default is `1000000`)
extend_expiry_on_get	---	Whether to extend expiry on each get (default is `true`)
extend_expiry_on_set	---	Whether to extend expiry on each set (default is `false`)
sync_method	---	How the cache is synced to persistent storage (default is `in-background`)
persistent_storage	---	Persistent storage backend (default is `sqlite`)

cache:
  - name: enmasse.cache.builtin.1
    extend_expiry_on_get: true
    extend_expiry_on_set: false

Learn more about Python Redis programming as an alternative caching backend.

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`)

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

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.

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_365

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_365:
  - 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.

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
hosts	Yes	URL or newline-separated list of URLs of Elasticsearch nodes, e.g. `http://elasticsearch:9200`
timeout	---	Request timeout in seconds (default is `90`)
body_as	---	How to send the request body (default is `POST`)
is_active	---	Whether the connection is active (default is `true`)

elastic_search:
  - name: enmasse.elastic.1
    hosts: http://elasticsearch:9200
    timeout: 60
    body_as: json

Usage examples: Python ElasticSearch

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

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

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

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

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.

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`)

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.

The enmasse overview explains how enmasse works and how to use it
This complete DevOps tutorial discusses how to deploy your services and projects