Skip to Content

Audit Logging

Introduction

The Audit Logging page of the Management Console allows an administrator of a Harmony organization to retrieve logs of Harmony user activity taking place in Management Console and Cloud Studio, and external users accessing the API Manager Portal page.

To access the Audit Logging page, log in to the Jitterbit Harmony Portal, then use the Harmony Portal menu in the top left and navigate to Management Console > Audit Logging:

management console audit logging

As an alternative to viewing audit logs on the Management Console Audit Logging page, you can retrieve audit logs using a REST API. The Audit Log Service API is described later on this page.

Note

Audit logs are retained for 30 days after the user activity takes place.

Prerequisites

To enable and view audit logs, you must be a member of a role with Admin permission in the organization. For information on roles and permissions, see Managing Permissions, Roles, and Members.

Enable 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 policies 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).

Audit Logging Page Header

The header along the top of the Audit Logging page includes date and time filters, a search bar, and additional options:

Page header

Date and Time Filters

By default, audit log data from the past two days are displayed in the audit logging table.

Use the From and To calendar fields to filter the audit logging data by date and time:

  • From: Click the calendar icon calendar icon to adjust the starting date for the audit logs. Click the clock icon clock icon to adjust the starting time for the audit logs.

  • To: Click the calendar icon calendar icon to adjust the ending date for the audit logs. Click the clock icon clock icon to adjust the ending time for the audit logs.

Once the desired date and times have been selected, click the search button search button in the search bar to populate the audit log table with the desired audit logs.

The search bar allows you to filter the logs by the search criteria provided below:

Search bar

Search Criteria

These are examples of the search criteria that can be used:

Criterion Valid Search
Username username=example@jbexample.com
Action action=query
action=update
Environment ID environmentid=123456
Environment Name environmentname=production
Operation Name operationname=login

Searches can contain a combination of criteria. Combined search criteria must be separated by a semi-colon (;) between each criterion. These are examples of valid combined searches:

action=update;environment=production
environmentid=123456;action=create

Additional Options

Additional audit log options display on the right side of the page next to the search bar:

download button

  • Download: Click to download a ZIP file containing a CSV file with the current audit log data based on the applied filters and search criteria.

  • Down Arrow: Click to filter the columns that are displayed in the audit log table. By default, all columns are selected to be displayed:

    Column view options

View Audit Logs

Each row in the audit logs table displays audit logging data of activity and logins taking place in Management Console and Cloud Studio:

data rows

  • Username: The username of the user performing the activity.

  • Operation Name: The name (path) of the operation (the API call to Jitterbit Harmony) that was logged.

  • Action: The action performed by the user, one of Create, Delete, Update, or Query:

    • Create: Indicates the user created new data in the contents of a page in Management Console or a project in Cloud Studio. For example, creating a new agent in Management Console or deploying a project in Cloud Studio would be Create actions.

    • Delete: Indicates the user deleted data from the contents of a page in Management Console or a project in Cloud Studio. For example, deleting an agent in the Management Console or deleting a project from Cloud Studio would be Delete actions.

    • Update: Indicates the user updated the contents of a page in Management Console or a project in Cloud Studio. For example, changing the name of an agent in Agents > Agents would be an Update action.

    • Query: Indicates the user viewed the contents of a page in Management Console or a project in Cloud Studio. For example, viewing the list of projects in Cloud Studio would be a Query action.

  • Time: The timestamp of the activity. Times are displayed in your browser's time zone.

  • Environment ID: The environment ID where the activity takes place.

  • Environment Name: The name of the environment where the activity takes place.

    Note

    Empty columns for Environment ID and Environment Name indicate that the activity is not related to a specific environment.

Audit Log Service API

As an alternative to viewing audit logs on the Management Console Audit Logging page, you can retrieve audit logs using a REST API. This requires the use of either command line utilities such as curl or applications such as Postman.

To use the Audit Log Service API, after enabling audit logging for the organization (described earlier on this page), follow these steps:

  1. Retrieve an authentication token using the User Service Controller API. This token is required in order to use the Audit Log Service API.

  2. Retrieve logs using the Audit Log Service API.

Retrieve an Authentication Token

Retrieving an authentication token requires the use of the User Service Controller API.

Important

If your Jitterbit Harmony organization has TFA enabled, this request will fail. Retrieving the authentication token requires two different requests.

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:

