Creating an integration for Jira assets using the Jira Server plugin

Use the Jira server plugin to access and manage Oomnitza asset records directly within a Jira Server ticket. There's no need to leave Jira to view or modify assets.

Key features of the Oomnitza integration for desk agents include:

• Immediate visibility of assets linked to the ticket reporter.
• Link assets effortlessly to any Jira ticket.
• Edit asset details right within Jira Server.
• Customize asset information fields in Jira Server to meet your requirements.

Navigation

Installing the Oomnitza plugin

Configuring the Oomnitza plugin

Using the integration

Disabling the plugin

Integration security

Installing the Oomnitza plugin

To install the free Oomnitza plugin in Jira complete the following steps:

Navigate to the App page

1. Log in to Jira Server as an administrator.
2. From the top navigation bar in your application, choose Settings.
3. Select Manage Apps.

Search for the Oomnitza app

1. From the Find new apps sidebar, search for Oomnitza for Jira Server.
2. Follow the on-screen instructions to install the app.

Configuring the Oomnitza plugin

Without leaving the Manage Apps menu, select Oomnitza Integration Setup in the sidebar.

Complete the following steps to configure the plugin:

1. Provide your Oomnitza System Name and your Oomnitza API access token. For further information, refer to Creating an API token. The API token must be associated with a user with Configuration > Write permissions.
2. Click Connect.
   
3. Select Activate integration.
4. Choose the appropriate asset-to-ticket mappings. It's suggested to map the Jira Reporter field to the Oomnitza Assigned To field. This links the asset to the ticket in Jira.
5. Click Next.
   
6. Choose the Jira project(s) for the integration.
7. Decide which field to show in the Oomnitza data panel header.
8. Enable or disable the display of each asset’s image in the data panel.
9. Select the specific fields to show in the Oomnitza data panel. It's recommended to display the Assigned To field. Ensure this and other fields are editable if you intend to update them from Jira.
10. Click Save. Your integration is now active.
    

Using the Integration

The Oomnitza Jira server and data centre plugin for Jira assets provides you with the ability to:

• View all assets tied to the issue reporter
• Link specific assets to a Jira ticket
• Edit assets from within Jira Server

View all assets tied to the issue reporter

Go to a ticket in Jira. 

If you have an active Oomnitza session open in your browser, you'll be automatically logged in. Otherwise, click Log in.

The list of Oomnitza assets associated with the incident reporter is displayed in the Oomnitza Data Panel on the right.

You can use the search to filter assets assigned to the user. 

Link specific assets to a Jira ticket

1. From the Oomnitza Data Panel, select the dropdown
2. Search for the asset you wish to link to the ticket.
3. Click Apply. 
4. Update the Assigned to value to match the Reporter.
5. Go back to the Data Panel. The asset will now be linked.

Edit assets from within Jira Server

Prerequisites: To update an Oomnitza field in Jira, it must be set as editable. Check this in Oomnitza by navigating to Configuration > Data model > Assets and choosing the field. For more details, see  Creating Custom Fields in Oomnitza.

From the Oomnitza Data Panel, select the asset you wish to change.

• In the Oomnitza Data Panel, pick the asset you want to edit.
• For text fields, enter the new data and click outside the textbox to save.
• For dropdowns, scroll and pick the desired value.

Your changes will be reflected in both Jira and Oomnitza.

Disabling or uninstalling the plugin

To disable the Oomnitza plugin in Jira, complete the following steps:

1. Log in to Jira as an administrator.
2. From the top navigation bar in your application, choose Settings.
3. Select Manage Apps.
4. Find the Oomnitza integration, and click Disable or Uninstall. 

Jira Server Integration Security

Oomnitza uses several mechanisms for protecting integrations with external systems. The mechanisms allow Oomnitza to protect customer data from unauthorized access and from malicious or accidental changes.

Authentication

The Oomnitza Jira plugin authenticates using an API access token (integration secret) that's generated in Oomnitza.

To create an Oomnitza API token, navigate to Configuration > Security > API tokens. Ensure you have permission to read, create, and revoke these tokens.

When assigning the token, ensure it's given to a user with Configuration > Write permissions, whether that's you or someone else.

Jira Server user authentication

To work with the plugin window the Jira Server user has to have an authenticated session. To have this authenticated session, the Jira Server user has to provide the correct credentials in the plugin window.

After authentication, Oomnitza creates and supports a standard user session.

The session time is restricted according to Oomnitza instance session configuration.

The plugin receives and stores the browser storage authorization headers: Cookie and Oomnitza-session.

Authorization

After the plugin installation, the Jira Server admin goes to the add-ons setup page.

If Jira Server admin configures the plugin or mappings, the plugin checks that the Jira Server user role is an admin.

The Jira Server admin has to enter an integration secret (access token) and provide your Oomnitza instance system name on the Oomnitza integration setup page.

The API access token is embedded in API calls and allows for editing and viewing mappings in Oomnitza.

The authenticated Oomnitza Jira Plugin has the same level of permissions as the corresponding Oomnitza user and sends authorization headers with each request.

The plugin does not update the information in Jira Server, only in Oomnitza.

Connections

There is no direct connection between the plugin window and Oomnitza except for authentication. Jira Server retransfers all requests from plugin window to the corresponding Oomnitza instance.

Jira Server ComponentAccessor is used by plugin window to receive tickets IDs and Oomnitza’s system name.

In addition, Jira Server ComponentAccessor is used by the plugin window to convert Jira user IDs into user emails to log in to Oomnitza.

The Plugin communicates with Jira via ComponentAccessor to read fields and comments for Jira tickets. This connection allows for seamless integration between user tickets and assets.

In other words, this connection allows the Plugin to send comments and fields from Jira to Oomnitza if the corresponding mappings are configured in Jira.

The following table describes protocols used to host communication between Jira, Oomnitza, and Oomnitza Jira Plugin: 

Direction	Protocol	Authentication
Jira Server to Oomnitza	*443: HTTPS POST/PUT/DELETE/GET  requests	API access token
Oomnitza Jira Plugin to Oomnitza via Jira Server	*443: HTTPS POST/GET  requests	Cookie and Oomnitza-session

* The Oomnitza application has security built into its design. Connections between the Oomnitza application, Oomnitza Jira Plugin and Jira Server take place only over Secure Sockets Layer (SSL) using the latest version of Transport Layer Security (TLS) the operating system is capable of using.