Git Integration Plugin - Xyna-Factory/xyna GitHub Wiki

The Git Integration Plugin provides functionality to connect a Workspace with a Git repository and coordinate shared developement.

In order to work with the Git Integration Plugin, three major steps need to be done:

1. Installing the Plugin
2. Setting up a Git repository
3. Configuring the Workspace connection with the Plugin

The following chapters describe how to implement these steps.

Table of Contents Installing the Plugin Setting up Git repository Creating Workspace-XML Setting up Git repository Workspace Connections Adding a Workspace Connection Removing a Workspace Connection Credentials Workspace Configuration Synchronization between local and remote Workspace Managing the Workspace Configuration Pushing changes Switching branches Refresh Workspace

• .\xynafactory.sh importapplication GitIntegration.VERSION via CLI (with the version name substituted for VERSION) to import a current version of the Application GitIntegration
• .\xynafactory.sh stop Stop the Factory
• In server/server.policy, near the end of the file, but before permission com.gip.xyna.XynaUsagePermission, add the following lines:

permission java.nio.file.LinkPermission "symbolic";

permission java.lang.RuntimePermission "accessUserInformation";

• .\xynafactory.sh start Start the Factory
• XynaBlackEdition/install_black_edition.sh -b In the directory with the Xyna installer, reinstall the bash completion to add new CLI commands from the plugin for auto completion via the tabulator key
• source ~/.bashrc Rerun .bashrc (or restart console) to make code completion available

To setup the repository, the following steps are necessary:

If not already done, create the Workspace you want to share and optionally add Workflows and other XMOM-Objects to it.

The Plugin needs a serialized version of the Workspace Configuration written into one or more files to be committed to the repository. This is necessary for comparing the condition of the local and the remote version of the Workspace, as explained below in Synchronization between local and remote Workspace. These files can be created via the CLI, using the command createworkspacexml. There are two variants in which this information can be stored:

1. ./xynafactory.sh createworkspacexml -workspaceName WORKSPACE_NAME -f -s The meta data is distributed among multiple files (one of them named workspace.xml), being stored in revisions/rev_REVISION/config. Force (-f) is necessary, because the Workspace is not connected, yet.
2. ./xynafactory.sh createworkspacexml -workspaceName WORKSPACE_NAME -f All meta data will be stored in the file workspace.xml.

Variant (2) is only recommended for small Workspaces.

Keep in mind: This information - regardless of being stored in only a file workspace.xml or distributed between that file and some others - is commonly referred to as Workspace-XML, regardles of the mode being used.

• Create a folder for the server repository, e.g. xyna_001/repo/server/gittest and switch to it
• git init Initialize a new repository
• Create a folder for a client repository, e.g. xyna_001/repo/client1 and switch to it
• Clone repository to be used by a client: git clone file://[...]/repo/server/gittest
• Switch to the correct branch, e.g. git checkout -b main
• In case you haven't set up your Git user, yet:
  • git config --local user.email "MAIL_ADDRESS" with your e-mail-address substituted for MAIL_ADDRESS
  • git config --local user.name "NAME" with your name substituted for NAME
• Add XMOM objects and meta data from your Workspace to the repository
  • Create an appropriate directory structure in your local clone - e.g. create workspaces/WORKSPACE_NAME in xyna_001/repo/client1 (with the name of your Workspace for WORKSPACE_NAME)
  • Copy the meta data from your Workspace to this directory - e.g. cp -r /opt/xyna/xyna_001/revisions/rev_REVISION/config /opt/xyna/xyna_001/repo/client1/gittest/ (with REVISION being the revision number of your Workspace, as shown via listworkspaces -t)
  • Copy the XMOM XMLs - e.g. cp -r /opt/xyna/xyna_001/revisions/rev_REVISION/saved/XMOM /opt/xyna/xyna_001/repo/client1/gittest/
  • Add, commit and push the folders:
    • git add .
    • git commit -m "MESSAGE" with a commit message for MESSAGE
    • git push (execute git push --set-upstream origin main when pushing for the first time)

To manage shared developement in a Workspace with the Git Integration Plugin, a Workspace Connection needs to be added. This allows to sync changes to the Workspace, which can be:

• Changes to the Workspace content (Workflows and other XMOM-Objects)
• Changes to the Workspace Configuration