Region Base 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:

Header Required Example Description
Content-Type Required '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 Parameter Required Type Example Description
email Required String alice@jbexample.com Jitterbit Harmony username (email address) with a role with Admin permission in the organization
password Required String Jitterbit4Ever! 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
}

Retrieve an Authentication Token with TFA Enabled

If a user's Jitterbit Harmony organization has two-factor authentication (TFA) enabled, retrieving the authentication token requires two requests using the User Service Controller API:

  1. Retrieve a TFA Code

  2. Use the TFA Code to Retrieve an Authentication Token

Retrieve a TFA Code

A valid TFA code is required to retrieve an authentication token when TFA is enabled. An example request showing logging in to the NA region and requesting a TFA code:

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!",
    "deviceId": "abcd"
}'
Base URL

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

Region Base 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:

Header Required Example Description
Content-Type Required '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 Parameter Required Type Example Description
email Required String alice@jbexample.com Jitterbit Harmony username (email address) with a role with Admin permission in the organization
password Required String Jitterbit4Ever! Jitterbit Harmony user password
deviceId Required String abcd Identifier that will be used to confirm the TFA code in the next request
Response Body

The returned response body contains an error message indicating that a TFA code was sent to the user's email address.

Response Body
{
  "status": false,
  "operation": "User login",
  "errorCode": "VALIDATE_TFA_LOGIN_EMAIL",
  "errorMessage": "Validate your login with authentication code. An email from Jitterbit with the code was sent to you.",
  "authenticationToken": null,
  "serverUrl": "https://na-east.jitterbit.com",
  "orgAttrs": [],
  "defaultOrgId": null
}

Use the TFA Code to Retrieve an Authentication Token

The TFA code sent to the user's email address can now be used in the second request to retrieve the authentication token. An example request showing logging in to the NA region with a TFA code and retrieving the authorization token:

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

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

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

These headers are required:

Header Required Example Description
Content-Type Required '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 Parameter Required Type Example Description
email Required String alice@jbexample.com Jitterbit Harmony username (email address) with a role with Admin permission in the organization
password Required String Jitterbit4Ever! Jitterbit Harmony user password
code Required String 112233 TFA code sent to the Jitterbit Harmony user's email
deviceId Required String abcd Identifier submitted to generate the TFA code in the previous request
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
}

Retrieve 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"
    }
}'

Note

If present in the log output, passwords, password phrases, and authentication tokens are overwritten with asterisks to mask them.

Base URL

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

Region Base 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 Optional accept Header Description
auditlog 'accept: application/json' Returns audit logs in JSON format
auditlog/download 'accept: application/zip' Returns audit logs in a compressed (ZIP) CSV format with filename format audit-log_YYYY_MM_DD_HH_MM_SS.zip

URL Parameters

These parameters can be passed in the URL:

Parameter Required Type Example Description
detail Optional Boolean detail=true Indicates 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 can be used in the request:

Header Required Example Description
accept Optional 'accept: application/json'
'accept: application/zip'
Indicates format that will be accepted in the response: one of json or zip. If used, must match the endpoint as shown above.
authToken Required 'authToken: 1_70dfe7f7-1d47-4ad5-be5d-bc4a222dd2g4' Passes the authorization token (authenticationToken) returned by the User Service Controller API.
Content-Type Required '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:

Parameter Key Required Type Example Description
queryParams Not applicable Required Map "queryParams": {
"organization_id": "20980"
}
The query parameters used when searching the audit log database; query terms are combined with an AND operator.
queryParams organization_id Required String 20980 Harmony organization ID. The organization must be located in the region that matches the base URL.
queryParams organization_name Optional String JB Example Company Name of the organization.
queryParams operation_name Optional String /jitterbit-cloud-restful-service/... The name (URL) of the operation (the API call to Jitterbit Harmony) that was logged.
queryParams action Optional String QUERY The action performed by the operation.
queryParams action_timestamp Optional String 2021-01-01T00:00:00.000Z From date timestamp, in yyyy-MM-ddTHH:mm:ss.sssZ format.
queryParams environment_ids Optional String 132510, 132520, 132530 Comma-separated list of environment IDs to use in the query.
queryParams environment_names Optional String Development, QA Comma-separated list of environment names to use in the query.
range Not applicable Required Map "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.
range fromTimestamp Required String 2021-01-01T00:00:00.000Z "From" date timestamp, in yyyy-MM-ddTHH:mm:ss.sssZ format.
range toTimestamp Required String 2022-01-01T00:00:00.000Z "To" date timestamp, in yyyy-MM-ddTHH:mm:ss.sssZ format.

