Running the RA Web Service SOAP Agent Migration Assistant

Use the RA Web Service SOAP Agent Migration Assistant to migrate RA Web Service Agent version 3.x Job and Connection objects. By converting SOAP job objects, the referenced connection objects are converted automatically during the same conversion run. The tool converts objects by client. Start the tool separately for each client where SOAP objects have to be converted to version 4.

Requirements

The RA Web Service SOAP Agent Migration Assistant requires: 

  • AE v12+ (because RA Web Service SOAP Agent is compatible with Automation Engine v12+).
  • Objects to migrate must be from RA Web Service Agent version 3.x.
  • Use Java 1.8 for starting the Migration assistant.

Prerequisites

Before running the Migration Assistant:

  1. Backup everything and test the migration on a separate system before performing it on your production data.
  2. File system based WSDL references in connection objects must be manually changed to URLs before the migration.

Running the Migration Assistant

To run the a migration:

  1. Stop all Agents that are involved in the migration process.
  2. Make sure no RA Web Service Agent Jobs are running during the migration process.
  3. Install the new RA Web Service SOAP Agent v4.

    4. RA Web Service Agent v3.x and RA Web Service SOAP Agent v4 can be installed side by side on the same system if those versions are supported on that Automation Engine version. For information on which Rapid Automation Agents are supported on with which Automation Engine versions, see the Automic Compatibility Matrix.

  4. Unzip the contents of the migration-assistant.zip file to the local file system.

    5. Contents and folder structure

    • bin: converter tool
      • WS3Converter.jar
    • conf: configurations files
      • uc4config.xml: parameters for the connection to your Automation-Engine
      • login_dat.xml: login credentials for establishing a session to a specific Automation-Engine client.
      • migrationconfig.xml parameters for the migration run such as the name of objects to convert from version 3 (wildcards supported)...
  5. Execute WS3Converter.jar.

    6. WS3Converter.jar Command Line Parameters

    java -jar WS3Converter.jar [-c <path to uc4config.xml>] [-l <path to login_dat.xml>] [-m <path to migrationconfig.xml>]

    The optional parameters can be omitted if the configuration files are located in the conf directory (default).

    Use java -jar WS3Converter.jar -h for parameter help.

    • When configuration files are located in conf directory (default).
      • Edit the configurations files in conf directory according to the examples below.
      • Change directory to bin and run the following command line in a terminal or in a command prompt:

        • java -jar WS3Converter.jar

        When prompted, enter the password according to the credentials specified in login_dat.xml.

    • When configurations files are not located in conf directory, but somewhere else in the files system.
      • Edit the your configurations files according to the examples below.
      • Run the following line in a terminal or in a command prompt (paths for configuration files are provided by command line parameters):

        • java -jar WS3Converter.jar -c C:\Automic\uc4config.xml -l C:\Automic\Automation.Platform\login_dat.xml -m C:\Automic\migrationconfig.xml

        When prompted, enter the password according to the credentials specified in login_dat.xml.

Example Configuration Files

uc4config.xml

<?xml version="1.0" encoding="ISO-8859-15"?>

<configuration>

<timeout>60</timeout>

    <connections>

        <connection name="Default Connection" system="SYSTEMNAME">

            <cp ip="localhost" port="2217"/>

        </connection>

    </connections>

</configuration>

login_dat.xml

<?xml version="1.0"?>

<login>

    <default>

        <login src="adm">

            <system>AUTOMIC</system>

            <client>100</client>

            <name>USER</name>

            <department>DEV</department>

            <language>E</language>

        </login>

    </default>

</login>

migrationconfig.xml

<?xml version="1.0" encoding="ISO-8859-15"?>

<configuration>

    <migrationConfig>

 

        <!-- Name or name filter for WebService SOAP 3 object(s) to convert. Wild cards characters "*" and "?" are supported. -->

        <convertWS3Objects>JOBS.WEBSERVICE.*</convertWS3Objects>

 

        <!-- Set this parameter to 'true' if you want to replace your existing WebService SOAP 3 objects with the converted WebService SOAP 4 objects. -->

        <replaceWS3Objects>false</replaceWS3Objects>

 

        <!-- Name-suffix for creating new WebService SOAP 4 objects in case of replace is 'false'. -->

        <nameSuffix>.WS4</nameSuffix>

 

        <!-- Optional WebService SOAP 4 agent name. If no value is set, an online WebService SOAP 4 agent will be taken. -->

        <ws4Agent></ws4Agent>

 

    </migrationConfig>

</configuration>