Microsoft A4SWIFT 2.1 Service Pack 1 Installation Guide
[image]

The Microsoft® BizTalk® Accelerator for SWIFT (A4SWIFT) 2.1 Service Pack 1 (SP1) for BizTalk Server 2004 consists of the updates that have been made since the release of A4SWIFT 2.1. This service pack is a prerequisite for installing the SWIFT 2006 Message Pack for A4SWIFT 2.1.

This document provides guidance on the installation process to ensure minimum downtime, as well as a description of some of the updates. For a complete list of the updates in the service pack, see Knowledge Base article 922264 at http://go.microsoft.com/fwlink/?LinkId=73925.

Prerequisites

The following are prerequisites for installing the service pack on BizTalk Server 2004:

  • You must install the software update for the issue described in KB article 922264 referenced previously.

  • Back up your A4SWIFT 2.1 database before applying the service pack. For more information, see http://go.microsoft.com/fwlink/?LinkId=72873.

Caution
The service pack updates the A4SWIFT 2.1 database to the A4SWIFT 2.1 SP1 schema. This updated database schema cannot be rolled back by uninstalling the service pack. The schema is, however, compatible with a configuration where the service pack has been uninstalled.

  • Back up any files under the %programfiles%\Microsoft BizTalk Accelerator for SWIFT folder that you have made changes to. This could include items such as any customized schemas and Microsoft Office InfoPath 2003 forms.

  • Back up the Assemblies folder under %programfiles%\Microsoft BizTalk Accelerator for SWIFT\Assemblies before installing the service pack. This is required if you uninstall the service pack to restore the system to the state it was in before the service pack was installed.

Important
Any customizations to your A4SWIFT artifacts must be reapplied after installing the service pack.

Installation

Follow these basic steps to install the service pack:

  1. Undeploy the BizTalk Rules Engine (BRE) rules using the BRE Deployment utility, and manually delete the A4SWIFT vocabularies A4SWIFT_CODELIST and A4SWIFT_Functions using the Business Rule Composer tool in BizTalk Server 2004.

  2. Undeploy any projects or assemblies that have references to one or more of the following A4SWIFT 2.1 assemblies:

    • Microsoft.Solutions.FinancialServices.SWIFT.FrrOrchestration

    • Microsoft.Solutions.FinancialServices.SWIFT.FrrSchemas

    • Microsoft.Solutions.FinancialServices.SWIFT.MrsrService

    • Microsoft.Solutions.FinancialServices.SWIFT.RuntimeSchemas

  3. Undeploy all A4SWIFT assemblies in the following order:

    • Microsoft.Solutions.FinancialServices.SWIFT.FrrOrchestration

    • Microsoft.Solutions.FinancialServices.SWIFT.FrrSchemas

    • Microsoft.Solutions.FinancialServices.SWIFT.MrsrService

    • Microsoft.Solutions.FinancialServices.SWIFT.RuntimeSchemas

    Note
    When undeploying the MrsrService.dll you may receive an error similar to the error listed below:

    “Some items in the removed assembly are still being used by items not defined in the same assembly, thus removal of the assembly failed. Make sure that items in the assembly you are trying to remove fulfill the following conditions:

    1. Pipelines, maps, and schemas are not being used by Send Ports or Receive Locations.

    2. Roles have no enlisted parties."

    To correct this error, follow these steps:

    a. Log on to the BAS Web site using an account belonging to the BAS Administrators group.

    b. Click the Agreements link under Trading Partner Management Tools in the left pane, and deactivate all A4SWIFT MRSR-related agreements, including the MRSRDefault_Unparsed agreement.

    c. Undeploy the Microsoft.Solutions.FinancialServices.SWIFT.MrsrService after performing steps a and b.

  4. Download and run the service pack.

  5. Update the InfoPath forms in the A4SWIFT 2.1 installation folder. If you have run the FormPublish tool prior to installing A4SWIFT 2.1 SP1, it is likely that existing SWIFT InfoPath forms have a timestamp that is more recent than files in the SP1 package. In this case, you will need to manually extract the SP1 InfoPath forms:

    • Open the Temporary folder on the home directory created during the package extraction.

      Note
      This step must be performed BEFORE clicking Next in the Installation Wizard. The path to which the files are extracted is indicated by a momentary progress dialog box titled Verifying Package.

    • Unzip the SWIFT InfoPath Forms.zip file provided with the installation package.

    • Copy all the InfoPath forms from the file to the A4SWIFT 2.1 installation folder, overwriting any existing InfoPath forms in the folder.

  6. On the computer running Microsoft SQL Server™ that hosts the A4SWIFT database, execute the script QFERollupDbUpdate.sql against the A4SWIFT database. The script is located in the %programfiles%\Microsoft BizTalk Accelerator for SWIFT\Scripts folder.

  7. Unzip the SWIFT InfoPath Forms.zip file provided with the installation package. Copy all the InfoPath forms from the file to the A4SWIFT 2.1 installation folder, overwriting any existing InfoPath forms in the folder.

  8. Manually redeploy the A4SWIFT assemblies in the following order:

    • Microsoft.Solutions.FinancialServices.SWIFT.RuntimeSchemas

    • Microsoft.Solutions.FinancialServices.SWIFT.MrsrService

    • Microsoft.Solutions.FinancialServices.SWIFT.FrrSchemas

    • Microsoft.Solutions.FinancialServices.SWIFT.FrrOrchestration

  9. From the %programfiles%\Microsoft Biztalk Accelerator for SWIFT\SDK\Tools\ folder, run RepairBAS.exe.

    Note
    If after running RepairBAS.exe the A4SWIFT partner profile agreements are not active, verify whether the Partner profiles have been deployed. If not, deploy all the required partner profiles and then activate the agreements for those partners manually.

  10. Rebuild and deploy any projects or assemblies that you had previously used with A4SWIFT 2.1.

    Note
    If you have made any customizations to SWIFT artifacts, reapply those changes before you deploy.

  11. Redeploy the BRE rules for your schema projects by using the A4SWIFT BRE Deployment utility.

  12. If you customized any schemas under the %programfiles%\Microsoft BizTalk Accelerator for SWIFT\SWIFT Messages\A4SWIFT 2.1 folder, make the same changes after applying the service pack.

  13. If you have published any InfoPath forms, you must remove and republish the forms. At a command prompt, navigate to %programfiles%\Microsoft BizTalk Accelerator for SWIFT\SDK\Tools folder and run FormPublish.exe –d. This will unpublish your previous forms. Then republish the new forms by running FormPublish.exe –p.

  14. Restart the Rule Engine Update service and the BizTalk Service on all your computers, including the server hosting BAS.

  15. Back up the Assemblies folder after the service pack is installed. This is required if you must uninstall the service pack and restore the system to the state it was in before the service pack was installed. Back up all files including the following:

    • Microsoft.Solutions.FinancialServices.SWIFT.MRSR.Interfaces.dll

    • Microsoft.Solutions.FinancialServices.SWIFT.MRSR.Utilities.dll

