Chapter 1. Asset Repository

Business Rules and other assets and resources created in Business Central are stored in asset repository, which is otherwise known as the Knowledge Store.

The Knowledge Store is a centralized repository for your business knowledge. The Knowledge Store connects to the Git repository to store various knowledge assets and artifacts at a single location. Business Central provides a web front-end that allows you to view and update the stored content. You can access the content by using the Project Explorer from the unified environment of Red Hat JBoss BRMS.

All business assets are stored in repositories. These repositories are then saved in directories called organizational units. By default, the Knowledge Store in Business Central does not contain any organizational unit. Therefore, to be able to create your own business assets, you need to create an organizational unit and a repository first.

1.1. Creating an Organizational Unit

It is possible to create an organizational unit either in the Administration perspective of Business Central, using the kie-config-cli tool, or the REST API calls.

Creating an Organizational Unit in Business Central
Important

Note that only users with the admin role in Business Central can create organizational units.

Procedure: Using Business Central to Create an Organizational Unit

  1. In Business Central, go to AuthoringAdministration.
  2. On the perspective menu, click Organizational UnitsManage Organizational Units.
  3. In the Organization Unit Manager view, click Add.

    The Add New Organizational Unit dialog window opens.

    Figure 1.1. Add New Organizational Unit_Dialog Window

    A screenshot of the Add New Organizational Unit dialog window.
  4. Enter the two mandatory parameters (name and default group ID) and click Ok.
Creating an Organizational Unit Using the kie-config-cli Tool

Organizational units can be created using the kie-config-cli tool as well. To do so, run the create-org-unit command. The tool then guides you through the entire process of creating an organizational unit by asking for other required parameters. Type help for a list of all commands.

For more information about the kie-config-cli tool, see Chapter 6, Command Line Configuration.

⁠⁠Creating an Organizational Unit Using the REST API
Important

Note that only users with the rest-all role can create organizational units.

To create an organizational unit in Knowledge Store, issue the POST REST API call. Details of the organizational unit are defined by the JSON entity.

Input parameter of the call is a OrganizationalUnit instance. Call returns a CreateOrganizationalUnitRequest instance.

Example 1.1. Creating an Organizational Unit Using the Curl Utility

Example JSON entity containing details of an organizational unit to be created:

{
  "name"         : "helloWorldUnit",
  "owner"        : "tester",
  "description"  :  null,
  "repositories" :  []
}

Execute the following command:

curl -X POST 'localhost:8080/business-central/rest/organizationalunits/' -u USERNAME:PASSWORD -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"name":"helloWorldUnit","owner":"tester","description":null,"repositories":[]}'

For further information, refer to chapter Knowledge Store REST API, section Organizational Unit Calls of Red Hat JBoss BPM Suite Development Guide.

1.2. Creating a Repository

There are three ways to create a repository: through the Administration perspective of Business Central, the kie-config-cli tool, or using the REST API calls.

⁠Creating a Repository in Business Central
Important

Note that only users with the admin role in Business Central can create repositories.

Procedure: Using Business Central to Create a Repository

  1. In Business Central, go to AuthoringAdministration.
  2. On the perspective menu, click RepositoriesNew repository.

    The New Repository pop-up window is displayed.

    Figure 1.2. New Repository Dialog Window

    A screenshot of the New Repository dialog window.
  3. Specify the two mandatory parameters:

    • Repository name
    Note

    Make sure that the repository name is a valid file name. Avoid using a space or any special character that might lead to an invalid name.

    • Organizational unit: Specifies the location of the newly created repository.
  4. Click Finish.

You can view the newly created repository either in the File Explorer or the Project Explorer.

⁠Creating Repository Using kie-config-cli Tool

To create a new Git repository using the kie-config-cli tool, run the create-repo command. The tool then guides you through the entire process of creating a repository by asking for other required parameters. Type help for a list of all commands.

For more information about the kie-config-cli tool, see Chapter 6, Command Line Configuration.

⁠⁠Creating Repository Using REST API
Important

Note that only users with the rest-all role can create repositories.

To create a repository in the Knowledge Store, issue the POST REST API call. Details of the repository are defined by the JSON entity. Make sure you established an authenticated HTTP session before executing this call.

