Version Control

As a developer and object designer, you create and manage multiple versions of an object, export and import these versions to and from a remote repository, rollback changes to a previous version and have access to the Client's commit history. You can synchronize repositories across multiple nodes of a system to access your data and, simultaneously, ensure a collaborative working environment for all developers and object designers.

This page includes the following:

Overview

Using a remote repository and Version Control allows you to back up and properly store different versions of your Client, which you can restore at any point in time. It also allows you to work on your own and collaboratively within a team in a setup with multiple environments. The data stored in a remote repository is not tied to a particular node and is therefore accessible from any node in your system.

You can access the Version Control functionality from the Process Assembly. To be able to use it, you must set up a remote repository, connect it to your system and initialize your Client. Once your Client has been initialized, you can carry out the following operations:

Commit your changes to the remote repository
Merge changes made in other branches to your Client
Rollback to a previous version of your Client
Create a new branch from an existing branch
Pull changes that have been committed to your branch from another client.

Important!

If there is at least one object for which you do not have write (W) privileges, the operation you are trying to carry out is aborted and an error message is displayed. In this case, you can select your changes and can continue with those changes. If you need help with your authorization and privileges, contact your system administrator.

For more information, see :
You can exclude certain objects from being written into the remote repository by using the variable (VARA) object UC_VERSIONCONTROL_EXCLUDE - Exclude Changes from Commit. Excluding objects is useful if you want to avoid overwriting certain configurations or if you want to reduce your export or import volume.

Setting up a Remote Repository

Before you start working with Version Control, you must set up a git repository. You can do it either manually or using services such as GitHub or Bitbucket. To enable communication between the Automation Engine and the repository with an SSH key, you have to generate the necessary SSH keys first. The Automation Engine accepts only RSA, DSA, and ECDSA keys. Key files must be stored using the format PKCS #8.

To create an SSH key in the Automation Engine server and add the public key to your GitHub or Bitbucket account, follow these steps:

Generate the SSH key. Make sure you use a supported format, for example, RSA.

$ssh-keygen -m PEM -t rsa -b 4096 -C "your_email@example.com"
When prompted to enter a file in which to save the key, press Enter.

Enter a file in which to save the key (/home/you/.ssh/id_rsa): [Press enter]

This action accepts the default file location.
When prompted to enter a passphrase, leave it empty.

If you choose the default key name and folder, the result should be similar to this:

Note: Make sure that the known_hosts file has an entry for the GitHub or Bitbucket server. Otherwise Version Control does not work properly.
Add the content of the public key (id_rsa.pub) to the SSH keys in your GitHub or Bitbucket account. For more information, please refer to the GitHub or Bitbucket documentation.

Next, you have to define the REPOSITORY_SSH_DIR parameter (secure connection) to specify the path of the generated SSH keys on the file system of the Automation Engine. You can define it either in the parameter UC_SYSTEM_SETTINGS - Systemwide Settings in Client 0 or in the UC_CLIENT_SETTINGS - Various Client Settings for the relevant client.

If the parameter has been set the system settings (REPOSITORY_SSH_DIR) in Client 0, all the clients in the system use the SSH directory that you want to use when connecting to a remote repository.
If the parameter is set in the client settings (REPOSITORY_SSH_DIR) in a particular client, it overrides the definition in the system settings and this particular client uses the SSH directory that you define here.
If no parameter is defined, the system uses the default SSH directory of the user who is used to launch the Automation Engine on the file system of the operating system.

To enable Version Control, you have to establish a connection between your Client and the remote repository. The REMOTE_REPOSITORY_URLparameter in the UC_CLIENT_SETTINGS - Various Client Settings allows you to define the repository's SSH URL which is needed to establish the connection.

Examples

ssh://git@bitbucket.example.com:7999/example/test_repo.git
git@github.com:example/test_repo.git

Initializing your Client

Initializing your Client allows you to work with the Version Control functionality. Doing so synchronizes your Client's content with the content of a specific branch in your remote repository.

To initialize your Client, select one of the following options:

Create a new branch.

In this case, you export the content of your Client to a new branch in the remote repository. All objects are stored as separate files.
Select a branch already available in your remote repository.

Important! When you select a branch already available for initialization,
- your Client's content is replaced with the content of the branch you have selected, including all users. The users that were exported to the branch remain in the initialized client, but they are locked. They must be unlocked in Client 0 and a new password must be set.
  
  This behavior applies only when using AE authentication. When using LDAP authentication, the users are not locked. For more information, see About LDAP.
- the client must be stopped, otherwise you get an error message.

Committing Changes

Committing changes to the remote repository allows you to add new, modified, or deleted objects as a new version of your Client. To avoid conflicts and keep your Client and the remote repository synchronized, the system fetches the status of the repository and compares it to the status of your Client. The system then highlights the objects that have been modified since the last commit by any of the users in your Client. These changes are listed in the Uncommitted Changes view and are ready to be committed. Once a change has been committed, it is shown in the Commit History view.

Important! Entering a Commit Message is mandatory and it is recommended to describe clearly the changes that are being committed.

Uncommitted Changes List

The Uncommitted Changes list displays all new, modified, and deleted objects that have not been committed to the remote repository yet. You can select one or multiple changes since the last commit. You can also use the Filter functionality to restrict the number of records that are displayed and, for example, display only your changes. The system then verifies whether you have the necessary privileges to do so or not.

