USU Service Management

User Guide

2

1 Content

1 CONTENT 2

2 INTRODUCTION 4

3 INSTALLATION 5

3.1 JIRA PLUGIN 5

3.1.1 INSTALLATION FROM ATLASSIAN MARKETPLACE 5

3.1.2 MANUAL INSTALLATION WITH .JAR PACKAGE 6

3.2 USU SERVICE MANAGEMENT PACKAGE (VALUEMATION) 8

3.2.1 INSTALLATION 8

4 CONFIGURATION 11

4.1 CONFIGURATION OF JIRA PLUGIN 11

4.1.1 DEFAULT OBJECT MAPPING 11

4.1.2 CREATE JIRA USER FOR THE CONNECTOR 14

4.1.3 CREATE CUSTOM FIELDS IN JIRA FOR THE CONNECTOR 15

4.2 CONFIGURATION OF USU SERVICE MANAGEMENT PACKAGE (VALUEMATION) 16

4.2.1 CONFIGURATION VM GENERIC INTERFACES 16

4.2.2 CONFIGURATION OF INTERFACE MAPPING 18

5 USE CASES 19

5.1 USE CASE 1: CREATE JIRA ISSUE 19

5.1.1 CREATE NEW ISSUE IN JIRA 19

5.2 USE CASE 2: ADD COMMENTS 22

5.2.1 CREATE A COMMENT IN JIRA 22

5.2.2 CREATE A COMMENT IN USU 23

5.3 USE CASE 3: CHANGE WORKFLOW STATUS IN JIRA 24

5.4 USE CASE 4: MANUAL SYNCHRONIZATION TO USU 25

6 MONITORING 27

6.1 JIRA 27

6.1.1 CONNECTOR LOG 27

6.1.2 STANDARD JIRA LOG 27

6.2 USU SERVICE MANAGEMENT PACKAGE (VALUEMATION) 28

6.2.1 GENERIC INTERFACE DATA QUEUES 28

6.2.2 PROCESS INSTANCES FOR MONITORING 28

3

6.2.3 USU LOG FILE 28

7 EXAMPLE OF FIELD MAPPINGS 29

7.1 SCENARIO 1: SIMPLE FIELD MAPPING IN THE DIRECTION FROM JIRA TO USU 29

7.2 SCENARIO 2: SIMPLE FIELD MAPPING IN THE DIRECTION FROM USU TO JIRA (IN THE RESPONSE) 33

7.3 SCENARIO 1 AND 2: RESULT 35

8 LIST OF SUPPORTED FIELD NAMES 36

4

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 a field Mapping. Here you can find basic and

advanced information about creating fields, Objects and Object Mapping. Admin user has many

options for setting up Object Mapping.

5

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.

6

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.

7

• Install The connector for Jira.

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

8

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.

9

• Ignore the warning in the last file. It is caused by 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.

10

• 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 collide with your

customizing, please contact our support team for advice.

11

4 Configuration

4.1 Configuration of Jira Plugin

4.1.1 Default Object Mapping By default, the interface is capable of following activities:

• Send a Jira Issue data to USU Service Management (Valuemation), where 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.

• 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.

• Two images below demonstrate user view of Default Objects and Object Mapping.

12

Default Object Mapping is 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 interface.

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

• External User is user name of the Jira User which is set in the Target System of the Generic

Interface in USU.

• You can use the button Test Connection to verify the configuration. Hint: first you have to

save the configuration by clicking on the Edit button.

13

• Only one Interface should be set as active.

• If you want to copy an interface including the mappings, just reneame the default interface.

The current Default interface will be saved with the new name. At the same time new Default

interface will be created with the default setttings (as inactive).

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

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

14

4.1.2 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 steps: (Link to Jira documentation - Create user)

• Go to User Management Administration.

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

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

• See the user details:

15

4.1.3 Create Custom fields in Jira for the Connector The default mapping expects two custom fields on Issue to store the USU Ticket Number and Link to

the USU Ticket. With the default mapping you have to use the exact names as bellow. If you want to

use different names, you have to 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 basic 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 (Single-line).

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

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

16

4.2 Configuration of USU Service Management Package

(Valuemation)

4.2.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.

17

• 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

18

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.2.2 Configuration of Interface Mapping The Object and Field Mapping on 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.

19

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.

• Assignee Issue with SITJIRAINTEGRATION user.

20

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

21

• 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.

22

5.2 Use Case 2: Add comments

5.2.1 Create a Comment in Jira

• Make a Comment to created Issue.

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

the USU Ticket.

23

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.

24

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).

25

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 in already linked to an USU Ticket,

the Ticket will be updated. Otherwise, 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.

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

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

26

• 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).

27

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 ERROR level.

• Capacity of log is 10 000 records. If there are more records than 10 000 the oldest records are

deleted.

• Set up 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 file of JIRA.

28

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.

29

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 field in Jira and USU Objects (in our connector configuration).

• Go to Issues Management and create Custom Field myTextField.

• Create field in USU Service Management called myTextFieldUSU.

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

• Click button Fields and all fields. Click button +Field and create field myTextField.

• The same way do it also for Valuemation Ticket (USU Objects) and name the field

myTextFieldUSU.

30

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

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

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

USU.

31

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 created field myTextFieldUSU and click OK.

32

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

• See the details of USU Input Mapping.

33

7.2 Scenario 2: Simple Field Mapping in the direction from USU

to Jira (in the response) There is 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 default

value in 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 button + Field Map and fill the table with created fields and select direction from USU to

Jira.

34

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 in the same way as

step three in Scenario 1. You can check your work in images bellow.

35

7.3 Scenario 1 and 2: Result • Create an Jira Issue and fill custom field myTextField with text “Hi from Jira!”. Custom field

myTextField 2 leave empty.

• See the USU Ticket.

• See the Jira Issue.

36

8 List of supported field names

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

Technical field name Type Description

dueDate Column

statusId Column

summary Column

description Column

assignee Column

assigneeId Column

creator Column

creatorId Column

labels Column

priority Column

project Column

created Column

sitIssueURL Column

simpleStatusName Column

comments Collection Collection of Issue Comments

attachments Collection Collection of Attachments

subTaskObjects Collection Collection of Sub Tasks (Issues)

inwardLinks Collection Collection of Issue Links (inward)

outwardLinks Collection Collection of Issue Links (outward)

status Object Issue Status Object

assignee Object Assigned Jira User Object

Custom Fields Your custom fields can be used as well. The standard Jira Custom field types are supported.

37

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

Technical field name Type Description

body Column

IssueKey Column

Issue Object Issue Object

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

Technical field name Type Description

username Column

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

Technical field name Type Description

filename Column

filesize Column

mimetypes Column

value Column Base 64 encoded content of the attachment

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

Technical field name Type Description

sourceObject Object Source Issue

destinationObject Object Destination Issue

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 USU Side. The depth of the recursion is limited to 10 levels.

38

USU Service Management

Sýkora IT s.r.o. www.sykorait.com

support@sykorait.com +420 608 031 240