1. Content

2. Introduction

Welcome to the User Guide for USU Service Management Connector for Jira. 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.

The connector is based on Object and Field Mapping. Here you can find basic and advanced information about default functions of our Connector. Of course the admin users also have many options for setting up Object and Field Mapping of our Connector according to their needs. Our User Guide provides basic instructions on how to do this.

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 application USU Service Management Connector for Jira in the Atlassian Marketplace.

• Download and install the connector.

• Input license key.

3.1.2 Manual installation with .jar package

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

• Go to Jira Administration – Manage apps.

• Upload USU Service Management Connector for Jira. Select Jar format of the file

• Install the connector for Jira

• Get started working with USU Service Management Connector for Jira

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 ServiceManagmentConnectorForJira_v1_0_3.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 Jira Plugin

4.1.1 Create Jira User for the Connector

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

Follow these step: (Link to Jira documentation - Create user)

• Go to User Management Administration.

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

• The created Jira user must be part of JIRA Service Desk and Jira Software groups.

• See the user details:

4.1.2 Create Custom fields in Jira for the Connector

Default mapping expects two Jira custom fields on Issue to store the USU Ticket Number and USU Ticket Link to the USU Ticket. The Default_ GetMasterData mapping expects two Scriptrunner fields to store generated list of USU System-CI and generated list of USU Model Tickets. With both default mappings you have to use the exact names as below. If you want to use different names, you can change the mappings.

Follow these steps: (Link to Jira documentation - Create custom field)

• Go into the Issues Administration – Custom fields.

• The new custom fields must be placed at least on the edit screens.

• Create two standard custom fields (if you use same names (same format as technical name of those fields) and settings for fields as model examples you don´t need to change Default interface settings in Object Mapping):

  • Name: Valuemation Ticket Link; Type: Text Field (Multi-line).

  • Name: Valuemation Ticket No; Type: Text Field (Single-line).

• Change Object Mapping in case of different custom field names.

• Image below demonstrate names of custom fields which work properly with both default object mappings.

4.1.3 Configuration of Jira 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 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 image below after this change

4.1.4 Configuration of Allowlist

It is necessary to add your USU URL to Allowlist (System Settings of Jira). The Connector is not able to connect your USU Environment without this. This behavior of the Connector is mainly for safety reasons. It is not possible to send data from the Connector to an unknown environment.

Log Comment of our Connector informs you about it with this Error comment.

4.1.5 Default Object Mappings

Mapping in this version of Jira Plugin contains two default interfaces: Default Interface and Default_GetMasterData Interface. The basic difference between them is in USU Webservice. Default Interface is using InterfaceTransactionStart Webservice, Default_GetMasterData Interface is working with SITGetObjectsSetLastSyncTS Webservice.

Default Interface is capable of following activities:

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

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

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

• Send status change of Jira Issue (done) to USU Ticket (solved).

• The Default interface and mappings will be created automatically when the page Object Mapping is loaded.

• Image below demonstrates user view of Default Interface Object Mapping.

Default_GetMasterData Interface is capable of following activities:

• Download Systems (CI´s) and Model Tickets data from USU Service Management to Jira. The data will be stored in custom tables of the Connector and can be referenced in Jira Issues.

• You can change parameters of the request in Object Mapping Events. Default Target conditions for System-CI are set up as below:

{
      "types":[
         {
            "type":"SITStagingSystem",
            "condition":{
               "buildCondition":"catalog",
               "catalog":"SITStagingSystemsChanged"
            },
            "sortedBy":[
               "datchg descending"
            ],
            "fields":[
               {
                  "name":"name"
               },
               {
                  "name":"status"
               },
               {
                  "name":"systemname"
               },
               {
                  "name":"systype"
               },
               {
                  "name":"validfrom"
               },
               {
                  "name":"validto"
               },
               {
                  "name":"datchg"
               }
            ],
            "seekRead":{
               "pageRequest":"first",
               "pageSize":"100"
            }
         }
      ]
   }
}

• Image below demonstrates Events dialog for System-CI

• Image below demonstrates user view of Default_GetMasterData Interface Object Mapping

Both Object Mappings are almost ready to use. What is necessary to do:

• Go to Manage Apps and select Object Mapping of our Connector.

• Click Edit button and set up a connection to USU and activate default interfaces. It is possible to set up more Interfaces as active at the same time.

• USU URL: http://[HOST]/vmweb/services/api/execwf

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

• External User is the user name of the Jira User which is set in the Target System of the Generic Interface in USU. Otherwise the interface calls may be looped.

• After you have saved the configuration by clicking on Edit button, you can use the button Test Connection to verify the configuration.

• If you want to copy an interface including the mappings, just rename the default interface. The current Default interface will be saved with the new name. At the same time a new Default interface will be created with the default settings (as inactive).

• Create an external Jira user in Jira (go to 4.1.2).

• Create custom fields in Jira (go to 4.1.3).

4.1.6 Internal/External Comments Feature