The list displays the following columns by default:

Name
Type
Change

Last object change

An object can be new, removed, modified, renamed, or moved.
Last Modified

Date of the last object modification
Modified by

User that modified the object
Archive Key 1 and 2

Archive keywords as defined in the respective object

Click the refresh icon at the top right-hand corner of your environment to refresh the current view.

Using Filters

It is possible to use different filters to customize the content of the Uncommitted Changes list. You can search for the Name and/or Type of an object and for a specific Change.

To Use the Filter Function

Select Filter to open the filter pane.

The Name and Type fields are displayed by default.
Select Add Filter Criteria to add the relevant category to the filter pane.

You can add the following categories:
- Change to select one of the following options:
  - New Object
  - Removed Object
  - Modified Object
  - Renamed Object
  - Moved Object
- Last Modified to select objects modified within a specific time period
- Modified by to select objects modified by a specific user
- Archive Key 1 and Archive Key 2 to search for a specific key
At the bottom of the filter pane, select Filter to apply your filter criteria or Reset to go back to default (unchecked).

Notes:

All these actions are optional.
Select Select all to select all options available and Clear selection to clear all checkboxes.

Commit History List

The Commit History list displays the commit message, the date and time of the commit, and the user that committed the changes. These changes correspond to the branch that is active, which is clearly marked with a green checkmark. You can also see the commit history of other branches by selecting the relevant branch from the drop-down list.

The list displays the following columns by default:

Active

Shows if the commit is part of the active branch
Commit Message
Created date

Date on which the object was created
Created by

User that created the object
Commit ID

Click the refresh icon at the top right-hand corner of your environment to refresh the current view.

From the Commit History view, you can rollback your Client to a previous version, merge other branches into your Client, create a new branch from a specific commit, or pull changes in your current branch from a remote repository into your Client.

Rolling Back to a Previous Version

Rolling back to a previous version is only available for the branch that is currently active.

Important! Keep in mind that the complete content of the Client is restored from the remote repository. This is also true even when, after initialization, the system compares statuses of the repository and the client and highlights only the objects that have been modified. Thus the importance of understanding what happens to the objects when rolling back to a previous version. There are three possible scenarios:

An object exists in the remote repository but not in your Client.

In this case, the object is imported to your Client.
An object exists in both, the remote repository and your Client.

In this case, the object is overwritten with the version from the remote repository.
An object exists in your Client but not in the remote repository.

In this case, the object is deleted in your Client.

The Rollback button is available only if you are in the active branch or if you have selected a commit. After you have selected the relevant commit in the Commit History and clicked Rollback, the system checks if there are any uncommitted changes in your Client. If so, a warning lets you know that all changes since the last commit are lost if you proceed with the rollback.

After successfully rolling back, the new Commit Message is marked as a rollback and includes the commit ID. This ID helps to identify uniquely the rollback, because the commit message does not have to be unique.

Merging Branches to your Client

Merging allows you to incorporate changes that are committed to other branches into the current Client.

Important! Merging can only be initiated from the target branch.

For example, if you are working in a development branch and you have to get the current status of the master branch to test your work, you have to merge the master branch into your (active) development branch. If, after testing, you want to merge your work into the master branch, you must do it from the client that is connected to the master branch.

When you merge content, some objects might present conflicts that you must check before importing them into your Client. In this case, the operation is halted until the conflicts are resolved. You can access the Compare view and go through the conflicts one by one to ensure the best possible resolution of the conflict.

Important: the original version is always the one in the Client you are currently working.

In the Compare dialog, all conflicts are presented side by side. The left pane shows the XML data of the original object and the right pane the XML data of the object as present in the repository. The input field on the top right corner allows you to define how many lines above and below the conflict are shown. This option is especially helpful for large XML files.

You can select one of three options:

Keep Original: this action keeps the original object version in your Client and discards the version from the repository.
Overwrite Original: this action overwrites the original object version in your Client with the version from the repository.
Keep Both: this action keeps the original object version in your Client and also adds the version from the repository separately, adding a suffix to differentiate both versions.

Keeping the original, overwriting the original or keeping both versions automatically results in a new version of the object that needs to be committed to avoid inconsistencies in the system.

Branching

As an administrator, you want to set up new clients based on versions of other clients so that developers can work in a particular environment. You can get such an environment by creating a new branch from a particular commit.

Important! For security reasons, passwords and other encrypted fields are not exported to the repository. When you create a new branch and initialize your Client from another branch, the Client's credentials (such as Login, Connection, User objects) have to be set up again. Also, User objects are locked after being imported into another client and must be unlocked by the system administrator.

In the Commit History view, select the commit to use as basis for your new branch and click New Branch from Selected. The new branch is listed with the rest of the branches available for your Client and has the status of the commit selected.

Pulling

Given that multiple clients can use the same branch, you might have to incorporate some changes that are committed to the active branch into your Client to ensure that your content is up-to-date and synchronized with the repository.

The Pull button is available in the Commit History view of the active branch. In this view, an indicator shows which commit on the active branch corresponds to the current status of your Client. When you Pull, the most recent commit is imported to your Client and the indicator is set accordingly.

Important! You cannot commit changes unless you have the same status of the repository. When you pull and you have uncommitted changes, the system warns you that all uncommitted changes will be overwritten. To keep your uncommitted changes, you can rename the objects or can use the regular export function. For more information, see Importing/Exporting Objects.