Upgrading

Version 20.0.7488


Upgrading



ArcESB 2020 is the latest version of several earlier application releases, including the following:

  • IP*Works! EDI AS2 Connector V7 (/n software)
  • AS2 Connector V2 (/n software)
  • AS2 Connector V3, FTP Connector V1, OFTP Connector V2, and SFTP Connector V1 (RSSBus)
  • RSSBus Connect 2016, 2017, 2018, and 2019

Upgrading From RSSBus Connect 2016, 2017, 2018, or 2019

This section describes the simple process of upgrading from an earlier release of ArcESB or RSSBus Connect.

For help upgrading from an earlier version than RSSBus Connect 2016, please begin with the next section.

Drop-In Upgrade

Upgrading to ArcESB 2020 from RSSBus Connect 2016, 2017, 2018, or 2019 can be a one-step in-place upgrade. Simply run the ArcESB installer to update application resources (.exe’s, .dll’s, .jar’s, .war’s) without disturbing configuration data.

If the ArcESB installer detects an RSSBus Connect installation, the installer uses this same installation path to store configuration data (profile, connectors/ports, certificates). Thus, the settings from older versions are automatically used by the new ArcESB installation.

Manually Transferring Configuration Data

If an in-place upgrade is not possible, configuration data can still easily be transferred from previous versions of ArcESB/RSSBus Connect.

The first transfer method is to export connector (port) settings from the older version and import these connectors (ports) in the new version. Connectors (ports) can be exported from the Ports tab by clicking the cogwheel and selecting ‘Export Port Settings’. In later versions of RSSBus Connect, connectors (ports) can be exported from the Flows tab by right clicking the connector (port) in the flow and selecting ‘Export Port Settings’. Connectors can be imported from the Flows tab of ArcESB by clicking the cogwheel in the top-right and selecting ‘Import Workspace’.

The second method transfers all configuration data at once by managing folders on disk. All configuration information is held in the ‘data’ folder of the installation directory. Copying over the ‘data’ folder from a previous version into the same folder in the latest version will effectively copy over the entire application configuration.

The default installation directory for ArcESB is:

Windows: C:\Program Files\ArcESB
Java: ~/arcesb

The default installation directory for RSSBus Connect is:

Windows: C:\Program Files\RSSBus\RSSBus Connect
Java: ~/rssbus/connect

On a Unix system, ‘~’ resolves to the home directory of the user where the Java servlet is installed. On a Windows system, ‘~’ resolves to %ProgramData%.

Note: If you do not see the ArcESB installation directory, check for the RSSBus Connect default installation directory. The ArcESB installer will attempt to detect RSSBus Connect installations and use the pre-existing folder structure from RSSBus Connect.

Upgrading Application Data Source Connectors

ArcESB introduced a new approach to connecting to external data sources that are applications rather than traditional databases (e.g. SalesForce, NetSuite, QuickBooks, etc). In RSSBus Connect, each external data source application required a dedicated connector (port) to interface with the application. In ArcESB, a single connector called the CData Connector is used to connect to each application data source.

CData Drivers

The CData Connector uses CData drivers to connect to a specific data source. CData is our parent company, and they provide the ADO.NET and JDBC drivers that enable connectivity to hundreds of cloud and on-premise applications, databases, and more. These drivers were used under-the-hood in previous RSSBus Connect connectors (ports), so the interface and approach to accessing data in these application data sources has not changed.

In order to upgrade this set of connectors (ports) to ArcESB, the appropriate CData driver must be installed and configured in a CData Connector. Please see the CData Connector documentation for details on installing CData drivers. Once the CData driver is installed and selected within the CData Connector’s settings, the CData Connector can be configured with the same connection settings and credentials that were used in RSSBus Connect connectors (e.g. the SalesForce Connector, the HubSpot Connector, etc).

Preserving Input and Output Mappings

After establishing a connection with the CData Connector, Input and Output mappings can easily be copied over from RSSBus Connect to ArcESB. Each mapping is stored on disk as an XML file that can be copied from its original location to the ArcESB CData Connector.

