Confluence Integration

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:

    confluence-connector-01.png

  4. Click the ‘Install‘ button

    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 manually:

  1. Download the latest version of add-on from our github link, 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.

    confluence-connector-02.png

  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:

    confluence-connector-03.png

Setting up the Device42 – Confluence connection

  1. On the configuration page click Edit to setup connection to Device42 instance.

    The following page opens.

    confluence-connector-04.png

  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:

    confluence-connector-05.png
    confluence-connector-06.png
    confluence-connector-07.png


Set up automatic synchronization

You can set up the automatic update using the Cron Expressions

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

    confluence-connector-08.png

    confluence-connector-09.png

  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.

confluence-connector-11.png


Configuring Confluence space filters

The Device42 – Confluence connector allows “smart” configuration of macros and can restrict the list of CIs available on the macro edit screen. You may also add filters to the selection list for each CI: e.g. Devices, Racks, PDUs, or Parts.

In the current version Device filter parameter search is case-insensitive, the tag search is case-insensitive too. For Racks, PDUs, Parts the search is case-sensitive, the tag search doesn’t work yet.

Filter details

  1. General settings

    In general settings you can select the list of configuration items that would be available for the selected space. Devices, Racks, PDUs and Parts are available. At least one option should be selected.

    confluence-connector-12.png

  2. Devices

    You can filter the Devices configuration items by Device Type, Service Level and Customer. The filter is case-insensitive. Filter searches for the exact match.

    You can filter the Devices by Tags. There are two search options: OR search which will check that Device contains at least one tag from the list (Tags option) and AND search which will check that Device contains all the tags from the list (All Tags option). Tags are comma separated.

    confluence-connector-13.png

  3. Racks

    You can filter the Racks configuration items by Room and Building. The filter is case-sensitive. Filter searches for the exact match.

    The tags option for the Racks is not implemented yet. The functionality is planned similar as Devices.

    confluence-connector-14.png

  4. PDUs

    You can filter the PDUs configuration items by Model Name. The filter is case-sensitive. Filter searches for the exact match.

    The tags option for the PDUs is not implemented yet. The functionality is planned similar as Devices.

    confluence-connector-15.png

  5. Parts

    You can filter the Parts configuration items by Part Model Type. The filter is case-sensitive. Filter searches for the exact match.

    The tags option for the Parts is not implemented yet. The functionality is planned similar as Devices.

    confluence-connector-16.png

Set up space filter

  1. To access the filters you should use space administration menu. Depending on the Theme it can be under Space Admininstration inside the Browse section or inside the Space Operations section.

    Documentation-like themes:

    confluence-connector-18.png

    confluence-connector-19.png

    Non-documentation themes:

    confluence-connector-20.png

  2. Change the filter configuration settings

    confluence-connector-21.png

  3. Press the save button to store the settings

  4. 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 space – you will see the error message notifying you about that.

Reset spacefilter

  1. To access the filters you should use space administration menu. Depending on the Theme it can be under Space Admininstration inside the Browse section or inside the Space Operations section.

    confluence-connector-22.png

  2. Press the ‘Reset‘ button

  3. You will see success message on the top of the filter if the filter was reset


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

    confluence-connector-23.png

  2. Open External Content, you can find 3 Device42 macros. If you have too many macros – you can search for device42 using search field.

    confluence-connector-24.png

  3. Select Link or Details macro. Select the needed CI category, select one or more CIs. You can preview macro using preview button.

    confluence-connector-25.png

  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.

    confluence-connector-26.png

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

confluence-connector-27.png

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.

confluence-connector-28.png

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.

confluence-connector-29.png

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

confluence-connector-30.png

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

confluence-connector-31.png

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

confluence-connector-32.png