REST API Specification for Subscription Services

This topic outlines how to subscribe to information published by Automic Automation Intelligence such as alerts, definitionalData, events and predictions. You can then use these subscriptions to feed the information to other parts of your system.

Note:

  • Predictions subscriptions now only require a jobStreamId. JobId and userSuppliedJobStreamId are no longer supported

  • The URL for deletion of a subscription for a subscriptionId now includes a slash just before the subscriptionId

  • All subscriptions are now persisted to a single database table named PubSub_V2

This page includes the following:

API Specification

Use the requests as follows:

  • POST to create a subscription

  • GET to retrieve a subscription

  • DELETE to delete subscriptions

Exception handling

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.

Status Codes

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.

Authentication

Currently, authentication is not required for this API.

Requests

This table describes the generalized subscription endpoints:

HTTP Verb Resource Input Expected Output (HTTP/1.1)
POST /v2/subscription/{topic} 
{
“callBackUrl” : [String],
“callBackVerb” : [String],
“filter” : {
    “key1” : “value1”,
    “key2” : “value2”,
    .
    .
    .
  }
}

Where:

  • callBackUrl is the URL to which subscribed messages are sent

  • callBackVerb is the HTTP request method used to send the published data to callBackUrl

  • filter is a collection of key/value pairs used to select which published AAI messages should be sent to the callBackUrl

Note:

Messages are channeled through different topics. The available topics are listed in Appendix A.

For more information, see Available Topics.

Success code: 201 Created

Content:

{
  "subscriptionId" : [String],
  "callBackUrl" : [String],
  "callBackVerb" : [String],
  “topic” : [String],
  “filter” : {
    “key1” : “value1”,
    “key2” : “value2”,
    .
    .
    .
  }
}
GET /v2/subscription/{subscriptionId} N/A

Success code: 200 OK

Content: 

{
  "subscriptionId" : [String],
  "callBackUrl" : [String],
  "callBackVerb" : [String],
  “topic” : [String],
  “filter” : {
    “key1” : “value1”,
    “key2” : “value2”,
    .
    .
    .
  }
}
GET /v2/subscriptions/{topic} N/A

Success code: 200 OK

Content: 

[
  {
    "subscriptionId" : [String],
    "callBackUrl" : [String],
    "callBackVerb" : [String],
    “topic” : [String],
    “filter” : {
      “key1” : “value1”,
      “key2” : “value2”,
      .
      .
      .
    }
  },
 { another subscription
 },
 .
 .
 .
]
DELETE /v2/subscription/{subscriptionId} N/A Success code: 200 OK

Data Dictionary

  • callBackUrl

    Allowed values: Any valid URL

  • callBackVerb

    Optional. PUT is the default if not specified

    Allowed values: PUT, POST

  • topic

    Allowed values: See Available Topics below

    A 404 (Bad Request) response is returned if the topic is not supported

  • filter

    Allowed values: See Available Topics below

Available Topics

This table describes the topics and their filter parameters:

Topic Filter Parameters Description
Alerts See Swagger documentation

See Swagger documentation

Note:

Alert content also includes a bestCasePredictedRunEndTime field containing a time if available or “Unavailable” if not
Predictions See Swagger documentation See Swagger documentation
DefinitionalData See Swagger documentation See Swagger documentation
Events See Swagger documentation See Swagger documentation
JobRunPredictions jobId

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 jobStreamId

JobStream run ids that have changed for the following reasons:

because 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 or when a forecast jobstream run starts running.

Expected message content:

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

transitionType can be

DELETED

MERGED

REPLACED_BY_REAL_RUN

EXPIRED

The supercedingJobStreamRunId is included for MERGED and REPLACED_BY_REAL_RUN transitionTypes
NptfPredictions jobStreamId

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 None

A signal that the converter has run

Expected message content: None

Enabling the Subscription API

You can subscribe to events on the Swagger JAWS subscriptions page and receive notifications when those events occur.

To Enable the Subscription API

  1. Go to the Swagger JAWS subscriptions page at http://<aai hostname>:8080/subscriptionService/swagger-ui.html#/. The list of available subscriptions appears.

  2. Select the subscription.

    Example

    To subscribe to AAI Alerts, on the Swagger JAWS subscriptions page, use POST /subscritptions/alerts.

    This screenshot shows its location:

    Scroll down to Model Example | Value to enter the subscription definition:

  3. Enter the API endpoint that will receive the subscription alerts.

  4. In the Configuration Tool enable subscription.* parameters for the subscription you want to receive.

    Example

    For alerts, enable the subscriptions.publishAlerts parameter:

  5. Set the SubscriptionService logger to DEBUG.

  6. Verify that the subscriptions are sent by reviewing the subscriptions.log in the /<Install Dir>/jboss/standalone/log directory.

See also:

Configuration Tool - Params Tab