Atlassian Confluence – Device42 Integration

This integration connects Device42 to your Atlassian Confluence instance with the following features:

• Display details of particular Device42 object (devices, racks, PDUs and parts are supported).
• Display inline link to particular Device42 object (devices, racks, PDUs and parts are supported).
• Display table of Device42 objects.
• Synchronize Device42 data with Confluence manually or periodically.
• Filter set of Device42 CIs to display inside macros for specific space.

Installing the Confluence integration add-on

Device42’s Atlassian Confluence add-on (aka “Device42 CMDB Connector for Confluence”) can be found in the Atlassian Marketplace. You can easily install it using the UPM (Universal Plugin Manager) built in to Confluence. However, if you have some special requirements (e.g. an environment that blocks Confluence from access to the internet), it is possible to install the Device42 Confluence integration plugin manually. Please note that the plugin requires a stable connection between the servers hosting your Confluence application and that which is hosting Device42 for successful operation.

Automatic installation

Installing the add-on:

1. Log in as a user with ‘Confluence System Administrators‘ global permission.
2. From the Confluence administration console, int the Atlassian marketplace section select Find add-ons menu.
3. In the search field type ‘Device42‘ and press ‘Enter‘.You should see the following screen:
4. Click the ‘Install‘ buttonA 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 manually:

1. Download the latest version of add-on from our github, or download from the Atlassian Marketplace: Device42 CMDB Connector for Confluence. If you don’t have internet connecton (i.e. you have the secured sandbox environment) you can download the .jar file from a computer outside your network, and bring it using a thumb drive.
2. Log in as a user with ‘Confluence System Administrators‘ global permission.
3. From the Confluence 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 (from step 1) to upload using the file chooser or by specifying a network location by entering a URL.
6. Click Upload.A confirmation message will appear when the add-on has been successfully installed.

You can now manage the add-on from the add-on list (“user-installed add-ons”), found on the Manage add-ons page.

Configuring the Device42 Confluence add-on

To configure the add-on:

1. Log in as a user with ‘Confluence Administrators‘ global permission.
2. From the Confluence administration console, Select DEVICE42 CONNECTOR > Device42 Connection to open the configuration page.
   

   Keyboard shortcut : g + g + start typing Device42.

   You will see the configuration screen:

   

Setting up the Device42 – Confluence connection

1. On the configuration page click Edit 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

Synchronize manually

Data from your Device42 instance is cached inside the internal Confluence database. To keep your data updated, you should run a sync periodically. You can do this automatically or manually.

To launch an immediate synchronization:

1. On the configuration information page, click the ‘Update‘ button
2. A confirmation dialog will appear. Press the ‘Update Data‘ button inside that dialog
3. Wait a couple of seconds until the server requests the new data from Device42
4. After the synchronization has completed, you will see the following on the synchronization info screen:
   
   

Set up automatic synchronization

You can set up the automatic update using the Cron Expressions.

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

Note: The Device42 Confluence Connector integration uses the default Confluence Scheduler mechanism. Instead of using the “Update Data” dialog or the “Setup Cron” dialog, you can instead use the Scheduled Jobs menu to run Device42 Update jobs directly from that page. You may also set up a cron schedule if desired, and those changes will be automatically reflected on the Device42 Configuration page. By default, the job is scheduled to run on the midnight server time on the daily basis.

Configuring Confluence Space Filters

Filter Settings

Each Confluence space can have a space filter configured. There can be multiple filters configured for one or multiple CI types. If you’re configuring multiple filters for one CI type, you can then use these filters separately by adding multiple table macros to the space and selecting each “Space filter” you have created to be able to filter that CIs on multiple values/categories.

Note: Pagination is not yet available for the table macro, if you need to view more than the default 50 results in the table, you can change this value on the Device42 plugin connection screen and set the “Dropdown Limit” to a higher value like 100 or 150. Don’t set this value too high as this will might cause significant delays in drop down displays for the plugin:

1. The filter settings are accessed from the “Space Tools” menu at the bottom left corner:

2. On the settings page you can configure any CI or multiple CIs using one interface. Note that if you configure the “Device” CI and the “Parts” CI for example, the filter will be applied only to the CI you have selected in your Table Macro drop down:

3. Let’s configure a space filter to show Software with a name of “.NET”:

4. Don’t leave this screen until you get the green confirmation prompt confirming your filter has been saved. This is required so the plugin has the time necessary to process the filtering of the database items stored in your Confluence database.

5. Once the filter has been saved, you can go back to the space with your table macro and apply it to the CI you have created the filter for, save the space and view the results:

Filter Templates

Filter templates allow a user to configure a global filter template which can then be used in any specific Confluence space with predefined CIs and values for each of the CI’s fields.

