Events

A subscription is triggered by a Control Hub event. You can create a subscription for a single event type.

A subscription is triggered each time the event occurs for objects that you have at least read permission on. For example, if you create a subscription for a changed job status, the subscription is triggered each time any job that you have permission on changes status. The subscription is not triggered for jobs that you do not have access to.

A subscription can be triggered by the following event types:

Data SLA Triggered: Triggers the subscription each time a data SLA triggers an alert.
Execution Engine Not Responding: Triggers the subscription each time a registered engine stops responding.
Job Status Change: Triggers the subscription each time a job status changes.
Max Global Failover Retries Exhausted: Triggers the subscription each time a job enabled for failover has reached the maximum number of pipeline failover retries to attempt across all available engines. The limit is configured for each job in the Global Failover Retries property.
Pipeline Committed: Triggers the subscription each time a pipeline version is committed.
Pipeline Status Change: Triggers the subscription each time a pipeline status changes.

Event Conditions

By default, subscriptions are triggered when all events of the selected type occur. For example, an email is sent every time any job changes its status.

You can define conditions to filter subscription events so that only a subset of events performs an action. For example, you can configure a subscription so that Control Hub sends an email only when the job named SocialMediaFeed changes status.

When you define conditions for subscription events, the subscription is triggered for objects that you have at least read permission on and when the condition is met. For example, if you create a subscription for all job statuses that change to inactive, the subscription first checks that you have permission on that job. If true, the subscription then checks the condition. If the condition is true, then the subscription triggers. The subscription is not triggered for jobs that you do not have access to.

You can define a simple condition by selecting a single subscription parameter and then entering the value that the parameter must equal. For example, you can define a simple condition where a pipeline committed event is triggered only when the pipeline is named WebLogCollection.

To define a condition using multiple parameters or to define a more complex condition using the IBM StreamSets expression language, define an advanced expression for the condition.

Advanced Expressions

To define an advanced expression for an event condition, select Use Advanced Editor and then define an expression using the IBM StreamSets expression language.

Subscription expressions support a subset of elements provided with the expression language, including:

String and miscellaneous functions

All string functions are supported; however, typically you will use the following:

str:contains()
str:endsWith()
str:startsWith()

For more information about the expression language string functions, see string functions.

Some miscellaneous functions are also supported. For more information, see miscellaneous functions.

Subscription parameters

Use subscription parameters to define the argument to evaluate. For example:

${str:contains(JOB_NAME, "tutorial")}

In this example, the expression evaluates to true when a job name contains the string tutorial.

You can also use subscription parameters independent of the string functions. For example:

${JOB_NAME=="tutorial" || JOB_NAME=="test"}

In this example, the expression evaluates to true when the job name exactly matches the string tutorial or the string test.

Note the different syntax for using subscription parameters in event conditions as compared to subscription actions. You do not have to enclose the parameter name in double curly brackets in event conditions.

Operators

You can use operators to create more complex expressions, such as ==, >, or &&. All expression language operators are supported.

For more information about the expression language operators, see operators.

Expression Completion

Use expression completion to determine the parameters and functions that you can use for an advanced expression.

To invoke expression completion, enter the required expression syntax in the Expression field using the dollar sign and curly brackets: ${}. Then begin typing the expression inside the brackets. Control Hub displays a list of valid expression elements which you can scroll through.

For example, when you type ${j} to define an advanced expression for a job status change event, the following list displays:

The list displays available parameters with a c icon and available functions with an f icon. Select a parameter or function from the list to add it to the expression.

After selecting parameters or functions from the list, you must complete the expression using the required syntax for the IBM StreamSets expression language.

For more information on expression completion, see Tips for Expression Completion in the Data Collector documentation.

Example Expressions

The following table includes some examples of how you might use advanced expressions with subscription events:


Expression	Description
${str:contains(TO_STATUS, "ACTIVE")}	Evaluates to true when the job status changes to active or inactive, but not activating or inactivating.
${str:contains(ERROR_MESSAGE, "Not responding")}	Evaluates to true when the error message associated with the job status change contains the string `Not responding`.
${str:contains(JOB_TAG, "north")}	Evaluates to true when the job has at least one tag with the value `north`, including a nested tag that contains the value, such as `sales/north`. The job can have additional tags with other values.
${str:startsWith(SLA_ID, "714ab")}	Evaluates to true when the SLA ID starts with the string `714ab`.
${str:endsWith(JOB_ID, "775e")}	Evaluates to true when the job ID ends with the string `775e`.
${JOB_NAME=='test1' \|\| JOB_NAME=='test2'}	Evaluates to true when the job name is either `test1` or `test2`.
${JOB_NAME=='test' && str:contains(TO_STATUS, "INACTIVE")}	Evaluates to true when the job name is `test` and the job status changes to inactive.
${LAST_REPORTED_TIME>1539734400}	Evaluates to true when the last reported time of an execution engine is earlier than the epoch or Unix time of 1539734400, or Tuesday, October 16, 2018 5:00:00 PM.