Creating and Configuring a Jira Data Center System of Record

Prerequisites

  • A Jira Data Center instance with an account that has the following permissions:
    • Read access to Users
    • Read access to Issues
    • Read access to Groups
  • For Username/Password authentication: Valid credentials for a user with the above permissions
  • For Personal Access Token authentication: A valid PAT created in Jira Data Center
  • Network connectivity requirements:
    • SGNL requires inbound connectivity to your Jira Data Center instance on port 443
    • If inbound connectivity is not possible, consider deploying the SGNL On-Premises Connector which requires only outbound connectivity from your network

Configuring Jira Data Center

Option 1: Username and Password Authentication

If you plan to use username and password authentication, ensure you have the credentials for a service account with the necessary read permissions. No additional configuration is required in Jira Data Center.

Option 2: Personal Access Token Authentication

  1. Log in to your Jira Data Center instance as a user with the necessary permissions
  2. Navigate to your Profile settings (click your avatar in the top right corner and select “Profile”)
  3. Click on “Personal Access Tokens” in the left navigation menu
  4. Click “Create token”
  5. Provide a descriptive token name (e.g., “SGNL Integration”)
  6. Set an appropriate expiration date for the token
    • Note: SGNL securely encrypts and stores all tokens. Consider your organizational policies when setting the expiration
  7. Click “Create” and copy the generated token
  8. Save the token in a secure temporary location. You will need this when configuring SGNL

