A Complete Example - ReadConsumptionBatch

The example details the execution of a ReadConsumptionBatch - a business operation. It produces a data file set and exports consumption and counter-information matching a specified value.

This example explains the various scenarios at the wire protocol level. Gives insight into the workings of the operation at the HTTP level with the response codes.

Starting a Long-Running Operation

A consumption export requests for consumptions or counters related to a limit with the code VERT over a specified period.

Request
POST http://localhost:9998/readconsumptionbatches
Accept: application/vnd.oracle.insurance.resource+json,application/vnd.oracle.insurance.resource+json
Authorization: user testuser1
Content-Type: application/vnd.oracle.insurance.resource+json
{
   "transactionEndDateTime" : {
      "value" : "1970-10-11T14:04:42.509+01:00"
   },
   "transactionStartDateTime" : {
      "value" : "1970-10-11T14:04:41+01:00"
   },
   "limitCodes" : [ "VERT" ]
}

Response:

201
Content-Length: 0
Content-Type: application/vnd.oracle.insurance.resource+json
Vary: Accept,Accept-Encoding,Accept-Language,Origin
X-Content-Type-Options: nosniff
X-Frame-Options: deny
X-OHI-APP-ID: ALI
X-OHI-APP-VERSION: 6.0.0
X-XSS-Protection: 1; mode=block
Location: http://host:port/api/generic/readconsumptionbatches/12324

Interactively Following a Long-Running Operation

Use a GET operation and the monitor link to invoke the related address after some time for Polling.

Request

GET http://localhost:9998/generic/readconsumptionbatches/12324
Accept: application/vnd.oracle.insurance.resource+json

Response

A long-running operation still in progress returns a response entity with the HTTP Response code: 200 (OK). For a long-running operation that reaches an end state, the response contains the same 201 code but a different response entity.

For a Successful Consumption Export
200
Content-Length: 909
Content-Type: application/vnd.oracle.insurance.resource+json
Vary: Accept,Accept-Encoding,Accept-Language,Origin
X-Content-Type-Options: nosniff
X-Frame-Options: deny
X-OHI-APP-ID: ALI
X-OHI-APP-VERSION: 6.0.0
X-XSS-Protection: 1; mode=block
{
   "type" : "readConsumptionBatch",
   "id" : 12324,
   "createdBy" : 20,
   "lastUpdatedBy" : 20,
   "objectVersionNumber" : 1,
   "status" : "Completed",
   "links" : [ {
      "href" : "http://host:port/api/generic/readconsumptionbatches/12324",
      "rel" : "self"
   }, {
      "href" : "http://host:port/api/generic/tasks/19009761",
      "rel" : "operator",
      "httpMethod" : "GET"
   }, {
      "href" : "http://host:port/api/datafilesets/822F386E57B83BA4E053020011ACC5FC",
      "rel" : "datafileset",
      "httpMethod" : "GET"
   } ],
   "creationDate" : {
      "value" : "2019-02-18T18:11:51.004+01:00"
   },
   "lastUpdatedDate" : {
      "value" : "2019-02-18T18:11:51.004+01:00"
   },
   "transactionEndDateTime" : {
      "value" : "1970-10-11T14:04:42.509+01:00"
   },
   "transactionStartDateTime" : {
      "value" : "1970-10-11T14:04:41+01:00"
   },
   "limitCodes" : [ "VERT" ]
}

Consider the following rel tag:

  • datafileset - refers to the produced result of the long-running operation. Follow the link for the actual result.

Read Data File Set Integration Point for more information.

