products versions - {webMethods Integration Server version: 10.15 and above}
Introduction
In a previous article, we introduced Our new delivery channel, webMethods Package Manager and described how this now cli tool can be used to share and distribute both your own custom packages and install Software AG licensed packages.
Here we will expand on this and explain how you can use wpm and git version control to allow developers to collaborate and develop packages, ensuring that after installing a package with wpm, they can then commit changes back to the git repo via the git command or the “teams” feature in Service Designer.
Pre-requisite
- That you have already read and followed the first article on wpm Our new delivery channel, webMethods Package Manager
- Installed and configured the wpm cli tool as described in the above article.
- Have a GitHub id.
- Installed Service Designer.
Steps to follow
The following steps will show you have to get your own packages into GithHub so that they can be version controlled and then explain the steps in order for another developer to download the package using wpm, and then commit changes via git.
Create a new package and get it into GitHub
To get your own package into a Git repository you will need access to the packages folder of your local development environment and a GitHub account.
First, in GitHub create a new git repository and name it the same as your package, and do not initialize it with a README as the repository will need to be empty. After creation, you should see something like the following
You can follow the instructions other than the “add” command, but first make sure that you are at the root level of your package, before running the commands
$ cd <SAG_HOME>/IntegrationServer/packages/MyGreatPackage
$ git init
$ git add .
$ git commit -S -m "Moving my package to a git repo for the first time!"
$ git branch -M main
$ git remote add origin https://github.com/............
$ git push -u origin main
The -S option on the commit command ensures that the update is cryptographically signed, but will require that you have shared a GPG key/pair with your git account (Github docs on signing commits). You can remove it if you haven’t done this, but I would recommend configuring it especially if you want to share the package with the outside world as it will allow you to verify the version and reassure the developers who want to use your package.
Once done reload the web page and you will see that the commands have been replaced with your package contents.
You will notice that in the above screenshot, the package is documented thanks to the included README.md file. As of webMethods 10.15, a README.md file is created automatically when creating a new package and we would recommend that you regularly update this file to help other developers better use your package. For packages created with older versions of webMethods just create the file manually beforehand.
Install the package using wpm
You can of course install the package into any other developer environment using the git clone command from directly in the packages directory e.g.
$ cd <PATH_TO_LOCAL_REPO>
$ git clone https://github.com/............
However, you can also use wpm for convenience and consistency, the advantage being if you use a package registry then you do not need to know the specific git details for a given package. Out of the box wpm allows you to pull packages, but not push changes because it does not retain the git metadata. You can override this with the -lr (local repository) option when using the install option.
$ wpm install -u johnpcarter -p <DEVELOPER_ACCESS_TOKEN> -r https://github.com/<GIT_ID> -l <PATH_TO_LOCAL_REPO> MyGreatPackage
Create a folder on your computer and use that above to replace ‘PATH_TO_LOCAL_REPO’. After the command had completed you will see a subfolder with the name of the git repo from where you pulled your package. You can check whether git is working by running the following command from the command line in the created directory.
$ git status
On branch main
Your branch is up to date with 'origin/main'.
nothing to commit, working tree clean
Make the Designer aware of your local repository.
You now have your local repository either via the git clone command or wpm, but it still needs to be linked to Service Designer. To do this open the git repository perspective in Service Designer.
Then add your local repository, by clicking on “Add an existing local Git repository”, then browse to the above folder that you created and select it.
Then select the git repository for your package as shown below and click add.
The next steps are to create a project for your package and then make it recognized as a package in the package navigator
Add the package explorer to your git perspective if not yet visible, click on Window → Show View → Package Explorer.
From that view you will see a project with the name of your package, now you need to ensure that it is recognized as a webMethods package, by right-clicking and selecting “Move Project to IS Package”.
One more setup step is required, but you only have to do this once for your environment and not each time you add a package. That is to ensure that your workspace is updated whenever files change of the file system, you can do that from the Designer → Settings → General → Workspace and check the option “Refresh using native hooks or polling”
Without this, your package navigator won’t show the correct git icons or status when making changes.
Finally, you can switch back to the service perspective, you should have an icon in the toolbar as of now. The Package Navigator view will now show your new package and include the git indicator “round dot” to show that the package is under version control.
To commit or pull changes use the “teams” menu from the context menu of any asset within the package. For instance to commit changes for a service, right-click → “Team” → “Commit”
If committing verify that the service assets appear correctly in the staged section, enter a description for your commit and click on the “commit and Push” button
The designer will ask you to enter your git credentials the first time, remember to use a developer access token and NOT your personal password. If your commit is successful the stage area will appear empty and the git icon next to your service will revert to normal.
NOTE Do not attempt to pull changes using the wpm update command, instead using the team menu and the pull option.
Compare code changes with flow services
This part is optional but I thought I would add it as it is a really cool feature, but unfortunately little known. It is possible to compare changes made to your flow services between commits, branches, or tags in your git repository. However, do not use the “Compare with” option next to the team menu. This implementation is the default Eclipse option and will show you the differences between the raw XML files of your flow service assets.
We have added our option in the context menu named “Compare Element(s) With” and from there select “Revision”
From there you can browse the commit history for your package and select the commit or branch that you want to compare your current version with.
Next steps
- Setup your own private package registry to make developer collaboration easier.
- Start reusing your packages in webMethods.io Integration.
- learn about git.
Useful links | Relevant resources
Guideline for developing packages in this article - webMethods packages from a developers perspective
Download the latest version of Service Designer - here
Check out available packages - Software AG package registry
Learn more about version control with git - Git tutorial