To find the mappings XML files, first locate the ‘data’ directory in the RSSBus Connect installation. By default, this directory is located here:

Windows: C:\Program Files\RSSBus\RSSBus Connect\data Java: ~/rssbus/connect/data

Each connector (port) in RSSBus Connect has a dedicated folder within the data directory; open the folder for the application connector (e.g. the SalesForce Connector, HubSpot Connector). Inside this folder is a ‘Templates’ folder that holds the Input and Output mappings. Make a copy of this ‘Templates’ folder for use in the next step.

ArcESB uses the same folder structure as RSSBus Connect (a ‘data’ directory that includes a dedicated folder for each connector configured in the application). Navigate to the ‘data’ directory for ArcESB, open the folder specific to the CData Connector, and replace the ‘Templates’ folder with the copied ‘Templates’ folder from the previous step.

Note: When ArcESB is installed, it will attempt to detect an RSSBus Connect installation and use the exact same folder paths as RSSBus Connect. In this case, the CData Connector folder will be in the same data directory as the old application connectors. Otherwise, the default data directory location for ArcESB is as follows:

Windows: C:\Program Files\ArcESB\data Java: ~/arcesb/data

After the ‘Templates’ folder has been copied into the CData Connector’s dedicated data directory folder, refresh the ArcESB UI to see the mappings available in the CData Connector settings panel.

Connector Settings

Aside from the Input and Output Mappings, the connector settings from RSSBus Connect’s application connectors must be re-configured in the CData Connector.

Upgrading External Connectors

A small number of connectors were moved from embedded in RSSBus Connect to external in ArcESB. If your RSSBus Connect flow includes the following connectors, a simple additional download is required to add the connector to ArcESB:

  • SQL Server
  • Oracle
  • PDF

Once ArcESB is installed, these connectors will have a red exclamation point in the flow, indicating that they need to be added to the application’s library. Simply find the appropriate connector in the list of downloadable connectors, download the installer, and run the installer to make the connector available in the application.

Upgrading from AS2 Connector

This section also applies to upgrading from FTP Connector, OFTP Connector, and SFTP Connector.

Installing ArcESB

Windows Users

The Windows installation of ArcESB will target a different installation path than earlier versions of the product and listen on a different port. This ensures that both releases can be run side by side without conflicting with one another. Simply run the setup.exe and follow the prompts to install the application on the machine.

Java Users

As with previous versions of the AS2 Connector (and other releases in the Connector family), the application is provided as a distributable arcesb.war file. If you distribute this WAR file to your Java server using the server’s built-in deployment wizard, this replaces your existing installation of the AS2 Connector in its entirety, including trading partner profiles.

If you want to perform an in-place upgrade of the AS2 Connector and still preserve your profile settings between installations, create a copy of your previous installation’s data folder prior to deploying the new package. This data folder is located in the /WEB-INF/data/ folder under the existing Web application folder. Once you have copied this folder into a new location, deploy ArcESB in place of the existing installation. When launching the application for the first time, the connectors (ports) are not configured. Click Import Profiles to specify the location where you copied your data folder to restore your profiles.

Alternatively, you can rename the arcesb.war provided with ArcESB to install this version of the application as a parallel application.

Importing Profile Information

If you are upgrading from an earlier version of the AS2 Connector, SFTP Connector, or other previous versions, there are several methods available to detect and import your existing partner profile configurations.

Import Automatically

If you are installing the Windows edition of ArcESB on a machine where a previous version of the application was installed, the installation program attempts to detect the installation of the previous version and can import the profile settings from it. If a partner profile is detected that is of the same name as one already configured in ArcESB, this process will create a duplicate entry with a number appended to the identifying field to ensure that it is unique. You can safely delete duplicate profiles after they are imported.

Import Using the importProfiles API

ArcESB’s Admin API includes an importProfiles action that can be used to import settings from previous versions. The importProfiles action requires two parameters:

  • DataDirectory - The location of the data folder where old profile/partner configuration is stored, and DuplicateAction must be the
  • DuplicateAction - How ArcESB should respond if an imported profile/partner configuration causes a conflict with the current configuration (valid values are ‘Overwrite’, ‘Rename’, and ‘Skip’)

