General Guidelines for Migrating AgilePoint Server to New Hardware

Objective

General Guidelines for Migrating AgilePoint Server to New Hardware

Summary

Below are some general guidelines to be considered when migrating AgilePoint Server to new hardware. The goal is to ensure a smooth migration and reduce production server downtime. Most likely, you will encounter more unexpected issues, this documentation will continue to be updated based on feedback from customers and support interactions.

NOTE: For upgrading AgilePoint to a newer version, please refer to the upgrade documentation that is specific to the AgilePoint version that you want to upgrade.

Details

Migrating AgilePoint Server to new hardware is not exactly the same as a fresh installation, as most likely you will have customizations (e.g. custom configurations in IIS/custom components) that exist in your existing server configuration which would not be carried over in a standard fresh installation. It is best practice for your AgilePoint System Administrator to keep AgilePoint system profile documentation up to date with information about your AgilePoint system and configuration for project transition, system administration, upgrades, etc. It is highly recommended to have this information on hand ahead of time before even attempting the hardware upgrade in a testing/staging environment. It is also common that you will identify more issues to be addressed during the upgrade in the testing/staging environment, the goal is to not be addressing these issues when upgrading in your production environment. Below are some items your AgilePoint System Administrator should have documented in the AgilePoint system profile list. The items below have been deliberately separated by AgilePoint related topics and custom business specific requirements. The custom business specific requirements are specific to your company's environment and are more difficult for Ascentn to pinpoint and document, this is the job of your AgilePoint System Administrator, not Ascentn Support.

AgilePoint Related Information

Are there any AgilePoint specific information or data elements such as files that will need to be transferred to the new machine? For example:

  • Backup the AgilePoint Server netflow.cfg file
  • Gather custom component AgileParts, AgileWorks, AgileConnectors, and AgileStubs
  • Backup AgilePoint Server and AgilePoint Enterprise Manager web.config files
  • Document the User name and password for Domain/System User account to run AgilePoint
  • Document the AgilePoint workflow database name, location, and authentication information
  • Gather the key/mission critical process templates.

For more information on specific AgilePoint related files and configurations, refer to the latest AgilePoint Pre-Installation Check List and Installation Guide.

Internal Business Specific Requirements

Are there any company policies/environment specific items that may affect the AgilePoint Server installation? For example:

  • Your company might have a strict security policy on new hardware where all files are read-only.
  • When setting SPN, you need a few days to get the approval.
  • Antivirus related issues for email correspondence.
  • Firewall

This type of information is specific to each individual business environment and needs to be determined by your AgilePoint System Administrator before installing AgilePoint Server. A few examples are provided above, however there may be more issues to consider.

Ideally, the testing/staging server should be exactly the same as the production server on many aspects (e.g. hardware/software/security for machine and application). As a high level concept, we recommend if you are planning a hardware upgrade in your production environment, perform a hardware migration in your testing environment first to document the impacted areas of the change in hardware and to identify potential issues. This can be done by substituting a new piece of hardware in your testing/staging environment. This hardware does not necessarily need to be as powerful as the new hardware for your production environment. You may also recycle old machines by re-formatting, or creating a Virtual PC, then it becomes 'new hardware' for AgilePoint. One exception is if you plan to do stress testing/benchmarking in the testing/staging environment, you probably will need a more powerful machine (this will also require production keys vs. temporary keys as temporary keys are limited to one thread and will hinder stress testing results). Make note of all the issues and resolutions while performing the migration in your testing/staging environment so that you have reference material when doing the same migration in the production environment later. Plan ahead if there are any items that require longer time to prepare/get approval. After you are satisfied with the testing/staging environment, then perform the same migration to the targeted new hardware in your production environment.

Steps for Migrating AgilePoint Server to New Hardware in Testing/Staging Environment:

  1. Backup the AgilePoint workflow database (whether or not it resides on the machine targeted for the hardware upgrade).
  2. Install AgilePoint Server on the new hardware. Refer to the AgilePoint Pre-installation Check List and Installation Guide for installing and configuring AgilePoint Server on new hardware. Contact Ascentn Support if you do not have this documentation.

    NOTE: If you are using a temporary key temporarily for your new hardware migration in production, once the testing in finished, it is important to apply the permanent key to the new hardware before allowing your end users to start using the new hardware. This is because temporary AgilePoint license keys are setup for only single thread processing, therefore using temporary AgilePoint license keys is not recommended for high performance/high volume transactions. You may run into issues like a process only being initiated after a long time or an action is only performed after a long time, and usually end users report those as not able to initiate process/perform the action. Contact Ascentn Support for instructions on replacing temporary AgilePoint license keys with permanent AgilePoint license keys.

  3. Deploy the pre-existing netflow.cfg file to the new machine.
  4. (Optional) Deploy the pre-existing AgilePoint Server and AgilePoint Enterprise Manager web.config files. This step is required if you have made customizations to your AgilePoint Server and AgilePoint Enterprise Manager web.config files.
  5. Point the AgilePoint database to your testing database (not the production database) using the AgilePoint Server Configuration Utility.
  6. If you are using SharePoint, and AgilePoint Server and SharePoint are on the same machine, and you are using AgilePoint v3.x or earlier, you will need to deploy the pre-existing AgilePointSettings.xml file to the new hardware.
  7. Migrate all of your custom components (i.e. AgileParts, AgileWorks, AgileConnectors, and AgileStubs) from the old hardware to the new hardware.
  8. Identify all the key/mission critical process templates that are running on your old server hardware. Deploy and test these process templates on the new hardware (i.e. initiate the process and run the process until the STOP activity). This is to capture any hard-coded items in the process templates custom components (if any) and any special privileges needed for the custom components.
  9. If you plan to use name mapping (DNS mapping/Fully Qualified Domain Name, FQDN/host header/etc.) for your production server, perform name mapping testing on the new hardware in the testing environment too. Then test AgilePoint on the new hardware, for example:
    1. Initiate a process by using the mapping URL (submitting a document/form to SharePoint or via your custom application) from a client machine.
    2. Make sure a process can move from one activity to the next activity, until the process is completed (i.e. reaches the STOP activity).
    3. For Manual Activities, make sure the UI behaves as expected.
    4. For Automatic Activities, make sure it executes as expected.

    NOTE: Migrating the other AgilePoint Suite components to new hardware is straight forward and is not much different than performing a fresh installation. One thing to note is if you are using SharePoint integration and AgilePoint v4.0 or later, remember to reconnect to the SharePoint integration database, refer to SharePoint installation instructions for more information.