One of the most confusing topic for a newbie of Red Hat JBoss BPMS and BRMS is how to deal with the Business Central internal repository.
At the first sight, it appears as the central repository and since it’s even implemented with the “trendy” GIT technology, the newbie is prone to consider it as a sort of central GIT repository – a unique source of truth!

Actually, the Business Central stores all assets in a Virtual File System (VFS). The goal of the VFS is storing all the modifications applied to each asset: so as the user saves an artifact, it is stored in an ordered way and that version can always be retrieved. This sounds really safe, but the side effect is that loads of useless versions of a file are stored. Moreover, the Business Central VFS is backed by a GIT repository, so every save is translated in a GIT commit (this implies that in Business Central a GIT commit contains always one file!).

For this reason when a user looks at GIT repository of the Business Central, he/she can be disoriented because he/she find a bunch of useless and misleading commits. In fact, according the GIT philosophy, a developer should commit a group of artifacts when they are consistent, usually when he/she implements a new feature, after a successful build and a test.

In order to implement even a simple feature, a Business Central user changes more than an artifact (a BPMN diagram, a form, a data object) and like any other kind of developer, he will not get the expected result at the first tentative. So looking back at the git history (git log), he/she will see tens of meaningless commits.

Said that, if a Business Central user want to consolidate his changes in a Central GIT Repository, he has to squash all those commits in a unique consistent commit.

The rest of the article will teach how to deal with the Business Central repository: from simple operations, till how to consolidate the work in a central repository and how to cooperate with other developers.

Import or Export files

The first basic need for a Business Central user is to import and export artifacts for different reasons:

• exchange artifacts with a colleague
• modify an artifact with a more comfortable editor (Java classes, DRL files, etc)
• save the project in a corporate Source Control Management system (Subversion, CVS, PVCS, etc)

Business Central does not offer an graphical way to exchange content externally: there is a way to import from an external GIT repository, but it’s just a start up procedure, since the user cannot pull further from the initial repository. Moreover there is no way to download artifacts or the whole project, from the Web UI.

The solution is using the GIT interface. In fact, even if the user is not interested in using GIT for versioning purposes, he/she has to learn the basics of GIT, because it is the only accessible interface to his/her assets! For persons that don’t like the command line, Eclipse provides a graphical UI that is pretty easy.

Business Central GIT URL

The first step is knowing the URL of the repository. If the default port is not changed the URL should follow this pattern:

ssh://<user>@<business-central-host>:8001/<repository-name>

It’s possible to get the list of existing repositories, looking at Administration view: Authoring -> Administration

Here an example of the repository list:

The developer can set up the GIT repository in Eclipse through the following wizard:

There are many resources available on the web lo learn the basics of GIT and tutorials on how to use Eclipse or other graphical interface for it. For this reason, henceforth the instructions will stay focus on the GIT command line (the reader should easily map the GIT commands in the equivalent actions in a graphical interface).

SSH Set up

The Business Central exposes an old SSH protocol that requires a bit of configuration, so the user has to tweak his/her ssh configuration following these instructions:

• Add the following lines to ~/.ssh/config

  Host *
    VerifyHostKeyDNS no
    StrictHostKeyChecking no
    HostKeyAlgorithms +ssh-dss
    PubkeyAcceptedKeyTypes +ssh-dss
    UserKnownHostsFile /dev/null

• Ensure that ~/.ssh/config has these access rights: -rw-------

  chmod 600 ~/.ssh/config

Export a project from Business Central

Here the instructions to follow for a user who wants to extract the content from an existing repository:

• Get the repository URL as described before
• Clone the repository

  $ git clone ssh://<user>@<business-central-host>:8001/<repository-name>

• A new directory is created with the content of the Business Central repository
• From now on, the user can retrieve the latest updates from Business Central through the pull command in the repository directory:

  $ git pull

Import a project in Business Central

Let’s consider a user that has a project in the file system to import in the Business Central, here the steps that such user has to follow:

• Create the repository in the Business Central
• Within the project directory initialize the GIT repository (unless he hasn’t already done before):

  $ git init

• Add the remote reference to the Business Central (bc)

  $ git remote add bc ssh://<user>@<business-central-host>:8001/<repository-name>

• Add everything and commit

  git add -A
  git commit -m "init"

• In order to override the initial content, the user has to “force” the push

  git push -f -u bc master

  optionally add -u flag to set bc as default remote repository for pushing

• Now the local project is available in the Business Central

Team working in Business Central