This can be useful when you need to define a preconfigured template that you use in multiple CI space filters instead of having to create a separate one for each space.

1. Access the Filter Templates by clicking on the Device42 Filter Templates link from the Device42 Connector menu found on the left hand side of Confluence’s main menu.

2. A settings page will open with the following items:

3. Above, a new template filter can be created by clicking on the Filter templates drop down and selecting “Create new…” menu item and entering a name of your choice like “parts_fan” above for example.

4. After this, select the CIs you want to be selectable from the “General settings” tab (in most cases you want to leave the default settings).

5. The CI tabs at the top allow you to select and configure the CI filtering you need:

6. Here we will configure the “Parts” CI to show only the “fan” type items:

7. The search is case insensitive and of contains type, meaning any values specified here will be checked against all database entries matching the CI’s type and containing these values.

8. Don’t forget to click “Save” at the bottom, if the button is grayed out after you have entered a value, make sure you click out of the text box and then click the “Save” button.

9. You can also “Reset” the custom filter you’ve created by clicking the “Reset” button. Note: This will also delete your custom filter entry. This doesn’t apply to the “default” filter.

10. Once this is done, these filter templates will be available in the Space Device42 filter settings drop down:

By loading the template filter, you pass in the values saved in the filter template into your specific space instance filter which can then be further modified.

Configuring Space Restrictions

The Device42 Confluence Connector allows you to specify which spaces the Device42 macros can be used with.

Configure Space Restrictions

• Log in as a user with Confluence Administrators global permission.

• From the Confluence administration console, select DEVICE42 CONNECTOR > Device42 Restrict.

• Turn space restrictions on.

• In the Allowed spaces field, select all spaces where you want to allow the Device42 macros to be used.

• Click Save.

• Now if you go to a space where Device42 macros are not allowed based on the space restrictions, you will get an access denied message if you try to use one of the Device42 macros.

• In addition, if Device42 macros were allowed for the space and had been used on the page, and then the space did not allow Device42 macros, then the data that those macros returned would not be displayed on the page.

Using Device42 Macros

You can add information about Device42 Configuration Items inside your Confluence pages using Macros. Device42 Confluence connector provides 3 different Macros to achieve that goal: Details Macro, Link macro and Table macro. You can apply space filter for the list of the possible Configuration Items you want to see inside the specific space. Also you can apply the filter to the each of the Configuration Items category (see Space Filters Configuration for details).

Objects macros

You can add information about one or set of the specific Configuration Items into your page using Device42 Details macro and Details42 Link macro. They have the similar configuration but different view functionality: for Device42 Details macro you can see the table of the CI parameters, the view macro contains the link only, but shows the additional information when you hover over that link.

Edit Device42 Object Macros

1. To add the macro on the page select insert other macros from the top menu
2. Open External Content, you can find 3 Device42 macros. If you have too many macros – you can search for device42 using search field.
3. Select Link or Details macro. Select the needed CI category, select one or more CIs. You can preview macro using preview button.
4. Press the insert button to add the macro on page. Please note, that in edit mode the macro is not rendered, but you will be able to see the name of the macro, one letter for category and set of numbers for CI ids.

View Device42 Details Macro

The details macro shows the information regarding the CIs in the table. For the set of CIs you will see additional table for each of CIs. You can follow the link to access the CI inside the Device42 application

View Device42 Link Macro

The link macro shows the short link to the Device42 application for the selected CI. For the set of CIs you will see set of links one for each row. You can follow the link to access the CI inside the Device42 application. If you hover over the link – you will see the detailed information about the linked CI inside the Confluence page.

Search Macro

Unlike the objects macro that links to the specific CIs inside the Device42 application the search macro shows the items according to search criteria.

Device42 Table Macro

The table macro allows you to see the table of the CIs of the selected type with the application of space filter and in-macro search criterias.

In the current version in-macro search works for Devices only. For the other CI Types the Space Filter parameters would be applied.

When you select Table Macro in the edit mode you can select the needed CI type as the macro parameter. Optionally you can select name of the search criteria and value. There are 2 sets of fields that allow to have the “and-search” for the specific items. The following parameters are supported:

• type
• service_level
• in_service
• rack
• room
• building

You should type the exact naming for the parameter inside Filter parameters. Inside the value parameters you should type the prefered value of the specified parameter. If there are no CIs that apply your criteria (with the addition of the space filter) you will see no results for the table.

If you add wrong parameter you will see the error message instead of rendering of the table.

In the edit mode the macro is not rendered, but you can see the selected CI type info and specified filter parameters.

In the view mode you will be able to see the table with the filtered CIs