Jira (self-hosted) Integration

Device42-Jira (Self-Hosted) Integration

Integration Prerequisites

To use the Device42-Jira integration, users must have:

– Device42 virtual appliance, running, properly configured, and populated with CIs (to sync to Jira)
– Jira instance [Server, self-hosted for this version], properly configured, with the Device42 plugin installed.

*If you are looking to integration Device42 with Jira Service Management and/or Jira Cloud, see the Device42-Jira Service Management/Cloud integration page.

Device42-Jira self-hosted Integration Feature Overview

The Device42-Jira integration offers users the following functionality:

• Synchronize select Device42 data with Jira, automatically (and/or manually)
• Attach configuration items synced from Device42 to Jira issues
• Search for Jira issues relating to a Device42 CI(s) and/or CI data
• Create custom fields and apply them to specific projects, create custom field sets, and populate custom fields using built-in stackable filters to create a customized set of Device42 CIs.
• Store filter templates for the fast future usage
• Automate common IT workflow with validators and conditional functions, based on the Device42 custom field values
• Automatically request the next free IP address on a subnet, and acquire it when an issue transitions

Installing the Device42 Jira add-on

The Device42 add-on is the part of Atlassian Marketplace, so you can easily install it using the UPM [Universal Plugin Manager]. The add-on’s search capability is provided by Jira from the Jira search box. However, if you have some specific environment that blocks Jira from access to the internet it is possible to install Device42 plugin manually. Please note that the plugin requires a stable connection between the server hosting your Jira application instance, and your Device42 application instance to operate properly.

It can also be downloaded from the Device42 Integrations Page:

https://www.device42.com/integrations/jira/

Automatic installation

To install the add-on:

1. Log in as a user with the ‘Jira System Administrators’ global permission.
2. From the Jira administration console, click the Add-ons. Select Find add-ons.
3. In the search field type ‘Device42’ and press ‘Enter’.See screenshot:
4. Click the ‘Install’ button
5. A confirmation message appears when the add-on is successfully installed. You can now manage the add-on from the user installed add-on list on the Manage add-ons page.

Manual installation

To install the add-on:

1. Download the latest version of add-on from the link. If you don’t have an internet connection available (i.e. a secured sandbox environment), you can download the JAR file on a network with internet access, and transfer it via an USB thumb drive or other external media.
2. Log in as a user with ‘Jira System Administrators’ global permission.
3. From the Jira administration console, click the Add-ons. Select Manage add-ons.
4. Click the Upload add-on link at the top right side of the page. The following dialog appears:
5. Enter the location of the JAR file (downloaded in step 1) to upload using the file browser or by specifying a network location by entering a URI.
6. Click Upload. A confirmation message appears when the add-on is successfully installed. You can now manage the add-on from the user installed add-on list on the Manage add-ons page.

Configure the Integration

To configure the Jira add-on:

1. Log in as a user with ‘Jira Administrators’ global permission.
2. From the Jira Administration Console, click ‘Add-ons’.
3. Select DEVICE42 CONNECTOR > Device42 Connection to open the configuration page.

   Keyboard shortcut: g + g + start typing Device42. You will see the configuration screen and would be able to execute configuration actions.
   

   Initially the configuration shows only links for the base configuration of the plugin:

   

Set up the Device42 connection

1. On the configuration page click Edit or follow the Configure link to setup
   connection to Device42 instance.The following page opens:
2. Enter the connection information
3. Click ‘Save’.
4. You will see the saved details on the configuration view screen

Manual Syncronization

The data from the Device42 instance is cached inside the internal Jira database. To ensure it is up-to-date, it should be periodically synchronized. To manually perform an immediate synchronization:

1. On the configuration information page, simply click the ‘Update Data’ button
2. A confirmation dialog will appear; Press the ‘Update Data’ button on that dialog to confirm.
3. The dialog will be closed and you will see current collection statistics data (for manual scan you will see the warning message that scan is pending to be started that is shown for about 15 seconds)
   
