VCS: Example Setups

The plugins described in the Integration Endpoint Plugins topic (here) can be used in several different scenarios and do not necessarily have to be used together. This section describes two different possible setups.

System Comparison

It is possible to use just the outbound integration endpoint plugins to have the configuration from each system in a DTAP environment published to different branches in a remote Git repository allowing for easy (manual) comparison of configurations using the 'diff' tools Git offers.

Systems can publish their configurations with scheduled intervals or on demand either via workbench or by invoking the outbound integration endpoints remotely via REST (resource operation available in the STEP REST API V1).

Such a setup can be used to ensure systems are in sync or only have expected differences. If differences are found, STEPXML files held in the Git branches can manually be imported one by one on a system that needs to be updated, or alternately, multiple files can be zipped and supplied to an inbound integration endpoint configured to use the 'STEPXML Joiner' pre-processor described in Integration Endpoint Plugins > Inbound Integration Endpoint 'STEPXML Joiner' Pre-processor Plugin here.

Note: The VCS integration functionality offers no automatic dependency handling meaning that it is the responsibility of the user transferring files to ensure that all files necessary to create / update configuration objects are included and, given that the 'STEPXML Joiner' pre-processor is not used, that files are imported in the correct order.

A tool like Jenkins https://jenkins.io/ could, with this setup, be used to monitor the branches for changes. With a monitoring tool, diff reports can be sent to users via mail.

Branch comparisons can be made using the Git command line tool (refer to, for example, https://git-scm.com/docs/git-diff), or if a tool like Bitbucket is used, via a web interface as shown below.

Semi-automated System Synchronization

With a tool like Jenkins configured to monitor branches for changes, instead of just sending diff reports to users, a Jenkins job could be used to automatically keep systems in sync. The diagram below illustrates a setup where changes on STEP system 'SYS A' automatically are deployed on another STEP system 'SYS B'.

For this to work, a Jenkins job must monitor the 'SYS A' branch for changes, and when such changes are identified, compare the branch with the 'SYS B' branch, produce a .ZIP file containing files from the 'SYS A' branch that differ, and then pass the .ZIP file to an inbound integration endpoint on 'SYS B' configured to use the 'STEPXML Joiner' and 'Invoke OIEP' plugins.

Example Jenkins job 'Build' shell script ($gituser, $gitpassword and $sysbpassword, $sysbuser defined via 'Username and password (separated)' bindings):

#!/bin/bash
timestamp=$(date +%s)
gitserver='bitbucket.org/john-smith/step-conf.git'

sysbstepserver='sys-b.domain.com'
hotfolder='/upload/hotfolders/ConfigurationManagement/in'


git clone https://$gituser:$gitpassword@$gitserver checkout_$timestamp
cd checkout_$timestamp
git checkout $sys-b
git checkout $sys-a
git pull
git diff -z $sys-b..sys-a --name-only --diff-filter=ACMRT | xargs -0 zip cpg_diff_$timestamp.zip
sshpass -p $sysbuserpassword scp cpg_diff_$timestamp.zip $sysbuser@$sysbstepserver:$hotfolder

The Jenkins job could further, via REST, invoke the inbound integration endpoint on 'SYS B' and monitor the import process, notifying human users if errors occur. Alternately, the inbound integration endpoint could be scheduled to run frequently, and an error reporter plugin could be used to notify users about errors.

Note: For a setup like this, be aware that the 'STEP Importer' processing engine cannot handle all updates. Refer to the VCS: Considerations and Limitations topic for more information here.