Audit Logging¶

Introduction¶

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

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

As an alternative to viewing audit logs on this page, you can retrieve audit logs using a REST API. The Audit log service API is described later on this page.

Prerequisites¶

To enable and view audit logs, you must be a member of a role with Admin permission in the organization.

Enable audit logging¶

The control to enable or disable audit logging is synchronized across these two Management Console pages:

• This page: Select Audit Logging Disabled to turn on or Audit Logging Enabled to turn off audit logging for the currently active organization:

  

  

• Organizations page: Select the appropriate organization in the table. In the Organization Policies drawer, select the API Management tab, then select Enable audit logging to turn audit logging on or off for the organization.

Audit Logging page header¶

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

Search bar¶

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

Search criteria¶

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

Combine searches¶

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

Date and time filters¶

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

To change the period, click the calendar icon in the date range bar:

A date picker opens where you can set the start and end dates for the display period:

To reset the period to the default, click the date range bar's reset icon.

Additional options¶

To the right of the date and time filters are the following controls:

• Refresh: Refresh the table data.

• Columns settings: Open the column settings drawer:

  

  Use this to change the arrangement and visibility of columns. The drawer has the following controls:

  • Show All: Make all columns visible.
  • Move: Drag and drop to change the position of the column relative to others.
  • Hide: The column is visible. Click to hide it.
  • Show: The column is hidden. Click to show it.
  • Save: Save the columns.
  • Cancel: Close the columns drawer without saving changes.

• 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.

Audit logging page footer¶

When there are more than 100 operations, they are split into pages of 100 each. You can move through them using these navigation buttons at the bottom of the table:

• First page: Go to the first page.

• Previous page: Go to the previous page.

• Next page: Go to the next page.

• Last page: Go to the last page.

View audit logs¶

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

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

• 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 the Management Console, an API in API Manager, 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 the Management Console, an API in API Manager, 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 the Management Console, an API in API Manager, or a project in Cloud Studio. For example, changing the name of an agent in the Management Console would be an Update action.

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

• Activity Info: When a deployment action occurs, this column displays the names of the affected Cloud Studio project and operation. When a project is deployed, the name of the project is displayed. When a single operation is deployed, the name of the project containing the operation and the name of the operation is displayed. When an API Manager security profile is added or removed, the change is displayed. When a user role is changed, the change is displayed.

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

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

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

• Jitterbit Endpoint URL: A description of the endpoint. If no description is available, the endpoint URL is shown.

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.

   • If your Harmony organization does not have two-factor authentication (TFA) enabled, retrieve your authentication token with a standard login request.

   • If your Harmony organization has TFA enabled, retrieving the authentication token requires two requests:

     1. Retrieve a TFA code

     2. Use the TFA code to retrieve an authentication token

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.

An example request showing logging in to the NA region and retrieving the authorization token:

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:

Headers¶

These headers are required:

Body parameters¶

These required parameters are passed in the body of the 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 "123456" for the first organization that this user belongs to. An example of the response:

{
  "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": "123456",
      "orgName": "JB Example Company",
      "orgZoneUrl": "https://na-east.jitterbit.com"
    },
    {
      "orgId": "20970",
      "orgName": "example@jbexample.com",
      "orgZoneUrl": "https://na-east.jitterbit.com"
    }
  ],
  "defaultOrgId": "123456",
  "sessionTimeoutInSeconds": 14400
}

Retrieve an authentication token with TFA enabled¶

If a user's 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:

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:

Headers¶

These headers are required:

Body parameters¶

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

Response body¶

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

{
  "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:

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:

Headers¶

These headers are required:

Body parameters¶

These required parameters are passed in the body of the 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 "123456" for the first organization that this user belongs to. An example of the response:

{
  "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": "123456",
      "orgName": "JB Example Company",
      "orgZoneUrl": "https://na-east.jitterbit.com"
    },
    {
      "orgId": "654321",
      "orgName": "example@jbexample.com",
      "orgZoneUrl": "https://na-east.jitterbit.com"
    }
  ],
  "defaultOrgId": "123456",
  "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:

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": "123456"
    },
    "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:

Endpoints¶

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

URL parameters¶

These parameters can be passed in the URL:

Headers¶

These headers can be used in the request:

Body parameters¶

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

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:

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:

{
  "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,
      "acitivity_info": 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,
      "acitivity_info": 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": "CREATE",
      "action_timestamp": "2023-03-23T07:59:59.999Z",
      "environment_ids": [
          "654321"
      ],
      "environment_names": [
          "Default Environment"
      ],
      "sort_values": [
          1679393229672
      ],
      "user_id": null,
      "acitivity_info": "Project: Salesforce to NetSuite Operation: Get Customers",
      "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}"
    },
. . .
  ]
}