4. If you wish to stop current scan you can abort the scan. Click the ‘Abort’ button and confirm the abort. Please note, that the currently scanned Configuration Item list will be synchronized partially.
5. You will see current scan statistics on the main screen (it could be started manually or automatically). After the synchronization completed the warning message will disappear

Configure automatic synchronization

Automatic sync/updates are configured using regular Cron Expressions, which you are likely already familiar with.

Cron expression rules you can see here.

1. On the configuration information click ‘Setup Cron’ button
2. Enter the cron expression rule inside the cron configuration dialog
3. Click ‘Save’ button
4. You will see the saved details on the configuration view screen

Delete plugin data

If you wish to clear up the plugin data, you can use the ‘Delete plugin data’
functionality. There are two different options for plugin data cleanup for Jira. ‘Connection’ option remove connection settings, all filter data, scan results for the configuration items. The ‘All’ option will remove custom fields and their data additionally. To delete the plugin data:

1. Click the ‘Delete’ icon.
2. Select one of the option ‘Connection’ or ‘All’
3. In the opened dialog select the confirmation checkbox
4. Click the ‘Delete’ button

Device42 Custom Field & Filter usage

The Device42 Jira Connector provides one new Custom Field type in Jira, The “Device42 Custom Field” which works with Device42 configuration items.

To create a new custom field Device42 Custom Field:

1. Log in as a user with ‘Jira Administrators’ global permission.
2. From the Jira administration console, click the Issues. Select FIELDS > Custom Fields.

   [Keyboard shortcut: g + g + start typing custom fields.]
   

3. Click the “Add Custom Field” button, the following dialog will be displayed:By default, this dialog displays the Standard, or most common choices for custom fields. Click on the All or Advanced option in the left navigation to access to all custom fields.
4. In the list, look for Device42 Custom Field, or type Device42 in the top right search box and select the custom field:
5. Click Next.
6. Give it a name, a description. Click Next.
7. Associate the field to screens. Click Update.

Now your custom field is created. If you wish to change the context or other variables in your custom field, see Configuring a Custom Field. Please note that plugin supports creation of multiple Device42 custom fields on the same screen.

Configure filters

Device42 Jira Connector allows intelligent configuration of the custom fields and can restrict the list of CIs available on the custom field edit screen. You can also add filters to the selection list for each configuration item. It is also possible to configure filter templates that can be used to pre-set options for new filters. The filter templates section also allows one to edit the default filter that is applied to all projects by default, or after a filter reset for the project. Please note that *ANY CHANGES TO THE DEFAULT FILTER* will affect *ALL PROJECTS* that do not have their own custom filter configuration.

General filter details

1. General settingsIn general settings, you can select the list of configuration items that would be available for the selected custom field in the selected project. At least one option should be selected.
2. General filter capabilities

You can switch on and off any parameter. The parameter will be hidden in any view of the field. All the parameters can be enabled / disabled for the custom fields provided by the plugin. Device42 supports smart filtering using the QL language. Each CI filter settings contains the list of parameters of each CI that can be used for filtering. The values within different parameters are being combined using AND logic. The filter search is *not* case sensitive. The filter inclusion is checked according to the operation. For the multiple parameters (like tags) filter is being applied for each parameter in the list. For the CI parameters (like part model) filter is being applied to ID, and any searchable parameter within the CI representing the parameter.

For each parameter, the following rules can be applied:

a) You can enter the value and the CIs will be filtered by this value.

Example: ‘test”. Only the CIs that has in the specified parameter ‘test’ word would be displayed

b) You can enter set of values separating them by the comma ',' or ampersand '&'. The CIs would be filtered according to the AND logic.

Example: ‘hello, world‘. Only the CIs that contain the words ‘hello’ and ‘world’ inside the specified parameter would be displayed. CIs with the parameter ‘Hello world’ would be displayed, but CIs with the parameters ‘hello’ and ‘world’ would be skipped.

c) You can enter set of values separating them by the vertical bar '|'. The CIs would be filtered according to the OR logic.

Example: ‘hello| world‘. The CIs that contain the word ‘hello’ or the word ‘world’ inside the specified parameter would be displayed. The OR is not exclusive, so the CIs with the parameter ‘Hello world’ would be displayed, too.