Business Central provides a multi user editing environment and at the same time a test runtime for your projects. Many users can edit the artifacts at the same time; an important capability is the centralized locking system: as a user starts editing a file, that content is locked and nobody can edit the same file.

In the following picture how the lock is displayed in the project explorer:

This is really useful because it avoids the parallel editing and the need for merging the changes. In fact, merging graphical assets like decision tables or process diagram is practically impossible, so the locking is the best strategy for the team cooperation. Nevertheless, this comes at the cost of being quite careful to save as soon as possible the work and close the file; otherwise if a user opens and starts editing many different files, other users are stuck waiting the other finishing his/her job.

Unfortunately, concurrent editing a project has other drawbacks:

• two users can change two different resources that are correlated, so it could happen that they disturb and slow down each others.
• the testing environment is shared among all the users, so as a user deploys his changes can interfere with the testing activities of the others.

The bottom line is that the teamwork in Business Central is not suited for high intensive development on the same project. Business Rules are usually self contained, for this reason they are more easy to manage in a shared authoring environment, whereas Business Process requires a more isolated approach, even because deploying a new version of process project requires that all pre-existing process instances defined by that project would be removed.

Working in an isolated authoring environment

The following part of the article will describe an advanced technique to get an isolated environment for each developer and a shared team repository where to merge changes; since it relies on an advanced usage of GIT, the readers need a good understanding of GIT operations.

In order to give to each developer his/her own isolated authoring and test environment, an instance of Business Central should be dedicated for this purpose, it can be installed in his/her workstation or in a centralised server (one process per user). In such configuration, the Business Central (BC) repository has the role of a sandbox, whereas the team will use a central GIT repository as unique source of truth (blessed repository Ref. Distributed Git – Distributed Workflows). Hereafter, a graphical representation of the proposed configuration:

The local GIT repository is a copy of the repository that each developer has in his/her own workstation: it’s used to consolidate the work done in the Business Central and push in the shared GIT.

Initializing the environment

The goal of this procedure is creating a GIT repository for each developer that has 2 remote references:

• the reference bc for the dedicated Business Central, where each developer has his/her own master branch
• the reference shared for the shared GIT repository, where the whole team has a branch called team (where is tracked the shared content)

WARNING
Since Business Central uses master as default branch, it’s better using master branch to share content with the Business Central. To avoid confusion, the master branch will not be synchronized in the shared repository. The user should consider the master as a shallow branch.

The team leader creates the shared GIT repository:

• create the project in the Business Central
• clone the initial project in his/her local repository

  $ git clone ssh://<user>@<business-central-host>:8001/<repository-name>

• rename the business central reference with a meaningful name (bc)

  $ git remote rename origin bc

• consolidate in one single commit on a new branch called team

  $ git checkout -b team
  

• push the new team branch in the shared server

  $ git push -u shared team

  optionally add -u flag to set shared as default remote repository for pushing

The other developers clone the shared repository and align their Business Central:

• create a repository in their Business Central
• clone the shared repository

  $ git clone -b team ssh://<shared-git-host>/<repository-name>

• rename the shared repository reference with a meaningful name (shared)

  $ git remote rename origin shared

• create a branch called master

  $ cd <repository-name>
  $ git checkout -b master

• add the remote reference to the dedicated Business Central

  $ git remote add bc ssh://<shared-git-host>/<repository-name>

• push the master branch in their Business Central

  $ git push -uf bc master

Sharing an update

As general rule of thumb, it’s better to share as soon as possible a coherent change.

When a user wants to share something, he can follow this procedure:

• synchronize the team branch

  $ git checkout team
  $ git pull

• pull the Business Central content

  $ git checkout bc
  $ git pull

• squash all Business Central changes in the team branch

  $ git checkout team
  $ git merge --squash master

• add the changes and commit

  $ git add -A
  $ git commit -m "some useful comment"
  $ git push

• throw away the sandbox history and reset the Business Central on top of the team commit

  $ git checkout master
  $ git reset --hard team
  $ git push -f

The worst thing that can happen during this procedure is stumbling across a conflict to be merged manually. If it’s caused by plain text file (Java, deployment descriptors, DRL files), the user should be able to merge it, otherwise the simplest thing to do is picking one of the two and reapply manually the changes from the other. This can be painful and error prone, so to avoid this emergency practice, the team should be as much as possible in synch using a informal communication channel e.g. using a team chat message.

Conclusion

Unless of really simplistic organization where just casual users work on a project, the Business Central cannot be the central repository that the name could suggest.

In this article, the reader has learned how to use the Business Central GIT interface to exchange files or to share the content with a “blessed GIT Repository”.