Input parameter of the call is a RepositoryRequest instance. Call returns a CreateOrCloneRepositoryRequest instance.

Example 1.2. Creating Repository Using Curl Utility

Example JSON entity containing details of a repository to be created:

{
  "name"                   : "newRepository",
  "description"            :  null,
  "gitURL"                 :  null,
  "requestType"            : "new",
  "organizationalUnitName" : "helloWorldUnit"
}

Execute the following command:

curl -X POST 'localhost:8080/business-central/rest/repositories/' -u USERNAME:PASSWORD -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"name":"newRepository","description":null,"requestType":"new","gitURL":null,"organizationalUnitName":"helloWorldUnit"}'

For further information, refer to chapter Knowledge Store REST API, section Repository Calls of Red Hat JBoss BPM Suite Development Guide.

1.3. Cloning a Repository

It is possible to clone a repository either in Business Central or using the REST API calls. The kie-config-cli tool cannot be used to clone arbitrary repositories. Run git clone, or use one of the following options instead:

Cloning a Repository in Business Central
Important

Note that only users with the admin role in Business Central can clone repositories.

Procedure: Using Business Central to Clone a Repository

  1. In Business Central, go to AuthoringAdministration.
  2. On the perspective menu, choose RepositoriesClone repository.

    The Clone Repository pop-up window is displayed.

    Figure 1.3. Clone Repository Dialog Window

    A screenshot of the Clone Repository dialog window.
  3. In the Clone Repository dialog window, enter the repository details:

    1. Enter the Repository Name to be used as the repository identifier in the Asset repository and select the Organizational Unit it should be added to.
    2. Enter the URL of the Git repository:

      • For a local repository, use file:///PATH_TO_REPOSITORY/REPOSITORY_NAME.
      • For a remote or preexisting repository, use https://github.com/USERNAME/REPOSITORY_NAME.git or git://HOST_NAME/REPOSITORY_NAME.

        Important

        It is important to use the HTTPS or Git protocol instead of a SCP-style SSH URL. Business Central does not support the basic SSH URL and fails with Invalid URL format.

      Note

      The file protocol is only supported for READ operations. WRITE operations are not supported.

    3. If applicable, enter the User Name and Password of your Git account to be used for authentication.
  4. Click Clone.

    A confirmation prompt with the notification that the repository was created successfully is displayed.

  5. Click Ok.

    The repository is now being indexed. Some workbench features may be unavailable until the indexing has completed.

You can view the cloned repository either in the File Explorer or the Project Explorer.

Note

If you are deploying Business Central on WebLogic server, set the following Java system property in the setDomainEnv.sh file (for Linux) or setDomainEnv.cmd file (for Windows):

JAVA_OPTIONS="%JAVA_OPTIONS% -DUseSunHttpHandler=true"

This enables the WebLogic server to use the HTTP handlers.

Cloning a Repository Using the REST API

To clone a repository, issue the POST REST API call. This call creates or clones (according to the value of the requestType parameter) the repository defined by the JSON entity.

The input parameter of the call is a RepositoryRequest instance. The Call returns a CreateOrCloneRepositoryRequest instance.

Important

Note that, only users with the rest-all role can clone repositories.

Example 1.3. Cloning a Repository Using the Curl Utility

Example JSON entity containing details of a repository to be cloned:

{
  "name"                   : "clonedRepository",
  "description"            :  null,
  "requestType"            : "clone",
  "gitURL"                 : "git://localhost:9418/newRepository",
  "organizationalUnitName" : "helloWorldUnit"
}

Execute the following command:

curl -X POST 'localhost:8080/business-central/rest/repositories/' -u USERNAME:PASSWORD -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"name":"clonedRepository","description":null,"requestType":"clone","gitURL":"git://localhost:9418/newRepository","organizationalUnitName":"helloWorldUnit"}'

For further information, refer to chapter Knowledge Store REST API, section Repository Calls of Red Hat JBoss BPM Suite Development Guide.

1.4. Removing a Repository

Repositories can be removed using any of the following procedures.

Removing a Repository in Business Central

The simplest way to remove a repository is using the RepositoryEditor in Business Central.

