Audits | DCM User Manual

Retrieves list of audits.

DCM_API_DOMAIN will be provided by DCM.

Request

URL: <DCM_API_DOMAIN>/audits

Method: POST

Format: application/json

Headers: The following headers must be included in the request

Parameter	Type	Mandatory	Default Value	Description
content-type	string	Yes		Indicates the media type of the resource. Use `application/json`.
authorizationToken	string	Yes		Token to be used when accessing the API. Value is `Bearer <token>`. Use token from Token . `audience` is `ext-api-notification`.

Parameter

Type

Mandatory

Default Value

Description

content-type

string

Yes

Indicates the media type of the resource. Use application/json.

authorizationToken

string

Yes

Token to be used when accessing the API. Value is Bearer <token>.

Use token from Token . audience is ext-api-notification.

Parameters:

Parameter	Type	Mandatory	Default Value	Description
query	string	Yes		A structured string that allows calling application to specify the data that it wants to retrieve.

Query structure:

query {
    audits(projectId: <project_id>, startTime: <start_time>, endTime: <end_time>, timezone: <timezone>) {
        <data_fields_to_be_retrieved>
    }
}

Query parameters:

Parameter	Type	Mandatory	Default Value	Description
project_id	string	Yes		The ID of the project from where the notifications will be retrieved from.
start_time	DateTime	No	Now - 1 hour	The start of the period data is requested for. Time periods are in UTC format and can be a maximum of a 24 hour period.
end_time	DateTime	No	Now	The end of the period data is requested for
timezone	String	No	Etc/UTC	The timezone name for parameters and data (IANA timezone database specification). See https://en.wikipedia.org/wiki/List_of_tz_database_time_zones for the list of timezone names. Eg. “Australia/Sydney”, “Europe/London”
data_fields_to_be_retrieved	string	Yes		The fields to be retrieved. Allowed values: auditId projectId message startTimestamp endTimestamp dismissed dismissedBy read readBy

Notes:

If end_time is more than 1 day after start_time an error will occur and no data will be retrieved.

Response

Format: application/json

Parameters:

Name	Type	Description
errors.message	String	Description of the error if one occurred.
data.audits	List	List of audits.

Examples

Retrieve all audit fields.

JavaScript

const getAudits = async function(token, projectId, startTime, endTime) {
    return new Promise(function(res, rej) {
        const url =  '<DCM_API_DOMAIN>/audits';
        const method = 'POST';
        const headers = { 
            'content-type': 'application/json',
            'authorizationToken': `Bearer ${token}`
        };
        const query = `query {
            audits(projectId: "${projectId}", startTime: "${startTime}", endTime: "${endTime}") {
                auditId
                projectId
                message
                startTimestamp
                endTimestamp
                dismissed
                dismissedBy
                read
                readBy
            }
        }`;
        const options = {
            url: url,
            method: method,
            headers: headers,
            body: JSON.stringify({ query })
        };

        const req = request(options, function callback(error, response, body) {
            body = JSON.parse(body);
            ...
            ...
        });
    });
}

Response with all of the audit fields.

JSON

{
  "data": {
    "audits": [
      {
        "auditId": "<audit_id>",
        "projectId": "<project_id>",
        "message": "New Site created",
        "startTimestamp": "2021-12-08T06:02:50.476Z",
        "endTimestamp": "2021-12-08T06:02:50.476Z",
        "dismissed": false,
        "dismissedBy": null,
        "read": false,
        "readBy": null
      }
    ]
  }
}

Retrieve some of the audit fields.

JavaScript

const getAudits = async function(token, projectId, startTime, endTime) {
    return new Promise(function(res, rej) {
        const url =  '<DCM_API_DOMAIN>/audits';
        const method = 'POST';
        const headers = { 
            'content-type': 'application/json',
            'authorizationToken': `Bearer ${token}`
        };
        const query = `query {
            audits(projectId: "${projectId}", startTime: "${startTime}", endTime: "${endTime}") {
                message
                startTimestamp
                dismissed
                read
            }
        }`;
        const options = {
            url: url,
            method: method,
            headers: headers,
            body: JSON.stringify({ query })
        };

        const req = request(options, function callback(error, response, body) {
            body = JSON.parse(body);
            ...
            ...
        });
    });
}

Response with some of the audit fields.

JSON

{
  "data": {
    "audits": [
      {
        "message": "New site created",
        "startTimestamp": "2021-12-08T06:02:50.476Z",
        "dismissed": false,
        "read": false
      }
    ]
  }
}

Retrieve the “message” audit field only.

JavaScript

const getAudits = async function(token, projectId, startTime, endTime) {
    return new Promise(function(res, rej) {
        const url =  '<DCM_API_DOMAIN>/audits';
        const method = 'POST';
        const headers = { 
            'content-type': 'application/json',
            'authorizationToken': `Bearer ${token}`
        };
        const query = `query {
            audits(project_id: "${projectId}", start_time: "${startTime}", end_time: "${endTime}") {
                message
            }
        }`;
        const options = {
            url: url,
            method: method,
            headers: headers,
            body: JSON.stringify({ query })
        };

        const req = request(options, function callback(error, response, body) {
            body = JSON.parse(body);
            ...
            ...
        });
    });
}

Response with the “message” notification field only.

JSON

{
  "data": {
    "audits": [
      {
        "message": "New site created"
      }
    ]
  }
}