V4.x Upgrade Process & Notes

In version 4.0 IMan has undergone some major improvements. This guide is designed to assist you in planning the upgrade.

This guide does not replace the existing upgrade guide, it works in conjunction to assist you through the upgrade.

License Change Notice

Per previous email notices this upgrade changes the 'Unlimited' license.

Please consult the following notification for further information.

Sites With Test Licenses

Sites with test licenses should upgrade the primary server first. The test or additional servers will then inherit the integration count from the primary server.

TLS 1.2 Compatibility & Check

Introduced in this version is the requirement that TLS 1.2 security protocol is present on the server.

It is imperative that you have run windows update after any Windows Components/Prerequisites have been installed.

TLS compliance can be checked by pressing the appropriate button on this utility.

If successful the check will respond display a corresponding message (as shown below).

V4 Upgrade Checker

Bundled in the download is a program which allows you evaluate the job configuration update process against all the integrations on the current machine.

This should be run prior to an upgrade so that you're aware of any changes.

To run the program simply launch it after you have downloaded the v4 installer, then press the Check button.

Message Results

These flag up known conditions and changes, with a link to the page indicating the change.

Error Results

These flag up unknown conditions and changes which may indicate that an error will occur during the integration update.

If the upgrade process fails for any reason, it may be necessary to contact Realisable for a resolution.

Duplicate Field Mappings

In previous versions the connector transform would occasionally mangle the mappings, resulting in a field being mapped twice, but IMan would continue to work.

Due to the changes in the version the upgrade process will result in an error (as per the following).

Where an error is reported the following actions should be taken prior to upgrading.

  1. Open the integration in the designer. Open the transform as per the error.
  2. Go to the Field Mapping tab, change to the Transaction Id per the error.
  3. Unmap each of the fields reporting the error.Since there are duplicates there may be more than one field mapping to the reported field. Prior to unmapping the field any logic should be noted as it will need to be reinstated after the upgrade process.
  4. Repeat steps 2-4 for each transform.
  5. Upgrade the integration and then map the field and reinstate any logic for the field in the subsequent transforms.

Non-unique Hashcodes

The following error is typically the result of the manually editing configuration files.

To remedy the error we recommend identifying the field within the integration, remove it from the transform altogether, re-add the field and restore any logic.

The following points provide direction on various strategies. Each of strategies follows the same pattern by removing the field from a transform, which in turn removes the field from all following transforms.

It is thereforce necessary to find the transform reporting the error and work backwards through the transform logic to find the first transform where the field can be removed.

The following steps should be followed for any field being removed:

  • Note any logic the fields participates in i.e. Formulae, mapping, audit reports.
  • Remove the field(s), per below.
  • Upgrade the integration.
  • Reinstate the field(s) and any logic.

The following describes the possible course of action dependent on where a field has been added to an integration.

  • Hierarchy Transforms - If a field has been added through a hierarchy transform e.g. in a new child record, the field can be removed from the child record. Similarly, the field can be deselected and re-added from the field mapping of the hierarchy transform. The latter strategy removes the field from the hierarchy and subsequent transform. Re-adding the field ensures the uniqueness as this is a function of IMan.
  • Flatten Transforms - Fields can be deselected and re-added from the field mapping of the flatten transform. This removes the field from the flatten and subsequent transform. Re-adding the field ensures the uniqueness as this is a function of IMan.
  • Map Transforms - If a field has been added through a map transform, the field can be deleted and re-added. Re-adding the field adds it by ensuring its uniqueness.
  • Connectors - Fields can be unmapped and re-added from the field mapping of a connector. Unmapping the field removes it from the connector and subsequent transforms. Re-mapping the field adds it by ensuring uniqueness.
  • Read Transforms - As a last resort fields can be removed from the entire integration by removing them from their source i.e. the Read transform(s).

Other Error Messages

If the upgrade process fails for any reason, it may be necessary to contact Realisable for a resolution.