Jira Ticketing Provider Configuration Guide

Jira uses HTTP basic authentication with a username and API Token.

Creating a user

All API Tokens are associated with a user and mirror the policies that are assigned to the user. It is common practice to create a group and assign permissions to the group, and finally make the user part of the group. For more details, see Atlassian's documentation on user management.

1. Log in to Jira as an Admin

Once logged in, navigate to gear icon (top right) -> User Management.

2. Click on groups in left panel

Once in the groups screen, create a group.

3. Assign correct permissions to group

In the bottom part (Group product access) Select the product "User" (Can access the product, with no product admin permissions). We are implementing a simple setup. It is possible to do project based setup but that is for advanced users. Hit Save.

In addition, in certain product configurations, the user may need read and write access to specific projects of interest. Please refer to Jira Documentation for details.

4. Click on users in left panel

Create a user with a password. Assign the user to the group you created above, using the lower part of this panel. Hit Save.

Please note that user creation is not mandatory. However it is strongly recommended that you create a service user rather than tie the API token to a specific user who can leave your organization and thus break your integration.

Once logged in, navigate to gear icon (top right) -> Personal Settings (atlassian account settings).

6. Create an API Token for the Service User

In the top menu, go to "security". Click on "Create and Manage API Tokens", In the panel that opens up you can create API Tokens. Please note that the API Token will only be available at creation time. If its lost, you will have to revoke it and recreate a new token. It is best practice to rotate tokens every 90 days at least. More details are in Atlassian's documentation.

Configure the Integration

Create your integration by supplying the following values.

URL The root URL of your Jira instance. This may be in the format https://<tenant>.atlassian.net/.

Username The username of the user account created in step 4.

Password The API Token created in step 6.

Custom Fields

To configure custom fields for this integration, see the Jira Ticketing Provider Custom Fields Configuration Guide.

Ticket Hierarchy and the `parent` Field

Jira supports a native parent-child relationship between issues. Synqly exposes this through the parent field on the Ticket type.

Supported operations

Operation	Behaviour
`CreateTicket`	Set `parent` in the request body to create the ticket as a child of an existing ticket.
`PatchTicket`	Use JSON Patch `add` or `replace` on `/parent` to reparent a ticket, or `remove` to clear the parent.
`GetTicket`	The `parent` field is populated with the parent ticket's key whenever a parent is set in Jira.

Referencing a parent

Pass either the ticket key (e.g. "PROJ-42") or the numeric internal ID (e.g. "10001") in the parent field. Synqly automatically selects the correct Jira API format based on the value.

Issue hierarchy

Jira Cloud enforces a fixed issue hierarchy. Common supported relationships are:

Epic → Story / Task / Bug (and other standard non-Epic issue types)
Task / Story → Sub-task

Attempting to assign a parent that violates Jira's configured hierarchy (for example, setting an Epic as a child of another Epic) will return a 400 error from Jira.

Note: Synqly maps only the native Jira parent field. The deprecated Epic Link and Parent Link custom fields are not used.