All requests to the importProfiles action must be sent as HTTP POST requests.

The following is an example importProfiles request that can be entered directly into a web browser:

http://localhost:8001/api.rsc/importProfiles?DataDirectory=C:\\Program Files\\RSSBus\\RSSBus Server\\data&DuplicateAction=Skip&@x-http-method=POST

More information about the Admin API can be found in the Admin API section.

Configuring a Transparent Upgrade

After running the installer for ArcESB and importing partner profiles from a previous installation of the application into ArcESB, the new version has backwards compatibility for receiving URLs in the old version. However, there are two key differences:

  1. ArcESB uses a different local port than the application server used to host the previous installation of the application. This avoids conflicts with the installation of a previous version of the AS2 Connector so that you can maintain both versions of the application and transfer partners to the new version at your own pace.

  2. The Incoming, Outgoing, and Sent Folders from the previous installation of the AS2 Connector are not automatically imported into the profiles used in ArcESB. By default, the application uses its own local file resources so as not to interfere with the currently running instance of the application. This also ensures that, if automation is enabled in the previous profile, the application does not immediately begin sending files that are waiting to be sent in the older version of the AS2 Connector.

If you want to replace your instance of the AS2 Connector:

  1. Determine whether you want to use the old folder structure from the previous installation of the AS2 Connector or use ArcESB’s default folder structure.
  2. Determine whether you wish to use your existing receiving URL or a new one.

Keeping Your Previous Folders

If you do not plan to add trading partners or configure additional connectors in ArcESB, it may be easiest to point ArcESB to the same folders used in the previous installation of the application. You can configure the Input/Send, Output/Receive, and Sent Folders for the new connectors (ports) to point to the old locations in the Advanced configuration tab for each connector (port).

This lets you integrate with the local file system using the same resources that you used previously, but if you add additional connectors in the future, the application creates these in a different data folder by default.

Advantages

  • The existing back-end business logic is preserved for configured trading partners.

Disadvantages

  • Additional connectors use a different data folder by default.

Switching to Use the New Folders

If you plan to add more partners or configure additional connectors in ArcESB, it may be best to switch to the new folder structure that ArcESB uses by default. This structure is described below.

The directory where ArcESB is installed contains a data folder that contains all connector and profile configuration data. Each configured connector in ArcESB has its own folder within this data folder. The connector-specific folder contains the following folders:

  • Locks - A folder for maintaining file locks on files processed by the connector; this folder should not be touched.
  • Logs - A folder where the connector will write connector-specific logs.
  • Pending - Connectors that wait for a partner response will store pending messages in this folder (only certain connector types require this).
  • Receive - Connectors that receive/download files from an external source will place those files here. Connectors that operate on local data (without sending or receiving from an external source) will place files here after they are processed.
  • Send - Files placed in this folder are slated to be processed/sent/uploaded by the connector.
  • Sent - The connector places a copy of processed/sent/uploaded files here.

For AS2 Connectors, place files that should be sent to external trading partners in the connector’s Send folder, and pick up files received from external trading partners in the connector’s Receive folder.

Advantages

  • A consistent folder structure will be maintained if additional trading partners are configured.

Disadvantages

  • Business logic may need to be reconfigured to use the new folder structure.

Using a New URL

The server provided with ArcESB listens on different ports and uses different URLs for receiving AS2 transmissions than earlier releases. After you import your profiles into ArcESB, you must update your trading partners so that they are sending to your new Receiving URL.

By default, the server provided with ArcESB listens in plaintext on port 8001 and uses SSL/TLS on port 8401. You can find the Receiving URL by clicking Profile > AS2 Profile

Advantages

  • Transition trading partners at their own pace.
  • No downtime.

Disadvantages

  • Trading partners need to change your URL in the profile configuration on their end.
  • An additional port must be opened on the firewall.
  • Both versions of the application are maintained.

Using the Existing URL