Configuration

After applying the service pack, the new recommended setting for the SWIFT Disassembler pipeline property “Treat blank lines as parse errors” is False. This allows errors to be caught by XML validation and passed as valid in the case of MT586 field 70F.

This is a change from the previously recommended setting. In A4SWIFT 2.1 and A4SWIFT 2.3 the recommended setting for the pipeline property “Treat blank lines as parse errors” is True. This setting was recommended for the following reasons:

  • When the SWIFT accelerator received messages that contained an empty CrLf delimited field, an empty node was created in the resulting XML. If the schema level attribute suppress_empty_nodes was set to True, the BizTalk parser would strip this node from the XML losing the information in the original message.

  • When the message was sent to Message Repair, the message could be deemed structurally invalid if the missing nodes were required nodes. Message Repair would be unable to repair the XML because InfoPath cannot load XML documents with structural errors.

To address these issues, we applied the following updates to the service pack:

  1. All schemas were changed to have the schema-level attribute suppress_empty_nodes set to False.

  2. The SWIFT Disassembler component was changed so that only empty nodes that did not represent data in the original message are removed. The A4SWIFT schemas have some fields that are zero length: examples are the TextBlock fields at the end of the header and StartOfBlock and EndOfBlock fields for certain message sections. The SWIFT Disassembler was changed to remove empty nodes that represent schema-level zero length fields, while leaving any that represented data in the original message intact.

Many SWIFT messages have narrative fields that are delimited by CrLf and must contain one or more non-whitespace characters to be valid. These fields are represented in the schema with fields that either have a minLength set to one (1), or a validation pattern that requires one non-whitespace character, or both. The MT586 field 70F is the only exception where the SWIFT specifications allow an empty field. Before the updates, the “Treat blank lines as parse errors” pipeline property always flagged this field as invalid when it was empty.

Uninstalling Service Pack 1

There are two sets of uninstall instructions, which correspond to the following environments:

  1. The environment has software updates that are related to MCRR that were released after A4SWIFT 2.1.

  2. The environment has A4SWIFT 2.1 with no additional Accelerator software updates.

Select the instruction set that corresponds to the environment in which the service pack was installed:

