1

eyeShare Studio

Integrating with Jira

CONTACT: info@ayehu.com

2

LEGAL NOTICE .................................................................................................................................... 4

ABOUT AYEHU SOFTWARE TECHNOLOGIES........................................................................................ 5

ABOUT THIS DOCUMENT ................................................................................................................... 6

REQUIREMENTS ......................................................................................................................... 7

Supported Version ........................................................................................................................... 7

MODULE OPERATION ................................................................................................................. 7

INTEGRATION ARCHITECTURE ....................................................................................................... 7

MODULE INSTALLATION..................................................................................................................... 8

REQUIREMENTS ......................................................................................................................... 8

INSTALLATION PROCESS – NEW INSTALL ........................................................................................ 8

INSTALLATION PROCESS – UPDATE ............................................................................................... 9

MODULE CREATION AND CONFIGURATION ..................................................................................... 12

PROXY SETTINGS...................................................................................................................... 12

MODULE GENERAL SETTINGS ..................................................................................................... 12

SERVER SETTINGS .................................................................................................................... 13

PROJECTS ............................................................................................................................... 14

FILTERS .................................................................................................................................. 15

MAPPING ............................................................................................................................... 16

Fields ............................................................................................................................................. 17

Severity .......................................................................................................................................... 18

State .............................................................................................................................................. 20

VARIABLES USAGE ........................................................................................................................... 21

CONDITION ............................................................................................................................. 21

ACTIVITY ................................................................................................................................ 23

ACTIVITIES........................................................................................................................................ 24

JIRA CREATE ISSUE ................................................................................................................... 24

JIRA GET ISSUE ........................................................................................................................ 26

3

JIRA UPDATE ISSUE .................................................................................................................. 26

TROUBLESHOOTING ......................................................................................................................... 30

MODULE IS DOWN ................................................................................................................... 30

THE MODULE IS NOT PULLING ISSUES ........................................................................................... 30

NEW ISSUES FROM JIRA DO NOT CREATE EYESHARE INCIDENT .......................................................... 30

TEST CONNECTION FAILURE ....................................................................................................... 30

CREATE ISSUE, UPDATE ISSUE, GET ISSUE .................................................................................... 31

CONFIGURATION FILE ...................................................................................................................... 33

PROXY SETTINGS...................................................................................................................... 34

TIPS 34

RECOVERY WORKFLOW ............................................................................................................ 34

4

Legal Notice

© 2016 Ayehu Software Technologies Ltd ("Ayehu").

The contents of Ayehu's publications, whether found on this website and/or in the

project of an eBook and/or any other project of publication (collectively the

"Publications"), are owned and copyrighted by Ayehu.

A single copy may be printed solely for personal and non-commercial use.

No part of the publication may be altered, reproduced, distributed, or transmitted in

any project or by any means, including photocopying, issuing, or other electronic or

mechanical methods, without the prior written consent of Ayehu, except in the case

of brief quotations embodied in critical reviews and certain other noncommercial

uses permitted by law.

Any printed and/or electronically displayed (or any other such similar project of

display available) material (the "Materials") must contain the following copyright

notice: "Copyright © 2016 Ayehu Software Technologies Ltd. All Rights Reserved."

and any other copyright or other proprietary rights notices which were contained on

the Materials. Any other use of the Materials, either in whole or in part for any other

reason is expressly prohibited, unless prior written consent is obtained from Ayehu.

For the avoidance of any doubt, "Ayehu" and the names of all Ayehu Software

Technologies Ltd products and services referenced in this document are copyrighted

to Ayehu.

Other products' and/or companies' names referenced in the Materials may be the

trademarks of their respective owners.

5

About Ayehu Software Technologies

Ayehu was founded in 2007 to develop and market innovative solutions for the

prevalent problem of network and IT system downtime. Ayehu’s flagship product,

EYESHARE, significantly reduces MTTR by bridging the gap between critical business

situations and relevant human resources.

Contact details:

Ayehu Software technologies, Ltd.

26 Harokmim Street

Holon, 5885849, Israel.

Tel: +972 (0)3 649 50 70

Website: http://www.ayehu.com

email: info@ayehu.com

6

About this Document

This document describes the eyeShare – Jira integration components, Module

configuration and activities.

The following style conventions are used in this document:

Convention Use

Calibri Regular text

Calibri Bold Names of menus, commands, buttons, and other elements of the