If information about how was the comment created in Jira was shared (internally or with Custumer), we need to set the following

• Add new Field map to Comment-Ticketdesc mapping

• Add new Object Field propertiesString to Jira Issue Comment (Jira Objects)

• Add new Object Field propertiesString to Ticket Description (USU Objects)

4.2 Configuration of Script Runner

There are more options how the Model Tickets and Cis in the Connector’s tables can be referenced from a Jira Issue. We recommend using Script Runner for that (made by Adaptavist, tested with version 8.2.1).

Here are the steps needed for creation of the references to Model Tickets and Cis:

• Create Resource in Script Runner and make a Local Database Connection.

• Create two Database picker Fields in Script Runner (don´t forget to put created fields on Issue screen):

  • Field Name: USU System-CI; Type: Database picker.

  • Field Name: USU Model Tickets; Type: Database picker.

• Create two Jobs in Script Runner.

  • Custom Scheduled Job for System-CI.

  • Custom Scheduled Job for Modeltickets.

• Fill in the tables according to your needs (there are examples how to set up a scheduler) .

• Copy and paste the script bellow to Inline Script Table and set up a new URL.

import groovy.json.StreamingJsonBuilder

def authString = "Bearer [Personal Access Token]".getBytes().encodeBase64().toString()

def body_req = '''{
"eventTypeName": "runObjectMapping",
"objectMappingName" : "System-CI"
}''';

URL url = new URL("http://.../jira/rest/SITVmConnectorBackend/1.0/SITVmConnectorBackend");
HttpURLConnection con = (HttpURLConnection) url.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Authorization", "Basic ${authString}");
con.doOutput = true;
con.setRequestProperty("Content-Type", "application/json");
//con.outputStream.withWriter("UTF-8") { new Streaming JsonBuilder(it, body_req)}
con.getOutputStream().write(body_req.getBytes("UTF-8"));
con.connect();

println("url: " + url);
println("Content>:" + con.getContent())
println("ResponseCode:" + con.getResponseCode())
println("getResponseMessage:" + con.getResponseMessage())

con.disconnect();

• You can do the Script for Model Tickets (we recommend to create a New Job for it) in the similar way.

4.3 Configuration of USU Service Management Package (Valuemation)

4.3.1 Configuration VM Generic Interfaces

• Connection to your USU Service Management (Valuemation).

• Go to the catalog VM Generic Interfaces.

• Open the Interface SIT_USU_Atlassian_Connector. Open the Target System “SIT_JIRA”.

• Open the Target System SIT_JIRA. Input the URL of the REST Endpoint of your Jira into the field Webservice URL.

• Click on Authorization and select the proper Authorization Method (Basic Authorization). Input the data to access your Jira. The user needs to have the rights to use the REST API and Write permission on Jira Issues and Issue Comments.

Hint: This username has to be set in the field External User in the Interface in the Jira Connector.

• Select or create an USU user, which will be used for communication in the direction JIRA -> USU. The user should have the role SITJiraIntegration. This user information should be set in the setting of the Interface in the Jira Plugin.

• The user must have a person assigned.

• Configuration of the USU Web Service and Web Service Client. The implementation is done with the USU Generic Interface module. It means that the user (in our case SITJIRAINTEGRATION) must be assigned to the Web Service Client Interface Handling. In our case it is achieved by assignment to the User Group INTERFACE EXECUTORS.

4.3.2 Configuration of Interface Mapping

The Object and Field Mapping on the USU side is done by the Generic Interface module from USU. Detailed documentation can be obtained at USU or you can contact Sykora IT for support.

5 Use Cases

5.1 Use Case 1: Create Jira Issue

5.1.1 Create new Issue in Jira

• Fill a summary field (required).

• Add attachments (images and documents).

• Fill a description.

• Assign the Issue to SITJIRAINTEGRATION user

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

• 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: Add comments

5.2.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.2.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.

5.3 Use Case 3: Change workflow status in Jira

• Change workflow status of Jira Issue to Done.

• Status of USU Ticket is automatically changed to Solved (IN).

5.4 Use Case 4: Manual synchronization to USU

In addition to the automatic event-driven synchronization, there is the button Sync with USU in the More menu in Jira Issue. It sends the Issue data to USU. If the Issue is already linked to an USU Ticket, the Ticket will be updated. Otherwise, the new Ticket is created. The button is useful when you have older Issues which should be synchronized and were created before the installation of the Connector. Or if you want to synchronize only specific Issues.

• Go to the Connector settings and turn on Sync with USU button.

• Open one of the created Jira Issue and click the Sync with USU button.

• POP-UP message is sent automatically from USU about successful synchronization.

• The USU Ticket is automatically created in USU Service Management.

• Jira Issue is automatically updated (Valuemation Ticket No and Valuemation Ticket Link are added from USU Service Management).

5.5 Use Case 5: Generate USU Systems and USU Model Tickets

