f1 Content

2 Introduction

Welcome to the User Guide for USU Service Management Connector for Jira (Cloud). This manual is made for users who Administer Jira Issues and USU Tickets. This connecting tool provides two-way data transfer between Jira and USU. 

Our User Guide describes basic information about the installation and configuration of our Connector step by step. Furthermore, you can find here a summary of the basic functioning of our Connector. Of course, the admin users also have many options for setting up Connector according to their needs.

Our Team hopes that USU Service Management Connector for Jira will help you transfer data between Jira and USU more efficiently and make your work more successful. We are ready to help you if you would need anything else. Don´t hesitate to contact us (contact information can be found on the last page of our User Guide).

Your SykoraIT

3 Installation

3.1 Jira plugin

3.1.1 Installation from Atlassian Marketplace

• Search for the application USU Service Management Connector for Jira in the Atlassian Marketplace. Our Connector has server and cloud hosting type versions. Please select the cloud version.

Open

Open

• Download and install the connector.

• Input license key.

• The successful installation contains a new Setting page of our Connector where you can find generated InterfaceKey in the Default Interface.

• The InterfaceKey is used for communication with USU Service Management Interface Actions. The image below demonstrates the right installation. The key has to be globally unique.

3.1.2 Manual installation via Manage Apps Administration

• Login into Jira as Administrator (or user with Administrator´s permissions).

• Go to Jira Administration – Apps and select Manage Apps.

• Click the Upload app button and paste the Descriptor URL of our Connector (which will be provided by the Vendor). 

Example: https://marketplace.atlassian.com/files/1.2.1-AC/artifact/descriptor/513ce61e-c05d-4728-b013-9fadbd0be955/atlassian-connect.json?access-token=ae1a62d6

• If the button Upload app is missing on your screen, check the Settings of UPM. Both conditions have to be checked.

• Install The connector for Jira.

• Get started working with USU Service Management Connector for Jira.

• The successful installation contains a new Setting page of our Connector where you can find generated InterfaceKey in the Default Interface. The InterfaceKey is used for coupling to USU Service Management Interface Actions. The image below demonstrates the right installation. 

3.2 USU Service Management Package (Valuemation)

The installation package for USU Service Management (Valuemation) will be provided by Sykora IT. If you do not have it, please contact us at support@sykorait.com.

3.2.1 Installation

• Import the file USU ServiceManagmentConncetorForJira_v1_0_0.zip.

• Ignore the warning in the last file. It is caused by a missing index in USU Service Management Standard. Import the file by the Import button. 

• Go into the catalog Generic VM Interfaces. You should find the interface SIT_USU_Atlassian_Connector. It will run when the status is set to Active/Scheduled.

• Go into the catalog Processes for Deployment and activate the process SIT_Interface.Process initialized Data queues.

• Go to the Object Customizer and open the Object Type Ticketdesc. As a „Modify On Save“ there should be the workflow SIT_Ticketdesc_Save_rework assigned. If it collides with your customizing, please contact our support team for advice.  

4 Configuration

4.1 Configuration of USU Service Management

4.1.1 Add SIT_InterfaceTransactionStart Webservice to Interface Handling

• Open the catalog Web Service Clients, then select Interface Handling to configure. It is necessary to add the new Web Service SIT_InterfaceTransactionStart. 

4.1.2 Configuration Generic Interfaces

• The Generic Interface and Interface Actions in USU must have names in this format:

  • SIT_USU_Atlassian_Connector_Cloud_InterfaceKey

• Copy the generated InterfaceKey from the Settings page of our Connector in Jira (see section 3.1.1/3.1.2).

• You can either create the Interface and Interface Actions manually by using Copy action from the context menu or use the Workflow SIT_CopyInterface. 

• Workflow SIT_CopyInterface:

  • Select the Generic interface that you want to change.

  • Paste InterfaceKey from the Jira Plugin Settings. 

• A newly created Generic Interface appears in the list of Generic Interfaces.

• Manual Creation of Copy Generic Interface:

  • Click on the Interface with the right button of the mouse and select Copy. 

• Paste the generated InterfaceKey at the of the Interface name.

4.1.3 Configuration Generic Interface Source/Target Systems

• Copy Generic Interface Source/Target System SIT_USU_Atlassian_Connector_Cloud, or if you used the SIT_CopyInterface Workflow, it will be done automatically.

• Create Generic Interface Source/Target Systems is the same as demonstrated in section 4.1.1.

• Copy the generated InterfaceKey from the Settings page of our Connector.

4.1.4 Configuration Generic Interface Actions

• Copy the Actions. If you used the SIT_CopyInterface Workflow, it will be done automatically.

• Create Generic Interface Actions is the same as demonstrated in section 4.1.1.

• Copy the generated InterfaceKey from the Settings page of our Connector.