To receive requests on the same URL that is used by the previous version, stop the server hosting the previous version so that the same port can be assigned to ArcESB. You also need to assign the server to the same port that you were using for the previous version. You can configure the port by right-clicking the icon in the system tray and then clicking Server Options. The application automatically recognizes requests to resources that were supported in previous versions of the application (/as2connector/pub/ReceiveFile.rsb and /Receiver.aspx, for instance) and forwards them to the appropriate resources in ArcESB.

Advantages

  • Trading partners do not need to change profiles.
  • Maintain one system.

Disadvantages

  • Downtime while old server is stopped to free up a port for the new server.
  • Existing profiles must first be imported.

Note: If the port that you configure is an SSL/TLS-enabled port, you also need to configure the same SSL/TLS certificate that was used for the previous version of the AS2 Connector on this port. If you were previously hosting an SSL/TLS port in ArcESB, the same certificate store is the location of SSL/TLS certificates in ArcESB (the local machine’s personal account).

After you configure ArcESB to use the same port that you used in older versions of the application, you start receiving incoming transmissions at the folders configured above.

Upgrading an RSSBus Connect Amazon AMI

ArcESB 2020 has a dedicated AMI that can be downloaded from the AWS Marketplace and used to create a new ArcESB 2020 instance. Preserving settings from an RSSBus Connect AMI to a new ArcESB AMI requires exporting configuration settings from the old instance and importing these settings in the new instance.

In addition, older RSSBus Connect instances require an extra step in order to export configuration settings in a way that can be read by the new instance. To determine if this extra step is required, launch the RSSBus Connect application, navigate to the About page, and note the build number recorded on this page.

Builds Older Than (Less Than) 7073

Instances with builds older than 7073 need to update to the latest archived build of RSSBus Connect before exporting configuration settings.

  • Navigate to the download archive and download RSSBus Connect 2019 (Java Edition)
  • SSH into the current AMI
  • Stop the service running the application with the command: sudo systemctl stop jetty
  • Clean up the folder where the application is deployed with the command: sudo rm -Rf /opt/rssbus/work/*
  • Extract the rssbus.war file from the .zip file downloaded in the first step
  • Navigate in the command prompt to the directory where the rssbus.war file was extracted and run the following commands to replace the old .war file:
    • sudo rm /opt/rssbus/webapps/rssbus.war
    • sudo cp rssbus.war /opt/rssbus/webapps/rssbus.war
  • Start the service to run the application: sudo systemctl start jetty

The latest build of RSSBus Connect 2019 is now installed, and you can follow the export and import steps in the next section.

Builds 7073 or Later

Note: The steps described in this section will ensure that configuration settings remain the same during the upgrade. However, the configuration settings do not include data files processed by the application and log files for previous transactions. In order to preserve all application data, please follow the instructions for copying application folders directly from the filesystem in our Back Up and Migrate ArcESB guide. To make a persistent copy of the relevant folders (‘data’, ‘workspaces’, ‘db’), they must be copied from the Amazon VM to a local machine via a transfer protocol like SFTP or SCP; then, the same folders must be transferred back to the VM after the AMI upgrade has completed.

The following steps will export configuration settings from the old version:

  • Launch RSSBus Connect (if necessary) and log into the administration console
  • In the application UI, navigate to the Flows page and use the cogwheel in the top right to Export Workspace
    • Ensure that the checkboxes for ‘Include profile settings’, ‘Export all workspaces’, and ‘Export Private Info’ are checked
    • Save the resulting .zip/.arcflow export file for later import in the new instance

The following steps import the configuration settings previously exported:

  • Download the new (ArcESB) AMI and use it to launch a new instance
  • Log into the ArcESB administration console in the new instance
  • Navigate to the Flows page
  • Use the cogwheel in the top right to Import Workspace and navigate to the .zip file exported previously
    • Alternatively, drag the exported .zip/.arcflow file onto the Flows page canvas and click ‘Import’ in the resulting modal

After following these steps, ArcESB will preserve the configuration settings from the previous RSSBus Connect instance.