Jira Service Management

Package: SERVICE

1. General

Customers have the option of creating so-called "requests" (tickets) in the "Jira Service Management Portal". This requires enabling customers in the Contacts module. Tickets created via the Jira Service Management Portal are automatically created as a new record in brainX in the Tickets module.

In the Tickets module, brainX users can compose replies in the "External comments" block. The customer automatically receives an email with the reply. The reply is also displayed in the customer's Jira Service Management Portal.

2. Activation and configuration

2.1. Global settings

After opening the "Jira Service Management" settings item in the company information, only one block is available for the basic settings (authentication) in the first step:

• General settings → Details of the endpoint

Company information - Jira Service Management

2.1.1. General settings

The following fields are available in the "General settings" block:

• Jira URL → Enter the Jira URL (e.g. https://ihrefirma.atlassian.net)
• Main user account → Name of the main user account (email address of the Jira main user; the main user is required for the API calls)
• Main user API token → API token of the main user (can be generated in the main user's Atlassian account under the "Security" settings item)

Once the data has been entered, the "Save endpoint" button is activated. After clicking the button, a connection to Jira is established, data is retrieved and the following blocks are additionally displayed:

• Webhook settings → Display of the webhook settings
• Project settings → Selection of the Jira project
• Status mapping → Mapping of the values of the "Jira status" field to the corresponding values of the "Status" field in the Projects module

Company information - Jira Service Management active

2.1.2. Webhook settings

The following fields are available in the "Webhook settings" block:

• Jira security key → Display of the Jira security key
• Jira webhook URL → Display of the Jira webhook URL

2.1.3. Project settings

The following fields are available in the "Project settings" block:

• Project → Picklist of the Jira projects

The "Project" picklist displays all Jira projects that have been released based on the configuration in Jira.

After selecting the project, further fields are displayed:

• Request type → Picklist of the request types available in the selected Jira project (e.g. "Submit request or incident")
• Responsible user for new tickets → Picklist of the brainX users. The user selected here is automatically entered as the responsible person in tickets that customers create via the Jira Service Management Portal.

2.1.4. Status mapping

In the "Status mapping" block, the values of the "Jira status" field are mapped to the corresponding values of the "Status" field in the Tickets module.

On the left-hand side, all available values of "Jira status" are listed. On the right-hand side, a picklist is used to assign each Jira status value a corresponding value from the picklist values of the "Status" field available in brainX from the Tickets module.

Jira Service Management - Mapping of status values

Once all status values have been mapped, the "Status mapping" block appears as follows:

Jira Service Management - Status values mapped

To save the status mapping, the "Save mapping" button must finally be clicked.

2.2. User settings

In My settings - Integrations tab, users can authenticate with Jira and store a private API token.

My settings - Integrations tab

After clicking the "Jira Service Management" tile in the "Available integrations" area, the "Jira authentication" popup is displayed:

Jira authentication popup

The following fields are available in the "Jira authentication" popup:

• Jira URL → Enter the Jira URL (e.g. https://ihrefirma.atlassian.net)
• Email address → Email address of the Jira user
• Private API token → API token of the user (can be generated in the user's Atlassian account under the "Security" settings item)

After clicking the "Store token" button, the authentication is carried out and the user can use the integration.

3. Usage

3.1. Jira Service Management Portal

3.1.1. Access to the Jira Service Management Portal

3.1.1.1. Activate access

After activating the Jira Service Management integration in the company information, the "Jira Service Management" block is available in all records of the Contacts module.

Contacts module - Jira Service Management block

In the Contacts module, the following fields are available in the "Jira Service Management" block:

• Allow access to Jira Service Management → Toggle to activate access
• Access from → Date from which access is active
• Access until → Date until which access is active

If the record is now saved, the contact automatically receives an email with a link to the Jira Service Management Portal.

3.1.1.2. Deactivate access

Access to the Jira Service Management Portal for customers/contacts is automatically deactivated as soon as the date entered in the "Access until" field in the Contacts module is reached.

Active access can also be terminated before the date specified in the "Access until" field by setting the toggle in the "Allow access to Jira Service Management" field to "off".

To extend access, a corresponding date in the future must be entered in the "Access until" field.

3.1.2. Using the Jira Service Management Portal

If access to the Jira Service Management Portal has been activated in the Contacts module, customers have the option of sending a request in the portal.

After logging in, the start page in the Jira Service Management Portal appears as follows (example):

Jira Service Management Portal

After clicking the "Submit a request or incident" action link, the input mask for creating an incident/ticket is displayed:

Jira Service Management Portal - Create request

After filling in the input mask and clicking the "Send" button, a new record is created in brainX in the Tickets module.

The entries in the portal are transferred to a new record in the Tickets module as follows:

• "Summary" field → "Title" field
• "What are the details of your request?" field → "Description" field

3.2. Tickets module

Customers have the option of creating requests/tickets in the Jira Service Management Portal. These requests are automatically created as a ticket in the Tickets module.
CRM users can enter a reply in the "External comments" block. The customer automatically receives an email and the comment is also displayed in Jira Service Management on the customer's side.

Tickets module - External comments block

The page describes a clearly delimited integration between brainX and Jira Service Management — a ticket portal for customers, bidirectional communication and status synchronisation. Both sections make sense. Here they are:

4. Practical examples

1 - Grant customers access to the support portal

Initial situation: A company wants to offer its customers a professional self-service portal through which they can submit support requests and track the progress of their processing.

Procedure: In the Contacts module, for the respective contact in the Jira Service Management block, the Allow access to Jira Service Management toggle is set to on and a validity period (Access from / Access until) is stored. The contact automatically receives an email with the access link to the portal. After logging in, they can create requests, which are immediately created as a ticket in the brainX Tickets module.

Result: Customers can submit support requests around the clock on their own. The support team sees all tickets directly in brainX - without manual transfer.

2 - Process a support request and reply to the customer directly

Initial situation: A customer has submitted a request via the portal. A support employee wants to reply to the customer directly from within brainX without having to log in to Jira.

Procedure: In the Tickets module, the relevant record is opened. The reply is entered in the External comments block. The reply is automatically sent to the customer by email and appears at the same time in the customer's Jira Service Management Portal.

Result: All communication with the customer runs through brainX. The employee does not have to switch between two systems, and the customer sees the reply both by email and in their portal.

3 - Create a ticket in brainX and make it visible in the customer portal

Initial situation: A support employee records a ticket directly in brainX (e.g. based on a phone call) and wants the customer to be able to track the ticket in their portal.

Procedure: A new record is created in the Tickets module. Since the associated contact already has access to the Jira Service Management Portal, a request is automatically created in the portal on behalf of the contact. The customer sees the ticket as if they had created it themselves, and can comment on it as well as follow its progress.

Result: Tickets recorded internally in brainX are seamlessly visible in the customer portal. Communication remains central and transparent for both sides.

5. Frequently asked questions

Does every brainX user need their own Jira account?

For basic operation of the integration (receiving tickets, sending comments), only the system-wide main user account, which is stored in the global settings, is required. Users who want to use Jira functions directly beyond that can optionally store their own API token in My settings → Integrations tab.

What happens when a user's API token expires?

API tokens have an expiry date. Once expired, no connection to Jira is possible any more via this user. The expired token must be deleted in the user's Atlassian account, a new token created and then stored in brainX under My settings → Integrations tab.

How is a customer's access to the portal limited in time?

In the Contacts module, a validity period can be set in the Jira Service Management block via the Access from and Access until fields. Access is automatically deactivated as soon as the Access until date is reached. To extend access, all that is needed is to enter a new date in the future. A premature manual withdrawal of access is possible at any time via the Allow access to Jira Service Management toggle.

Are status changes in Jira automatically applied in brainX?

Yes, via the configured status mapping, Jira status values are automatically assigned to the corresponding status values in the Tickets module in brainX. Status changes in Jira are transmitted to brainX via the webhook and automatically updated there.

Does the background task for the portal absolutely have to be active?

Yes, the Jira Service Management customers background task must be active so that access to the portal can be activated or deactivated for contacts. The task is responsible for creating or removing customers in Jira Service Management. Without an active background task, access status changes in brainX are not transmitted to Jira.

7. Video-Tutorials