Access to Bonita Artifact Repository (Subscription editions only)

Set up access to Bonita Artifact Repository to download development dependencies.

What is Bonita Artifact Repository?

Bonita Artifact Repository is a solution to access Maven artifacts produced by Bonitasoft, which can be consumed as dependencies in downstream projects.

For now, only Bonita Test Toolkit is available from Bonita Artifact Repository.

An Internet connection is required.

Ask for credentials to your account manager

Once your subscription is registered, your account manager will automatically receive an email with valid credentials. These credentials will last as long as your subscription, but you will not need to change them if you extend that subscription.

Credentials are unique per subscription access and include:

A subscription access login (the email used for the subscription)
A subscription access token

Maven

In the below example, we use Maven as the project build tool for extension projects. But it is also possible to use Gradle if it is the tool of your choice.

Maven settings overview

Once you were granted with Bonita Artifact Repository credentials, you have to configure Maven to use Bonita maven repository.

This is done in a text file named settings.xml. The file location depends on your Maven installation, which is explained on Maven official documentation.

This file usually lives in these places (replace <USERNAME> by yours) :

Linux: /home/<USERNAME>/.m2/settings.xml
MacOS: /Users/<USERNAME>/.m2/settings.xml
Windows: C:\Users\<USERNAME>\.m2\settings.xml

Sample sections of settings.xml

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
  <localRepository/>
  <interactiveMode/>
  <offline/>
  <pluginGroups/>
  <servers/>
  <mirrors/>
  <proxies/>
  <profiles/>
  <activeProfiles/>
</settings>

Bonita Maven repository declaration

In this settings.xml file you have to declare Bonita Maven repository to let Maven know that some dependencies can be found there. In the following code snippet, you will find how to declare new repositories to Maven.

Part of settings.xml

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <!-- ...  -->
    <profiles>
        <profile>
            <id>Bonita</id>
            <repositories>
                <repository>
                    <id>bonitasoft-releases</id>
                    <name>Bonitasoft Releases</name>
                    <releases>
                        <enabled>true</enabled>
                    </releases>
                    <snapshots>
                        <enabled>false</enabled>
                    </snapshots>
                    <url>https://bonitasoft.jfrog.io/artifactory/maven</url>
                </repository>
            </repositories>
        </profile>
    </profiles>
    <!-- ...  -->
  <activeProfiles>
    <activeProfile>Bonita</activeProfile>
  </activeProfiles>

</settings>

Do not forget to mark Bonita profile as active in the activeProfiles section or the declared repositories will not be used for dependency resolution.

Authentication

Now that Maven is aware of Bonita Maven repository, you have to give it the credentials to be allowed to download artifacts. Credentials are defined in the repository servers section. We strongly advise you to use password encryption feature to enforce security.

Server authentication in settings.xml

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">

    <!-- ...  -->
    <servers>
        <server>
            <!-- This server ID must be the same as the one use for repository declaration ! -->
            <id>bonitasoft-releases</id>
            <!-- The login associated to your subscription access -->
            <username>SUBSCRIPTION_ACCESS_LOGIN</username>
            <!-- The token after encryption associated to your subscription access -->
            <password>SUBSCRIPTION_ACCESS_ENCRYPTED_TOKEN</password>
        </server>
    </servers>
    <!-- ...  -->
</settings>

Maven configuration in Bonita Studio

Starting from Bonita 2021.2, Bonita Studio uses Maven internally to resolve required dependencies.

If you want to set up access to Bonita Artifact Repository using Bonita Studio, please refer to the dedicated page on how to configure Maven from Bonita Studio.

Troubleshooting

ERROR: Could not find artifact in central

Symptom:

Your Maven build fails with an equivalent error:

[ERROR] Failed to execute goal on project XXX: Could not resolve dependencies for project XXX: Could not find artifact com.bonitasoft:bonita-test-toolkit:jar:1.0.0 in central (https://repo.maven.apache.org/maven2)

Causes:

The active profile in your settings.xml file is missing ;
Or the active profile is not matching the ID in the <profiles></profiles> section.

Example:

<settings>
    <profiles>
        <profile>
            <id>Bonita</id> <!-- ID of your profile containing Bonita Maven repository definition -->
            <repositories>
                <!-- ... -->
            </repositories>
        </profile>
    </profiles>
    <activeProfiles>
        <activeProfile>foobar</activeProfile> <!-- Incorrect ID! -->
    </activeProfiles>
</settings>

Solution:

The active profile must match the profile ID containing Bonita Maven repository definition.

Example:

<settings>
    <profiles>
        <profile>
            <id>Bonita</id>
            <repositories>
                <!-- ... -->
            </repositories>
        </profile>
    </profiles>
    <activeProfiles>
        <activeProfile>Bonita</activeProfile> <!-- Correct ID -->
    </activeProfiles>
</settings>

ERROR: authentication failed / status: 401 Unauthorized

Symptom:

Your Maven build fails with an equivalent error:

[ERROR] Failed to execute goal on project XXX: Could not resolve dependencies for project XXX: Failed to collect dependencies at com.bonitasoft:bonita-test-toolkit:jar:1.0.0: Failed to read artifact descriptor for com.bonitasoft:bonita-test-toolkit:jar:1.0.0: Could not transfer artifact com.bonitasoft:bonita-test-toolkit:pom:1.0.0 from/to bonitasoft-releases (https://bonitasoft.jfrog.io/artifactory/maven): authentication failed for https://bonitasoft.jfrog.io/artifactory/maven/com/bonitasoft/bonita-test-toolkit/1.0.0/bonita-test-toolkit-1.0.0.pom, status: 401 Unauthorized

Causes:

Invalid maven configuration

The <server></server> section is missing in your settings.xml file ;
Or the ID in the <server></server> section is not matching the ID of the repositories' definition ;
Or you set an incorrect username in the <server></server> section. It should be the email used for your Bonita subscription ;
Or you set an incorrect password in the <server></server> section. If you used maven encryption, it should starts and ends with curly braces (i.e. <password>{MZ8lWg+K9FA9B0qh/RkJgN}</password>). You also need to escape curly-brace literals in your password.

Example:

<settings>
    <profiles>
        <profile>
            <id>Bonita</id>
            <repositories>
                <repository>
                    <id>bonitasoft-releases</id> <!-- ID of the Bonita Maven repository definition -->
                    <!-- ... -->
                </repository>
            </repositories>
        </profile>
    </profiles>
    <activeProfiles>
        <activeProfile>Bonita</activeProfile>
    </activeProfiles>
    <servers>
        <server>
            <id>foobar</id> <!-- Incorrect ID! -->
            <username>foo</username> <!-- Incorrect username! -->
            <password>bar</password> <!-- Incorrect password! -->
        </server>
    </servers>
</settings>

Solution:

The server ID must match the ID of the repositories' definition ;
The username should be an email format, the email used for your Bonita subscription ;
If you used maven encryption, it must be the exact output of Maven command line mvn --encrypt-master-password <password>.

Example:

<settings>
    <profiles>
        <profile>
            <id>Bonita</id>
            <repositories>
                <repository>
                    <id>bonitasoft-releases</id> <!-- ID of the Bonita Maven repository definition -->
                    <!-- ... -->
                </repository>
            </repositories>
        </profile>
    </profiles>
    <activeProfiles>
        <activeProfile>Bonita</activeProfile>
    </activeProfiles>
    <servers>
        <server>
            <id>bonitasoft-releases</id> <!-- Correct ID -->
            <username>walter.bates@acme.com</username> <!-- Example of a correct username -->
            <password>{MZ8lWg+K9FA9B0qh/RkJgN}</password> <!-- Example of a correct encrypted password -->
        </server>
    </servers>
</settings>

Credentials may be invalid

You can easily check that your credentials are valid with a simple command line like this one using curl

curl -i --user "<SUBSCRIPTION_ACCESS_LOGIN>:<SUBSCRIPTION_ACCESS_TOKEN>" 'https://bonitasoft.jfrog.io/artifactory/api/system/ping'

If credentials are valid, you should get a response 'OK' with a status code HTTP 200.

HTTP/1.1 200 OK
Date: Fri, 26 Aug 2022 10:27:53 GMT
Content-Type: text/plain
Transfer-Encoding: chunked
Connection: keep-alive
[... headers ommitted ...]

OK

If not, there is maybe a problem with the credentials you are using, check you’ve made no typo error and contact support.

ERROR: authorization failed, status: 403 Forbidden

Symptom:

Your Maven build fails with an equivalent error:

[ERROR] Failed to execute goal on project XXX: Could not resolve dependencies for project XXX: Failed to collect dependencies at com.bonitasoft:bonita-test-toolkit:jar:1.0.0: Failed to read artifact descriptor for com.bonitasoft:bonita-test-toolkit:jar:1.0.0: Could not transfer artifact com.bonitasoft:bonita-test-toolkit:pom:1.0.0 from/to bonitasoft-releases (https://bonitasoft.jfrog.io/artifactory/maven): authorization failed for https://bonitasoft.jfrog.io/artifactory/maven/com/bonitasoft/bonita-test-toolkit/1.0.0/bonita-test-toolkit-1.0.0.pom, status: 403 Forbidden

Causes:

Your credentials are valid but your are not allowed to access what you are asking for. Contact your support to check your permissions.