4.2 Configuration of Jira Plugin 

It is necessary for the well-behaving of our plugin to configure some basic parts. Firstly create (invite) a new Jira User (Technical User – our example of the Technical User is named SITJIRAINTEGRATION) for communication between Jira and USU. Then set up properly Jira Plugin Settings page. 

4.2.1 Invite a new Jira User for the Connector

The communication between Jira and USU runs in the backend. It needs a special user (Technical User) on both sides. It is recommended to have dedicated users for that. 

• Go to User Management Administration.

• Invite a new user for communication between Jira and USU Service Management.

• The created Technical User has to have access to the Jira Software Application and these permissions minimally (for a default installation of Jira, this corresponds to the Basic role):

  • Browse Projects

  • Create Issues

  • Edit Issues

  • Transition Issues

  • Add Comments

  • Edit Own Comments

  • Create Attachments

  • Delete Own Attachments

 (Jira documentation – Invite a User)

4.2.2 Creation and Configuration of Jira Custom Fields

Another small part for good functioning is to create two Custom Fields in Jira for receiving USU Ticket Number and USU Link  (name them as you wish). We recommend using the Short text (plain text only)  type for USU Ticket Number and the Paragraph (support rich text) type for USU Link. 

(Jira documentation – Create a Custom field)

The USU Link, which comes from USU Service Management to Jira Custom Field, can be displayed better in Jira Custom Field. It needs to change the Jira Custom Field configuration. 

• Go to Issues Administration and select Field Configuration. Search for USU Link Custom Field which you created. Select Action Renderers and change the Renderer to Wiki Style Renderer.

• View of the USU Link should look like the image below after this change. 

4.2.3 Configuration of Jira Plugin Interface

On the Interface Tab, you can configure the connection to USU Service Management. Follow the instructions below on how to set up Jira Plugin Interface. It is possible to create another interface. But you have to create InterfaceKey for new interfaces manually.

• USU URL – the link of USU where should be our plugin connected. 

http://[USUURL]/vmweb/services/api/execwf

• USU Servicename - SIT_InterfaceTransactionStart.

• USU Username – USU User with access to Generic Interface

• USU AccessToken – your Access Token you can find in Web Service Clients Catalog under the Interface Handling.

• USU Password - encrypted by runCrypto.bat (from USU).

• InterfaceKey - a unique key used to ensure the communication via WebHooks. Will be generated automatically only for the Default interface. 

• Account ID  - ID of the Jira User used in the Generic Interface. You can find this ID in the detail information about user (at the end of a link). See the image below. 

• You can use the Test Connection button to verify the configuration. Hint: first you have to save the configuration by clicking on the “Save Settings” button.

It is possible to create more interfaces than one. Click “+ Create an Interface” button and configure another one. Bare in mind it is necessary to create InterfaceKey manually for another Interface.

4.2.4 Configuration of Jira Plugin Interface (Forge version)

All the information mentioned above remains applicable to this version of the application. The primary changes in this section are related to the UI, which has been updated to align with the Forge framework.

Note: No default interfaceKey is created in this version. This encourages the creation of interfaceKeys with a more readable and structured format.

4.3 WebHooks

4.3.1 Application WebHooks (Dynamic Webhooks)

4.3.1.1 Create Jira WebHook (authorized by app itself)

• Specify Issue criteria (JQL filter).

• Select related Issue events.

• Press the Create WebHook button.

Note that only a subset of JQL and WebHook events is supported for now.

• Registration restrictions – A maximum of 100 WebHooks per app is allowed.

4.3.2 Application WebHooks (Forge version) - System webhooks

To support a broader range of webhooks, including advanced JQL capabilities, we leverage Jira System Webhooks. This approach ensures greater flexibility and seamless integration with the application.

4.3.2.1 Creating a Jira Webhook

• Access Jira System Webhooks
  Navigate to Jira System Webhook Settings and click the Create a Webhook button.

• Configure the Webhook

  • Events: Select the relevant events provided by our app to ensure accurate data synchronization:

    • Issue Created

    • Issue Updated

    • Comment Created

    • Comment Updated

    • Attachment Created

    • Attachment Deleted

  • Secrets: Leave the secret field empty. The data is already authorized through the app's permissions.

• Set the Webhook URL

  • Obtain the Webhook URL from the App Settings:

    • Go to the app interface within the settings.

    • Click the three-dot menu next to the desired interface.

    • Select Copy Interface Webhook URL.

  • The copied URL will be unique to the specific interface and may look something like this:

    https://a8830105-ba1d-4385-a16f-e7c08070e3a4.hello.atlassian.dev.net/x1/bWXLK5TQVvruTgeBnVyE49t5Lcs?issue_id=${issue.id}&issue_key=${issue.key}&interfaceKey=USM_DOC

