REST API Specification for Subscription Services

You can use the REST API to subscribe to information published by Automic Automation Intelligence to then forward them to an HTTP REST endpoint either in our outside your AAI system. That includes also third-party systems such as ServiceNow, Slack, or DX Operational Intelligence, so that the information is published directly on the target system. This section gives you an overview of the function and implementation of these subscription services.

Overview

The subscription services provided are an integral part of AAI and are installed by default. The API reference is written in OpenAPI (Swagger) and all exchanges are in JSON format. You can subscribe to events on the Swagger JAWS Subscriptions page, which has a complete list of endpoints available and can be reached using the following URL:

http://<aai_hostname>:8080/subscriptionService/swagger-ui.html#/

Click any of the endpoints listed to display or hide the operations available for that endpoint. Once you expand an operation, you can see a brief description of its purpose as well as all relevant parameters. POST operations include examples of how to use them. You can also try out all the operations available.

Implementation Steps

Subscribing to information published by AAI such as alerts, definitional data, events and predictions allows you to feed this information to other parts of your system and/or third-party systems so that they receive notifications when those events occur.

To use these services you have to:

1. Enable the relevant subscription services using the Configuration Tool, see Enabling Publishing for Subscription Services.

2. If you want to integrate these services with a third party, you need to define a template, which transforms the AAI data output to a format accepted by that third party before publishing it to the target system, see Working with Templates.

3. Create the subscription services where you define all the relevant data, including the endpoint to which the data should be delivered, see Working with Subscriptions.

Exception Handling, Common HTTP Status Codes, and Usage in the REST API

HTTP status codes are generally used to indicate processing results. Whenever practical and useful, details of the error condition are reported back to the caller as a JSON formatted object.

This list describes the most common HTTP status codes and their usage:

• HTTP 200 - OK

  The information you requested should be in the payload

• HTTP 201 - Created

  The request has been fulfilled and a new resource has been created

• HTTP 400 - Bad Request

  When a call does not contain valid input or when an API is not yet implemented.

  See error detail payload for additional information {Error : unexpected JSON format}

• HTTP 404 - Not Found

  The requested resource is not found in Automic Automation Intelligence

• HTTP 422 - Unprocessable Entity

  For a duplicate subscription

• HTTP 500 - Internal Server Error

  Something unexpected went wrong on the server side. See error detail payload for additional information.

Parameters

These are some of the parameters available for the subscription services REST API requests. They can be used with both versions of the REST API.

• alertTimeZone

  Description: The time zone in which the alert was defined.

  Note:

  If the time zone is not specified explicitly, the system will try to guess it but it might not be accurate. Use this parameter to set it explicitly.

  Mandatory: No

• alertType

  Description: The type of the alert that is to be forwarded.

  Mandatory: Yes

• callbackUrl

  Description: The URL of the third-party system to be called.

  Mandatory: Yes

• callbackVerb

  Description: The HTTP method that the third-party system accepts.

  Allowed values: PUT, POST

  Mandatory: Yes

• filter (v2 only)

  Description: A collection of key/value pairs used to select which published AAI messages should be sent to the callBackUrl.

  Mandatory: No

• header1 / header2 / header3

  Description: Any custom headers that the third party system requires. For example, content type, accept or authorization headers.

  Mandatory: No

• jobStreamId

  Description: The id of the jobstream to be monitored for alerts that need to be forwarded. The jobStreamId and alertType parameters together form the filter that decides which alerts will be forwarded. Subscriptions are created on the pair of jobstream - denoted by the jobstreamId - and the alert type generated on that jobstream.

  Mandatory: Yes

• suppressionEnabled

  Description: Defines is the subscription will be forwarded or not. If this parameter is not configure, the subscription behaves as if it were not enabled.

  • Disabling this parameter means that the subscription is not suppressed.

    The alert (defined for a particular jobstream and a particular alert type) is forwarded to the third party system.

  • Enabling this parameter means that the subscription is suppressed for the period defined in the suppressionTime parameter.

    Any further alerts (for that particular jobstream and of that particular alert type) are restricted from being published for the period defined.

  Mandatory: No

• suppressionTime

  Description: When suppression is enabled for a subscription, this parameter defines how long a subsequent alert is suppressed.

  Mandatory: No

• templateId

  Description: The ID of a template that is used to transform the alert payload so that a third-party system can use it.

  Note:

  The payload of an AAI alert is transformed only when a template is associated with a subscription. If it is not associated (templateId is set to null), the alert payload is used as defined by AAI.

  Mandatory: No

Enabling Publishing for Subscription Services

You enable the subscription services using the Configuration Tool. To do so, follow these instructions:

