Skip to end of metadata
Go to start of metadata

Introduction

Audit logging lets an administrator of a Harmony organization retrieve logs of activity taking place in Management Console and Cloud Studio. The logs can be retrieved in either JSON or compressed CSV format.

An example of the log output that can be retrieved is shown at the end of this page. Audit logs are retained for thirty days after creation. Though you can specify a date in the past and the future, only logs from the last thirty days of activity are available.

These logs are retrieved using a REST API. All audit logs require the use of either command line utilities such as curl or applications such as Postman. This document assumes that you are familiar with the use of such tools and as such does not cover their usage.

To use audit logging, follow these steps:

  1. Enable audit logging for the organization.
  2. Retrieve an authentication token using the User Service Controller API. This token is required in order to use the Audit Logging API.
  3. Retrieve logs using the Audit Log Service API.

Prerequisites

Audit logging requires these prerequisites:

To perform queries and retrieve a subset of the available logs, additional parameters can be specified as described in the APIs below.

Enabling Audit Logging

To enable and disable audit logging for a specific organization:

  1. Log in to the Jitterbit Harmony Portal and go to Management Console > Organizations.
  2. Select the appropriate organization from the menu in the top navigation bar.
  3. Use the Action menu for that organization to select Edit Organization Policies.
  4. Select Enable Audit Logging and click Save to save the organization polices and to turn on audit logging for the organization.
NOTE: Make sure you are accessing the desired organization, which can be changed in the top navigation bar (see Changing the Selected Organization in Jitterbit Harmony Portal).

Retrieving an Authentication Token

Retrieving an authentication token requires the use of the User Service Controller API. An example request showing logging in to the NA region and retrieving the authorization token:

Using curl
curl --location --request PUT 'https://na-east.jitterbit.com/jitterbit-cloud-restful-service/user/login' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "alice@jbexample.com",
    "password": "Jitterbit4Ever!"
}'

Base URL

The base URL depends on the region that the organization is located in:

RegionBase URL
NA
https://na-east.jitterbit.com/jitterbit-cloud-restful-service/user/login
EMEA
https://emea-west.jitterbit.com/jitterbit-cloud-restful-service/user/login
APAC
https://apac.jitterbit.com/jitterbit-cloud-restful-service/user/login

Headers

These headers are required:

HeaderRequiredExampleDescription
Content-TypeRequired'Content-Type: application/json'Indicates format that will be sent in the request.

Body Parameters

These required parameters are passed in the body of the request:

Required ParameterRequiredTypeExampleDescription
emailRequiredStringalice@jbexample.comJitterbit Harmony username (email address) with a role with Admin permission in the organization
passwordRequiredStringJitterbit4Ever!Jitterbit Harmony user password

Response Body

The returned response body contains a list of the organizations that the user is associated with in addition to the authentication token ("authenticationToken"). This token is required for subsequent authorization with the Audit Logging API. In this example, the authentication token is "1_70dfe7f7-1d47-4ad5-be5d-bc4a222dd2g4". The organization ID is shown as "20980" for the first organization that this user belongs to. A pretty-printed example of the response:

Response Body
{
  "status": true,
  "operation": "User login",
  "authenticationToken": "1_70dfe7f7-1d47-4ad5-be5d-bc4a222dd2g4",
  "serverUrl": "https://na-east.jitterbit.com",
  "cloudAppsUrl": "https://na-east.jitterbit.com",
  "orgAttrs": [
    {
      "orgId": "20980",
      "orgName": "JB Example Company",
      "orgZoneUrl": "https://na-east.jitterbit.com"
    },
    {
      "orgId": "20970",
      "orgName": "example@jbexample.com",
      "orgZoneUrl": "https://na-east.jitterbit.com"
    }
  ],
  "defaultOrgId": "20980",
  "sessionTimeoutInSeconds": 14400
}

Retrieving Audit Logs

Once you have the authentication token, the organization ID, and a time period you are interested in, you can retrieve audit logs. An example showing retrieving all records beginning on January 1, 2021 and including the detailed version of the records:

Using curl
curl --request POST 'https://api.na.jitterbit.com/v1/auditlog?detail=true' \
--header 'accept: application/json' \
--header 'authToken: 1_70dfe7f7-1d47-4ad5-be5d-bc4a222dd2g4' \
--header 'Content-Type: application/json' \
--data-raw '{
    "queryParams": {
        "organization_id": "20980"
    },
    "range": {
        "fromTimestamp": "2021-01-01T00:00:00.000Z",
        "toTimeStamp": "9999-01-01T00:00:00.000Z"
    }
}'

Base URL

The base URL depends on the region that the organization is located in:

RegionBase URL
NA
https://api.na.jitterbit.com/v1/auditlog
EMEA
https://api.emea.jitterbit.com/v1/auditlog
APAC
https://api.apac.jitterbit.com/v1/auditlog

Endpoints

The Audit Log Service has these endpoints (APIs) available:

