Setup

DYCE Connector for Jira & Jira Service Management connects to Jira Service Management using an Atlassian OAuth 2.0 (3LO) app. Setup consists of registering that app in Atlassian, then running the DYCE Connector for Jira Onboarding wizard in Business Central, which creates the OAuth2 setup, table mapping and authorization in one guided flow.

Prerequisites

• A Jira Service Management site.
• Rights to create an OAuth 2.0 app in the Atlassian Developer Console.

Registering the OAuth 2.0 app in Atlassian

1. Open the Atlassian Developer Console and create a new OAuth 2.0 integration.
2. Under Permissions, add the Jira Service Management APIs the connector needs and grant the required scopes listed below.
3. Under Authorization, set the Callback URL to:

   https://app.dyce.cloud/jira/oauth/callback

   Business Central cannot receive a browser redirect directly, so the callback is handled by a DYCE Connect page. That page displays the authorization code, which is copied back into Business Central to complete authentication.
4. Note the Client ID and generate a Client secret. The secret is only shown once by Atlassian, so store it safely until it is entered in Business Central.

Required scopes

Which scopes are required depends on whether only the standard organization and customer fields are synchronized, or whether detail (custom) fields are also mapped. The onboarding wizard proposes a minimal starter set of scopes on its Scopes and authorization step (manage:jira-organization, manage:jira-service-management-project, read:jira-user, read:servicedesk-request, write:jira-service-management-request, offline_access); for a complete setup, use the scopes below instead.

Scopes for organization and customer synchronization

Scope	Purpose
offline_access	Obtain a refresh token so access tokens can be renewed automatically
read:jira-user	Read Jira user information (used to test the connection)
read:jira-work	General read access to Jira
read:servicedesk-request	Read service desk requests
write:servicedesk-request	Create and update service desk requests
manage:servicedesk-customer	Create and manage Jira Service Management customers (Contact → Customer synchronization)
read:servicedesk:jira-service-management	Read service desks (spaces)
write:servicedesk:jira-service-management	Manage service desks
read:servicedesk.organization:jira-service-management	Read which organizations are linked to a service desk
write:servicedesk.organization:jira-service-management	Link organizations to service desks (space assignment)
delete:servicedesk.organization:jira-service-management	Unlink organizations from service desks
read:organization:jira-service-management	Read organizations
write:organization:jira-service-management	Create and update organizations (Customer → Organization synchronization)
delete:organization:jira-service-management	Delete organizations

Additional scopes - only applicable if using detail fields

Field mappings with Field Category set to Custom Field are sent through Jira's organization/customer detail fields API instead of the standard create/update call, and therefore need these additional scopes. If no custom fields are mapped, they can be left out:

Scope	Purpose
read:organization.detail:jira-service-management	Read organization detail fields
write:organization.detail:jira-service-management	Write organization detail fields
read:organization.detail-field:jira-service-management	Read the organization detail field definitions
read:customer.detail:jira-service-management	Read customer detail fields
write:customer.detail:jira-service-management	Write customer detail fields
read:customer.detail-field:jira-service-management	Read the customer detail field definitions

Create Service Management Setup

The Jira OAuth2 Setup List page also offers a Create Service Management Setup action that creates a ready-to-use OAuth2 setup with all scopes above - including the detail field scopes - already applied.

Running the onboarding wizard

Open DYCE Connector for Jira Onboarding from the Assisted Setup page, or search for it directly (Alt+Q). The wizard guides through four steps:

1. OAuth setup
   Reuse an existing, enabled OAuth2 setup, or create a new one by providing a Setup code, the Client ID from Atlassian, the Base URL (defaults to https://api.atlassian.com), the Token endpoint URL (defaults to https://auth.atlassian.com/oauth/token) and whether tokens should be refreshed automatically. Use Open OAuth setups to review or adjust the setup on the full list page.
2. Table mapping
   Reuse an existing table mapping, or create a new one by choosing the BC Source Table, the Jira Entity Type, a Description, and optionally enabling a combined name. Field mappings for the new table mapping can be configured directly in this step. Open entity configuration shows the Jira REST endpoint used for the chosen entity type; see Table and field mapping for details.
3. Scopes and authorization
   The wizard lists its starter set of required scopes and, if Apply required scopes automatically stays enabled, writes them to the OAuth2 setup. Enter the Client secret and select Start authorization to begin the Atlassian consent flow described below. Review the required scopes afterwards and extend the OAuth2 setup if detail (custom) fields will be mapped.
4. Summary
   Shows the OAuth2 setup and mapping status, the Cloud ID status, and the endpoint in use. From here, Initialize job queue and Start job queue set up background processing - see Job Queue for what this does. Select Finish to close the wizard.

Authorizing with Atlassian

Selecting Start authorization (or Authenticate on the Jira OAuth2 Setup List, described below) runs the following flow:

1. Business Central opens the default browser at the Atlassian authorization page.
2. Sign in with an Atlassian account that has access to the Jira Service Management site and approve the requested scopes.
3. Atlassian redirects to the DYCE Connect callback page, which displays an authorization code.
4. Back in Business Central, confirm that the code is visible, then paste it into the Enter Authorization Code dialog.
5. Business Central exchanges the code for an access and refresh token, stores them securely, and retrieves the Cloud ID and Site URL of the Jira site.

Once authenticated, access tokens are refreshed automatically before they expire as long as Auto Refresh Tokens stays enabled; see Job Queue for how the refresh threshold is configured.

Managing OAuth2 setups

Multiple OAuth2 setups can be maintained on the Jira OAuth2 Setup List page, for example to connect to more than one Jira site. Each setup shows its Base URL, Client ID, Auto Refresh Tokens setting, current OAuth Scopes, and whether a client secret, access token or refresh token is stored, along with the Last Token Refresh and Token Expires At timestamps.

Available actions:

• Create Service Management Setup - creates a setup pre-filled with the complete Jira Service Management scope set (see tip above), including the scopes only needed for detail fields.
• Authenticate - runs the authorization flow described above.
• Refresh Token - manually refreshes the access token using the stored refresh token.
• Test Token - calls the Jira API to confirm the stored token still works.
• Clear Tokens - removes the stored access and refresh tokens, for example before re-authenticating with different scopes.

remarque

An OAuth2 setup cannot be deleted or renamed while it is referenced by a Jira table mapping.

Permissions

Three permission sets are included with DYCE Connector for Jira & Jira Service Management. To review the permissions included in each one in detail, open the Permission Sets page (Alt+Q) and use the Permissions action.

• DYCEJiraRead (DYCE Connector for Jira Read)
  Read-only access to all Jira Connector tables: OAuth2 setup, table and field mappings, entity configuration, activation rules, assigned spaces, and the message queue and its logs. Automatically included in the standard D365 Basic - Read permission set.
• DYCEJiraEdit (DYCE Connector for Jira Edit)
  Adds insert, modify and delete rights for synchronization data: the message queue, message detail log, tracking requests and follow-up actions. This is the permission set needed to enable or disable sync and trigger a manual sync on a Customer or Contact, and to manage messages as described in Understanding messages. Includes DYCE Connector for Jira Read and is automatically included in the standard D365 BASIC permission set.
• DYCEJiraAdmin (DYCE Connector for Jira Admin)
  Adds insert, modify and delete rights for configuration data: OAuth2 setup, table and field mappings, entity configuration, activation rule assignments and space assignments. Includes DYCE Connector for Jira Edit and is automatically included in the standard D365 SETUP permission set.