• Purpose of the URL

  • This URL ensures that webhook events (e.g., issue updates, comments) are forwarded to the correct interface in the app.

  • The app identifies the interface via the unique interfaceKey in the URL and processes the webhook data accordingly.

Webhook Data Verification:
The app only trusts the event type and issue ID from the webhook payload. All other data is retrieved directly from Jira using the app’s permissions, ensuring accuracy and security.

Data Forwarding:
Based on the interface configuration, the app fetches Jira data and securely forwards it to the designated third-party interfaces. This ensures that only verified and authorized data is processed, regardless of who triggers the webhook.

By following these steps, you can integrate Jira System Webhooks with our application seamlessly.

4.4 Event Mapping

Event to Generic Interface Action mapping:

• To map a specific Generic Interface Action to a specific event, simply open the Event Mapping tab and fill in the desired Generic Interface Action name to a related issue event. If no value is specified, the default value is used.

Default Values for Generic Interface Actions:

* interfaceyKey  - identifies the certain interface.

4.4.1 Event Mapping (Forge version)

Event mapping functionality in this app version remains consistent with previous versions. The main change is where the mapping settings are configured.

To update event mapping:

1. Navigate to App Settings:

   • Open the app settings and locate the desired interface where you want to adjust the event mapping.

2. Access Event Mapping Options:

   • Click on the three-dot menu next to the interface.

   • Select Event Mapping from the dropdown menu.

3. Update Event Mapping:

   • Make the necessary changes to the event mapping following the process described earlier in this documentation.

4.5 Firewalls

There is a possibility to use Whitelisting for incoming messages to USM (Connector -> USM). You can use these two static IP addresses:

• 99.80.183.117

• 99.81.135.32

4.5.1 Firewalls (Forge version)

Current IP Address Ranges for Outbound Connections: IP addresses and domains for Atlassian cloud products | Atlassian Support

You can use these IP address ranges to allow Forge apps to make connections through firewalls or integrate with software that has a managed IP allowlist.

Important Note:

• The IP address range for outgoing connections is shared by all Forge apps. Allowing connections from this range permits connections from any Forge app.

4.6 Functions of Jira Plugin Connector

After these steps you have made before our Connector should be able to do: 

• Send a Jira Issue data to USU Service Management (Valuemation), where the new Ticket will be created.

• Send back USU Ticket number and USU Ticket link to Jira Issue.

• Sending comments from Jira to USU and from USU to Jira.

• Sending Attachments from Jira to USU.

• Creating more interfaces which can be active in the same time.

4.7 Scenario configuration

Create Ticket in USM (Jira → USM)

1. Create new Status in Jira wf

2. Set status event to Issue created

3. Create webhook in Connector app settings

5 Use Cases

5.1 Use Case 1: Create new Issue in Jira

Now it is time to check if everything is configured in the right way. Create an Issue in Jira and fill all the fields according to description below.

• Summary field (required).

• Make any Description.

• Assign this Issue to some User.

• Custom Fields USU No and USU Link should be a part of Create Issue dialog. Don´t fill in these field with anything.

• The USU Ticket is automatically created with all values from Jira Issue.

• Created Jira Issue is automatically updated. Jira Issue update contains Valuemation Ticket Number and Valuemation Ticket Link. Click the link and view the Ticket in USU Service Management. 

5.2 Use Case 2: Send attachments

5.2.1 Create an Issue in Jira with any attachments

• Create an Issue and add 1 – 2 attachments (JPG, PNG, doc, pdf) .

• All attachments are sended and saved to USU Service Management. 

5.3 Use Case 2: Add comments

5.3.1 Create a Comment in Jira

• Make a Comment to a created Issue.

• The Comment from Jira is automatically created in the USU Ticket. It appears as a Ticket Description in the USU Ticket.

5.3.2 Create a Comment in USU

• Add a Ticket Description to a Ticket in USU Service Management (Valuemation). The Ticket must be assigned to an Issue (via a value in the field sitJiraKey). 

• Comment from USU is automatically created in Jira Issue after refreshing Jira page.

6 Monitoring

6.1 Jira

6.1.1 Standard Jira Log

• Place to search for troubleshooting is the standard log file of JIRA.  

6.2 USU Service Management Package (Valuemation)

6.2.1 Generic Interface Data Queues

• Each incoming and outgoing REST Message is stored in the catalog Generic Interface Data Queues. 

• There you can check the status of the messages and find hints for troubleshooting. 

6.2.2 Process Instances for Monitoring

• The messages about newly created Ticket descriptions are sent in the Background by the process engine. 

• For each new Ticket description there should be an instance of the process SIT_Inteface.Process initialized Data queue. 

6.2.3 USU Log file

• Another place to search for explanation is the log file of the USU Process Engine or the USU Web Server.