How to automate package import to a local Integration Server

Introduction

When developing in teams on larger projects it is a common task after the setup of a new local service development to retrieve already existing packages from version control and import them to the yet empty local workspace. As with webMethods the code resides in the server an additonal step is required, making the packages known to the local development server. This can be done by right-clicking the project associated with the package in the Designer and select "Move package to IS", but for larger projects with many packages it is better to automate this process.

As "Move package to IS" just creates a symbolic link in the package directory of Integration Server, this can be done via a script which contains the floowoing commands:

  • mklink /j <targetLocation> <sourceLocation> [for windows]
  • ln -s <sourceLocation> <targetLocation> [for mac and linux]

Nota Bene: The support for windows junctions created with the mklink /j command has been introduced with Service Development Plug-in to Designer 10.3 Fix 16  to Designer, so you need at least this version and patch level in order to have this working on Windows.

The ANT script can be found on Github: https://github.com/SoftwareAG/webmethods-integration-examples/tree/master/localdev_tools_importPackages2IS

Integration Server vs. Microservice Runtime

In this article we use Integration Server and Microservice Runtime synonymously.

With version 10.5 there have been 2 major changes to microservice runtime, which have to be taken into account if your local development server is a Microsrevice Runtime:

Platform Manager has been removed: This means a Microservice runtime can not be managed after installation via Command Central. As the Microservice Runtime is primarily intended for runnin in a containerized environment, this is usually not needed.

Instances have been removed: As Microservice Runtime is primarily intended for running in a containerized environment, multiple instances in one installation does not make much sense.This results in a different directory for the packages:

  • Integration Server: [webMethods.home]\IntegrationServer\instances\default\packages
  • Microservice Runtime: [webMethods.home]\IntegrationServer\packages

Prerequesites

Designer Workstation 10.3 or higher.

For Windows:

  • Local Version Control Integration Plug-in to Designer 10.3 Fix 14 or higher
  • Service Development Plug-in to Designer 10.3 Fix 16 or higher

How it Works

Import of existing IS packages into a local workspace

To get a versioned IS package into the local Integration Server as a local service development package, 2 things have to be done:

  • Import the package directory as project into Designer with Import project from the Git perspective (This can be done for multiple packages at once).
  • Create symbolic links in the package directory of Integration Server pointing to the package directories in the git directory.
    • mklink /j <targetLocation> <sourceLocation> [for window]
    • ln -s <sourceLocation> <targetLocation> [for mac and linux]

Afterwards either a restart of IS or an activation and reload of the packages is required.

The provided ant sript automates the creation of the links for a windows environment, as this is the most common os for developers (can be easily adjusted to linux), and activates the packages afterwards, so only the refresh of the development server view in Designer remains.

The original script was written by Biswa Bhusan Dalai (Software AG).

Disclaimer: The services used for package activation and package reload are not part of the documented build in services and may be changed in a future version without prior notification.

Step by step instruction

  1. Clone/checkout your repository
  2. Setup of the script for a project
  3. Move your packages to Integration Server

If this is the first setup of your local development environment, you need to Clone/checkout your repository and import all the package and tooling directories as eclipse projects.

Setup of the script for a project usually only needs to be done for every project, although there may be minor adjustements to be done later on, but these should be done centrally for the whole project

If the packages are known to eclipse either by importing them in the previous step or because the Deisgner Workstation has been re-installed and they already exist in the local workspace, the packages need to be moved to the Integration Server.

Clone/checkout your repository

Start Designer and select a local workspace. In this part we assume we do not have the packages in the local Designer workspace. Otherwise continue with Move your packages to Integration Server.

After a fresh installation the local Integration Server only contains the standard packages.

In Designer, open the Git perspective you can either add the local directory holding your packages directly

or you can use the Git perspective to clone the Git repository holding the packages of you project directly.

Keep in mind that the local Git directory should be outside the Eclispe/Designer workspace.

Every Integration Server package is its own Designer project. In this example we already have an additional tools project holding the common scripts and assets for ther overall project. If a tools project (or similar) does not yet exist, create one. Right-click all package directories and the tools directory and select Import Projects.

They will now be visible as Eclipse projects in the Package Explorer, but not yet in the Package Navigator as the packages have not yet been imported to the local Integration Server.

Setup of the script for a project

If you do not have the files import_IS_packages.xml and build.properties, copy them to the tools project.

Open the file  import_IS_packages.xml in the ANT editor. Check the following settings

property integration-server-packages, this points to the package directory of your local Integration Server

  • For Integration Server and Microservice Runtime 10.3
    <property name="integration-server-packages" value="${webMethods.home}\IntegrationServer\instances\default\packages" />
  • For Microservice Runtime 10.5 and higher
    <property name="integration-server-packages" value="${webMethods.home}\packages" />

Ant classpath: check if the correct ant library is referenced:

    <path id="classpath.ant">
        <fileset file="${webMethods.home}/common/lib/ant/ant-contrib-1.0b3.jar"/>
    </path>

Adjust the settings in build.properties to the typical installation in your organization and especially set the list of packages belonging to your project in the correct order.

Move your packages to Integration Server

If this hasn't been done before, check/adjust the settings in build.properties to your local installation. If you already did this before and only re-installed your local Designer Workstation, the settings probably can remain the same.

Execute the ant task with the default target import-multiple-packages

In the Service Development Perspective right-click on the local Integration Server and select Refresh.

The packages are now loaded and visible in the Package Navigator:

To try it out make a local change

Save the changed service, right-click on it in Service Navigator and select "Compare Elements with - Revision" and select latest Revision to open the flow compare editor.