Procedure: Using Business Central to Remove a Repository

  1. In Business Central, go to AuthoringAdministration.
  2. Select Repositories from the tree menu on the left.
  3. In the RepositoryEditor on the right side of the page, locate the repository you want to delete from the list of available repositories.
  4. From the drop-down menu, select masterDelete.

    The following message will appear:

    Are you sure you want to remove Repository "REPOSITORY_NAME"? Some editors may become inoperable if their content is inaccessible.
  5. Press OK to delete the repository.

Removing a Repository Using the kie-config-cli Tool

Repositories can be removed using the kie-config-cli tool as well. To do so, run the remove-repo command.

For further information about the kie-config-cli tool, see Chapter 6, Command Line Configuration.

Removing a Repository Using the REST API

Important

Note that only users with the rest-all role can remove repositories.

To remove a repository from the Knowledge Store, issue the DELETE REST API call. Make sure you established an authenticated HTTP session before executing this call.

The call returns a RemoveRepositoryRequest instance.

Example 1.4. Removing a Repository Using the Curl Utility

Execute the following command:

curl -X DELETE 'localhost:8080/business-central/rest/repositories/REPOSITORY_NAME' -u USERNAME:PASSWORD -H 'Accept: application/json' -H 'Content-Type: application/json'

For further information, refer to chapter Knowledge Store REST API, section Repository Calls of Red Hat JBoss BPM Suite Development Guide.

1.5. Managing Assets

Note

To activate and use the feature described below, login to Business Central with a user that has the kiemgmt role assigned.

To make management of projects easier, Red Hat JBoss BRMS now provides a way to manage multiple projects based on standards. This allows you to create repository structures using industry standard best practices for maintenance, versioning and distribution of your projects.

To start with, repositories can now be managed or unmanaged.

Managed and Unmanaged Repositories

Unmanaged Repositories are the repository structures that you are used to. They can contain multiple unrelated projects.

Managed Repositories, on the other hand, provide version control at the project level and project branches for managing the release cycle. Further, Managed Repositories can be restricted to just a single project or encompass multiple projects. When you create a Managed Repository, the asset management configuration process is automatically launched in order to create the repository branches. Corresponding project structure is created as well.

Note

Multi-project repositories must be managed.

Procedure: Creating an Unmanaged Repository

  1. In Business Central, go to AuthoringAdministration.
  2. Click RepositoriesNew Repository.

    The New Repository window is displayed.

  3. Enter the repository name and select an organizational unit the repository belongs to.
  4. Click Finish.

Procedure: Creating a Managed Repository

  1. In Business Central, go to AuthoringAdministration.
  2. Click RepositoriesNew Repository.

    The New Repository window is displayed.

  3. Enter the repository name and select an organizational unit the repository belongs to.
  4. Select the Managed Repository check box and click Next to enter additional details of the Managed Repository.

    6565
  5. Choose either the Single-project Repository or the Multi-project Repository radio button.

    If the project you are creating is simple and self-contained, select the Single-project Repository radio button. Note that you will not be able to add more projects to this repository later.

    For more complex projects, where there is likely to be a parent project that encompasses smaller ones, select the Multi-project Repository radio button.

    6566
  6. Enter the details of the managed project along with the GAV (Group, Artifact, Version) details.

    Note that all projects created in a Multi-project Repository will be managed together, with their version numbers being incremented together as well. Details of the parent project will be inherited by all future projects that you create in this Managed Repository.

  7. Click Finish .
Note

If you create an unmanaged repository and add a pom.xml file (a parent Project Object Model (POM) file) directly under the repository directory, Red Hat JBoss BRMS converts the repository to a managed repository. For instructions about changing the repository status back to unmanaged, see the Red Hat Knowledgebase article An Unmanaged Repository Unexpectedly Turned Into "Managed" in BRMS / BPM Suite.

Managed Branches

With Managed Repositories comes the added advantage of Managed Branches. As in Git, you can choose to work on different branches of your project (for example: master, dev and release). This process of branching can also be automated for you, by selecting the checkbox while creating a new Managed Repository (for both single and multi-projects).

You can switch between branches by selecting the desired branch while working in the Project Explorer.

Repository Structure