1. On the Configuration Tool, go to the Params tab and show the less common configured parameters, see Configuration Tool - Params Tab.

2. Set all the subscription.* parameters for which you want to enable subscription services to true.

   The subscriptions.publishAlerts parameters is enabled (true) by default.

   

3. Once the subscriptions are enabled, make sure that you can verify that they are sent.

   To do so, on the Logging tab, display the all loggers parameters and set the subscriptions logger to DEBUG.

   

4. Open the subscriptions.log file in the /<Install Dir>/jboss/standalone/log directory to check if the subscriptions were sent as expected.

Working with Templates

Templates define the mapping between AAI alerts and the third-party system. That means the template substitutes the values of the AAI alerts with values that are readable by the target system.

You can create a template for a specific third-party integration and use that template's ID for all subsequent requests. That means that you only need to create a template for a specific purpose once.

The following templates are provided by default:

• DX OI Job Late Alert to create an alert in DX OI for every job that is running when a jobstream is late

• ServiceNow Create Incident for alerts, to create an incident ticket in ServiceNow

• Slack Event for events, to create a notification in Slack

• Slack Jobstream Delayed for alerts, to create a notification in Slack

• Slack Prediction for predictions, to create a notification in Slack

REST API Specifications

The preview and templates section of the JAWS Subscriptions page allow you to work with templates with and without saving them to the database. Use the corresponding requests as follows:

Preview

• GET to preview an alert message with an existing template to transform it

• POST to preview an alert message with a new template to transform it, without saving the template to the database

Templates

• GET to search templates by name as well as to get one or all templates from the database, specified by the ID

• DELETE to delete a template from the database, specified by the ID

• POST to add a template and save it to the database

• PUT to updated and existing template and save it to the database

The HTTP status codes and their usage apply to all operations are the same for all operations available on the JAWS Subscriptions page, see Exception Handling, Common HTTP Status Codes, and Usage in the REST API.

Defining Templates

A template is defined in JSON as a set of key/value pairs. It contains the template's name, which should identify the purpose of the template, and the transformation rules (the template itself). Defining both parameters - name and template - is mandatory when creating a template.

{
  "dateFormat": "string",
  "name": "string",
  "replaceMap": {},
  "template": {},
  "timeZone": "string"
}

When the template runs, it creates a JSON output payload with the keys as defined in the template.

Example

The template defines the following:

• key: text

• value: AAI: Jobstream ${jobStreamName} is completed

Template

{
    "name": "Slack-Complete",
    "template": {
        "text": "AAI: Jobstream ${jobStreamName} is completed"
    }
}

When run, the output payload is created with the respective substitutions.

Output Payload

{
    "text": "AAI: Jobstream ipmt-jaws-target is completed"
}

When defining the value for a key, you can also use include special operators, which are identified as ${parameter}. When the template runs, they are replaced in the string value with the corresponding values from the AAI alert payload. Any value of an AAI alert payload can be used as a parameter. You can also use multiple parameters, all of which will be processed and replaced accordingly.

Example

{
  "targetJob" : {
    "schedulerName" : "R11-01",
    "schedulerId" : "AYMcS-3IAAo=",
    "jobId" : "AYMcdQpLEiY=",
    "externalJobId" : "2562",
    "jobName" : "ipmt-jaws-target"
  },
  "jobStreamAverageEndTime" : "2022/10/19 00:02:36.729 IST",
  "jobStreamAverageDuration" : "5:33.729",
  "startTime" : "10/18/2022 14:27:03 EDT",
  "elapsedTime" : "0:04:52",
  "severity" : "normal",
  "jobStreamName" : "ipmt-jaws-target",
  "alertType" : "JOBSTREAM_COMPLETE",
  "predictedJobs" : "0",
  "alertTime" : "10/18/2022 14:32:08 EDT",
  "runningJobs" : [ ],
  "percentComplete" : "100",
  "lateEndTime" : "10/18/2022 14:33:00 EDT",
  "jobStreamId" : "AYPrK9JuB_Y=",
  "asOfTime" : "10/18/2022 14:31:55 EDT",
  "earlyLate" : "-0:01:05",
  "jobStreamRunId" : "AYPsWb_YcdE=",
  "predictedEndTime" : "10/18/2022 14:31:55 EDT",
  "jobsInJobStream" : "6",
  "completedJobs" : "5",
  "visibleAlertType" : "Complete"
}

An alert payload in AAI can also contain complex objects, which can also be used as a parameter. To do so, you have to specify their full path separated by a dot. For example, the jobName of the targetJob can be referred to by ${targetJob.jobName}.