d) You can change the sequence of operations using the parenthesis. '()'. The CIs would be filtered according to logic based on the result operation.

Example: ‘(1| 2), (3, (4 |5))‘. The CI can pass the filter if: 1) it contains 1 or 2 inside the specified parameter; 2) it contains 3 inside the parameter; 3) it contains 4 or 5 inside the specified parameter.

Project filters

1. Open Project Administration
2. Click Device42 Filters link on the bottom of the menu
3. Select the custom field you want to configure
4. If you wish load the filter preset clicking ‘Load from template’ link.
5. Change the filter configuration settings
6. Press the save button to store the settings
7. You will see success message on the top of the filter if the filter was saved

Note: if you haven’t selected any value in the general settings to display CIs inside the custom field, you will see an error message notifying you about that.

Reset project filter

1. Open Project Administration
2. Click Device42 Filters link on the bottom of the menu
3. Select the custom field you want to reset filter for
4. Press the ‘Reset’ button
5. You will see success message on the top of the filter if the filter was reset

Filter templates

Device42 has the possibility to manage the filter templates that could be used as the preset to start with filter management for the custom field. Filter templates functionality has the same possibility as the project filter except for the custom field selection. Instead of a selection of the custom field administrator able to create the new filter with the specified name, edit the existing filter or reset (delete) the named filter. Also, there is a possibility to manipulate with the default filter that would be used for the projects that do not contain own filter.

1. Log in as a user with ‘Jira Administrators’ global permission.
2. From the Jira administration console, click ‘Add-ons’ then select ‘Device42 Connector’ > ‘Device42 Filter Templates’
3. If you wish to create a new filter template from the ‘Filter Templates’ selection list select ‘**Create New…’ and type the new name in the appeared text box
4. If you wish to edit the existing filter template select the needed filter template from the ‘Filter Templates’ selection list
5. Edit the needed filter template and click ‘Save’ button or reset the filter template for deletion (the default filter will be cleared but not deleted).

Load from template

Project administrator can use the filter template functionality in any project filter. The filter template will be loaded instantly and will replace all the data in the filter screen. After the loading of the template project administrator can edit the filter in the normal way. The filter itself will not be saved until the project administrator clicks the ‘Save’ button.

1. Click the ‘Load from template’ link
2. Select the needed filter template in the list of filter templates appeared in the popup
3. Click the ‘Apply’ link

Using the Device42-Jira Plugin with Jira Issues

View issue

On view screens a Device42 Custom Field looks so:

You can see the list of CIs that are linked to the issue through custom field. For each of CI you can find the brief information and a link navigating you to the Device42 application CI representation. If some of the CIs were not found inside the Device42 system they will be marked as the deleted.

If you add the Device42 custom field to the issue navigator you would be able to see the brief information about CIs linked to the ticket with the ability to follow the link to the Device42 application. If you hover over the link you will see the detailed information on the device.

Create/Edit issue

On create/edit screens you can link Device42 CIs to the Jira issue. The field in the edit mode which looks like:

In the edit mode, you can select the preferred type of the CI and link the issue to one or more of the CIs according to the type selected. You can search for the specific data using the context search mechanism. If you want to delete the CI, simply click the cross icon on the right of each of the selected CIs. The list of CI types and the list of CIs inside each of the type are shown according to the Project Filter applied to the project and custom field. You will not be able to assign the CIs outside the filtered scope. If the filter was created after the issue was edited the data will be shown inside the view mode, however, if you edit the issue the CIs and CI types outside the filter scope will be removed.

For the large scope of CIs plugin uses ajax to request the data for the CI selection list, so the CIs are loaded by portions. It is possible to search the custom field by the term. The search scope is the display name of the CI. In the future, we plan to extend this functionality and use the smart search of data.

Device42 Custom Fields

