Zum Hauptinhalt springen

Installation Manual

Table of Contents

1. Overview

This document describes the installation of the ADONIS Process Manager/ADOIT Enterprise Architect for Confluence apps for Atlassian Confluence as well as the setup and configuration for connecting them to an ADONIS and/or ADOIT Enterprise installation or an ADONIS and/or ADOIT Community Edition account.

The ADONIS Process Manager/ADOIT Enterprise Architect for Confluence apps can be obtained from Installation packages containing OBR files for upload to Confluence, or via a download from the Atlassian Marketplace (ADONIS Process Manager / ADOIT Enterprise Architect).

1.1. Installation

The installation consists of the following main steps:

Enterprise Edition :

  1. Configuration and preparation of ADONIS and/or ADOIT.
  2. Installation of the ADONIS Process Manager/ADOIT Enterprise Architect for Confluence app in Atlassian Confluence using the provided OBR files, or via download from the Atlassian Marketplace (https://marketplace.atlassian.com/).
  3. Configuration of the REST connection from ADONIS Process Manager/ADOIT Enterprise Architect for Confluence to ADONIS and/or ADOIT.

Community Edition :

  1. Installation of the ADONIS Process Manager/ADOIT Enterprise Architect for Confluence app in Atlassian Confluence using the provided OBR files, or via download from the Atlassian Marketplace (https://marketplace.atlassian.com/).
  2. Connection of the ADONIS Process Manager/ADOIT Enterprise Architect for Confluence with an ADONIS:CE/ADOIT:CE account

1.2. Where to get ADONIS Process Manager/ADOIT Enterprise Architect for Confluence

1.2.1. Installation package:

The installation package contains the following items:

  • confluence : this folder contains the ADONIS Process Manager/ADOIT Enterprise Architect for Confluence apps for Atlassian Confluence.

Figure 1: The installation package

(Note that the actual names of the OBR files might differ from the image above)

1.2.2. Marketplace:

The ADONIS Process Manager/ADOIT Enterprise Architect for Confluence apps can be found in the Atlassian Marketplace and from there downloaded and installed directly to your Confluence instance.

Figure 2: Atlassian Marketplace: ADONIS Process Manager for Confluence

Figure 3: Atlassian Marketplace: ADOIT Enterprise Architect for Confluence

2. Enterprise Edition: Configuration of ADONIS/ADOIT

Hinweis

In order to use ADONIS Process Manager/ADOIT Enterprise Architect for Confluence with your ADONIS/ADOIT Enterprise Edition, the Standard RESTful services module must be licensed and enabled!

  1. Open the Administration Toolkit.

  2. Go to the Library Management component and then to the Component Settings tab.

  3. Go to Standard RESTful services -> General.

    • Enable MFB REST globally.
    • In the Tokens tab configure the Settings of the local REST security context by adding a Key and generating a Secret (this can be done automatically by the Generate Secret button).
    • In the Technical user setting, select a technical user for the REST context. Available technical users are displayed in the table. If no user is available, go to User Management and create a technical user (this user must have Trusted Login ). You can assign one or more repository to the chosen technical user and therefore selecting what content should be available within REST.
      NOTE: All content that the technical user has access to, will also be available via the ADONIS Process Manager/ADOIT Enterprise Architect macros in Confluence for all Confluence users.
      For further information, please see chapter Enterprise Edition: Restricting access to ADONIS/ADOIT content.
    • The following REST Scenarios must be enabled for ADONIS Process Manager/ADOIT Enterprise Architect for Confluence to work:
      • Repository read APIs
      • Repository search APIs
      • Metamodel read APIs
    • [Optional] In the Cache Path setting, setup an absolute path on the webserver machine, accessible by ADONIS/ADOIT, where REST cache can be saved. The path should be dedicated to this purpose and not shared with other services. ADONIS/ADOIT will take care of managing it. Doing so will improve the response time for REST.
      Please note: if it is a SaaS ADONIS/ADOIT environment hosted by BOC Group then the Cache Path setting change must be requested from the Key Account Manager.
    • For the Enable Validator setting, the recommendation for ADONIS Process Manager/ADOIT Enterprise Architect for Confluence is to keep it disabled as enabling this parameter may slow down the execution of requests and cause high memory consumption and CPU usage on the web server.
    • Enable HATEOAS links setting has to be enabled for ADONIS Process Manager/ADOIT Enterprise Architect for Confluence, since it is used for links rendering.

Figure 4: Standard RESTful services settings

Figure 5: REST scenarios to enable

  1. Go to Web Client -> System page.
  • Configure the Base URL to match the web client URL.
  • In Technical Users , select the same technical user from the previous step.

Figure 6: Web Client System settings

3. Installation of the ADONIS Process Manager/ADOIT Enterprise Architect for Confluence app in Atlassian Confluence

This chapter describes the steps to install the ADONIS Process Manager/ADOIT Enterprise Architect for Confluence apps in Atlassian Confluence.

3.1. Installation with an Installation package

Before installing the app, make sure that the distribution file from the installation package 'adonis_process_manager_for_confluence.obr' / 'adoit_enterprise_architect_for_confluence.obr' is accessible from your computer, either via the file system or via an URL.

Steps to manually upload the ADONIS Process Manager/ADOIT Enterprise Architect for Confluence apps in Confluence :

  1. From the General configuration page of the Confluence administration, click Manage apps in the left sidebar.
  2. Click the Upload app link at the top right side of the page. The following dialog appears:

Figure 7: Upload an app in Confluence

  1. Enter the location of the JAR or OBR file to upload using the file chooser or by specifying a network location by entering a URL. In this case you want to select the 'adonis_process_manager_for_confluence.obr' / 'adoit_enterprise_architect_for_confluence.obr' file.
  2. Click Upload.

A confirmation message appears when the app is successfully installed.

  1. If prompted, restart your application to have your change take effect.

You can now manage the app from the user-installed app list on the Manage apps page.

The ADONIS Process Manager/ADOIT Enterprise Architect for Confluence configuration page can be reached from the Admin Configuration or by the Manage apps page.

3.2. Installation via the Atlassian Marketplace

  1. From the General configuration page of the Confluence administration, click Find New Apps in the left sidebar.
  2. In the search field enter ADONIS Process Manager for Confluence or ADOIT Enterprise Architect for Confluence.
  3. On the right of the ADONIS Process Manager/ADOIT Enterprise Architect for Confluence marketplace entry, select Buy now.
  4. Proceed as suggested by the Atlassian Marketplace dialogs.

4. Configuration of the REST connection

Once the ADONIS Process Manager/ADOIT Enterprise Architect for Confluence app has been installed in Confluence, the connection settings to ADONIS and/or ADOIT must be configured:

  • In Confluence, go to General Configuration
  • Navigate to ADONIS Process Manager/ADOIT Enterprise Architect Configuration
  • Select your edition (Enterprise Edition or Community Edition)
  • Change the configuration for the product (see Figure 9 and Figure 10, and descriptions below) and hit Save

Figure 8: Confluence General configuration

4.1. Enterprise Edition: Configure a connection

The following settings must be configured to establish a connection to ADONIS/ADOIT Enterprise Edition:

Web Client URLThe URL that you normally use to access the BOC Product.

When using Single-Sign On (SSO) with ADONIS/ADOIT: If an authentication server such as IIS is used to handle SSO between the client (typically the web browser) and ADONIS/ADOIT, you need to take additional steps to successfully establish a connection between the two systems. See Additional setup for SSO scenarios for further details.

The Web Client URL must also be set in the Confluence Allowlist Configuration to allow REST connections to your ADONIS/ADOIT instances!
REST IdentifierThe identifier provided for authentication (configured in the Admin Toolkit)
REST Secret KeyThe secret key provided for authentication (configured in the Admin Toolkit)
Use cache for artefact groupsImproves performance for large repositories. This is optional and disabled by default. For more information, see chapter How does the cache for model and object groups work?
LanguagesDefines the available languages for the Macros and Metamodel data.Only languages, that are supported by your ADONIS/ADOIT license must be entered here.
Time zoneDefines time zone, where ADONIS/ADOIT server instance is hosted. It is used, combined with Confluence user time zone settings to calculate proper values of date and time attributes in Macros.
HTTP Pool sizeThe maximum amount of parallel http threads used by the app.
HTTP Pool thresholdThe threshold for the amount of http threads. If this number is reached by the connection pool, the requests will be dropped.
Allow anonymous accessAllow anonymous users without login to access ADONIS/ADOIT content.
Please note: When connecting ADONIS/ADOIT to your Confluence instance, all content that the technical user in ADONIS/ADOIT has access to, is also being made available to all Confluence users.

4.2. Community Edition: Configure a connection

The following settings must be configured to establish a connection to ADONIS:CE/ADOIT:CE:

UsernameYour ADONIS:CE/ADOIT:CE account username.
PasswordYour ADONIS:CE/ADOIT:CE account password.
Use cache for artefact groupsImproves performance for large repositories. This is optional and disabled by default. For more information, see chapter How does the cache for model and object groups work?
HTTP Pool sizeThe maximum amount of parallel http threads used by the app.
HTTP Pool thresholdThe threshold for the amount of http threads. If this number is reached by the connection pool, the requests will be dropped.
Allow anonymous accessAllow anonymous users without login to access ADONIS/ADOIT content.
Please note: When connecting ADONIS/ADOIT to your Confluence instance, all content that the technical user in ADONIS/ADOIT has access to, is also being made available to all Confluence users.

The Community Edition URL (https://ce-api.boc-cloud.com/) must be set in the Confluence Allowlist Configuration to allow REST connections to your ADONIS/ADOIT instances!

Figure 9: Enterprise Edition: ADONIS Process Manager for Confluence Configuration

Figure 10: Community Edition: ADONIS Process Manager for Confluence Configuration

4.3. Enterprise Edition / Community Edition: Configure a connection

The following buttons are available on the configuration page:

SaveSaves the current configuration.
Test ConnectionTests the connection to the configured instance of ADONIS/ADOIT
Important: The configuration must be saved before the connection can be tested.
Build CacheBuilds up the ADONIS/ADOIT model caches for the REST interface.
ReinitializeTriggers the re-initialization to update the following components:
  • Cache for model and object groups: This retrieves the current state of the model and object groups from ADONIS/ADOIT and caches them.
  • The Metamodel: The metamodel data of ADONIS/ADOIT. If an update of the metamodel has been done on ADONIS/ADOIT, the reinitialization ensure that the latest version is used.
  • If the metamodel REST API has been enabled after starting Confluence and setting up ADONIS Process Manager/ADOIT Enterprise Architect for Confluence, the reinitialization must be executed.
Clear configurationClears the current configuration, effectively disconnecting ADONIS Process Manager/ADOIT Enterprise Architect for Confluence to ADONIS/ADOIT. Please note, that to completely disable ADONIS Process Manager/ADOIT Enterprise Architect for a given product, the section How to disable unused macros describes how to do it.

5. How to disable unused macros

In case you want to exclude specific macros of the ADONIS Process Manager/ADOIT Enterprise Architect for Confluence from usage, you can disable them in the Manage Apps view.

Steps to disable a macro

  1. Navigate to the "Confluence Administration" and to "Manage Apps".
  2. Expand "ADONIS Process Manager/ADOIT Enterprise Architect for Confluence" and the list of modules.
  3. There are many different modules listed. It is important to only disable modules that are listed in the table below, otherwise the functionality of ADONIS Process Manager/ADOIT Enterprise Architect will not work anymore.

Figure 11: ADONIS Process Manager for Confluence modules

For Enterprise Edition users: Please be aware, that disabling macros does not prevent access to any data. Even with all macros disabled, a user can still access all data of the Technical User via the REST API through Confluence.

Therefore, it is important to understand, that any restrictions to access data from ADONIS or ADOIT must be applied via the access rights of the Technical User.

This table contains which modules should be disabled to disable a specific ADONIS Process Manager/ADOIT Enterprise Architect macro:

ADONIS Model Imageadonis-model-image-macro
ADONIS Model Vieweradonis-model-viewer-macro
ADONIS Model Searchadonis-model-search-macro
ADONIS Model Listadonis-modellist-macro
ADONIS Object & Model Propertiesadonis-header-macro
adonis-space-admin-header-resources
space-admin-adonis-header
space-admin-adonis-header-2
adonis-header-plugin-space-admin-action
adonisspacesettings
ADONIS Query Tableadonis-table-macro
ADONIS Searchadonis-search-macro
ADONIS Chartadonis-workbench-macro
ADOIT Model Imageadoit-model-image-macro
ADOIT Model Vieweradoit-model-viewer-macro
ADOIT Model Searchadoit-model-search-macro
ADOIT Model Listadoit-modellist-macro
ADOIT Object & Model Propertiesadoit-header-macro
adoit-space-admin-header-resources
space-admin-adoit-header
space-admin-adoit-header-2
adoit-header-plugin-space-admin-action
adoitspacesettings
ADOIT Query Tableadoit-table-macro
ADOIT Searchadoit-search-macro
ADOIT Chartadoit-workbench-macro

6. Enterprise Edition: Additional setup for SSO scenarios

In case SSO is being used for user authentication, the following URL patterns must be whitelisted and passed through the ADONIS/ADOIT web application, without requiring user authentication:

If the base URL for ADONIS/ADOIT is:

Then the URL patterns to whitelist are:

including all the sub paths (e.g.to include https://ado.your-company.com/rest/connection).

Alternatively, a direct connection to ADONIS/ADOIT can be configured.

Figure 12: SSO setup

7. Appendix

7.1. Enterprise Edition: Restricting access to ADONIS/ADOIT content

Please be aware, that from within Confluence itself, you cannot effectively restrict access to any data of ADONIS or ADOIT, by using typical Confluence mechanisms alone, such as:

  • Confluence space permissions
  • Page restrictions
  • Disabling macros
  • etc.

This is due to the fact, that any Confluence user who can edit a page (e.g. in his personal space) can always include an ADONIS Process Manager/ADOIT Enterprise Architect macro and browse the objects & models in the repository (e.g. via the macro editor). Even if the user would not have any edit rights at all, ADONIS Process Manager/ADOIT Enterprise Architect continues to act as a proxy for authenticated Confluence users to the ADONIS/ADOIT REST interface, which still allows access to a limited set of APIs, that are needed for the macros to work.

Therefore, the proper way to limit access to ADONIS/ADOIT content, is to use the technical user configured in ADONIS/ADOIT for ADONIS Process Manager/ADOIT Enterprise Architect to restrict access (see chapter Enterprise Edition: Configuration of ADONIS/ ADOIT). Any requests from ADONIS Process Manager/ADOIT Enterprise Architect are processed by ADONIS/ADOIT within the context of this technical user. As such, the full power of the permission system within ADONIS and ADOIT can be used to control, which data will be available in Confluence and which data should not be accessible.

This includes restricting access to:

  • individual objects and models or entire object- & model-groups
  • to object types and model types (e.g. all processes, all documents, all applications, …)
  • individual attributes & relations (globally or for a specific object-/model-type)
  • based on object-/model-lifecycle state (e.g. only released processes or applications; only available in combination with a release workflow)

7.2. How to enable ADONIS Process Manager/ADOIT Enterprise Architect logging

By default, every Confluence plugin is configured to log WARN and ERROR levels.

To get more information about ADONIS Process Manager/ADOIT Enterprise Architect, enable the INFO log as described:

  • In Confluence, go to General Configuration
  • Navigate to Logging and Profiling
  • Enter a new log entry com.boc.confluence.plugin and select INFO as logging level:

Figure 13: Logging and Profiling

Additionally, DEBUG level can be used to further diagnostic issues, especially if requested from the BOC Hotline.

7.3. How to enable the cache for model and object groups?

To enable the cache for model and object groups:

  • In Confluence, go to General Configuration
  • Navigate to ADONIS Process Manager/ADOIT Enterprise Architect Configuration
  • Toggle the check box "Use cache for artefactgroups"
  • Press Reinitialize to initialize the cache

Figure 14: ADONIS Process Manager for Confluence Configuration (Enable cache)

7.4. How does the cache for model and object groups work?

If the "use cache for artefactgroups" setting is enabled, an in-memory cache of the group data of ADONIS/ADOIT is created in Confluence. What this means is that editing macros, as well as the Model Search, Model List, and Object & Model Properties macros, are faster.

Additionally, when editing macros, it is now possible to reload a specific sub-tree:

Figure 15: Reload a specific sub-tree

When this happens, a re-caching of the model group data is also triggered.

Furthermore, a re-caching is also triggered by a new ADONIS Process Manager/ADOIT Enterprise Architect scheduler:

Figure 16: Scheduled Jobs

By default, it is configured to run every 30 minutes from 7 AM to 18 PM. This is configurable, but we recommend to not make it faster than every 5 minutes to not overload the servers.

8. Troubleshooting

8.1. Enterprise Edition: The class icons are missing from the macros

The web base URL in the system settings of ADONIS/ADOIT must be configured to include the web application name, for example: https://mycompany.org/ADOIT_91/.

8.2. Enterprise Edition: How to solve SSL handshake: "sun.security.validator.ValidatorException: PKIX path building failed"

Indication

Error in Confluence log file: sun.securityvalidator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

Description

This error indicates a problem with the encrypted communication (TLS) from Confluence to ADONIS/ADOIT. The validation of the certification chain cannot be established.

For more information and a general solution, read the Atlassian support article Connecting to SSL services.

Solution

  • Ensure that a recent Java version is installed that includes the required global and intermediate certificates. For SaaS Customers of ADONIS/ADOIT, these certificates are DigiCert Global Root G2 and Thawte TLS RSA CA G1.The following Java versions have the certificates included:

  • Alternatively, you can download and manually import the certificates in the Java keystore (site certificate) and Java truststore (global and intermediate CA certificates), as described in the Oracle support article Working with Certificates and SSL.

  • Note: If you use a custom keystore location, make sure that you provide JVM options as parameters (also see the support article for further details):

    -Djavax.net.ssl.keyStore=<path to keystore>

    -Djavax.net.ssl.keyStorePassword=changeit

    -Djavax.net.ssl.trustStore=<path to truststore>

    -Djavax.net.ssl.trustStorePassword=changeit

The certificates can be viewed and downloaded, when accessing the ADONIS/ADOIT webclient via the webbrowser by clicking on the lock icon (SSL info).

Figure 17: Import the *.boc-cloud.com certificate

Please be aware, that if you import the *.boc-cloud.com certificate manually into your Java keystore, your certificate will not automatically be updated, when a new version of the certificate is used.

The typical validity and update cycle for the *.boc-cloud.com certificate is two years.

8.3. Enterprise Edition: The connection from ADONIS Process Manager/ADOIT Enterprise Architect prompts for authentication

This can happen if the requests from ADONIS Process Manager/ADOIT Enterprise Architect do not go directly to the Tomcat of ADONIS/ADOIT, but instead go through an Authentication server. Typically, this means, that SSO is used but setup incorrectly. See Additional setup for SSO scenarios for further details.

8.4. Enterprise Edition: The macros using the metamodel are not working after enabling the metamodel REST APIs in the Admin Toolkit

If the metamodel REST API has been enabled after starting Confluence and setting up ADONIS Process Manager/ADOIT Enterprise Architect, then the macros using the metamodel will not work immediately.

For example, adding a Query Table macro can show the following warning message:

Figure 18: Warning message of Macro ADONIS Table

To make ADONIS Process Manager/ADOIT Enterprise Architect aware of the metamodel REST API, a Confluence administrator must reinitialize ADONIS Process Manager/ADOIT Enterprise Architect from the admin configuration page.

Steps to reinitialize ADONIS Process Manager/ADOIT Enterprise Architect

  1. In Confluence, go to General Configuration
  2. Open the ADONIS Process Manager/ADOIT Enterprise ArchitectConfiguration
  3. Hit the reinitialize button

Figure 19: Reinitialize ADONIS Process Manager

  1. After a while, a message will notify the success of the operation.
  2. The macros using the metamodel will now work correctly.

Please note, that enabling the metamodel REST API in the Admin Toolkit requires a restart of ADONIS/ADOIT. If this did not happen, a restart must be done before following the steps for the ADONIS Process Manager/ADOIT Enterprise Architect reinitialization (see 2. Enterprise Edition: Configuration of ADONIS/ADOIT).