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 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:
<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 |
---|---|---|
|
No |
The unique identifier of the subscription. If not set, the identifier is generated by the server and saved to the definition file. |
|
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. |
|
No |
The unique identifier of the entity. If set, events are published only for this entity. |
|
No |
The unique identifier of the entity. If set, events are published for all descendants of this entity. |
|
No |
The type of entity. If set, events are published for all entities of this type, including all descendant types. |
|
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. |
|
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, |
|
No |
If set to |
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:
<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.
...
<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 usingackLimit
divided bychunkSize
.
-
-
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 inmultiplicity
has been subtracted. -
If each notification contains a
chunkSize
number of events, the number of jobs in the queue matches the number ofackLimit
jobs divided bychunkSize
, minus the number of instances defined inmultiplicity
.
-
Was this page useful?