Skip to end of metadata
Go to start of metadata

Introduction

  • Notifications are managed from the Configuration -> Notification sub-view.
  • The configuration format of notifications is XML. The JOC Cockpit offers an XSD schema-aware XML Editor for configuration purposes.
  • The configuration is applied by the JS7 - Monitor Service that inspects the workflow execution history and creates notifications as required.

    • Changes to the configuration are instantly applied by the Monitor Service.

Notification View

The Notification View allows to manage the configuration:


Explanation:

  • If this view shows an empty configuration then the "New" button can be used to created a configuration.
  • Alternatively a configuration can be added with the "Upload" button. A configuration sample is available from the jetty_base/resources/xsd/notifications/notification.xml-example file.

Configuration

Structure and Elements

The configuration make use of the following base elements that are available from the Configurations root element.

  • Fragments: Define re-usable configuration blocks for Messages, Monitors and monitored Objects.
    • MessageFragments
      • Message
        • Defines the content that is sent e.g. by mail to a user or that is used to parameterize a command line utility, e.g. for forwarding to a System Monitor.
          • Messages for use with E-Mail represent the mail body either for use with plain text e-mails or for use with HTML e-mails.
            • Messages for use with the Command Line represent a string that can be used with the Notifications/Notification/NotificationMonitors/CommandFragmentRef element, see below.
          • Message elements can include Monitor Variables that are placeholders for values, e.g. for the Workflow Path, Order ID etc.
          • Any number of Message elements can be added.
      • MonitorFragments. Such fragments come in a number of flavors for the following notifcation types.
        • MailFragment
          • The following elements are required to send mail:
            • MessageRef: Specifies the reference to a Message element that provides the mail body.
            • Subject: Specifies the mail subject that can include Monitor Variables.
            • To: Specifies the e-mail address of the recipient. Multiple recipients can be separated by comma.
          • The following elements are optional to send mail:
            • CC: The recipient of carbon copies. Multiple recipients can be separated by comma.
            • BCC: The recipient of blind carbon copies. Multiple recipients can be separated by comma.
            • From: The e-mail address of the account that is used to send mail. Consider that it depends on your mail server configuration if a specific account has to be used or if an arbitrary account can be used.
          • For details see JS7 - Notifications - Configuration Element MailFragment
        • CommandFragment
          • MessageRef: Specifies the reference to a Message element that provides the content that should be forwarded with the Command element. The message content is available from the ${MESSAGE} Monitor Variable for use with later elements.
          • Command: Specifies the shell command for Linux/Windows that is used to forward notifications, e.g. a System Monitor Agent utility.
            • The above notification view example makes use of a shell command like this:
              • echo "${MESSAGE}" >> /tmp/notification.log
            • The echo shell command appends the content of the ${MESSAGE} Monitor Variable to a file in the /tmp directory.
          • For details see JS7 - Notifications - Configuration Element CommandFragment
        • JMSFragment
        • NSCAFragment
          • This fragment type is used for direct connections to System Monitors that operate a Nagios-compatible NSCA service for passive checks such as Nagios®, Icinga®, Opsview®. This fragment type makes use of the JSend NSCA Java API.
          • The required connection attributes such as host, port, timeouts are specific for the respective System Monitor.
          • Consider that JSend NSCA can be used without encryption or with an XOR or TRIPLE_DES encryption. Additional encryption schemes are not supported.
          • For details see JS7 - Notifications - Configuration Element NSCAFragment
      • ObjectsFragments
        • Workflows: Any umber of workflow configurations can be added and are distinguished by a unique name that is added to this element.
          • Workflow: A specific workflow can be specified, e.g. by its name. The path attribute allows a regular expression to specify a part of the workflow path.
            • WorkflowJob: This element can be used to limit notifications to specific jobs in a workflow.
              • This includes to optionally specify the job name and/or its label.
              • When using this element then it is required to specify the criticality that can be one of ALL, NORMAL, CRITICAL.
              • Optionally the return_code_from and return_code_to attributes can be used to further limit notifications to jobs that complete with the given return code. For shell jobs the return code corresponds to the OS exit code.
  • Notifications: Define the effective notifications by references to the above Fragments elements.
    • Notification: Any number of notifications can be added and are distinguished by a unique name. A notification is assigned a type that is any of SUCCESS, WARNING and ERROR. This allows to specify notifications that are used e.g. in case of job errors and warnings. And this allows to specify notifications in case of successful workflow execution. Consider that successful executions include both absence of job errors and optionally presence of job warnings.
      • NotificationMonitors: Selects one or more of the above MonitorFragments. It is possible to select multiple fragments of the same fragment type.
        • CommandFragmentRef: Selects the CommandFragment to be used.
          • MessageRef: Selects the Message element to be used with the Command.
        • MailFragmentRef: Selects the MailFragment to be used in order to send notifications by mail. If multiple MailFragment elements are referenced then different types of mail, e.g. for different recipients or with different content and layout of the mail body can be used.
        • NSCAFragmentRef: Selects the NSCAFragment to be used for direct integration with a NSCA compatible System Monitor.
        • JMSFragmentRef: Selects the JMSFragment to be used to send notifications to a Java Message Queue compatible product.
      • NotificationObjects: Selects the workflows for which notifications are created.
        • WorkflowRef: Selects a Workflows element that limits notifications to the respective workflows. Any number of workflow references can be added.