Environment a: Additional software updates

  1. Before uninstalling Service Pack 1, back up the A4SWIFT database and all changes to the custom MRSR SDK artifacts.

    Note
    The schema and InfoPath artifacts can also be backed up. However, many of the changes that could be made to artifacts after applying the service pack are not supported for A4SWIFT 2.1 SP1.

  2. Uninstall any schema assemblies and BRE rules that might have been deployed.

    Note
    You must manually delete A4SWIFT_Codelist and A4SWIFT_Functions vocabularies. These are not removed by the BRE Deployment utility.

  3. Run the FormPublish utility to undeploy all existing forms and form templates from the BAS Web site.

  4. In Add/Remove Programs in Control Panel, use the Remove option for the BizTalk Accelerator for SWIFT 2.1 Service Pack 1 entry to uninstall the service pack.

  5. Deploy the following assemblies to the GAC from the backup assembly folder:

    • Microsoft.Solutions.FinancialServices.SWIFT.BreValidator.dll

    • Microsoft.Solutions.FinancialServices.SWIFT.CommonFunctions.dll

    • Microsoft.Solutions.FinancialServices.SWIFT.FrrHelper.dll

    • Microsoft.Solutions.FinancialServices.SWIFT.MrsrConfiguration.dll

    • Microsoft.Solutions.FinancialServices.SWIFT.MrsrHelper.dll

    • Microsoft.Solutions.FinancialServices.SWIFT.Shared.dll

    • Microsoft.Solutions.FinancialServices.SWIFT.ValidationMessages.ErrorLookup.dll

    • Microsoft.Solutions.FinancialServices.SWIFT.ValidationMessages.ErrorResources.dll

  6. After uninstalling Service Pack 1, overwrite the existing InfoPath forms with the InfoPath forms you backed up.

  7. Deploy the following assemblies to the GAC from the backup created during step 14 of the installation steps.

    • Microsoft.Solutions.FinancialServices.SWIFT.MRSR.Interfaces.dll

    • Microsoft.Solutions.FinancialServices.SWIFT.MRSR.Utilities.dll

  8. Republish the InfoPath forms using the FormPublish tool.

  9. Recompile and deploy the schema assemblies using the schemas in the A4SWIFT directory after uninstalling.

  10. Deploy the BRE policies using the BRE Deployment utility.

  11. Restart the BizTalk Host service and BRE deployment service.

Environment b: No additional software updates

  1. Before uninstalling Service Pack 1, back up the A4SWIFT database and all changes to the custom MRSR SDK artifacts.

    Note
    The schema and InfoPath artifacts can also be backed up. However, many of the changes made to artifacts after applying the service pack are not supported in a pre-service pack environment.

  2. Uninstall any schema assemblies and BRE rules that might have been deployed.

    Note
    You must manually delete A4SWIFT_Codelist and A4SWIFT_Functions vocabularies. These are not removed by the BRE Deployment utility.

  3. Run the FormPublish utility to undeploy all existing forms and form templates from the BAS Web site.

  4. In Add/Remove Programs in Control Panel, use the Remove option on the BizTalk Accelerator for SWIFT 2.1 Service Pack 1 entry to uninstall the service pack.

  5. Restore files which were backed up prior to installing the service pack.

    • Overwrite the existing InfoPath forms with the InfoPath forms you backed up.

    • Republish the InfoPath forms using the FormPublish tool.

    • Recompile and deploy the schema assemblies using the schemas left in the A4SWIFT directory after uninstalling.

    • Deploy the BRE policies using the BRE Deployment utility.

  6. Restart the BizTalk Host service and rule engine deployment service.

Known Issues

  • Custom MRSR: Upgrading to BizTalk Server 2006 and A4SWIFT 2.3 when A4SWIFT 2.1 SP1 has been installed will overwrite some of the contents of the Custom MRSR folder.

  • You must undeploy and redeploy all the SWIFT assemblies as specified in the installation section. To support in-progress orchestration instances, follow the side-by-side deployment guidelines recommended by BizTalk Server 2004 and re-version your dependent application assemblies. This will help provide a clean side-by-side experience. In the event that you cannot undeploy any of the SWIFT assemblies due to existing deployments and in-progress orchestration instances, follow the guidelines below to deploy A4SWIFT 2.1 SP1.

    • FrrSchemas and FrrOrchestration assemblies do not have any changes in SP1 and can simply be stored in the GAC if they cannot be undeployed prior to installing SP1.

    • RuntimeSchemas.dll contains the property schemas and SWIFTHeader schemas. The SWIFTHeader schema has a "MessagePriority" element under the "ApplicationHeaderBlock_Output" record that is changed from an optional element to a mandatory element. If you choose to simply store this assembly in the GAC, it is possible that existing MRSR orchestration instances may fail to parse the message if they try to use the new RuntimeSchemas.dll from within the orchestration.

    • For any new outbound SWIFT messages that are processed, the new runtime schema causes a message to suspend if the message is an outbound message and has the "MessagePriority" element missing. In A4SWIFT 2.1 this field was optional on the SWIFTHeader schema in RuntimeSchemas.dll and mandatory on all other message schemas. This means that even if such a message were to have passed though the pipeline it would have been suspended when the message was parsed by the actual message schema. Note that the RuntimeSchema is only used to detect the message type. A message must be parsed using the schema of its type to produce a valid output xml. Existing MRSR instances will be affected if both of the following conditions are met:

    1. The MRSR instance is processing an Outbound message that has the mandatory "MessagePriority" field missing.

    2. A direct bound port is used from the orchestration to process this message that uses the latest version of RuntimeSchemas.

  • MrsrService.dll: This assembly can be applied to the GAC without redeploying.

Copyright

Information in this document, including URL and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted in examples herein are fictitious. No association with any real company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

© 2006 Microsoft Corporation. All rights reserved.

Microsoft, MS-DOS, Windows, Windows Server, Windows Vista, and BizTalk are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

All other trademarks are property of their respective owners.