User interface.

Calibri Italic Special terms; the first time they appear.

Notes offering an additional explanation or a hint on how to

overcome a common problem.

Warnings indicating potentially damaging User operations and

explanations on how to avoid them.

7

Requirements

Supported Version

The supported version of eyeShare for this integration is Ayehu eyeShare 4.7 (and

above), with a Jira Module license.

The supported versions of Jira are Jira Software 6.4.9 and 7.0.0, on premise or on Jira

cloud and Jira Service Desk 7.1.0 on premise or on Jira cloud. Only Jira base package

is supported using this integration.

User Access

The Jira eyeShare module user has to be a member of the jira-administrators and

jira-developer groups.

Server Time

Times and time zones on eyeShare and Jira servers must be synchronized.

Module Operation

The Jira Module provides a bidirectional communication channel between Jira and

eyeShare. Once the Module is defined and available, eyeShare pulls new submitted

issues and updates, translates them into incidents and displays them in eyeShare

Dashboard. Issues closed in the Jira console trigger incident closure in eyeShare.

Integration Architecture

8

Module Installation

Execute the installation file and follow the installation wizard instructions.

Requirements

1. One of the following operating systems:

Windows 2008 Server 64-bit

Windows 2012 Server 64-bit

2. Software: .Net Framework 3.5.1 and 4.5.1 installed.

3. The user running the installation should be an Administrator of the target host.

Installation Process – New Install

1. Run the eyeShare installer.

2. In the Setup Type step select Custom and click Next.

3. Expand Integration Packs branch and select This feature will be installed on local hard drive for eyeShare Jira Server. Then click Next.

9

4. Continue the installation as described in the Installation Guide.

Installation Process – Update

For instances already running eyeShare 4.7 and above, proceed with the following steps to add the Jira integration module:

1. Execute eyeShare.exe, and click Next.

To run the installer as the Administrator, right click the executable and select

“Run as administrator”

10

2. Choose Modify and click Next.

3. Expand Integration Packs branch and select This feature will be installed on local hard drive for eyeShare Jira Server. Then click Next.

11

4. Click Install.

A success notice will appear at the end of the installation process.

12

Module Creation and Configuration

Proxy Settings

If accessing the Jira instance requires a proxy server, do the following:

1. Access C:\Program Files (x86)\eyeShare\eyeShare Jira Server\eyeShare Jira

Server.exe.config.

2. Set <add key="ProxyURL" value="http://<Name or IP of the proxy

server>:<Port>"/>.

3. Set (if required) <add key="ProxyUserName" value=""/>.

4. Set (if required) <add key="ProxyPassword" value=""/>.

5. Save the file.

6. Restart the eyeShare Jira Server service.

Module General Settings

1. In eyeShare Studio, access Configuration Modules, and click New.

2. In the Module Selection window, select Jira.

3. Configure the Module’s general settings:

13