In some cases, the mapping can get complicated because the values of the AAI alert and those in the target system do not align perfectly.

Example

In ServiceNow, the impact and severity value definition differs from their definition in AAI. To solve these kind of issues you can create a replacement map and use it in the replaceMap parameter definition. This map is a static list of replacements to be performed to get valid values as needed by the third party system.

In this example, the map defines the following replacement values:

• normal: 2

• critical: 1

To apply the replacements, you use a double parameter substitution, such as ${${severity}}.

Template

{
    "replaceMap": {
        "normal": "2",
        "critical": "1"
    },
    "template": {
        "short_description": "${jobStreamName}-${alertType}",
        "description": "AAI-${jobStreamName}-${alertType}",
        "urgency": "${${severity}}",
        "impact": "${${severity}}",
        "severity": "${${severity}}"
    }
}

When run, the template replaces first the inner parameter with the value as defined in AAI. This means that ${${severity}} becomes either ${Normal} or ${Critical}, depending on the AAI alert. These values then get replaced as specified in the replacement map and the output payload contains the values as required by ServiceNow.

Output Payload

{
    "short_description": "ipmt-jaws-target-JOBSTREAM_COMPLETE",
    "description": "AAI-ipmt-jaws-target-JOBSTREAM_COMPLETE",
    "urgency": "2",
    "impact": "2",
    "severity": "2"
}

A template can also have keys that are treated as variables, for example, _varl. These variables are not copied directly to the output payload, but are instead treated as placeholders and can be used as parameters for substituting in values in regular keys. Variables can have the same values as regular keys: strings and objects, replaced parameters, double-replaced parameters or any combination of them.

Example

Template

{
    "name": "Slack-Complete",
    "template": {
        "_var1": ${jobStreamName} and ${targetJob.jobName},
        "text": "AAI: Jobstream ${_var1} is completed"
    }
}

Output Payload

{
    "text": "AAI: Jobstream ipmt-jaws-target & impt-jaws-target is completed"
}

Depending on the third-party system, there can be special rules for handling time and date strings. Special operators are provided to handle these cases. Compare the two templates below.

Example

The two templates in this example handle time and date differently.

Template 1 uses ${lateEndTime} as is. In this case, date and time displayed in the output payload for template 1 uses the same date/time format and the time zone as defined in the AAI alert payload.

Template 1

{
    "name": "Slack-Complete",
    "template": {
        "_var1": ${jobStreamName} and ${targetJob.jobName},
        "text": "AAI: Jobstream ${_var1} is completed at ${lateEndTime}"
    }
}

Output Payload 1

{
    "text": "AAI: Jobstream ipmt-jaws-target & impt-jaws-target is completed at 10/18/2022 14:33:00 EDT"
}

Template 2 uses the dateFormat and timeZone parameters for ${lateEndTime}. In this case, the date/time is formatted and convert it to any desired time zone in the output payload. Any Java date/time format string and time zone can be used, either individually or together.

Template 2

{
    "name": "Slack-Complete",
    "template": {
        "_var1": ${jobStreamName} and ${targetJob.jobName},
        "text": "AAI: Jobstream ${_var1} is completed at ${lateEndTime}"
    }
    "dateFormat": "yyyy-MMM-dd'T'HH:mm:ss+0000",
    "timeZone": "UTC"
}

Output Payload 2

{
    "text": "AAI: Jobstream ipmt-jaws-target & impt-jaws-target is completed at 2022-DEC-10T18:33:00+0000"
}

Working with Subscriptions

The subscriptions section has two versions of the REST API available. Endpoints with no explicit version defined refer to version 1 (/subscriptionService/subscription/events). Version 2 endpoints have the version embedded in it (/subscriptionService/v2/subscription/{topic}).

You can use either one to create your subscriptions. Make sure you read the instructions on how to create subscriptions for the version that you want to use.

REST API Specifications

The subscriptions section of the JAWS Subscriptions page allows you to setup your event subscriptions. These specifications apply to both v1 and v2.

Use the corresponding requests as follows:

• POST to create a subscription

• GET to retrieve a subscription

• DELETE to delete subscriptions

The HTTP status codes and their usage apply to all operations available on the JAWS Subscriptions page, see Exception Handling, Common HTTP Status Codes, and Usage in the REST API.

POST operations include examples of how to use them. You can also try out all the operations available. To do so:

• Click the Try it out button at the right of the Parameters entry.

  The Example Value | Model switches to Edit Value mode.

• Enter the subscription definition and click the Execute button to run the test.

  The result of the test is listed in the Responses section.

• Click the Clear button to remove the definition used for the test.