If you already have the Workspace in your Factory, delete it to be able to re-add it via the Plugin as a connected repository: ./xynafactory.sh removeworkspace -workspaceName "WORKSPACE_NAME" -c with WORKSPACE_NAME substituted by the name of your Workspace

Next, you can add the Workspace connection - either via the CLI command addrepositoryconnection or in the Factory Manager, as shown in the following screenshots:

After clicking Add Workspace Connection in the GitIntegration section of the Factory Manager, you need to enter the path to your repository. You can either specify a Workspace you want to add in Workspace Name (Optional) or set the checkbox Full (Optional) to add all Workspaces that are stored at the specified path.

Hint: The content of a connected Workspace is not stored in a directory in revisions/rev_REVISION. Instead, it is stored in the local repository you specified during adding and revisions/rev_REVISION is just a symbolic link.

In case you need to remove a Workspace Connection, you have to do this via the CLI:

./xynafactory.sh removerepositoryconnection -d -workspace WORKSPACE_NAME The parameter -d leads to the Workspace also being deleted.

In order to push changes, you need to set up your git credentials. This can be done in the GUI as shown below.

The entered credentials will be used for commits to your Git repository. You need to enter at least the user name and the e-mail-address.

In addition to the contained XMOM-Objects, a Workspace has settings that make up the so-called Workspace Configuration. These settings are:

• Runtime Context Requirements
• Application Definitions
• Trigger and Trigger Istances
• Filter and Filter Instances
• Order Input Sources
• Order Types
• Setup for Storables (which DB tables/columns to use)
• References to used libraries in Data Types and Service Groups

The current Workspace Configuration can be written in a Workspace-XML, as described in Creating Workspace-XML. When changes are done to the Workspace Configuration, the Workspace-XML is not up-to-date, anymore. This is important for the synchronization with the remote version, which is going to be described in the following chapter.

The plugin manages three versions for synchronization, as shown in the following picture.

• Local Factory manages the Workspace. The Workspace Configuration is stored within the Factory, while the XMOM Objects are stored in your local repository and just linked from revisions/rev_REVISION.
• Remote Repository holds the current version of the Workspace in the Git repository. In that version, the Workspace Configuration is represented by a Workspace-XML, because for the repository, a serialized file-based version is necessary.
• Local Repository holds the XMOM Objects and a pending version of the Workspace Configuration to negotiate changes in either direction.

To check for changes to the Workspace Configuration and sync them in either direction, click the Button "manage config". This will give you the following view:

The shown Workspace Xml Status can be one of the following:

• Local changes There are differences between the local Workspace Configuration and the negotiating Workspace-XML.
• Remote changes There are differences between the remote Workspace-XML and the negotiating Workspace-XML that is stored in your local repository.
• Synchronous There are no differences.

You can trigger a comparison between the Workspace-XML in your local repository and the Configuration of your local Workspace via the button Compare workspace-xml and current config. In case this will lead to a status other than Synchronous, you will get a difference list. For instance, changing a Requirement of your Workspace would lead to this situation. Clicking the button Show in that list will let you handle this difference, as shown in the following screenshot.

Here you can resolve the conflict by deleting the additional dependency that you have in your local Workspace Configuration. That would reset your local changes. Alternatively, you can click Overwrite workspace-xml with current config which will persist the Workspace Configuration from your Factory in the Workspace-XML in your local repository, leading to a new status Remote changes. You can then push those changes via the button push.

If you have changes to your Workspace (either to the contained XMOM objects or the Workspace Configuration), you can push them via the push button. Here you can see the changes, select the ones you want to push and enter a commit message.

You can switch to a different Git branch - e.g. to create your changes in a separate feature branch. This can be done via the checkout button.

After adding a workspace connection, the workspace appears empty. To sync the workspace with the file system, first compare the Workspace-XML with the current config and resolve all runtime context dependency differences. This ensures that the workspace is property connected and has access to all objects it depends on. Next, execute the refreshworkspace command from the cli: ./xynafactory.sh refreshworkspace -d -workspace WORKSPACE_NAME. That will register all xmom objects. Finally, you can resolve the remaining differences between the Workspace-XML and the current workspace configuration.

When pulling remote updates from the repository, new xmom objects are deployed and removed xmom objects are deleted automatically. You do not need to execute refreshworkspace again.