In the Name field, enter a meaningful name for the new Module (e.g., "Jira

Module").

In the Description field, enter a description of the new Module.

From the Device field, select the Device on which the Module is installed.

This is the device on which the “eyeShare Jira Server” service is installed

and not the device where the actual Jira is installed.

In the Port field, enter the port through which the Jira Module operates.

From the Monitor field, select the Module's monitoring option: select “Yes” if

you wish eyeShare Server to monitor the Module’s availability.

Click Configuration.

Server Settings

To configure the server settings of the Jira Module:

14

In the URL field, enter the Jira URL.

i. For a Jira instance that is installed on premise use this

template of URL: http://ServerName:8080/rest/api/latest/

ii. For a Jira instance that is installed on the Atlassian cloud use

this template of URL:

https://SiteName.atlassian.net/rest/api/latest/

In the User Name field, enter a Jira user that is a member of the jira-

administrators and Jira-developers groups.

In the Password field, enter the password of the selected user.

Click Test Connection. If the connection was tested successfully,

proceed to the next step - Projects. Otherwise, refer to the

Troubleshooting section and search for your error.

To update the projects list (in the Projects window) - add new projects or

update an existing project - click the Clear Cache button.

Projects

In the Projects window you may import Jira projects and define their Filters and

Mapping. New Jira issues are pulled to eyeShare according to the project list and

their defined filters. Issues of projects that do not appear in the list are not pulled.

15

To add a new project to the list, select it from the Projects field, and click Add:

After adding the required projects, click Update to update the Module settings.

Filters

In the Filters window you may determine which issues are forwarded from Jira to the

eyeShare server. You can create several filters, each containing a number of

conditions. The operator between two filters is “Or” and the operator within a filter

is “And”. To get all issues of a specific project do not create any filters.

Click Add to add a new filter and new filter categories, and then click Update:

16

If the filter refers to a property that was not set in the Jira issue (the property

is empty), the issue will not be pulled.

Mapping

In the Mapping window you may translate Jira properties into eyeShare variables

and objects. The window is divided into three sections: Fields, Severity, and State.

The following checkboxes are located at the bottom of the Mapping window:

17

When checked, every time an issue is updated the rule base is checked to find a

matching rule.

When checked, incoming alerts and tickets are processed but an eyeShare incident is

not created.

In case of a tag that holds a condition that matches the message properties,

the mapping window is ignored.

Fields

In this section you can translate Jira properties into eyeShare variables. Click

Optional Properties to add eyeShare properties to the list, or to remove them from

it. The Jira properties list is updated automatically according to the selected project.

18

Severity

In this section you can translate Jira severities into eyeShare severities. There are

two options for severity selection:

Static Severity: all issues of the specific project open an eyeShare incident with the

selected static severity.

Customized Severity: issues open an eyeShare incident according to the selected

project field and its values. The possible fields in this category are all fields in the

specific project which are of list type (drop down list/radio buttons).

19

An eyeShare severity can be mapped into several Jira severities. For example, if you

wish all Highest and High Jira issues to be opened as Critical incidents in eyeShare,

type in “Highest, High” in the Jira Severity field:

The manually typed in values must be valid (and must exist in the drop down

list). The values are case sensitive.

20

State

In this section you can translate Jira states into eyeShare states. There are two

options for state selection:

Static State: all issues of the specific project open an eyeShare incident with the

selected static state.

When using a static state, closing the issue in Jira does not close the eyeShare

incident, and vice versa.

Customized State: issues of the specific project open an eyeShare incident according

to the selected project field and its values. The possible fields in this category are all

fields in the specific project which are of list type (drop down list/radio buttons).

An eyeShare state can be mapped into several Jira statuses. For example, if you wish

all To Do and In Progress Jira issues to be opened as Down incidents in eyeShare,

type in “To Do,In Progress” in the Jira Severity field.

21

Variables usage

When the Jira Module is available, related variables are discovered in eyeShare and

can be used to define conditions or used by any activity.

Condition

To use Jira variables in a condition, in the condition window select the Variables

radio button, and then select the Jira Module’s name from the list.

From the Project field select the relevant project name to discover its fields:

22

All imported Jira variables will then appear in the Standard Object Type list:

You may either add or not add the project to the condition. If you choose to

add the project name, change the condition to “AND” type; only fields from the

specified project will match the condition.

23

Activity

To use Jira variables in an activity, click the Add Variable button ( ) in the activity

(or, alternatively, press Alt+V). From the Type field select the Jira Module’s name

from the list.

All imported Jira variables will then appear in the Name list:

24

Activities

To use the Jira activities, open the Workflow designer window from eyeShare Studio,

and expand the Jira category from the toolbox. Then drag the relevant activity to the

designer area.

To learn more about the eyeShare Workflow designer please refer to the eyeShare

Workflow User Guide.

Jira Create Issue

This activity creates a new issue in Jira. Click Optional Properties to add/remove

fields.

Output: The ID of the new issue.

25

Create Issue activity allows setting only one value to Label, Multiple Choice, Radio Button and Checkbox type properties. To add more values or remove them use the Update Issue activity.

26

Jira Get Issue

This activity gets a list of Jira issues according to the selected criteria.

(Click Add to add filters to the list, and click Edit to modify the existing filters).

Filters are applied (by the activity) to issues which contain values in the

specified field.

Output: a result set of all matching issues.

Jira Update Issue

This activity updates an existing issue in Jira. Click Optional Properties to

add/remove fields.

Output: Success/Failure.

27

If there are no existing issues in Jira for the selected Issue Type the module

will not be able to discover the issue’s properties. To resolve this problem,

manually create an issue for the selected issue type and clear module’s cache.

28

To set the value of Label, Multiple Choice, Radio Button and Checkbox type properties, select the required action from the Update Issue activity and change one value at a time:

29

To set the value of Select List Cascading type fields use the following format: Value1:Value1.1 (Value 1 is the value to the parent list and Value1.1 is the value to the child list.

30

Troubleshooting

Module is down

If the Module is down, open the Configuration window and click Test Connection.

If the test is successful - verify your license contains Jira in the Modules

section.

If the test fails - continue troubleshooting according to the next section.

The module is not pulling issues

If the module is in Up state but new issues are not pulled, verify the specific project

was added to the module configuration (Projects window) and that the defined filter

complies with your issues.

New issues from Jira do not create eyeShare incident

If new events are created in the eyeShare Active Log window, but new incidents are

not created in eyeShare Dashboard:

1. Verify all Jira fields required for the mapping (module Configuration

Mapping window) are sent with data from Jira, and are not sent empty (you

may verify that by opening the Jira log [C:\Program Files

(x86)\eyeShare\eyeShare Jira Server\Logs] and searching for the incoming

messages.

Test Connection failure

1. Error: “Could not connect to net.tcp://ServerName: 11047./ The connection

attempt lasted for a time span…” ( “ServerName” represents the device you

have listed in the General Settings window).

Explication and/or Solution: Jira Module is not installed on “ServerName”, or

service “eyeShare Jira” is not running. If the specified server is incorrect then

select the correct server where the component is installed. If the server name

is correct then start the service (or restart it if it is already started). If the

service does not exist install it on the selected server.

31

Create Issue, Update Issue, Get Issue

1. Error: An activity displays the error “Unable to communicate with Jira

Module”.

Explication and/or Solution: Jira Module is in Down status, check

troubleshooting step “Module is down”.

32

33

Configuration File

The following settings are available within the eyeShare Jira module configuration file - eyeShare Jira Server.exe.config, located in the directory of the eyeShare Jira Module executable, assigned to the Windows service eyeShare Jira Server.

{eyeShare Install Directory}\eyeShare Jira Server

The Default location is C:\Program Files\eyeShare\eyeShare Jira Server\eyeShare Jira Server.exe.config

In order for updates to take effect, restart the Module’s Windows Service.

Log settings

The following settings define the eyeShare Module logging:

<add key="LogLevel" value="1"/>

1. Default: value="1"

2. Defines the level of details captured and written to the module log file:

1 – Critical errors are written to the log file

2 - Critical and warning errors are written to the log file

3 – All log levels are written to the log file

<add key="LogsDirectory" value=""/>

Default: value=""

Defines the log file path. The default path is the one set during the installation.

<add key="LogFileName" value=""/>

Default: value=""

Defines the log file name. The default name is “eyeShare_Jira Server_DDMMYYYY.log”. For example: eyeShare Jira Server_17092015.log

<add key="LoggingDateFormat" value="MM/dd/yyyy HH:mm:ss"/>

Default: value="MM/dd/yyyy HH:mm:ss"

Defines the date and time format written to log file entries.

<add key="LogNumberOfDaysToPreserve" value="14"/>

Default: value="14"

Defines the number of days log files are kept prior to auto deletion.

34

Proxy Settings

The following settings define the proxy connectivity.

<add key="ProxyURL" value=""/>

Defines the URL to connect to ServiceNow via a proxy server.

<add key="ProxyUserName" value=""/>

Defines the user for the proxy server.

<add key="ProxyPassword" value=""/>

Defines the password for the proxy server user.

Tips

Recovery Workflow

If you want to trigger a Workflow when an issue is closed, select the relevant option

from the following list and perform following steps:

The closed issue complies with the original issue’s condition:

1. In eyeShare Studio, go to Rules, and open the relevant rule.

2. Add a recovery workflow to the row of the original condition.

For example: if the condition to execute a Workflow when getting an issue is

“Priority = High”, the Workflow in the Workflow field is executed when the

issue is opened, and the Workflow in the Recovery Workflow field is

executed when the issue is closed.

35

The closed issue does not comply with the original issue’s condition:

1. In eyeShare Studio, go to Rules, and open the relevant rule.

2. Create a new condition that complies with the closed issue.

3. Add a recovery workflow to the new condition.

For Example: if the condition to execute a Workflow when getting an issue is

“Status = New”, the Workflow in the Workflow field is executed when the

issue is opened; however, closed issues do not comply with this condition. In

this case, add another condition - “Status = Closed” and add a recovery

Workflow executed when the issue is closed.