• Click the Cancel button to exit the Edit Value mode.

V1 Subscriptions

To create new subscriptions using v1, follow these instructions:

1. Go to the Swagger JAWS Subscriptions page at http://<aai hostname>:8080/subscriptionService/swagger-ui.html#/.

2. Expand the subscription section, which contains all endpoints available for v1 and v2.

3. Select the subscription the relevant subscription and make the necessary definitions.

   Example

   To subscribe to AAI Events, use POST /subscriptionService/subscritptions/events. When you click it, you can see a brief description of its purpose as well as all relevant parameters. All the parameters available can be used as a variable in the template definition.

Besides creating new subscriptions, you can get already existing ones as well as delete them. The JAWS Subscriptions page contains all the relevant information.

V2 Subscriptions

To create new subscriptions using v2, follow these instructions:

1. Go to the Swagger JAWS Subscriptions page at http://<aai hostname>:8080/subscriptionService/swagger-ui.html#/.

2. Expand the subscription section, which contains all endpoints available for v1 and v2.

3. Select GET ​/subscriptionService​/v2​/subscription​/{topic} and make the necessary definitions.

   Important!

   If you want to integrate a subscription with a third-party, make sure that the subscription request includes the template id of the relevant template.

4. In v2, messages are channeled through different topics. Make sure you define the relevant one. For more information, see Available Topics.

Besides creating new subscriptions, you can get an existing subscription using either a specific subscription ID or by using one of the topics available. You can also use a specific subscription ID to delete that subscription. The JAWS Subscriptions page contains all the relevant information.

Available Topics

This section provides an overview of the topics and their filter parameters.

• Alerts.<alertType>

  This topic definition must include the Alert plus the alert type to which you want to subscribe separated by a dot. For example, Alerts.JOBSTREAM_TARGETJOB_STARTED.

  The alert types available are listed in the POST /subscriptionService/subscritptions/alerts endpoint.

  The alert content also includes a bestCasePredictedRunEndTime field containing a time if available or Unavailable if not.

• Predictions

• DefinitionalData

• Events

• JobRunPredictions

  • Filter parameters: jobId

  • Description: Predicted jobRuns for the given jobId.

  • Expected message content:

    {
    "currentStatus" : "Success",
    "schedulerId" : "AW1LIB3CXhI=",
    "jobId" : "AW1LICjEY3M=",
    "isStartTimePredicted" : true,
    "jobDuration" : "5:02",
    "jobExternalId" : "12999",
    "jobStartTime" : "2019/11/20 15:10:14.854 MST",
    "jobEndTime" : "2019/11/20 15:15:16.854 MST",
    "jobName" : "Hourly_Target",
    "schedulerName" : "engautosysr11-01"
    }

• JobStreamRunsTransitioned

  • Filter parameters: jobStreamId

  • Description: JobStream run ids that have changed for the following reasons:

    • a user deletes a jobstream run

    • a user rebuilds jobstream run history

    • a jobstream run has expired

    • a jobstream run is merged into another jobstream run

    • a forecast jobstream run starts running

  • Expected message content:

    {
        "transitionType" : "TRANSITION_TYPE",
        "supercedingJobStreamRunId" : "abcd",
        "jobStreamId" : "efgh",
        "jobStreamRunId" : "ijkl",
        "jobStreamName" : "mkt_price_001"
    }
    

    The transitionType can be DELETED, MERGED, REPLACED_BY_REAL_RUN, EXPIRED.

    The supercedingJobStreamRunId is included for MERGED and REPLACED_BY_REAL_RUN transitionTypes.

• NptfPredictions

  • Filter parameters: jobStreamId

  • Description: What-If predictions for jobRuns that are not expected to finish.

  • Expected message content:

    {
    "schedulerName": "MyAutoSysScheduler",
    "jobStreamId": "AV8WnsrKSTE=",
    "asOfTime": "2017/10/24 13:16:20.809 MDT",
    "jobId": "AV8WnNSlBhE=",
    "schedulerId": "AV8WnMqXABo=",
    "jobStreamName": "mkt_price_003",
    "jobStreamRunId": "AV8WnNSlBhE=",
    "jobName": "mkt_price_003",
    "jobExternalId": "121",
    "jobStartTime": "2017/10/24 13:28:32.931 MDT",
    "isStartTimePredicted":true,
    "jobEndTime": "2017/10/24 13:32:35.322 MDT",
    "jobDuration": "4:02.391"
    "currentStatus": "Success"
    }

• PostConverterNotifications

  • Filter parameters: None

  • Description: A signal that the converter has run

  • Expected message content: None

See also:

Configuration Tool - Params Tab