Example

This example uses the auditlog/download endpoint to retrieve all records for organization 123456, with an action of QUERY, beginning as of January 1, 2023, including the detailed version of the records, and downloaded as CSV in a compressed (ZIP) file format to an output file:

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": "123456",
        "action": "QUERY"
    },
    "range": {
        "fromTimestamp": "2023-01-01T00:00:00.000Z",
        "toTimeStamp": "9999-01-01T00:00:00.000Z"
    }
}'

Example Log Output

This is an example fragment of the JSON output returned by the auditlog endpoint:

Response Body
{
  "records": [
    {
      "username": "alice@jbexample.com",
      "organization_id": "123456",
      "organization_name": "JB Example Company",
      "operation_name": "/jitterbit-cloud-restful-service/user/login",
      "action": "UPDATE",
      "action_timestamp": "2023-03-23T09:59:59.999Z",
      "environment_ids": null,
      "environment_names": null,
      "sort_values": [
        1680083968484
      ],
      "user_id": null,
      "request_body": "null",
      "response_body": "null"
    },
    {
      "username": "bob@jbexample.com",
      "organization_id": "123456",
      "organization_name": "JB Example Company",
      "operation_name": "/jitterbit-cloud-restful-service/subscription/list/647330",
      "action": "QUERY",
      "action_timestamp": "2023-03-23T08:59:59.999Z",
      "environment_ids": null,
      "environment_names": null,
      "sort_values": [
          1680081692921
      ],
      "user_id": null,
      "request_body": "null",
      "response_body": "{\"subscriptions\":[{\"organizationId\":\"123321\",\"lastUpdatedBy\":\"alice@jbexample.com\",\"offeringName\":\"Jitterbit Harmony Enterprise\",\"activatedOn\":1658343482577,\"createdBy\":\"alice@jbexample.com\",\"displayExpiresOn\":1660934256000,\"lastUpdatedOn\":1658343482660,\"expiresOn\":2607705456000,\"id\":\"125521\",\"createdOn\":1658343482577,\"offeringEnumId\":\"5\"}],\"operation\":\"List Subscription by Organization\",\"status\":true}"
    },
    {
      "username": "bob@jbexample.com",
      "organization_id": "123456",
      "organization_name": "JB Example Company",
      "operation_name": "/jitterbit-cloud-restful-service/project/env/detail/654321",
      "action": "QUERY",
      "action_timestamp": "2023-03-23T07:59:59.999Z",
      "environment_ids": [
          "654321"
      ],
      "environment_names": [
          "Default Environment"
      ],
      "sort_values": [
          1679393229672
      ],
      "user_id": null,
      "request_body": "null",
      "response_body": "{\"projEnvDetails\":{\"noOfConnections\":0,\"lastUpdatedBy\":\"alice@jbexample.com\",\"agentClusterId\":1,\"noOfHostedEndPoints\":0,\"appRuntime\":\"sandbox\",\"agentGroupId\":\"99999\",\"urlPrefix\":\"defaultUrlPrefix\",\"permission\":7,\"envId\":\"654321\",\"agentGroupName\":\"Production Cloud Agent Group\",\"lowestAgentVersion\":\"11.0.0.0\",\"createdOn\":1515425638817,\"orgId\":\"123456\",\"noOfScripts\":0,\"noOfProjects\":0,\"createdBy\":\"bob@jbexample.com\",\"envName\":\"Default Environment\",\"envType\":2,\"noOfFileFormats\":0,\"envDesc\":\"Default environment created by Harmony\",\"lastUpdatedOn\":1661335689017,\"noOfOperations\":0},\"operation\":\"Get detail of a Project Env\",\"status\":true}"
    },
. . .
  ]
}

Note

For the returned output of environment_ids and environment_names, a response with a null value indicates that the operation does not have an impact on the environment. A response with a single value indicates that the operation was at the environment level and impacts only that environment. A response with multiple values indicates that the operation was at the organization level and impacts multiple environments.