Configure JIRA Plugin

General Configuration

Please use English as the default language setting in the user preferences of the user being used for authentication when OTRS interacts with JIRA.

Enable the Remote-API-Calls in the JIRA System Settings of the Administration in order to create JIRA Tickets out of OTRS!!!

Config-File

The OTRS Integration for JIRA has to be configured for JIRA and OTRS separately.

The JIRA configuration has to be conducted via a configuration file named 'otrsintegration.properties'.

You have to, e.g., specify the URL of OTRS and the login information.

When changing configurations in this file plugin has to be deactivated and than activated again to reload the config file.

Please find beneath a typical config file. Explanations to the config options are documented inline in the code block

The config file has to be placed within a conf folder under your JIRA Home Directory.

To identify your Home Directory from within JIRA:

Go to Administration > System Info
find the 'File Paths' section
there is an entry 'Location of JIRA Local Home'

Examples:

if your JIRA Home Directory is under /opt/jira_data the folder to place the otrsintegration.properties file is /opt/jira_data/conf
or if your JIRA Home Directory is under C:\jira\home the folder to place the otrsintegration.properties file is C:\jira\home\conf

When the plugin is installed and no config file is found there will also be an error in the log file stating the exact path where the file is to be expected.

otrsintegration.properties

# OTRS CONNECTION SETTINGS

# The SOAP URL of the OTRS server, e.g. http://localhost/otrs
OTRSURL=http://localhost/otrs

# The URL of the OTRS server for the Link in JIRA. Leave empty to use the above.
OTRSURL_FORLINK=

# Specify the username for updating issues in OTRS.
OTRS_SOAP_USERLOGIN=root@localhost

# Specify the password for updating issues in OTRS.
OTRS_SOAP_PASSWORD=root

# SPECIAL FIELDNAMES

# JIRA Customfield name or ID holding the OTRS ticket ID, e.g. OTRSTicketID
OTRSKEY=OTRSTicketID

# OTRS Dynamicfield name holding the JIRA issue ID, e.g. JIRAIssueID
JIRAKEY=JIRAIssueID

# JIRA FILTER SETTINGS

# Enter a list of project keys, comma separated, that are used to filter the issues
# for those given projects. Leave empty to disable the filter and send mail for all projects.
OTRS_PROJECT_FILTER=TEST,OTH

# Specify one or more special JIRA user. When this user creates or changes an issue the
# OTRS ticket will not be updated. This should in particular include the JIRA user used
# by OTRS to update or create issues.
JIRA_SPECIAL_USER=otrs2jira

# OTRS DEFAULT VALUES

# Specify the email address for updating issues in OTRS. This will only be used when
# the JIRA user has not specified one.
OTRS_SOAP_FROM=me@mail.org

# Default values for creating an OTRS Ticket from JIRA. These will be overwritten
# by possible mappings.
OTRS_DEFAULT_CUSTOMER=Testcustomer
OTRS_DEFAULT_QUEUE=Raw
OTRS_DEFAULT_STATE=new
OTRS_DEFAULT_PRIORITYID=3

# Default TimeUnit value for creating an OTRS Article. This will be overwritten by entered
# values (if enabled). Empty values will not be transfered.
OTRS_DEFAULT_TIME_UNIT=

# Prefix for the OTRS subject field, this will be added to all articles created by JIRA.
# You can use a space at the end of the prefix.
OTRS_SUBJECT_PREFIX=[JIRA]

# JIRA WORKFLOW SETTINGS

# Event name for the OTRS workflow commented event, e.g. OTRS_COMMENTED_EVENT.
# Only required if a separate workflow transition with event is used for commenting
# an issue. Also see the option regarding standard events below.
OTRS_COMMENTED_EVENT=OTRS_COMMENTED_EVENT

# Event name for the OTRS workflow resolved event, e.g. OTRS_RESOLVED_EVENT.
# Also see the option regarding standard events below.
OTRS_RESOLVED_EVENT=OTRS_RESOLVED_EVENT

