Using Asset Audit History

About Asset Audit History

The Asset audit history service provides APIs that enable you to retrieve historical information about REST requests in your Asset service repositories.

Before you begin, you must configure your audit metadata in your request headers. See asset-service-using-history.html#reference_c61144d3-a00d-42b9-b09b-acdd0bf91409.

The audit history APIs provide the following endpoints:

/<predix-asset-url>/system/configs
The audit history service is disabled by default. Use this endpoint to enable or disable the asset audit history service.
/<predix-asset-url>/system/audit
Use this endpoint to retrieve the old values and the new values of the requested assets.
/<predix-asset-url>/system/audit/changes
Use this endpoint to retrieve an old value and a new value record for each element in a collection that has changed.
/<predix-asset-url>/system/audit/snapshots
Use this endpoint to retrieve details about a single asset at a moment in time.

Enabling or Disabling Asset Audit History

Make sure that audit history is disabled before you begin a bulk upload of data. Enable audit history only when you want to track asset record changes.

Procedure

To check the state of audit history, submit this GET request:
```
GET <predix-asset-url>/system/configs
```
The JSON returned indicates either auditEnabled true or auditEnabled false.
To enable or disable audit history explicitly, submit a POST request with "enableAudit" : true or "enableAudit" : false in the JSON body:
Submit a POST request:
```
POST <predix-asset-url>/system/configs
```
To enable audit history, include this JSON array in the body:
```
[
{
	"enableAudit" : true
}
]
```
To disable audit history, include this JSON array in the body:
```
[
{
	"enableAudit" : false
}
]
```

Asset Service REST Request Headers

All REST requests must contain the following headers for multi-tenant support (provided by Predix UAA Service). Whenever the application makes a call to the service, these headers identify which tenant the application belongs to.

UAA Authorization

Header name: "Authorization"
Header value: "Bearer <token obtained from trusted issuer>". For more information, see t_connecting_your_app_to_a_platform_service_instance.html#task_2e2b8b0f-9a72-41d2-be37-273f01f8e47f.

Predix Zone

Header name: The zone-http-header-name from the VCAP_SERVICES environment variable for your Asset service instance. For example, Predix-Zone-Id.
Header value: The zone-http-header-value from the VCAP_SERVICES environment variable for your Asset service instance. For example, ba99ab7b-172f-4fe4-8ce9-45afa8a4ab0c.

Audit History

Header name:
x-audit-metadata

Example header value:

{"userId":"abc","reason"."xxx","evenTimestamp":"2016-03-25T06:10:36.661+05:30".eventId"."new equip2","masterEventId":new asset","otherInfo":"blue"}

See asset-service-using-history.html#reference_259d90dc-f54b-4953-b186-faf86792f915

Audit History Metadata Header

If you add the x-audit-metadata header to an Asset request, you can later query the audit history of the values included in the header. The results of the request include system-generated and user-defined metadata.

System-Generated Metadata Attributes

Predix Asset service provides the following system-generated attributes:


Attribute	Attribute Description
`timestamp`	Indicates the date and time the request was submitted.
`action`	Indicates the operation (CRUD) used in the request.
`elementOldValue` `elementNewValue`	Indicates the value of the element before the update and the new value after the change.

These attributes are optional and are tagged as metadata and indexed so they will return meaningful results if used in queries.

User-defined Metadata Attributes

You can define your own audit history metadata and use it in your headers:


Attribute	Attribute Description
`userId`	Identifies the `userID` as you have defined it. For example, you might define `userID` as the person who updated the record, or track the person who performed the physical work.
`eventTimestamp`	Tracks the date and time a submitted change to an asset actually occurs. For example, a maintenance event might be entered into the system at a given date and time, but the actual maintenance might have been performed before the data was updated. The `eventTimestamp` allows users to track when the actual change was made.
`reason`	Indicates the purpose of the request by a text string or a predefined set of codes defined for the business.
`eventId`	Customers can create separate change events that track metadata about a change. If a separate event is part of the asset model, then `eventId` can be used to link the change on the asset to the details found in the event. Alternately, customers could use this as a descriptor of the type of change that has taken place, such as “Scheduled Maintenance” or “Annual Inspection”.
`masterEventId`	The `masterEventId` can be used to tie smaller changes into a larger overarching change. For example, an engine overhaul master event would include many smaller, discrete events such as change the oil, replace valve stem seals, replace cylinders, and so on. Each of these individual changes would be recorded as part of the larger engine overhaul event.
`otherInfo`	Other info to be determined by the user.

