If you can't find the product or version you're looking for, visit support.ataccama.com/downloads

Notifications Handler

The notification handler is an online server component for scheduling generic jobs, such as executing a workflow or a Shell script. The execution schedule is determined based on certain changes detected in Metadata Management Module (MMM).

In order to perform scheduled jobs, ONE Runtime Server must be already running. Handler definitions are stored in *.noth files, which the component reads from the locations specified in the sources configuration element. Job executions are logged using the resultPersister (for more information, see How to Log Schedule Execution).

Integration with ONE Runtime Server Admin

As a prerequisite, both the Notification Handler Component and Workflow Component must be defined in the server configuration.

The Notification Handler interface (Notifications) is automatically available in the ONE Runtime Server Admin allowing you to:

List loaded notification handler definitions and display their state (last execution, next execution).
See their statuses (enabled, disabled, error).
Enable or disable a notification handler (which is reflected in the handler configuration files).
Show execution history as tracked by the persister.
List invalid notification handlers and display problem information.

Unsubscribe from the server.

Once the handler is enabled, MMM starts sending notification events to the server, which in turn runs the handler. When the handler is deactivated or the server is not running, MMM caches the unsent events and sends them when the handler becomes available again. As this requires some resources on the MMM side, we recommend first unsubscribing the handler from the server before removing it so that MMM can release any related resources.

Display state in the server Health monitoring - displays how many events were processed in the last hour, 24h, or since the server was started.

The information displayed in the health status section might differ from the actual metrics.

Notification Handler Server Admin interface

Notification handler configuration

Each job for which you want to set up a notification handler must be defined in its own .noth configuration file. Each configuration file must contain a single notificationHandler tag with only one job definition.

In addition, each file must represent a valid XML document (containing a single notificationHandler root element). The available jobs and their definition are described in Define events as parameters in jobs.

Example

The notification handler is defined using the following format:

Example

<notificationHandler>
  <description>Sample handler</description>
  <enabled>true</enabled>
  <job class="com.ataccama.adt.scheduler.job.RunWinCmdJob">
    <command>../resources/greeting.bat ${ewf_NotificationEvents}</command>
    <workingDir>.</workingDir>
    <logStartStop>false</logStartStop>
  </job>
  <serverName>one-server</serverName>
  <subscription ackLimit="5"/>
</notificationHandler>

In this case, the script greeting.bat would be executed whenever an event notification is received.

Enable a notification handler

Jobs are scheduled only if the enabled property is set to true. The property can be set either in the Notification Handler configuration file or using the ONE Runtime Server Admin Notifications section of the Workflows.

You also need to provide the name of the ONE Server to which the handler should subscribe (serverName). The same server is referenced in the Runtime Configuration.

Configure subscription

The following parameters are used to configure to which events the handler should subscribe.

If no entity specification is provided (entityId, entityAncestorId, or entityType), all events are published.

Parameter Required Description

Parameter	Required	Description
`subscriptionId`	No	The unique identifier of the subscription. If not set, the identifier is generated by the server and saved to the definition file.
`ackLimit`	Yes	The maximum number of events that the server sends after the last acknowledged event. Unless acknowledged, this number of messages might be sent multiple times.
`entityId`	No	The unique identifier of the entity. If set, events are published only for this entity.
`entityAncestorId`	No	The unique identifier of the entity. If set, events are published for all descendants of this entity.
`entityType`	No	The type of entity. If set, events are published for all entities of this type, including all descendant types.
`chunkSize`	No	The maximum number of events that can be sent at once, that is, in one notification. This option is used for optimization purposes as it helps reduce traffic when a large number of events occurs in a short period of time.
`chunkMaxDelay`	No	If the number of events on the server is lower than this value, the server waits no more than the specified amount of time before sending events. Expressed in milliseconds, for example, `1000`.
`excludeOwnModifications`	No	If set to `true`, the user does not receive events they initiated themselves. This helps prevent creating infinite loops of generating events, which could occur in cases when the events generated by the handler would in turn invoke the handler again.

subscriptionId

The unique identifier of the subscription. If not set, the identifier is generated by the server and saved to the definition file.

ackLimit

Yes

The maximum number of events that the server sends after the last acknowledged event. Unless acknowledged, this number of messages might be sent multiple times.

entityId

The unique identifier of the entity. If set, events are published only for this entity.

entityAncestorId