# Event name for the OTRS workflow closed event, e.g. OTRS_CLOSED_EVENT.
# Also see the option regarding standard events below.
OTRS_CLOSED_EVENT=OTRS_CLOSED_EVENT

# Set to true, if you also want actions upon standard events on an issue. Use this,
# when you do not want or cannot change the workflow events. Set to false otherwise.
OTRS_USE_STD_EVENTS=true

# COMMENT SETTINGS

# Specify whether JIRA standard comments should be transferred to OTRS (true/false)
JIRA_COMMENTS_ARE_TRANSFERED_TO_OTRS=true

# Specify whether the OTRS Comment Action shows an input field for TimeUnit (true/false)
OTRS_COMMENT_WITH_TIME_UNIT=false
# Specify whether the TimeUnit field is required for the OTRS Comment Action (true/false)
OTRS_COMMENT_WITH_TIME_UNIT_REQUIRED=false

# CREATE OTRS TICKET ACTION SETTINGS

# JIRA Customfield name or ID holding the OTRS queue (used by the Create OTRS Ticket Action)
CUSTOMFIELD_OTRS_QUEUE=Queue
# JIRA Customfield name or ID holding the OTRS customer (used by the Create OTRS Ticket Action)
CUSTOMFIELD_OTRS_CUSTOMER=Customer
# If this is set to false the link to the Create OTRS Ticket Action will not be shown and the
# action won't work
CREATE_OTRS_TICKET_ACTION_IS_ACTIVE=true
# If this is set to true the customer and queue on the Create OTRS Ticket Action will be read-only
CREATE_OTRS_TICKET_ACTION_IS_READONLY=false

# MAPPING SETTINGS

# Mappings from JIRA to OTRS.
# A number like in "cust_10100" will be treated as a customfield ID

# Mappings from JIRA fields to OTRS Text/Textarea/Dropdown fields
MAPPINGS=1,2,4,5,8,9,10
# Mappings from JIRA Date/Time or Date fields to OTRS Date/Time fields
DATE_TIME_MAPPINGS=6
# Mappings from JIRA Date/Time or Date fields to OTRS Date fields
DATE_MAPPINGS=7

# The actual mappings, if the mapping ID is not listed above it will be ignored
MAPPING_1=std_priority,dyn_jirapriority
MAPPING_2=cust_10700, dyn_jiramail
MAPPING_4=std_components,dyn_JiraComponents
MAPPING_5=std_fixForVersion,dyn_JiraFixVersions
MAPPING_6=std_created,dyn_SomeDate
MAPPING_7=cust_Date,dyn_AnotherDate
MAPPING_8=cust_Textarea,dyn_Textarea
MAPPING_9=cust_Dropdown,dyn_Dropdown
MAPPING_10=cust_OtrsOwner,std_owner

# Mapping prefixes you can use (case sensitive):
# MAPPING_PREFIX = MAPPING_
# CUSTOMFIELD_PREFIX = cust_
# DYNAMICFIELD_PREFIX = dyn_
# STANDARD_FIELD_PREFIX = std_

# OTRS standard field names you can use (not case sensitive):
# queue
# title
# type
# service
# sla
# state
# priority
# owner
# responsible
# customerUser

# JIRA standard field names you can use (not case sensitive):
# summary
# type
# reporter
# priority
# description
# key
# status
# assignee
# resolution
# votes
# id
# watches
# project
# timespent
# timeestimate
# timeoriginalestimate
# created
# updated
# duedate
# resolutiondate
# security
# environment
# components
# fixForVersion

The above config file is an example. Please change all relevant values, so it matches your environment. Especially remove the example mappings:

# Mappings from JIRA fields to OTRS Text/Textarea/Dropdown fields
MAPPINGS=
# Mappings from JIRA Date/Time or Date fields to OTRS Date/Time fields
DATE_TIME_MAPPINGS=
# Mappings from JIRA Date/Time or Date fields to OTRS Date fields
DATE_MAPPINGS=