Device42 Custom Field can be used to link the Configuration Item of the Device42 system to the Jira issue. You can have multiple independent Device42 custom fields inside one issue. You can link a set of Configuration Items to a particular issue using one custom field, but they should be of the same category (i.e. Devices only). You can apply a project filter for the list of the possible Configuration Items you want to see inside the specific project. Also, you can apply the filter to the each of the Configuration Items category (see Project Filters Configuration for details).

Search issues by Device42 Custom Fields

Device42 custom fields allow full-text search on the CI IDs and parameters. Almost all parameters are available for search, however, users cannot specify exact parameters to search. For example, if you search for the word ‘Device‘ you will find the issues with a custom field containing devices and custom fields with other CI types that contain the word ‘device’ in their name.

Simple search

1. Open the issue navigator. Select ‘Simple’ search mode
2. Click the ‘More’ selection list. Search for the custom field by name
3. Open the added custom field search filter
4. Add the search criteria in the text box under the filter
5. Click the ‘Update’ button. You will see the issues filtered by the custom field inside the issue navigator

Advanced search

1. Open the issue navigator. Select ‘Advanced’ search mode
2. Type the search request using JQL query language. Supported operators for the field: ‘~’, ‘!~’, ‘IS EMPTY’, ‘IS NOT EMPTY’.
   

   Example: D42 ~ “NH*”

3. Press ‘Enter’ … You will see the issues filtered by the custom field inside the issue navigator.

Jira Workflow automation

The Jira – Device42 connector plugin allows for the automation of business processes related to Device42 Entities. Current release allows to acquire the IP address in the selected Subnet automatically and configure the permission to show/follow the transition based on the content of the Device42 custom fields.

Post Function

The Device42 post function now have only option to acquire the IP address based on the selected network. The action is performed during the transition in the workflow, for example, when you move the ticket from one status to the other or create the ticket. The post function will gather information about the selected subnet from the Device42 custom field (the field can be selected inside the post function setup), will acquire the IP address from the Device42 instance. The notifications, error messages and IP address information will arrive inside the comments to the ticket.

Add post function to the workflow

To give your project the ability to request the next free IP address from Device42 automatically, do the following:

1. Edit the workflow that is used to manage the ticket life cycle for the
   specified issue type in the target project.

1. Inside the opened workflow for the edit mode click the transition you want to automate. If you don’t have the needed transition or your workflow is not configured the way you like, please follow the guides https://confluence.atlassian.com/adminjiraserver072/workingwithworkflows828787890.html and https://confluence.atlassian.com/adminjiraserver072/advancedworkflowconfiguration828787971.html

1. Inside the transition click the “Post Functions” tab and click “Add post function” link. That will open the list of post functions that can be added to the workflow.

1. Select the Device42 automation post function and click the “Add” button

1. Inside the edition mode for Device42 post function you can select the Device42 custom field that will have the information about the subnet, where the IP address should be acquired (source custom field, required).

1. It is required that the post function is processed in a specific position when configuring the transition. For regular transitions between two statuses, the POST function should be placed between “set issue status” default post function and “Update change history” default post function. By default, the Device42 post function arrives on the second place and nothing should be done.

1. When creating transitions, the behaviour is similar except there is another set of POST functions available. You can use a POST function in a workflow the same way you would any regular transition.

Post function usage

You can just follow the transition, fill the Device42 custom field if needed (inside the transition screen, if it was set up) and get the results of the IP address to acquire inside the comments and custom fields (if they are set up)

Condition / Validator functions

Device42’s Jira plugin has the possibility to validate the Device42 data inside the custom fields during the transition or check the custom field detains to indicate if the transition should be shown at all. Device42 custom fields could be checked on the amount of the CI stored, types of the CIs and values can be validated by the filter on the specific parameter criteria.

Condition specific setup

For the detailed information on condition setup please refer to the https://confluence.atlassian.com/adminjiraserver073/advancedworkflowconfiguration861253591.html#Advancedworkflowconfigurationconditions section

1. Edit the workflow as described in sections 1 and 2 for the post functions
2. Select the “Conditions” configuration tab and click the “Add Condition”
   button to add the new condition

1. Select the Device42 condition inside the radio button list and click “Add” button