For an Operation that Runs into an Issue
200
Content-Length: 587
Content-Type: application/vnd.oracle.insurance.resource+json
Vary: Accept,Accept-Encoding,Accept-Language,Origin
X-Content-Type-Options: nosniff
X-Frame-Options: deny
X-OHI-APP-ID: ALI
X-OHI-APP-VERSION: 6.0.0
X-XSS-Protection: 1; mode=block
{
   "type" : "readConsumptionBatch",
   "id" : 12328,
   "createdBy" : 20,
   "lastUpdatedBy" : 20,
   "objectVersionNumber" : 1,
   "status" : "Failed",
   "links" : [ {
      "href" : "http://host:port/api/generic/readconsumptionbatches/12328",
      "rel" : "self"
   }, {
      "href" : "http://host:port/api/generic/tasks/19009768",
      "rel" : "operator",
      "httpMethod" : "GET"
   } ],
   "creationDate" : {
      "value" : "2019-02-18T18:12:11.127+01:00"
   },
   "lastUpdatedDate" : {
      "value" : "2019-02-18T18:12:11.127+01:00"
   },
   "transactionEndDateTime" : {
      "value" : "1970-10-11T14:04:42.509+01:00"
   },
   "transactionStartDateTime" : {
      "value" : "1970-10-11T14:04:41+01:00"
   "limitCodes" : [ "VERT" ]
}

The missing rel="monitor" shows no operator activity on the long-running operation. The missing rel="datafileset" means something is wrong. The response shows a rel="operator" to get more information.

Example of a rel="operator"

200
Content-Length: 1253
Content-Type: application/vnd.oracle.insurance.resource+json
Vary: Accept,Accept-Encoding,Accept-Language,Origin
X-Content-Type-Options: nosniff
X-Frame-Options: deny
X-OHI-APP-ID: ALI
X-OHI-APP-VERSION: 6.0.0
X-XSS-Protection: 1; mode=block
{
   "type" : "task",
   "id" : 19009768,
   "createdBy" : 20,
   "lastUpdatedBy" : 20,
   "objectVersionNumber" : 1,
   "status" : "ERRORED",
   "subjectId" : 12328,
   "threadCode" : "adjulimits-inttest--1 ( main )",
   "links" : [ {
      "href" : "http://host:port/api/generic/tasks/19009768",
      "rel" : "self"
   }, {
      "href" : "http://host:port/api/generic/interfacedmessages/19006453",
      "rel" : "operator:messages",
      "httpMethod" : "GET"
   }, {
      "href" : "http://host:port/api/taskprocessing/19009768/restart",
      "rel" : "operator:restart",
      "httpMethod" : "POST"
   }, {
      "href" : "http://host:port/api/generic/readconsumptionbatches/12328",
      "rel" : "operator:subject",
      "httpMethod" : "GET"
   } ],
   "creationDate" : {
      "value" : "2019-02-18T18:12:11.127+01:00"
   },
   "lastUpdatedDate" : {
      "value" : "2019-02-18T18:12:11.127+01:00"
   },
   "table" : {
      "id" : 2109405,
      "links" : [ {
         "href" : "hhttp://host:port/api/generic/tables/2109405",
         "rel" : "canonical"
      } ]
   },
   "taskType" : {
      "id" : 8520,
      "links" : [ {
         "href" : "http://host:port/api/generic/tasktypes/8520",
         "rel" : "canonical"
      } ]
   }
}

Some other relevant links:

  • operator:messages - to get more information about the messages registered during the execution of the long-running operation.

  • operator:restart - to try and restart the failed operator.

  • operator:subject - provides the address of the long-running operation resource.

Example for operator:restart

Request
POST http://localhost:9998/taskprocessing/19009768/restart
Accept: application/vnd.oracle.insurance.resource+json
Response
200
Content-Length: 1141
Content-Type: application/vnd.oracle.insurance.resource+json
Vary: Accept,Accept-Encoding,Accept-Language,Origin
X-Content-Type-Options: nosniff
X-Frame-Options: deny
X-OHI-APP-ID: ALI
X-OHI-APP-VERSION: 6.0.0
X-XSS-Protection: 1; mode=block
{
   "type" : "task",
   "id" : 19009768,
   "createdBy" : 20,
   "currentAttemptCount" : 0,
   "lastUpdatedBy" : 20,
   "objectVersionNumber" : 3,
   "status" : "PENDING",
   "subjectId" : 12328,
   "threadCode" : "adjulimits-inttest--1 ( main )",
   "links" : [ {
      "href" : "http://host:port/api/generic/tasks/19009768",
      "rel" : "self"
   }, {
      "href" : "http://host:port/api/generic/interfacedmessages/19006453",
      "rel" : "operator:messages",
      "httpMethod" : "GET"
   }, {
      "href" : "http://host:port/api/generic/readconsumptionbatches/12328",
      "rel" : "operator:subject",
      "httpMethod" : "GET"
   } ],
   "creationDate" : {
      "value" : "2019-02-18T18:12:11.127+01:00"
   },
   "lastUpdatedDate" : {
      "value" : "2019-02-18T18:12:11.253+01:00"
   },
   "table" : {
      "id" : 2109405,
      "links" : [ {
         "href" : "http://host:port/api/generic/tables/2109405",
         "rel" : "canonical"
      } ]
   },
   "taskType" : {
      "id" : 8520,
      "links" : [ {
         "href" : "http://host:port/api/generic/tasktypes/8520",
         "rel" : "canonical"
      } ]
   }
}

Leveraging Notification Events

Sample Notification Event
{
  "type"  : "ReadConsumptionBatch",
  "topic" : "Notification",
  "timestamp" : {
     "value" : "2019-02-18T18:12:00.325+01:00"
  },
  "links" : [
     { "rel" : "operator:subject",
       "href" : "http://host:port/api/generic/readconsumptionbatches/12323"
     },
     { "rel" : "datafileset",
       "href" : "http://host:port/api/datafilesets/822F386E57B63BA4E053020011ACC5FC"
     },
     { "rel" : "file",
       "href" : "http://host:port/api/datafilesets/822F386E57B63BA4E053020011ACC5FC/datafiles/822F386E57B73BA4E053020011ACC5FC/data"
     }
  ]
}

The following fields are present:

  • type

    Denotes the type of the long-running operation.

  • topic

    Specifies the category of the event. Like a notification event.

  • timestamp

    The timestamp for when the event was generated.

  • links

    A collection of links unique for each long-running operation.

The example has the following links:

  • operator:subject

    Provides the resource location of the long-running operation. Follow this link to continue monitoring the long-running operation and get back to the original subject.

  • datafileset

    Present every time the long-running operation produces a result.

  • file

    This link is unique to the ReadConsumptionBatch. It gives the calling system access to the stream containing the consumption and counter export.