Sample Audit History API Requests

Use the Asset audit history service APIs to retrieve historical information about your assets.

To run the sample requests, use the asset-service-asset-model.html#reference_99274c09-7d07-40fe-95a7-3219cd905ca1 within a POST method. See asset-service-set-started.html#task_24953dd7-22e0-421c-8f7c-cb65f423c3e0.

The samples on this page abbreviate the base URL for the host that processes Asset service API requests. You need to include the full URI of your Asset service instance, from the VCAP_SERVICES environment variable, in your requests.

/system/audit Requests

Get Audit History for Assets for a Specific Collection

This example uses the identifier parameter to retrieve the history for assets with /locomotives* in the uri.

<asset-app-url>/system/audit?filter=identifier=/locomotives*

Returns

[
  {
    "id": 789,
    "versionId": -1,
    "userId": "",
    "timestamp": "2016-04-13T10:16:42.016-07:00[America/Los_Angeles]",
    "reason": "",
    "action": "CREATE",
    "identifier": "/locomotives/89",
    "eventId": "",
    "masterEventId": "",
    "otherInfo": "",
    "oldValue": "{}",
    "newValue": "{\n  \"uri\": \"/locomotives/89\",\n  \"type\": \"Diesel-electric\",\n  \"model\": \"3GS21B-89\",\n  \"serial_no\": \"0086\",\n  \"emission_tier\": \"0+\",\n  \"fleet\": \"/fleets/cn-4\",\n  \"manufacturer\": \"/manufacturers/national-railway-equipment\",\n  \"engine\": \"/engines/QSK19-28\",\n  \"hqLatLng\": {\n    \"lat\": 46.244201,\n    \"lng\": -73.666786\n  },\n  \"parent\": \"/locomotives/88\",\n  \"installedOn\": \"05/12/2015\",\n  \"dateIso\": \"2015-12-05T13:15:31Z\"\n}"
  },
  {
    "id": 788,
    "versionId": -1,
    "userId": "",
    "timestamp": "2016-04-13T10:16:42.016-07:00[America/Los_Angeles]",
    "reason": "",
    "action": "CREATE",
    "identifier": "/locomotives/88",
    "eventId": "",
    "masterEventId": "",
    "otherInfo": "",
    "oldValue": "{}",
    "newValue": "{\n  \"uri\": \"/locomotives/88\",\n  \"type\": \"Diesel-electric\",\n  \"model\": \"3GS21B-88\",\n  \"serial_no\": \"0085\",\n  \"emission_tier\": \"0+\",\n  \"fleet\": \"/fleets/cn-4\",\n  \"manufacturer\": \"/manufacturers/national-railway-equipment\",\n  \"engine\": \"/engines/QSK19-27\",\n  \"hqLatLng\": {\n    \"lat\": 49.640363,\n    \"lng\": -126.242998\n  },\n  \"parent\": \"/locomotives/87\",\n  \"dateIso\": \"2015-11-05T13:15:30Z\"\n}"
  },
  {
    "id": 787,
    "versionId": -1,
    "userId": "",
    "timestamp": "2016-04-13T10:16:42.015-07:00[America/Los_Angeles]",
    "reason": "",
    "action": "CREATE",
    "identifier": "/locomotives/87",
    "eventId": "",
    "masterEventId": "",
    "otherInfo": "",
    "oldValue": "{}",
    "newValue": "{\n  \"uri\": \"/locomotives/87\",\n  \"type\": \"Diesel-electric\",\n  \"model\": \"3GS21B-87\",\n  \"serial_no\": \"0087\",\n  \"emission_tier\": \"0+\",\n  \"fleet\": \"/fleets/cn-4\",\n  \"manufacturer\": \"/manufacturers/national-railway-equipment\",\n  \"engine\": \"/engines/QSK19-26\",\n  \"hqLatLng\": {\n    \"lat\": 49.296307,\n    \"lng\": -118.827314\n  },\n  \"parent\": \"/locomotives/86\",\n  \"installedOn\": \"05/12/2014\",\n  \"dateIso\": \"2014-12-05T13:15:31Z\"\n}"
  },
  {
    "id": 786,
    "versionId": -1,
    "userId": "",
    "timestamp": "2016-04-13T10:16:42.015-07:00[America/Los_Angeles]",
    "reason": "",
    "action": "CREATE",
    "identifier": "/locomotives/86",
    "eventId": "",
    "masterEventId": "",
    "otherInfo": "",
    "oldValue": "{}",
    "newValue": "{\n  \"uri\": \"/locomotives/86\",\n  \"type\": \"Diesel-electric\",\n  \"model\": \"3GS21B\",\n  \"serial_no\": \"0086\",\n  \"emission_tier\": \"0+\",\n  \"fleet\": \"/fleets/cn-4\",\n  \"manufacturer\": \"/manufacturers/national-railway-equipment\",\n  \"engine\": \"/engines/QSK19-28\",\n  \"hqLatLng\": {\n    \"lat\": 46.244201,\n    \"lng\": -73.666786\n  }\n}"
  },
  
    {
    ... SNIP
]

Get Audit History for a Specific Collection Before a Timestamp

This example uses the before parameter to retrieve the history for asset records matching /planets/venus with changes before a specific timestamp.

GET <asset-app-url>/system/audit?filter=identifier=/planets/venus:before=2016-08-10T13\:09\:58.747-07\:00

Response


[
  {
     "id": 608306,
     "versionId": -1,
     "timestamp": "2016-08-10T13:09:58.747-07:00[America/Los_Angeles]",
     "action": "UPDATE",
     "identifier": "/planets/venus",
     "eventTimestamp": "2016-08-10T13:09:58.747-07:00[America/Los_Angeles]",
     "oldValue": "{\n  \"uri\": \"/planets/venus\",\n  \"color\": \"gold\",\n  \"radius\": \"3,760 mi\"\n}",
     "newValue": "{\n  \"uri\": \"/planets/venus\",\n  \"color\": \"gold\",\n  \"radius\": \"3,760 mi\",\n  \"change\": 0\n}"
   },
   {
     "id": 608303,
     "versionId": -1,
     "timestamp": "2016-08-10T13:08:09.119-07:00[America/Los_Angeles]",
     "action": "CREATE",
     "identifier": "/planets/venus",
     "eventTimestamp": "2016-08-10T13:08:09.119-07:00[America/Los_Angeles]",
     "oldValue": "{}",
     "newValue": "{\n  \"uri\": \"/planets/venus\",\n  \"color\": \"gold\",\n  \"radius\": \"3,760 mi\"\n}"
   }\]

Response

/system/audit/changes Requests

GET a Specific Number of Changed Records

This example uses the changes and pagesize parameters to retrieve the detailed changes for three asset records.

<asset-app-url>/system/audit/changes?pageSize=3

Returns

[
  {
    "id": 3293,
    "versionId": -1,
    "userId": "",
    "timestamp": "2016-04-13T10:18:43.296-07:00[America/Los_Angeles]",
    "reason": "",
    "action": "CREATE",
    "identifier": "/engines/QSK19-28",
    "eventId": "",
    "masterEventId": "",
    "otherInfo": "",
    "elementAction": "added",
    "elementUri": "/engines/QSK19-28.manufacturer",
    "elementOldValue": "",
    "elementNewValue": "/manufacturers/cummins"
  },
  {
    "id": 3292,
    "versionId": -1,
    "userId": "",
    "timestamp": "2016-04-13T10:18:43.296-07:00[America/Los_Angeles]",
    "reason": "",
    "action": "CREATE",
    "identifier": "/engines/QSK19-28",
    "eventId": "",
    "masterEventId": "",
    "otherInfo": "",
    "elementAction": "added",
    "elementUri": "/engines/QSK19-28.RPM",
    "elementOldValue": "",
    "elementNewValue": "800"
  },
  {
    "id": 3291,
    "versionId": -1,
    "userId": "",
    "timestamp": "2016-04-13T10:18:43.296-07:00[America/Los_Angeles]",
    "reason": "",
    "action": "CREATE",
    "identifier": "/engines/QSK19-28",
    "eventId": "",
    "masterEventId": "",
    "otherInfo": "",
    "elementAction": "added",
    "elementUri": "/engines/QSK19-28.bore",
    "elementOldValue": "",
    "elementNewValue": "159"
  }
]