Jira

To configure an integration into Jira, the following steps need to be performed:

Configuring the Jira instance: usually, this task is performed by the Jira Administrator
Configure the CLIP target of type Jira: usually, this task is performed by the CLIP Administrator.

These two tasks will be described in more detail in the next two subsections.

Supported Versions

Please assure that the system you intend to integrate meets the version requirements outlined in the table below.

Product	Supported Version
Jira	???

System Preparation

Clip's Jira integration requires the creation of an integration user that performs the required operations to create and update incidents within Jira and therefore needs certain permissions within the Jira platform. In order to create an integration user, please perform the following steps:

click on "Administration", "User management"
click on "Create user" and create the integration user (see screenshot below)
provide the appropriate rights for that user: Go to "User management", click on "View project roles" (see screenshot below) of the integration user
provide the appropriate project roles (see screenshot below)

Create a new user:

View the user's project roles:

Provide the Service Desk Team role:

Clip Target Configuration

On the Clip Server edit the configuration file conf/ClipConfig.xml – for the Jira integration the file ClipConfig_New_Jira.xml contains the following example targets:

"MF_OMi" and "Jira" with integration "MF_OMi_Jira"
and "Jira_Source" and "ServiceNow" with integration "Jira_SN" which can be used as a template:

<integration status="active" name="MF_OMi_Jira">
    <target targetRef="MF_OMi"></target>
    <target targetRef="Jira"></target>
</integration>

<integration status="active" name="SN_Jira">
    <target targetRef="Jira_Source"></target>
    <target targetRef="ServiceNow"></target>
</integration>

XML

The following integration references the Jira example target called "Jira_Source":

<jiraTarget name="Jira_Source"
    url="https://applink.de:8585"
    user="ClipUser"
    passwd="password"
    incidentPolling="true"
    incidentPollingByQualifier="true"
    incidentPollingQualifier="status != closed and (reporter=[RL_IntegrationUser] or pro-ject='CLIPSD')"
    incidentPollingForNew="true"
    incidentPollingForNewQualifier="project='CLIPSD' and status != closed"
    incidentPollingAttributes="status,priority,description,assignee"
    statusField="status.name"
    closedStatusValueString="Closed"
    heartbeatIntervalSecs="20"
    updateCalcDelta="true"
    useProxy="false"
    proxyHost="myproxy.applink.de"
    proxyHostsExcluded="*.applink.de"
    proxyPort="8080"
    proxyUser="myUser"
    proxyPassword="myPwd">

XML

The following attributes have to be set in the Jira target definition:

"name" attribute of the target tag. For a standard integration, leave the default value "Jira" unchanged
"url" attribute: type in the URL of your Jira instance (e.g. https://applink.demo.jira.com). The URL should also include the HTTP/HTTPS port
"user" attribute: type in the integration user name for CLIP to log in to the Jira instance as configured in step 1) above, e.g. "ClipUser"
"passwd" attribute: type in the password to log in to the Jira Instance. The password can be entered in clear text or as an encrypted value. To encrypt the password, use the password encryption from "Miscellaneous" Tab of the Clip Server Web interface
"heartbeatIntervalSecs" attribute: (optional, default "60") can be set in order to increase or decrease the heartbeat and polling interval
"updateCalcDelta" attribute: should be set to "true" so that polling will only process the changed attributes

Proxy settings: if outbound communication from Clip to Jira needs to be established via a proxy server, the following settings need to be configured. Please note that when changing proxy related settings, the CLIP service needs to be restarted, a "Reload Config" in the GUI does not make the new settings effective:

useProxy: to use a proxy, set "useProxy" to "true"
proxyHost: please specify the hostname of the proxy server
proxyHostsExcluded: this optional attribute can be used to specify hosts which CLIP should not connect to via the proxy. Please note that if a proxy is used ( i.e. useProxy="true" ), this proxy is used for all connections that CLIP initiates, also for connections to OMi or NNMi. If connections to OMi or NNMi must not be initiated via the proxy, you have to use this attribute to exclude these hosts. The value for this attribute allows wildcards. As an example, if connections to all hosts in the domain "applink.de" should not use the proxy, set this attribute to : proxyHostsExcluded="*.applink.de"
proxyPort: port to connect to the proxy server
proxyUser: username to login into the proxy server
proxyPassword: password for "proxyUser" to login into the proxy server. The password can be entered in clear text or as an encrypted value. To encrypt the password, use the password encryption from "Configuration" Tab of the Clip Server Web interface

The next subsections describe how to poll for new incidents from Jira and the CLIP settings for checking for updates. Two attributes (incidentPollingForNewQualifier and incidentPollingQualifier) define qualifiers: the syntax for the qualifier has to match the "Where Clause" as specified by Jira in the documentation for the "AdvancedSearching Syntax". When customizing these qualifiers, please carefully review the Clip.log logfile for any issues and/or test your qualification criteria by means of the advanced search functionality in Jira.

Polling for new incidents in Jira

In addition to create and update incidents in a Jira target, CLIP can also retrieve new incidents and poll for updates from a Jira target to create and synchronize them with incidents in a peer target.
The following attributes control how CLIP performs the polling for new incidents:

incidentPollingForNew: to enable polling for new incidents, set it to "true", and "false" otherwise ( default: "false" )
incidentPollingIntervalSecsNew:the interval in seconds at which CLIP performs the polling operations ( default: 60 seconds )
incidentPollingForNewQualifier: this qualifier specifies the incidents which are supposed to be polled. To save resources on the target system, CLIP by default adds filters to the query and puts a limit for a time interval and does exclude incidents from the query created by itself by identifying them by the "reporter" field and the integration user configured in the "user" attribute.

Polling for updated incidents in Jira

For Jira incidents that have been created by CLIP as well as those retrieved, CLIP can poll these for updates to allow a bi-directional synchronization. The following attributes are used for "incident polling":

incidentPolling: to enable polling for updated incidents, set it to "true", or "false" otherwise ( default: "false" )
incidentPollingIntervalSecsChange: the interval in seconds at which CLIP performs the polling operations ( default: 60 seconds )
incidentPollingAttributes: a list of field names separated by semicolon that should be read and checked for changes.
"statusField": the name of the field that holds the current incident's status
"closedStatusValueString" attribute: the status value that will cause Clip to finish the synchronization once it is detected
incidentPollingByQualifier: selection of the method that CLIP uses to poll for updates. Two methods are available for polling for updates:
- incidentPollingByQualifier="false": incidents are polled sequentially (one-by-one) by their id as obtained from the CLIP DB.
- incidentPollingByQualifier="true": incidents are polled for updates in a bulk by using a proper qualification criteria configured in attribute "incidentPollingQualifier". This is the recommended method.
incidentPollingQualifier ( only relevant if incidentPollingByQualifier="true"): the qualification criteria to poll incidents for updates which have either been created by CLIP or retrieved by "pollingForNew". To save resources on the target system, CLIP by default adds filters to the query and puts a limit for a time interval.