Necessary Fields

The following fields have to be created if they didn´t exist already:

a text custom field for storing the OTRS Ticket ID, name must match the value of the 'OTRSKEY'
a custom field for storing an OTRS customer and an OTRS queue (if you want to create OTRS tickets from JIRA issues via the Create OTRS ticket action'): can be fields of type text, select list or SQL field (additional plugin necessary)
in the OTRS a dynamic field for the JIRA Issue ID, this should have been created automatically during the installation of the OTRS plugin, its name ('JIRAIssueID') has to match the value of the 'JIRAKEY'
Specified fields in mappings on both sides
- Mappings for JIRA fields that don´t exist will be ignored
- Mappings for OTRS fields that don´t exist will throw exceptions

Mapping

To map JIRA fields to OTRS standard fields you can use the following fields names (they are also listed in the config file):
Keys for OTRS standard fields Expand source
```
queue
title
type
service
sla
state
priority
owner
responsible
customerUser
```
To map JIRA fields to dynamic fields the internal OTRS name has to be used.
For JIRA custom fields their name as well as their ID can be used in mappings
The following JIRA system fields can be used for mappings:
Keys for JIRA standard fields Expand source
```
summary
type
reporter
priority
description
key
status
assignee
resolution
votes
id
watches
project
timespent
timeestimate
timeoriginalestimate
created
updated
duedate
resolutiondate
security
environment
components
fixForVersion 
```
If you want to map the assignee of the JIRA Issue to OTRS you need to make sure that an OTRS user with the same name exists. Otherwise you can specify a ORTS User with the name "-". The mapping for that would be std_assignee,std_responsible.

Supported field types

Currently the following field types can be mapped for creation and synchronization type-aware.

Text Field (< 255 characters)
Free Text Field (unlimited text)
Date / Time
- Supported target OTRS format 'YYYY-MM-DD hh:mm:ss' only, means: It is possible to map JIRA text fields to OTRS date / time fields if their value comply with the format
- Empty field allowed
Date
- Supported target OTRS format 'YYYY-MM-DD 00:00:00' only
- Empty field allowed
Single Select List
- Mapping depending on the key not the value

Multiple Select List fields in JIRA as well as components and versions will be transferred as comma separated lists to text fields in OTRS.

Mapping of other field types is undefined and should be tested before using in production.

Listener

No specific configuration necessary

Postfunctions

The following postfunctions are available:

Create OTRS Ticket

OTRS tickets can be created via action as well as post function.

When using as post function queue and customer selection can be configured via a typically configure post function dialog:

Update OTRS Ticket

To update the OTRS ticket please select the Update Otrs Ticket Status Postfunction from the available function options:

Here you can enter the new OTRS queue and status (the later by name or ID). Furthermore the mapping can be activated.

Actions

JIRA provides two issue actions for creating and commenting of OTRS tickets. Only the Create OTRS Ticket action is effected by some configuration:

Create OTRS Ticket

In order to create OTRS Tickets a customer and Ticket queue is mandatory. These fields can be mapped to configurable custom fields (CUSTOMFIELD_OTRS_QUEUE and CUSTOMFIELD_OTRS_CUSTOMER). The Create OTRS ticket dialogue will be pre-filled with values friom those fields.
The two fields can be set to read-only via the key 'CREATE_OTRS_TICKET_ACTION_IS_READONLY'
The Key 'CREATE_OTRS_TICKET_ACTION_IS_ACTIVE' controls wheter the action is enabled or not.

OTRS Comment

No configuration necessary

Page tree

Configure JIRA Plugin

General Configuration

Config-File

Necessary Fields

Mapping

Supported field types

Currently the following field types can be mapped for creation and synchronization type-aware.

Listener

Postfunctions

Create OTRS Ticket

Update OTRS Ticket

Actions

Create OTRS Ticket

OTRS Comment