1. Follow the generic setup section to configure the condition

Validator specific setup

For the detailed information on validator setup please refer to the https://confluence.atlassian.com/adminjiraserver073/advancedworkflowconfiguration861253591.html#Advancedworkflowconfigurationvalidators

1. Edit the workflow as described in sections 1 and 2 for the post functions
2. Select the “Validators” configuration tab and click the “Add Validator”
   button to add the new validator

1. Select the Device42 validator inside the radio button list and click “Add”
   button

1. Follow the generic setup section to configure the validator

Condition / Validator Generic Setting

The Device42 Custom Field validator and condition have essentially the same setup parameters and usage possibilities. The main/only difference is that the condition function will show or hide the transition link depending on the state of custom fields set up inside the condition configuration, while the validation function will check the states of the custom fields during the transition itself. Unlike the condition, the validator will show a user-specified error message (related to the specific custom field) during the transition, and as mentioned, this is configurable. The error message, when displayed, is also duplicated on the top of the transition screen.

The configuration screens for validation and condition are similar as well. You may freely add sets of validators (with “and” logic) and sets of conditions (with “or” or “and” logic depending on the condition setup).

Inside the validation configuration, an administrator can set up the validation for Configuration Items count, CI types, and can also add a filtering check against the configuration item’s parameters. You can also set up live validation that will update the selected configuration items cache with the latest data [a real-time call will be made to Device42 to live-validate the data, ignoring the cached data stored in the Jira DB]. For validation, an administrator can configure both the error message and can choose which custom field should be validated.

Advanced Validation Scenarios

It is possible to set up advanced scenarios where beyond validating the custom field itself, an administrator can select aggregation options such as “Any” (so if any Device42 custom field that exists in the system is validated, the transition will be validated), “All” (so all Device42 custom field existing in system should be validated to pass the transition), “None” (none of the Device42 custom fields should be validated; if any field is validated the validation fails).
For the validator, it is possible to add a custom error message that will be displayed when a user fails the workflow validation. The error message should contain clear instructions on how to fulfil the custom field’s validation criteria and should notify the user that a mistake was made. If an administrator leaves the message field empty, the default message will be generated. The administrator also has the ability to configure the live check for the CI details to be validated.

If this option is selected, for the CIs that supports the update by the CI id the data for the CIs stored in the custom field will be instantly retrieved from the Device42 instance and validated against, disregarding the cached value in the Jira DB. All the validation options follow “AND” logic between the sections. That means that the custom field should follow the amount criteria, type criteria, and filter value criteria to pass the validation.

Quantity Validation:

Exact Value, less than or Equals, Greater than or equals

The ‘amount’ validation option allows an administrator to limit the amount of CIs selected inside the custom field.

• The default option is “Any”, which switches off this validation criteria.
• Exact value means that to meet the validation criteria, the custom field in the ticket should contain the exact amount of CIs specified. The amount of configuration items can be set up inside the validation configuration in the field right to the amount selection.
• Equals or less means to pass the validation, the custom field in the ticket should not contain any more CIs than the number specified in the configuration. Zero CI is *not* allowed by this validation. Please note, if any other validation set up zero items, validation will not succeed.
• Equals or more means that to pass validation, the custom field in the ticket should not contain less configuration items than the amount specified in configuration.

The type validation option allows the administrator to limit the types of CIs that can be selected inside the specified custom field. It is possible to add multiple CI types. When multiple types are added, if Configuration Items with any of selected type is added to the custom field, the validation will succeed. If no types are added, this section will be ignored.

The value validation option is the most flexible one for the validation configuration. You can add one or more sets of validation options to pass or fail validation according to the values contained inside the Configuration Item parameters selected inside the custom field. You can freely add, remove or modify the rows inside this section. Each row can contain sets of configuration controls that allow the addition of validation criteria. If no rows are added, this section will be ignored during the validation. If there are multiple Configuration Items inside the custom field the validation will be passed if at least one configuration item inside the custom field passes the validation.