Monitor Variables

  • Syntax
    • All variables have to be used with the following syntax independently from the operating system in use: ${VARIABLE_NAME}
  • Scope
    • The Message element can include Monitor Variables: users can select the variable names from the below list of variables and use for example ${MON_N_CREATED}.
    • The Command elements can include Operating System Variables: users have to prefix variable names from the below list with JS7_ to use for example ${JS7_MON_N_CREATED}.

Notification Variables

The following variables are available from the configuration and can be used with Message elements and with Command elements.

 List of Notification Variables
NameDescription  Possible values
MON_N_IDThe unique identifier of the monitoring entry.
MON_N_TYPEThe message type corresponds to the specified type with the Notification element.SUCCESS, WARNINGERROR, RECOVERED
MON_N_STATUSA numeric status identifier that can be used for integration with a System Monitor.0-OK, 1-WARNING, 2-CRITICAL, 3- UNKNOWN
MON_N_RANGEAn indicator for the monitor scope.WORKFLOW, WORKFLOW_JOB
MON_N_NOTIFICATION_ID

The notification_id of the Notification element in use.


MON_N_RECOVERED_IDThe identifier of a monitoring entry that previously reported an error and that is considered recovered by the current monitoring entry.
MON_N_CREATEDThe timestamp that the monitoring entry has been added.

Order Variables

The following variables are available from orders and can be used with Message elements and with Command elements.

 List of Order Variables
NameDescription  Note
MON_O_CONTROLLER_ID
The JS7 Controller ID.
MON_O_CREATEDThe timestamp that the order monitoring entry is added.
MON_O_CURRENT_HOS_IDThe monitoring identifier of the current order step.
MON_O_END_HOS_IDThe monitoring identifier of the final order step.
MON_O_END_TIMEThe timestamp for the end of order execution.Consider that in case of job errors an order might be halted in a failed state and does not provide an end time as the order did not completely execute the workflow.
MON_O_END_WORKFLOW_POSITIONThe textual workflow position ...
MON_O_ERRORThe Boolean value true or false that indicates if an error occurred.
MON_O_ERROR_CODEA JS7 error code in case that a known error occurs.
MON_O_ERROR_REASONA predefined reason that indicates the cause of error, e.g. failed.
MON_O_ERROR_RETURN_CODE

MON_O_ERROR_STATEThe order state caused by the error, e.g. failed, broken.
MON_O_ERROR_TEXTThe error message in case that an error occurred.
MON_O_HAS_CHILDRENThe Boolean value true or false indicates that the current order is a parent order with forked child orders.
MON_O_HISTORY_IDThe Order History ID (unique identifier).
MON_O_LOG_IDThe identifier of the order log.
MON_O_MAIN_PARENT_IDIf the current order is a nested child order then this identifier points to the monitoring identifier of the main parent order.
MON_O_MODIFIEDThe timestamp that the order monitoring entry has been modified.
MON_O_NAMEThe Order ID (unique identifier).
MON_O_ORDER_IDThe Order ID (unique identifier).
MON_O_PARENT_ID

If the current order is a child order then this identifier points to the monitoring identifier of the direct parent order.

Consider that child orders can be nested.
MON_O_PARENT_ORDER_ID

MON_O_SEVERITYThe Order History status.
MON_O_START_CAUSE

MON_O_START_PARAMETERS