• Run the Script Runner Scheduler and open the Connector Administration – Model tickets and CI´s.

• There should be added CI´s and Modeltickets to the tables of our Connector.

• Create an Issue and see the new Script Runner Fields USU System-CI and USU Model Tickets. You should be able to pick one or more Items from a list of synchronized USU Items.

6 Monitoring

6.1 Jira

6.1.1 Connector Log

• Logs are situated in Object Mapping of our connector.

• It is possible to set up different levels of logging. We recommend the ERROR level.

• The capacity of the log is 10 000 records (you can see the current number of records on the counter). If there are more than 10 000 records the oldest ones are deleted.

• Set up the level of LOG, create an issue and refresh the LOG page.

6.1.2 Standard Jira Log

• Another place to search for troubleshooting is the standard log files 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 an explanation is the log file of the USU Process Engine or the USU Web Server.

7 Example of field Mappings

This chapter describes examples of possible Mappings between fields in Jira and USU Service Management (Valuemation).

7.1 Scenario 1: Simple Field Mapping in the direction from Jira to USU

There is a single line text custom field in Jira with the name myTextField. The value of the custom field should be sent to USU and stored in the new field name myTextFieldUSU in Ticket.

Follow those steps:

1. Create a field in Jira and USU Objects (in our connector configuration).

• Go to Issues Management and create Custom Field myTextField.

• Create a field in USU Service Management called myTextFieldUSU.

• Go to Objects of our Connector and select Jira Issue (Jira Objects).

• Click the Fields v button and see all created fields. Click the +Field button and create field myTextField.

• Do it the same way also for the Valuemation Ticket (USU Objects) and name the field myTextFieldUSU.

• If you are using multiple Custom Fields with the same name in Jira, you can specify the correct Custom Field by its ID rather than name in the Technical Name item. For example, the technical name could be "customfield_10000". The syntax is as in the example: customfield_ID.

• Example of a JQL condition for those Custom Field:

  • cf[10000] is not EMPTY

2. Create Field Mapping in the Issue-created Mapping.

• Go to Object Mapping of our Connector a select Issue-Ticket-Created.

• Click the + Field Map button and fill the table with created fields (new fields should be a part of roll down menu of Jira/USU field) and select direction from Jira to USU.

3. Create Mapping in USU Generic Interface Action

• Go to catalog Generic VM Interfaces and select SIT_USU_Atlassian_Connector.

• Then select from Interface Actions SIT_USU_Atlassian_Connector_CreateTicket.

• Select Input Interface Values Mapping to Valuemation and click button Add Valuemation Attribute. Select the created field myTextFieldUSU and click OK.

• Fill the name of the text field from Jira and click ok

• See the details of USU Input Mapping.

7.2 Scenario 2: Simple Field Mapping in the direction from USU to Jira (in the response)

There is a single line text custom field in Jira with the name myTextField2. When a new USU Ticket is created for a new Jira Issue, the value of the USU field named myTextFieldUSU2 should be stored into the custom field in Jira Issue.

1. Create field in Jira and USU Objects (in our connector configuration)

• The procedure is the same as for step one in 7.1. One important difference. Set up the default value in the USU field as “Hello from USU!”.

2. Create Field Mapping in the Issue-created Mapping (direction Jira<-USU)

• Go to Object Mapping of our Connector a select Issue-Ticket-Created.

• Click the + Field Map button and fill the table with created fields and select direction from USU to Jira.

3. Create Field Mapping in USU Generic Interface Action

• Go to Generic VM Interfaces -> SIT_USU_Atlassian_Connector_CreateTicket (output Mappings)

• Select Output Interface Values Mapping to Valuemation and continue as in the third step. You can check your work in the images below.

7.3 Scenario 1 and 2: Result

• Create a Jira Issue and fill the custom field myTextField with text “Hi from Jira!”. Custom field myTextField 2 leave empty.

• See the USU Ticket.

• See the Jira Issue.

8 List of supported field names

List of supported field names in the Jira Connector in the Object Issue.

List of supported field names in the Jira Connector in the Object Jira Project.

List of supported field names in the Jira Connector in the Object Issue Comment.

List of supported field names in the Jira Connector in the Object Jira User.

List of supported field names in the Jira Connector in the Object Attachment.

List of supported field names in the Jira Connector in the Object Issue Link.

List of supported field names in the Jira Connector in the Object CI´s.

List of supported field names in the Jira Connector in the Object Model Tickets.

Recursive Mapping: for some advanced use cases it is possible to use the name this in the case of Mapping of the type Object or Collection. It allows to create a dummy structure in the JSON when it is needed on the USU Side. The depth of the recursion is limited to 10 levels.

8.1 Supported Expressions

The function listToCollection also accepts Custom Field ID as a parameter. This can be useful when using multiple Custom Fields with the same name. An example: listToCollection("customfield_10010", "systemname").

8.2. External -> Jira mapping

List of supported fields in the Jira Connector in the Object Issue.