Each value validation row can be added to one of the subsets: “Or” or “And” subset. Those subsets would be checked separately. For “And” subset the validation will be passed when all “And” rows are successfully validated for the checked custom field. For “Or” subset the validation will be passed when any of row will be successfully validated for the checked custom field.

An administrator can specify the CI type the filter will be applied to. If the CI type in the custom field is not correct, the value of the filter validation row will be ignored (only the Configuration items of CI type specified in the filter will be checked. Any other will be ignored). If different CI types are added to the ‘And’ qualifier, only the rows containing appropriate CI types will be applied and checked through validation. If you select any qualifier, the row will be validated for any value in the custom field, disregarding the type, but you will not be able to select the parameter type.

If you selected the CI type for the validation it is possible to specify the parameter to be validated. If the ‘Any’ option is selected, the validation will be checked for all the parameters inside the configuration item. If there is a parameter that passes validation, the validation will be passed for this criterion.

Validation Types

There are 4 validation types that can be used for the validation of specific
parameter:

1. ‘Not Empty’* the parameter value should exist inside the Configuration Item. Addition value is not used.
2. ’Exact Value’ the parameter value should exactly equal the value specified inside the row in the configuration.
3. ’Contains the parameter’ value should contain the value specified inside the row in the configuration. The value supports the filter operators and sequences (so you can use the same language you use for the project filters, i.e. “(1|2),3” means that the configuration item parameter should contain “3” inside the text of parameter and additionally should contain “1” or “2” inside the text. For any parameter, all parameters will be checked and validation will pass if any parameter accepting the criteria found.
4. ’Not Contains the parameter’ should not contain the value specified inside the row in the configuration. The possibilities for the value are the same as described in contains section.

For the exact value, contains, and not contains validation options, you can select the value. The not empty will hide the option to enter the value:

When the “Add” button is pressed, a validator/condition will be added. The description will contain a short description explaining how the validation will be evaluated. You may edit the validator/condition while your workflow is in ‘edit mode’. To apply the validator/condition to the existing workflow and to real tickets, you must publish it. The example above proposes the validation criteria (inside validator) for the post function that acquires the IP address (with the addition of the filter criteria that the subnet name should contain the letter ‘a’).

Condition / validator usage

When the workflow is published, the validator/condition will start to work. As an example, the following workflow has to do and Done statuses, and during the transition, it will acquire an available IP address; this workflow will ask for the subnet to be specified during the transition, as well. The custom field dtptest1 is used on the view screen, and the transition contains the settings to prompt with the “Acquire IP” screen. The acquire IP screen contains only the dtptest1 custom field.

When a user enters the wrong data into the custom field the validator will fail the transition and indicate the error on the bottom to the custom field with duplication on the top.

When a user enters the proper data the transition will pass, and either the new IP address will be acquired via the post function or the error information will be inserted into the comment/text custom field linked to the post function.

Jira Applications support

Jira Software support

You can use Device42 Custom Fields on Jira Software boards.

1. If you do not have a Jira Software board you can create the new one

1. You can configure the created or the existing board to add the Device42
   Custom Fields to the Jira Software screens

1. Inside the Board Configuration screen you can add Device42 Custom Fields to
   the Backlog card view, Sprint card view (see Card Layout) or to the Issue Details View (see Issue
   Detail View)

1. As the result you will be able to see the Device42 fields inside the Jira Software board

Jira Customer Portal support

You can use Device42 Custom Fields inside Jira Service Management customer portal.

1. For the Service Management Portal you want to add Custom Fields to open Service Management Project administration. Open Request Types section. Open Edit Fields link for the needed ticket.
2. Press “Add Field” button. Select the needed Device42 Custom Fields and press Apply button.
3. Your customers will be able to use the Device42 Custom Fields when they are creating the tickets inside the customer portal

Downloading the Device42 – Atlassian Jira CMDB Connector

The addon can be downloaded via the link found on this page @ device42.com as follows:

https://www.device42.com/integrations/jira/

…or click here to download @ Atlassian Marketplace (or copy and paste URL below):

https://marketplace.atlassian.com/plugins/com.device42.atlas.jira.d42jira/server/overview