Configuring SGNL

  1. Login to the SGNL Console
  2. From the left menu, select Identity Data Fabric
  3. Click “Add System of Record” or “Add”
  4. The SGNL SoR Catalog will show up on the screen
  5. Click on “Jira Data Center” which will open up the New System of Record screen with configuration options pre-populated from the Jira Data Center SoR template
  6. Configure the following required fields:
    • Address: The URL of your Jira Data Center instance (e.g., https://jira.mycompany.com)
    • Authentication: Choose one of the following:
      • Username/Password (Recommended):
        • Username: The username of the service account
        • Password: The password for the service account
      • Personal Access Token:
        • Select “Bearer” authentication
        • Auth Token: Enter the Personal Access Token you created earlier
  7. Update the Adapter Configuration to use API version 2:
    {
  "apiVersion": "2",
  "includeInactiveUsers": false
}
  8. Click “Continue” to save your Jira Data Center System of Record. You will be taken to the System of Record details page
  9. All entities and relationships are created as defined in the Jira Data Center template:
    • Entities: User, Issue, Group, GroupMember
    • Relationships: UserMember, GroupMember, IssueAssignee, IssueCreator, IssueReporter
  10. If needed, you can edit an entity and modify any properties of the entity or the associated attributes. Hover over the entity to see the Edit button
  11. You can review the relationships created through the Relationships tab. To modify relationships, you must delete the existing one and create a new relationship
  12. Note that synchronization is disabled by default when a new System of Record is created. You can choose to enable synchronization on Entities individually by hovering over the entity to see the Enable Sync button
  13. Repeat for all Entities you want to synchronize to SGNL. Finally, enable synchronization for the System of Record
  14. After synchronization completes, SGNL will display the number of objects ingested per entity. You can then construct policies based on your Jira Data Center data and make access evaluation calls to SGNL
  15. Once ingestion is complete, you can use Data Lens to explore the SGNL graph

Synchronization Filters

To optimize performance and reduce unnecessary data synchronization, you should configure filters to sync only the data needed for your policies. This is particularly important for Jira Data Center instances with large datasets.

Configuring JQL Filters for Issues

SGNL uses Jira’s JQL (Jira Query Language) syntax to filter Issues during synchronization. JQL filters are passed directly to Jira Data Center at synchronization time.

JQL Basics

A JQL query consists of:

  • Fields: Words representing Jira fields (e.g., project, assignee, status)
  • Operators: Symbols or words comparing values (e.g., =, !=, IN, NOT IN)
  • Values: The specific values to match (e.g., “TEST”, “In Progress”)
  • Functions: Calculations on Jira data (e.g., currentUser(), now())
  • Keywords: Words that join or alter clauses (e.g., AND, OR, NOT)

Example JQL Filters

  1. Filter by Project:

    {
  "apiVersion": "2",
  "includeInactiveUsers": false,
  "issuesJqlFilter": "project = \"SGNL\""
}

  2. Filter by Multiple Projects:

    {
  "apiVersion": "2",
  "includeInactiveUsers": false,
  "issuesJqlFilter": "project IN (\"SGNL\", \"MVP\", \"PROD\")"
}

  3. Filter Active Issues Only:

    {
  "apiVersion": "2",
  "includeInactiveUsers": false,
  "issuesJqlFilter": "status NOT IN (\"Done\", \"Closed\", \"Resolved\")"
}

  4. Complex Filter (Active Issues in Specific Projects):

    {
  "apiVersion": "2",
  "includeInactiveUsers": false,
  "issuesJqlFilter": "(project = \"SGNL\" OR project = \"MVP\") AND status = \"In Progress\""
}

Note: When using JQL in SGNL’s adapter configuration, double-quotes within the JQL query must be escaped with a backslash (\) because the entire JQL filter is surrounded by double-quotes in the JSON configuration.

Configuring Group Filters

To sync only specific groups instead of all groups in Jira Data Center:

{
  "apiVersion": "2",
  "includeInactiveUsers": false,
  "groups": ["jira-administrators", "jira-software-users", "project-leads"]
}

Including Inactive Users

By default, inactive users are excluded from synchronization. To include them:

{
  "apiVersion": "2",
  "includeInactiveUsers": true
}

Complete Adapter Configuration Example

Here’s a comprehensive example that filters for active issues in specific projects and syncs only certain groups:

{
  "apiVersion": "2",
  "includeInactiveUsers": false,
  "issuesJqlFilter": "project IN (\"SGNL\", \"PROD\") AND status != \"Closed\"",
  "groups": ["jira-administrators", "jira-software-users"],
  "requestTimeoutSeconds": 30,
  "localTimeZoneOffset": 0
}

Adapter Configuration Fields

  • apiVersion: The Jira REST API version to use. Set to "2" for tested compatibility
  • includeInactiveUsers: Whether to sync inactive users. Default is false
  • issuesJqlFilter: JQL query to filter which issues are synchronized
  • groups: Array of specific group names to sync. If not specified, all groups are synced
  • requestTimeoutSeconds: Timeout for API requests in seconds. Default is 10
  • localTimeZoneOffset: Timezone offset for parsing date-time attributes without timezone info. Default is 0 (UTC). Range: -43200 to 50400 seconds (-12 to +14 hours)

Best Practices

  1. Start with restrictive filters: Begin by syncing only the data you need, then expand as necessary
  2. Use project-based filtering: If your policies are project-specific, filter issues by project to reduce sync time
  3. Monitor sync performance: Large Jira Data Center instances may benefit from more restrictive filters
  4. Test JQL queries: Test your JQL queries in Jira’s issue search before applying them in SGNL
  5. Consider sync frequency: For large datasets, you may want to reduce sync frequency from the default hourly schedule

Troubleshooting

Common Issues

  1. Authentication Failures:

    • Verify your credentials or Personal Access Token are correct
    • Ensure the account has the necessary read permissions
    • Check if the account is active and not locked

  2. Network Connectivity:

    • Verify SGNL can reach your Jira Data Center instance on port 443
    • Check firewall rules and network policies
    • Consider using the On-Premises Connector if inbound connections are not permitted

  3. JQL Filter Errors:

    • Test your JQL query in Jira’s advanced search first
    • Ensure all double-quotes in the JQL are escaped with backslashes
    • Verify field names and values exist in your Jira instance

  4. Incomplete Data Sync:

    • Check if filters are too restrictive
    • Verify the account has read access to all desired data
    • Review sync logs for specific error messages