Atlassian Jira

Overview

Periodically calls the Atlassian Jira Cloud REST API to collect the site's audit logs and issue activity logs. With the same connect profile, you can also use the query commands that retrieve audit logs and issue activities.

Scope

Requirements

Atlassian Jira Configuration

Collection uses the email and API token of an Atlassian account. Logs can be retrieved only within the permissions of the account that created the token, so to collect audit logs as well, create the token with an account that has the Administer Jira permission.

Create an API Token

Log in with the Atlassian account to use for collection, go to the API tokens page, and click Create API token.

In the dialog, enter the following and click Create.

• Name: Name to identify the token (e.g., logpresso)
• Expiration date: Expiration date of the token, up to one year

When the API token is created, click Copy to clipboard, keep the token in a safe place, and close the dialog. After you complete this step, you cannot view the API token again.

It may take up to a minute for a new token to start working. API tokens expire, so create a new token before the expiration date and update the API token in the connect profile.

Check Account Permissions and Language

To collect audit logs, the account that created the token must have the Administer Jira global permission. Issue activity is collected only for issues in projects the account can view, so grant the account permission to view issues in each project you want to collect.

The category values of audit logs are translated according to the language setting of the account that created the token. To prevent the same category from being stored as different values depending on the language setting, we recommend setting the account's language to English.

Logpresso Connect Profile Setup

Go to Settings > Connect Profiles, click Add, and configure as follows:

• Name: Unique name to identify the connect profile (e.g., Jira)
• Code: jira
• Type: Jira
• Subdomain: example if the site address is example.atlassian.net
• Email: Email of the Atlassian account that created the API token
• API Token: API token created in the previous step
• HTTP Proxy: Enter in IP:port format if you use a proxy. Leave empty for a direct connection
• Connect Timeout: 30 (seconds)
• Read Timeout: 60 (seconds)

After you register the connect profile, you can also use the audit log and issue activity query commands provided by the Jira app right away.

Logpresso Collection Setup

Register a separate logger for audit logs and for issue activity logs. Both loggers use the connect profile registered in the previous step.

Audit Log Collection Setup

Collects Jira audit logs, such as changes to permissions, users and groups, projects, and field, screen, and workflow configurations, as well as issue deletions. Go to Loggers > Loggers, click Add, and configure as follows:

• Name: Jira Audit
• Interval (sec.): 60
• Logger Model: Jira Audit
• Table: JIRA_AUDIT
• Connect Profile: jira
• Scan Days: 7
• Page Size: 1000
• Slice Minutes: 60

Scan Days is the number of days to go back when the logger runs for the first time, from 1 to 180. After the first run, the logger continues from the saved position, so changing the value has no effect. Jira keeps audit logs only for the retention period set by the site administrator (up to 6 months), so records older than the retention period are not collected.

Page Size is the maximum number of records returned per API request, from 1 to 1000. Slice Minutes is the time range one API request covers, from 1 to 1440 minutes. When the period to collect is longer than Slice Minutes, such as on the first run or when resuming after the logger was stopped, the logger splits the period into ranges of this length and saves the collection position after each range. Use the default values in most cases.

Issue Activity Log Collection Setup

Collects issue creation, field changes, and comment creation and updates. Go to Loggers > Loggers, click Add, and configure as follows:

• Name: Jira Issue Activity
• Interval (sec.): 60
• Logger Model: Jira Issue Activity
• Table: JIRA_ISSUE_ACTIVITY
• Connect Profile: jira
• Scan Days: 7
• Page Size: 100
• Slice Minutes: 60

Scan Days ranges from 1 to 365 and, as with audit logs, applies only to the first run. Page Size is the maximum number of issues returned per API request, from 1 to 100, and Slice Minutes works the same way as for audit logs. If Jira responds slowly because there are many issues, reduce Slice Minutes and Page Size to narrow the range one API request handles.

Issue descriptions, comment text, and author emails are collected without additional settings. Author emails may be empty depending on the profile visibility settings of the Atlassian account.

Post-Installation Verification

Run the following query to verify that collection works. Replace the table names with the names you specified for the loggers.

table duration=7d JIRA_AUDIT, JIRA_ISSUE_ACTIVITY
| stats count by _table

• Normal: Both tables have 1 or more records.
• Abnormal: If there are no results, check the subdomain, email, API token, and token expiration in the connect profile, the permissions of the account that created the token, network reachability (HTTPS/443), and the HTTP proxy setting. If there has been no issue activity or audited operation on the site in the last 7 days, the corresponding table may be empty.
• Collection error: If the logger status shows an error, check the cause in the error details of the logger. If HTTP 401: authentication credentials are incorrect or missing or authentication credentials are incorrect or missing (X-Seraph-LoginReason: AUTHENTICATED_FAILED) appears, check the email and API token in the connect profile and whether the token has expired.

References

• Manage API tokens for your Atlassian account
• Audit activities in Jira
• Jira Cloud REST API
• Connect Profiles
• Loggers