The unique identifier of the entity. If set, events are published for all descendants of this entity.

entityType

The type of entity. If set, events are published for all entities of this type, including all descendant types.

chunkSize

The maximum number of events that can be sent at once, that is, in one notification. This option is used for optimization purposes as it helps reduce traffic when a large number of events occurs in a short period of time.

chunkMaxDelay

If the number of events on the server is lower than this value, the server waits no more than the specified amount of time before sending events. Expressed in milliseconds, for example, 1000.

excludeOwnModifications

If set to true, the user does not receive events they initiated themselves. This helps prevent creating infinite loops of generating events, which could occur in cases when the events generated by the handler would in turn invoke the handler again.

Define events as parameters in jobs

The following section describes how to define jobs for notification handlers. As such, it mainly focuses on how to pass received events as variables to different types of jobs. For more general information about job definition, see Scheduler, section Available jobs.

Workflow jobs automatically receive additional variables ewf_NotificationEvents and ewf_NotificationEventsJson that contain received events. As MMM can send multiple events in a single notification, each variable carries one or more events for which the handler is invoked.

ewf_NotificationEvents: A string with semicolon-separated events where each event is a comma-separated list of values. For each event, the following structure is used: id,timestamp,entityStatus,entityType,entityId.

If the variable contains multiple events, the structure is as follows:
```
eventID,timestamp,entityStatus,entityType,entityId;eventID,timestamp,entityStatus,entityType,entityId;...
```

ewf_NotificationEventsJson: This variable contains events in a JSON array, for example:

[
  {
    "id":1,
    "timestamp":"2021-05-25T09:03:23.730010Z",
    "entityId":"cd456b86-157f-4432-b5df-c5602d5b9af5",
    "entityType":"tableAttribute",
    "entityStatus":"UPDATED"
  },
  ...
]

For each event, the following information is available:

id: The identifier of the event.
timestamp: The event timestamp, in XML format.
entityStatus: Describes how the entity was modified, for example, CREATED, UPDATED.
entityType: The type of entity.
entityId: The unique identifier of the affected entity.

Run shell script job

The job executes a Unix-like script. It uses a temporary script file to execute specified commands (the script file is created in the job’s resources directory). This script file is then passed to the selected interpreter (/bin/sh by default).

Workflow variables are provided as variable expansion in the command attribute, for example:

Configuration example

<job class="com.ataccama.adt.scheduler.job.RunShellScriptJob" workingDir="." interpreter="/bin/sh" command='echo \"$%ewf_NotificationEvents%\"' logStartStop="true"/>

The example outputs received events to the standard output stream. The job is run for each notification received.

Run workflow job

The job runs a specified workflow file. In this case, you can declare the variables in the variable element, as shown in the example. Alternatively, you can reference them directly in the workflow itself as they are automatically propagated there.

Configuration example

...
<job class="com.ataccama.adt.scheduler.job.WorkflowJob">
  <!-- for workflows coming from a named source use sourceId:workflowName notation, e.g. source1:myWorkflow.ewf -->
  <workflow>simple-params.ewf</workflow>
  <variables>
    <variable name="events" value="${ewf_NotificationEvents}"/>
  </variables>
</job>
...

The example invokes workflow simple-params.ewf and passes there the events variable. The worfklow is run for each notification received, not each event.

Run parallel workflows

Workflows have a multiplicity property that specifies how many instances can be run in parallel. In case the number of instances started exceeds this limit, they wait in the queue until some previous instance finishes.

In notification handler subscriptions, the ackLimit property determines how many events are delivered to the client after the last acknowledged one, while the chunkSize property configures how many events can be sent in a single notification. A workflow is run for each notification, not for each event.

These properties are applied as follows:

The number of processed events never exceeds the value set in the notification handler ackLimit property.
- If each notification contains only one event, events are split in the ackLimit number of jobs.
- If each notification contains several events (as many as configured in the notification handler chunkSize property), events are split in the minimum number of jobs determined using ackLimit divided by chunkSize.
The number of jobs run in parallel never exceeds the value set in the workflow multiplicity property.
- If each notification contains only one event, the number of jobs in the queue matches the limit set in ackLimit from which the number of instances specified in multiplicity has been subtracted.
- If each notification contains a chunkSize number of events, the number of jobs in the queue matches the number of ackLimit jobs divided by chunkSize, minus the number of instances defined in multiplicity.

Was this page useful?