If you do not select automatic branch management while creating a repository, you can create branches manually afterwards. For Managed Repositories, you can do so by using the Configure button. This button, along with Promote and Release buttons, is provided in the Repository Structure view. You can access this view, by clicking on RepositoryRepository Structure in the Project Explorer perspective menu.

Clicking on the Configure button allows you to create branches or edit automatically created ones.

6572

You can promote assets from the master branch to other branches using the Promote button. Similarly, you can Release branches and deploy them on the server using the Release button.

Both these functions are controlled internally by the use of pre-defined processes that are deployed on your instance. For example, when you click on Promote button after having done work on your development branch, a Promote Changes process is started in the background. A user, with the role of kiemgmt will have a user task appear in this task list to review the assets being promoted. This user can claim this task, and decide to promote all, some or none of the assets. The underlying process will cherry-pick the commits selected by the user to a release branch. This user can also request another review of these assets and this process can be repeated multiple times till all the assets are ready for release. The flow for this process is shown below:

6574

Similarly, when you click on the Release button, a release process flow is initiated. This process flow builds the project and updates all the Maven artifacts to the next version, and deploys the project to the runtime, if runtime deployment details are supplied.

Warning

Project branches to be released must start with the keyword release.

6575
Warning

Do not use Deploy To Runtime with Red Hat JBoss BRMS as it causes deploy failure. This function can only be used with Red Hat JBoss BPM Suite.

1.6. Maven Repository

Maven is a software project management tool which uses a project object model (POM) file to manage:

  • Builds
  • Documentation
  • Reporting
  • Dependencies
  • Releases
  • SCMs
  • Distribution

A Maven repository is used to hold or store the build artifacts and project dependencies and is generally of two types:

Local
Refers to a local repository where all the project dependencies are stored and is located with the current installation in the default folder as "m2". It is a cache of the remote downloads, and also contains the temporary build artifacts which have not yet been released.
Remote
Refers to any other type of repository that can be accessed by a variety of protocols such as file:// or http://. These repositories can be at a remote location set up by a third-party for downloading of artifacts or an internal repository set up on a file or HTTP server, used to share private artifacts between the development teams for managing internal releases.

1.7. Configuring Deployment to a Remote Nexus Repository

Nexus is a repository manager frequently used in organizations to centralize storage and management of software development artifacts. It is possible to configure your project so that artifacts produced by every build are automatically deployed to a repository on a remote Nexus server.

To configure your project to deploy artifacts to a remote Nexus repository, add a distributionManagement element to your project’s pom.xml file as demonstrated in the code example below.

<distributionManagement>
  <repository>
    <id>deployment</id>
    <name>Internal Releases</name>
    <url>http://your_nexus_host:8081/nexus/content/repositories/releases</url>
  </repository>
  <snapshotRepository>
    <id>deployment</id>
    <name>Internal Releases</name>
    <url>http://your_nexus_host:8081/nexus/content/repositories/snapshots/</url>
  </snapshotRepository>
</distributionManagement>

Replace the URLs in the example with real URLs of your Nexus repositories. The repository specified in the snapshotRepository element is used when the -SNAPSHOT qualifier is appended to the project’s current version number. In other cases the repository specified in the repository element is used.

If your Nexus server requires authentication, you will also need to modify your projects Maven settings to add your credentials in the settings-security.xml file, using a master password. By default, this file is in the $M2_HOME/conf folder, unless you have changed its location by modifying the kie.maven.settings.custom system property. It is also possible to create new user-specific settings.xml and settings-security.xml files in the ~/.m2 folder. In that case, these files will override the original ones.

See the following example of the settings-security.xml:

<servers>
  <server>
    <id>deployment</id>
    <username>admin</username>
    <password>{COQLCE6DU6GtcS5P=}</password>
  </server>
</servers>
Important

Note that keeping your server authentication credentials (for example the passwords) as a plain text in the settings.xml file is not recommended. All the information should be hashed with a master password in the settings-security.xml file.

For further information about password encryption and creating a master password, see the Apache Maven documentation, article Password Encryption.

With this configuration in place, clicking the Build & Deploy button in Business Central executes a Maven build and deploys the built artifacts both to the local repository and to one of the Nexus repositories specified in the pom.xml file.