Endpoint

Description
auditlogReturns audit logs in JSON format
auditlog/downloadReturns audit logs in a compressed CSV format

URL Parameters

These parameters can be passed in the URL:

ParameterRequiredTypeExampleDescription
detailOptionalBooleandetail=trueIndicates if the user_id of the user making the action is to be returned in the data. By default, this is false.

Headers

These headers are required:

HeaderRequiredExampleDescription
authTokenRequired'authToken: 1_70dfe7f7-1d47-4ad5-be5d-bc4a222dd2g4'Passes the authorization token (authenticationToken) returned by the User Service Controller API.
acceptRequired'accept: application/json'Indicates format that will be accepted in the response: one of json or zip.
Content-TypeRequired'Content-Type: application/json'Indicates format that will be sent in the request.

Body Parameters

These parameters can be passed in the body of the request:

ParameterKeyRequiredTypeExampleDescription
queryParamsNot applicableRequiredMap

"queryParams": {
  "organization_id": "20980"
}

The query parameters used when searching the audit log database; query terms are combined with an AND operator.
queryParamsorganization_idRequiredString20980Harmony organization ID. The organization must be located in the region that matches the base URL.
queryParamsorganization_nameOptionalStringJB Example CompanyName of the organization.
queryParamsoperation_nameOptionalString/jitterbit-cloud-restful-service/...The name (URL) of the operation (the API call to Jitterbit Harmony) that was logged.
queryParamsactionOptionalStringQUERYThe action performed by the operation.
queryParamsaction_timestampOptionalString2021-01-01T00:00:00.000ZFrom date timestamp, in yyyy-MM-ddTHH:mm:ss.sssZ format.
queryParamsenvironment_idsOptionalString132510, 132520, 132530Comma-separated list of environment IDs to use in the query.
queryParamsenvironment_namesOptionalStringDevelopment, QAComma-separated list of environment names to use in the query.
rangeNot applicableRequiredMap

"range": {
  "fromTimestamp": "2021-01-01T00:00:00.000Z",
  "toTimeStamp": "9999-01-01T00:00:00.000Z"
}

The time range of the audit logs that are to be returned. Specify a time in the future to return all logs. Logs are retained for thirty days. Though you can specify a date in the past and the future, only logs from the last thirty days of activity are available.
rangefromTimestampRequiredString2021-01-01T00:00:00.000Z"From" date timestamp, in yyyy-MM-ddTHH:mm:ss.sssZ format.
rangetoTimestampRequiredString

2022-01-01T00:00:00.000Z

"To" date timestamp, in yyyy-MM-ddTHH:mm:ss.sssZ format.

Example

This example would retrieve all records for organization 20980, with an action of QUERY, beginning as of January 1, 2021, including the detailed version of the records, and downloaded as a compressed ZIP:

Using curl
curl --request POST 'https://api.na.jitterbit.com/v1/auditlog/download?detail=true' \
--output 'download.zip' \
--header 'accept: application/zip' \
--header 'authToken: 1_70dfe7f7-1d47-4ad5-be5d-bc4a222dd2g4' \
--header 'Content-Type: application/json' \
--data-raw '{
    "queryParams": {
        "organization_id": "20980",
        "action": "QUERY"
    },
    "range": {
        "fromTimestamp": "2021-01-01T00:00:00.000Z",
        "toTimeStamp": "9999-01-01T00:00:00.000Z"
    }
}'

Example Log Output

This is a fragment of the output that is returned when using 'accept: application/json':

Response Body
. . .
  {
    "username": "alice@jbexample.com",
    "organization_id": "20980",
    "organization_name": "JB Example Company",
    "operation_name": "/jitterbit-cloud-restful-service/dashboard/statistics/todayssourcefilestats/20980/08-27-2021%2012:00:00%20-0600",
    "action": "QUERY",
    "action_timestamp": "2021-08-27T14:23:36.212Z",
    "environment_ids": null,
    "environment_names": null,
    "user_id": "1039951"
  },
  {
    "username": "alice@jbexample.com",
    "organization_id": "20980",
    "organization_name": "JB Example Company",
    "operation_name": "/jitterbit-cloud-restful-service/project/env/list/showallparams/20980",
    "action": "QUERY",
    "action_timestamp": "2021-08-27T14:23:36.520Z",
    "environment_ids": [
      "132520",
      "132530"
    ],
    "environment_names": [
      "Development",
      "Default Environment"
    ],
    "user_id": "1039951"
  },
  {
    "username": "alice@jbexample.com",
    "organization_id": "20980",
    "organization_name": "JB Example Company",
    "operation_name": "/jitterbit-cloud-restful-service/dashboard/statistics/entitlements/20980",
    "action": "QUERY",
    "action_timestamp": "2021-08-27T14:23:37.417Z",
    "environment_ids": null,
    "environment_names": null,
    "user_id": "1039951"
  },
. . .

  • No labels