Confluence Connector

Device42 Confluence Connector

This connector provides you with the ability to do the following tasks:

  • 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 add-on

Device42 add-on is the part of Atlassian Marketpace, so you can easily install it using UPM add-on search capability provided by Confluence from the box. However, if you have some specific environment that blocks Confluence from access to the internet – it is possible to install Device42 plugin manually. Please note that plugin requires stable connection between server hosting Confluence application and Device42 application to operate successfully.

Automatic installation

To install 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‘.

    See the 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:

  1. Download the latest version of add-on from link. If you don’t have internet connecton (i.e. you have the secured sandbox environment) you can download the jar file outside your network and bring it using the pin 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 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 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 and would be able to execute configuration actions

    confluence-connector-03.png

Set up Device42 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

The data from the Device42 instance is cached inside the internal Confluence database. To keep it updated you should synchronize it periodically.
To launch the synchronization immediately

  1. On the configuration information click ‘Update‘ button

  2. Confirmation dialog will appear. Press ‘Update Data‘ button inside that dialog

  3. Wait a couple of seconds until the server requests for the new data from the Device42 instance

  4. After the synchronization you will find the synchronization information 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: Confluence Device42 Connector uses the default Confluence Scheduler mechanizm. Instead of usage of Update Data / Setup Cron dialog you can use the Scheduled Jobs menu and Run Device42 Update job from that page. You can set up the cron schedule and the changes will be automaticaly reflected in the Device42 Configuration page. By default the job is scheduled to run on the midnight server time on the dayly basis.

confluence-connector-11.png


Configure space filters

Device42 Confluence Connector allows smart configuration of the macros and restrict the list of CIs availble on the macro edit screen. Also you can add the filters on the selection list for each CI like Device, Rack, PDU or Part.

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