MON_O_START_TIMEThe timestamp for the start of order execution.
MON_O_START_TIME_PLANNED

MON_O_START_WORKFLOW_POSITION

MON_O_STATE

MON_O_STATE_TIME

MON_O_TIME_ELAPSEDThe difference in seconds between the start time and the end time of order execution.
MON_O_WORKFLOW_FOLDER

MON_O_WORKFLOW_NAME

MON_O_WORKFLOW_PATHThe identifier of the workflow that the order is executed for.
MON_O_WORKFLOW_POSITION

MON_O_WORKFLOW_TITLEThe title of the workflow that the order is executed for.
MON_O_WORKFLOW_VERSION_IDThe version identifier of the workflow.

Order Step Variables

The following variables are available from order steps, e.g. from jobs executed with a workflow and can be used with Message elements and with Command elements.

 List of Order Step Variables
NameDescription  Note
MON_OS_AGENT_IDThe unique identifier of an Agent that is specified when registering an Agent.
MON_OS_AGENT_URIThe URI of the Agent that executes the current job
MON_OS_CREATEDThe timestamp that the monitoring entry is added.
MON_OS_END_PARAMETERSThe list of resulting order variables after execution of the current job or workflow instruction.
MON_OS_END_TIMEThe timestamp for the end of job execution.
MON_OS_ERRORThe Boolean value true or false that indicates if an error occurred.
MON_OS_ERROR_CODEA JS7 error code in case that a known error occurs.
MON_OS_ERROR_REASONA predefined reason that indicates the cause of error, e.g. failed.
MON_OS_ERROR_STATEThe order state for the current order step caused by the error, e.g. failed, broken.
MON_OS_ERROR_TEXTThe error message in case that an error occurred.
MON_OS_HISTORY_IDThe Order History identifier for the current order step.
MON_OS_HO_IDThe Oder History identifier.
MON_OS_HO_MAIN_PARENT_IDThe Order History identifier of the parent order in case that the current order is a forked child order.
MON_OS_JOB_CRITICALITYThe criticality as defined with the job.
MON_OS_JOB_LABELThe unique label of the job instruction in the workflow.The label is unique for each occurrence of a job in a workflow.
MON_OS_JOB_NAMEThe name of the job that the order is executing.
MON_OS_JOB_TITLEThe title of the job that the order is executing.
MON_OS_LOG_IDThe identifier of the task log.
MON_OS_MODIFIEDThe timestamp that the monitoring entry is modified.


MON_OS_POSITIONThe numeric position index of the order in the workflow.
MON_OS_RETURN_CODEFor shell jobs the operating system exit code is returned. For JITL jobs and for JVM jobs the return code optionally is implemented by the respective Java class.
MON_OS_SEVERITYThe Order History status of the current order step.
MON_OS_START_CAUSEThe cause for the start of the order step.
MON_OS_START_PARAMETERSThe list of order variables before execution of the current job or workflow instruction.
MON_OS_START_TIMEThe timestamp for the start of job execution.
MON_OS_TIME_ELAPSEDThe difference in seconds between the start time and the end time of order execution.
MON_OS_WARNThe indicator if a warning occurred, e.g. NONE.
MON_OS_WARN_TEXTThe warning message in case that a warning occurred.
MON_OS_WORKFLOW_POSITIONThe textual position indicator of the order in the workflow.

JOC Cockpit Variables

The following variables are available for access to JOC Cockpit and can be used with Command elements and with Message elements.

 List of JOC Cockpit Variables
NameDescription  Note
JOC_HREF_JOB
The JOC Cockpit URL that points to the Workflows view with the respective job.
JOC_HREF_JOB_LOGThe JOC Cockpit URL that points to the job's task log.This URL can be used to navigate in JOC Cockpit to the respective Task History entry and to immediately open the log view window.
JOC_HREF_ORDERThe JOC Cockpit URL that points to the Order History view.This URL can be used to navigate in JOC Cockpit to the respective Order History entry.
JOC_HREF_ORDER_LOGThe JOC Cockpit URL that points to the Order log.This URL can be used to navigate in JOC Cockpit to the respective Order History entry and to immediately open the log view window.
JOC_HREF_WORKFLOWThe JOC Cockpit URL that points to the Workflows view.This URL can be used to navigate in JOC Cockpit to the respective entry in the Workflows view.

Further References

  • No labels
Write a comment…