PHINMS 2.6.00 Release notes

03/11/2006

REvision HISTORY

+--------+----------------+----------------+---------------------------+
| **V    | *              | **Revision**   | **Reason**                |
| ersion | *Implemented** |                |                           |
| \#**   |                | **Date**       |                           |
|        | **By**         |                |                           |
+--------+----------------+----------------+---------------------------+
| 1.0    | Wende Long     | 02/13/2006     | Initial Draft             |
+--------+----------------+----------------+---------------------------+
| 1.1    | Vaughn         | 02/17/2006     | Updates                   |
|        | McMullin       |                |                           |
+--------+----------------+----------------+---------------------------+
| 1.2    | Michele Bowman | 03/11/2006     | Edits                     |
+--------+----------------+----------------+---------------------------+

TABLE OF CONTENTS

[1 Introduction 4](#introduction)

[1.1 Objective 4](#objective)

[1.2 Scope 4](#scope)

[1.3 Definitions, Acronyms and Abbreviations
4](#definitions-acronyms-and-abbreviations)

[1.4 References 4](#references)

[2 About This Release 5](#about-this-release)

[2.1 Compatible Products 5](#compatible-products)

[2.2 New Installs 5](#new-installs)

[2.3 Upgrades 6](#upgrades)

[3 FUNCTIONALITY 9](#functionality)

[3.1 New Features 9](#new-features)

[3.2 Defects Resolved In The Following Releases
10](#defects-resolved-in-the-following-releases)

[3.3 Known Bugs and Limitations 11](#known-bugs-and-limitations)

[4 FILES LIST 13](#files-list)

[5 FOLDERS LIST 14](#folders-list)

[Appendix A -- Using AutomatED UPGRADE feature
15](#appendix-a-using-automated-upgrade-feature)

[Appendix B -- Sending A Message Manually Using PHINMS Console
17](#appendix-b-sending-a-message-manually-using-phinms-console)

[Appendix C - PHINMS Upgrade Validation Checklist
19](#appendix-c---phinms-upgrade-validation-checklist)

# Introduction

## Objective

The purpose of the Release Notes is to communicate the major new
features and changes in the PHINMS version 2.6.00 software. It also
documents known problems and workarounds. This document is for users,
developers, and the IT support operation staff.

## Scope

This document describes new features and changes made since PHINMS
release 2.5.01.

## Definitions, Acronyms and Abbreviations

  ----------- -----------------------------------------------------------
  PHINMS      Public Health Information Network Messaging System

  CDC         Centers for Disease Control and Prevention

  MTDC        Middle Tier Data Center
  ----------- -----------------------------------------------------------

## References

  ------------------------------------------ -----------------------------------------------------------
  **Document or Site Name**                  **Location**

  PHINMS_2.6.00_Installation_Guide.doc       Documents Page

  Quick How Tos                              [www.cdc.gov/phin/phinms](http://www.cdc.gov/phin/phinms)
                                             Click on the PHINMS Installation link and then follow the
                                             Quick How To links.

  PHINMS 2.6.00 Software Online Help         not yet published
  ------------------------------------------ -----------------------------------------------------------

# About This Release

> This release is a major release since 2.5.01 with support of
> seamlessly upgrading from 2.1, 2.5.00 and 2.5.01 to 2.6.00 and the
> ability to send a message manually from the console.

## Compatible Products

This product has been tested on the following platforms with the
following requirements:

1.  Operating systems:

-   Windows 2000 Pro SP4

-   Windows XP Pro SP2

-   Windows 2003 Standard Server SP1

-   Windows 2003 Advanced Server SP1

-   SunOS 5.8(Solaris 8 equivalent)Solaris 8

-   Red Hat Linux release 8.0(Kernel 2.4.20-19.8smp)

2.  Disk space: 250M

3.  Memory: 512M

4.  System privileges: local administrator for Windows platforms,
    regular user on Solaris and Linux.

5.  Certified Databases:

-   Microsoft Access

-   Microsoft SQL Server 2000 SP3

    -   Oracle 9i

    -   MySQL 4.1

    -   HSQLDB 1.8.0

        6.  Application Servers:

```{=html}
<!-- -->
```
-   Tomcat 5.0.19

-   Weblogic Server 8.1 SP4 (on JDK 1.4.2)

    6.  Sender Side Proxy servers:

-   Netscape Proxy server 3.6 SP1 to SP6

-   Squid 2.5 Stable 10

    6.  Receiver Side Proxy Servers

```{=html}
<!-- -->
```
-   Netscape Proxy server 3.6 SP1 to SP6

-   IIS 5.0 with Weblogic 8.1 plugin

-   IIS 5.0 with Jakarta Tomcat Connector 1.2.2, 1.2.3, 1.2.4

-   IIS 6.0 with Weblogic 8.1 plugin

-   IIS 6.0 with Jakarta Tomcat Connector 1.2.2, 1.2.3, 1.2.4

## New Installs

The Installation wizard automatically installs and configures the
following major components:

-   Tomcat 5.0.19 server

-   JDK 1.4.2

-   PHINMS 2.6.00 web applications: Receiver

-   PHINMS 2.6.00 default configuration files and directory structure.

-   "PHINMS" directory in "Program menu", which includes shortcuts to
    start PHINMS 2.6 console and uninstall PHINMS 2.6.

-   Shortcut to PHINMS 2.6 console on user specific desktop.

-   Default database:

    a.  On Windows: MS access database, registered as "PhinmsgAccessDSN"
        under ODBC Data Source Administrator/System DSN.

    b.  On Solaris and Linux: HSQLDB 1.8.0 engine.

For Windows platforms, if you select "Install as service", Tomcat 5.0.19
will be installed as Windows service "PHINMS26_Tomcat5" and displays as
"PHINMS 2.6 Apache Tomcat" in the Windows Services panel. This Windows
service is installed as "Automatic" so that PHINMS 2.6.00 web
applications will be started when the machine is started. If PHINMS
2.6.00 is not installed as a Windows service, the end user has to run
\$(Install_directory)/2.6/tomcat-5.0.19/bin/startup.bat to start the
PHINMS 2.6. The "Install_directory" is the directory end users select
for the PHINMS 2.6.00 installation.

On Solaris and Linux platforms, use
\$(Install_directory)/2.6/tomcat-5.0.19/bin/startup.sh to start the
Tomcat server and use
\$(Install_directory)/2.6/tomcat-5.0.19/bin/shutdown.sh to stop the
Tomcat server. To use PHINMS 2.6.00 Console, you need start the Tomcat
server first.

When the Tomcat server is running, you can run the console by doing any
of the following:

-   From the desktop, select "PHINMS 2.6.00 Console."

-   On Windows, select "PHINMS/PHINMS 2.6.00 Console" from "Program
    Menu".

-   From the PHINMS installation directory: on windows run
    \$(Install_directory)/2.6/tomcat-5.0.19/console.exe and run
    \$(Install_directory)/2.6/tomcat-5.0.19/console.bin on Solaris and
    Linux platforms.

The PHINMS console is protected by a username and password by default.
Contact PHINMS help desk
([www.cdc.gov/phin/phinms](http://www.cdc.gov/phin/phinms) and click on
the Contact PHINMS link) for the default console username and password
and then change the default password.

## Upgrades

PHINMS 2.6.00 supports an upgrade from 2.1, 2.5.00 and 2.5.01 to 2.6.00.
To upgrade, during 2.6.00 installation, select "Upgrade from PHINMS 2.1
or 2.5". The next dialog provides end users with:

-   Upgrade 2.1 Sender to 2.6 Sender

-   Upgrade 2.1 Receiver to 2.6 Receiver on Tomcat server

-   Upgrade 2.5.00 or 2.5.01 to 2.6 on Tomcat server

-   Upgrade pre-2.6 Receivers to 2.6.00 on non-Tomcat application server

### Upgrade 2.1 Sender to 2.6.00 Sender

###   {#section .unnumbered}

The Install wizard asks end users to choose and locate the 2.1 Sender's
sender.xml file (e.g. c:\\phmsg21\\config\\sender.xml) from 2.1 Sender
host machine. If the 2.1 Sender was running from windows command window
and it prompted user for "PHINMS Client password" when started, the
2.6.00 upgrade wizard will prompt end users to enter that 2.1 "PHINMS
Client password". Then install wizard will ask end users to select the
directory to install 2.6.00 Sender into, by default it goes into
C:\\Program Files\\PhinMS\\ on windows. The rest of the install wizard
will finish the upgrading for end users with all 2.1 Sender
configuration values copied into 2.6.00. End users don't need to copy
(or re-configure) route map, client certificate, authentication
parameters, Transport Queue database connections and other settings into
2.6.00 installation.

End users need to manually change their applications such as Rhapsody,
eWebIT configuration values, to point to the 2.6.00 PHINMS outgoing
folder. Copy all message payloads waiting to be sent into the new 2.6.00
outgoing folder. The new 2.6.00 outgoing folder is located at
\$(Install_directory)/shared/outgoing/, where "install_directory" is the
directory new 2.6.00 Sender is installed.

###  {#section-1 .unnumbered}

### Upgrade 2.1 Receiver to 2.6.00 Receiver on Tomcat server

Install wizard asks end users to choose and locate the 2.1 Receiver's
receiver.xml file (e.g. c:\\phmsg21\\config\\receiver.xml) from 2.1
Receiver host machine. Then install wizard will ask end users to select
the directory to install 2.6.00 Receiver into, by default it goes into
C:\\Program Files\\PhinMS\\ on windows. The rest of the install wizard
will finish the upgrading for end users with all 2.1 Receiver
configuration values copied into 2.6.00. End users don't need to copy or
re-configure queue maps, service maps, worker queue database connections
and other settings into 2.6.00 Receiver installation.

The 2.6.00 Receiver on Tomcat server listens on HTTP port 5088. If HTTP
proxy was used in front of the existing 2.1 Receiver, end users need
change proxy server settings to forward HTTP traffic to port 5088.

If 2.1 Receiver was receiving messages from a Tomcat redirector, by
default AJP connector is not running on the 2.6.00 Receiver's Tomcat
server. End users need turn on the JK2 AJP 1.3 Connector on port 8009 by
uncommenting connector entry with port 8009 in Tomcat server
configuration file:
\$(Install_directory)/2.6/tomcat-5.0.19/conf/server.xml.

If 2.1 Receiver was saving payload to disk, end users need change their
application processor to pick up payload from new "receiverincoming"
folder, which is located at
\$(Install_directory)/shared/receiverincoming.

###  {#section-2 .unnumbered}

### Upgrade 2.5.00 or 2.5.01 to 2.6.00 on Tomcat server

The Install wizard asks end users to choose the 2.5 components to
upgrade: Sender only, Receiver only or Sender and Receiver. "Sender
only" means an upgrade of existing 2.5.00 or 2.5.01 Sender by install
wizard. "Receiver only" means an upgrade of existing 2.5.00 or 2.5.01
Receiver by install wizard. "Sender and Receiver" means an upgrade of
both Sender and Receiver together and in 2.6.00 end users will have both
Sender and Receiver running.

In the next dialog, the install wizard prompts end uses for "PHINMS
2.5.00/2.5.01 Install Directory", which is the directory end users
installed their PHINMS 2.5.00 or 2.5.01 into. In 2.5.00 or 2.5.01, this
directory is the parent folder of tomcat-5.0.19. Install wizard will
finish the rest of the installation and upgrade for end users without
the need of copying and re-configuring the 2.6.00 Sender or Receiver.

If upgraded a Sender, very important to know that end users have to
manually change their Application's configuration values to point to the
PHINMS outgoing folder. And copy all message payloads waiting to be sent
into the new 2.6.00 outgoing folder. New 2.6.00 outgoing folder is
located at \$(Install_directory)/shared/outgoing/, where
"install_directory" is the directory new 2.6.00 Sender is installed
into.

If an existing 2.5.00 or 2.5.01 Receiver was receiving messages from a
Tomcat redirector, then by default, the AJP connector on the 2.6.00
receiver is not running on the Tomcat server. The end user needs to turn
on the JK2 AJP 1.3 Connector on port 8009 by uncommenting connector
entry with port 8009 in Tomcat server configuration file:
\$(Install_directory)/2.6/tomcat-5.0.19/conf/server.xml.

If 2.5.00 or 2.5.01 Receiver was saving payload to disk, end users need
change their application processor to pick up payload from new
"receiverincoming" folder, which is located at
\$(Install_directory)/shared/receiverincoming.

###  {#section-3 .unnumbered}

### Upgrade pre-2.6 Receivers to 2.6.00 on non-Tomcat application server

If end users decide to run 2.6.00 Receivers on an application server
other than default tomcat server bundled with PHINMS 2.6.00, select this
upgrade option. This upgrade process will generate a WAR file and a
document with installation instructions. Install wizard asks for the
directory on your machine to save the WAR file and instruction document.
Please refer to PHINMS web site for future information on setting up
PHINMS Receiver manually.

# FUNCTIONALITY

## New Features

The following new features appear in the 2.6.00 release:

[Installation]{.underline}

-   New install wizard to provide seamless upgrade from 2.1, 2.5.00 and
    2.5.01 to 2.6.00.

[Core Transport]{.underline}

-   Sender multi-threading support. The sender can process messages
    targeted for different routes concurrently. Processing of the
    message for the same route is still sequential to preserve the
    message delivery order. By default, the sender creates three threads
    to serve all outbound messages.

-   Improved Transport error/retry handling. When there is a transport
    failure when sending to a specific route, PHINMS Sender will mark
    this route as "bad", and skip messages which belong to this route
    and start processing message for other routes. And Sender has a
    timeout set to revisit the messages belongs to the bad route.

-   Chunking and re-composing of Route-not-read Messages. PHINMS 2.6.00
    Sender can send large payload to a destination using chunking, the
    Route-not-read receiving side must be a 2.6.00 Sender and can
    re-compose chunks to generate the original large payload.

-   Message chunking support of Synchronous Message Handler Response
    from Receiver to Sender. In releases prior to 2.6.00, large message
    response from synchronous message handler was sent down to Sender in
    a single block. In PHINMS 2.6.00 Sender, Sender tells the Receiver
    the largest chunks it can receive and Receiver will break up large
    message handler response based on Sender chunk size. Both Sender and
    Receiver have to be 2.6.00 to realize this functionality.

-   On PHINMS 2.6.00 Sender side, log statements are organized based on
    the route name and time stamp. Organized logs can help monitor and
    debug problems of each specific route.

-   Sender's application response file name was
    current-time-in-milliseconds in previous PHINMS releases. Corrected
    in 2.6.00 as response file name plus a timestamp in milliseconds.

-   On 2.6.00 Receiver, the connection and data-read timeout between
    Receiver and synchronous message handler is configurable. The
    required directive in receiver.xml is \<messageHandlerTimeout\> and
    default timeout is 30 seconds (e.g.
    \<messageHandlerTimeout\>30\</messageHandlerTimeout\>). Modifying
    this value through PHINMS 2.6.00 console is not available and end
    users have to manually modify this value and restart the PHINMS
    Receiver for this timeout to take effect.

-   Dual decryption key support. To facilitate a smooth CDC decryption
    expiration and renew process without restarting all PHINMS Senders.

-   Status page of CDC PHINMS Receiver showing time stamp of last
    Heartbeat message received. This status page is currently only
    available at all CDC Receivers. End users will need a client
    certificate to authenticate into CDC for gaining access.

-   The PHINMS 2.6.00 sender inserts a version number in each message
    sent to receivers. PHINMS releases prior to 2.6.00 will ignore this
    version number, while 2.6.00 receivers will capture this version
    number and create a log entry showing the version number of the
    sender as \"Processing message from PHINMS 2.6\". When a 2.6.00
    receiver receives a message from a 2.1, 2.500 or 2.5.01 sender, it
    creates a log statement: \"Processing message from PHINMS 2.1,
    2.5.00 or 2.5.01\". This feature will assist in troubleshooting
    problems when multiple PHINMS versions are used in an environment.

[Console]{.underline}

-   The ability to send a test message from a sender Console to a PHINMS
    receiver.

## Defects Resolved In The Following Releases

### PHINMS 2.1 Bug fixes

-   PHINMS Senders prior to 2.6.00 have high CPU usage when
    authentication against CDC fails. PHINMS 2.6.00 Sender fixed this
    high-CPU usage defect.

-   PHINMS Receiver HTTP connection to synchronous message handler has
    no timeout set, which causes a Weblogic Server deadlock. PHINMS
    2.6.00 Receiver has a configurable synchronous message handler
    timeout to resolve this problem.

-   PHINMS Receiver receives duplicated messages. When Receiver worker
    queue table has been locked and prevents Receiver from inserting
    messages into it, the Receiver will receive and create duplicated
    messages in worker queue. PHINMS 2.6.00 has both in-memory and
    persistent cache to detect duplication and prevent it from
    happening.

-   PHINMS releases prior to 2.6.00 have this bug: when PHINMS router
    returns an "insert failure" and Sender still marks the message as
    "success". PHINMS 2.6.00 fixed this defect so that Sender will mark
    the outgoing message as "failure" after router gives an "insert
    failure".

-   PHINMS Receiver doesn't use persistent cache correctly even after
    creating cache record successfully. PHINMS 2.6.00 Receiver started
    to use persistent cache to prevent message duplication.

### PHINMS 2.5.01 Bug Fixes

-   When adding a database definition for Receiver in PHINMS console,
    the default "pool size" was set to be zero, which prevent Receiver
    from insert records into worker queue. In 2.6.00 PHINMS console, the
    default value is set to be 2.

-   PHINMS releases prior to 2.6.00 have "leaked" one database
    connection from connection pool, causing Receiver to run out of
    connections if database pool size is one. PHINMS 2.6.00 has fixed
    the leak and is able to run with a pool size of one.

## Known Bugs and Limitations

-   Application's configuration for PHINMS Sender outgoing folder has to
    be changed after upgrading 2.1, 2.5.00 or 2.5.01 Sender.

> In PHINMS 2.1, 2.5.00 and 2.5.01, outgoing folder are relative to a
> path tied with each version. Starting from release 2.6.00, the
> outgoing folder has been moved to be under a folder called "shared".
> The new folder structure will facilitate a better upgrade process for
> future releases. End users need do the following:

1.  Re-configure the Rhapsody or eWebIT to point to the new outgoing
    folder.

2.  If existing Sender still has payload under its outgoing folder, they
    must be copied from existing outgoing folder to the new PHINMS
    2.6.00 outgoing folder.

-   After upgrade, install wizard doesn't delete 2.1, 2.5.00 and 2.5.01
    directories and folder.

> Installation wizard doesn't delete existing 2.1, 2.5.00 and 2.5.01
> directories and files, which may still contain valuable configuration
> values and history data. PHINMS 2.6.00 will let the end user to decide
> what to do with their existing installation and files.

-   After upgrade, install wizard doesn't delete 2.1 windows service
    from windows Services.

> If end users have upgraded from a 2.1 Sender or Receiver running as
> windows service, PHINMS 2.6.00 install wizard doesn't remove your
> PHINMS 2.1 windows service. End users have to stop and remove that 2.1
> service manually after the upgrade.

-   After upgrade, install wizard doesn't delete 2.5.00/2.5.01 windows
    service from windows Services, but stop it and change startup type
    to "Manual"

> After upgrading from 2.5.00 or 2.5.01, PHINMS 2.5.00 or 2.5.01 still
> has all the necessary files to be ran again in case end users want to
> fall back onto 2.5.00 or 2.5.01 after the upgrade. The PHINMS 2.6.00
> install wizard doesn't delete 2.5.00/2.5.01 service from windows
> Services, however it stops 2.5.00/2.5.01 windows service and update
> its startup type to be "Manual".

-   PHINMS 2.6.00 Receiver "receiverincoming" folder has been moved into
    new "shared" folder. Applications pick up message payload from disk
    need to be re-configured to read payloads from the new folder.

-   PHINMS 2.6.00 Sender and Receiver log file folder
    (\$(Install_directory)/2.6/tomcat-5.0.19/phinms/logs) has been tied
    with release version number. Any log file cleanup tool has to be
    re-configured to monitor log files under new folder structure.

-   PHINMS 2.6.00 does not have MS SQL Server, Oracle, and MySQL JDBC
    drivers (JDBC jar files) bundled with the release. End users use any
    of those database as transport queue or worker queue need download
    those drivers and copy them (JDBC jar files) into 2.6.00
    installation directory:
    \$(Install_directory)/2.6/tomcat-5.0.19/webapps/receiver/WEB-INF/lib/

-   Before the start of 2.6.00 upgrade installation, it\'s good practice
    to stop the PHINMS software to be upgraded. If existing PHINMS
    software is running as Windows Service, end users should stop that
    service. Otherwise stop the PHINMS software from command window.

-   PHINMS 2.6.00 target installation directory selection is recommended
    to be version-neutral, such as C:\\Program Files\\PhinMS. PHINMS
    2.6.00 will create two folders under install directory: \"shared\"
    and \"2.6\". In the future when one needs to upgrade from 2.6 to
    version 3.0 of PHINMS, end users will still be able to use the same
    version-neutral install directory. The PHINMS 3.0 software will
    create a \"3.0\" folder under the same root install directory and
    share the \"shared\" folder.

-   \"PHINMS 2.6 Console\" shortcut on Windows Desktop and Programs Menu
    is only available for the Windows user who installed the PHINMS 2.6
    software. For security purposes, access to PHINMS console was
    controlled to local administrator role.

-   Under sender configuration, \"Connection Timeout\", \"Data Read
    Timeout", \"Delayed Retry Interval\", \"Polling Interval\" are
    defined in unit of second. \"Max Multi-Block Size\" and \"Max Log
    Size\" are defined in \"bytes\". \"LDAP Cache Timeout\" is defined
    in \"hours\".

-   The PHINMS Receiver URL has changed since v2.1. Most of the PHINMS
    2.1 Receivers have been using the Servlet URL as
    "/phinms21/receivefile". When upgrading the Receiver to v2.6.00,
    change the web server proxy configuration to point to
    "/receiver/receivefile".

-   The upgrade process will copy existing PHINMS JDBC Jar files into
    the 2.6 installation folders at
    \$(Install_directory)/2.6/tomcat-5.0.19/webapps/receiver/WEB-INF/lib/.
    It copies your Oracle, MS SQL Server, Mysql server JDBC Jar files
    into the 2.6 folders only when your existing PHINMS installation
    meets the following conditions:

> a\) Existing Jar files are reachable (recursively down) through your
> existing PHINMS folder (e.g. c:\\phmsg21).
>
> b\) Your existing Jar files fall into the following wildcard filters:
>
> Oracle JDBC drivers: ojdbc14\*.jar ocrs12\*.zip classes12\*.zip
>
> Oracle JDBC drivers: msbase.jar mssqlserver.jar msutil.jar
>
> MySQL JDBC drivers: mysql-connector\*.jar
>
> Postgre SQL JDBC drivers: pg\*jdbc\*.jar jdbc\*.jar
> postgresql\*jdbc\*.jar

If you find a bug or limitation, please contact us through the PHINMS
web site:\
[www.cdc.gov/phin/phinms](http://www.cdc.gov/phn/phinms) and then click
on the Contact PHINMS email link.

# FILES LIST

This release consists of the following files:

  --------------------------- -------------------------------------------
  **Filename (specify full or **Description**
  relative path)**            

  Phinms2.6.00win32.exe       Installation file on Windows 2000/2003/XP

  setuplinux.bin              Installation file on Linux

  setupSolarisSparc.bin       Installation file on Solaris Sparc

  setupSolarisx86.bin         Installation file on Solaris X86
  --------------------------- -------------------------------------------

# FOLDERS LIST

After an install or upgrade to 2.6.00, the following will be the
installation folder organization:

![](media/image2.png){width="5.99375in" height="5.1875in"}

The above is a folder image of PHINMS 2.6.00 installed under C:\\Program
Files\\PhinMS directory, under which there are two important folders:
"2.6" and "shared". The "2.6" folder contains the 2.6.00 runtime data
and files. The "shared" folder contains application-visible data
folders, such as sender's outgoing and sender incoming folders. It is
important to point out that applications may need to modify their
configuration files to point to the new outgoing folder under "2.6"
within 2.6.00 installation.

PHINMS 2.6.00 sender and receiver log files are located in the
2.6/tomcat-5.0.19/phinms/logs folder.

Upon a fresh install, the installer will need to manually copy JDBC
drivers into the 2.6/tomcat-5.0.19/webapps/receiver/WEB-INF/lib/ folder.
After an upgrade, most of the JDBC drivers in the original install
folders should be copied into the new folder. See Section 3.3 Known Bugs
and Limitations in these release notes for further details.

# Appendix A -- Using AutomatED UPGRADE feature {#appendix-a-using-automated-upgrade-feature .unnumbered}

Use the following procedures to install the PHINMS version 2.6.00
application. If you are upgrading from version 2.1, you will need to
choose either upgrade from 2.1 Sender or 2.1 Receiver.

1.  Go to the File Transfer Protocol site listed in the email or phone
    call you received from the PHINMS help desk, enter your user name
    and password and create a folder for it on your local drive and copy
    the executable file into the folder. Make a note of the folder name
    and path. You will need it later.

2.  If you have not received this email, you may not have requested the
    software using the request form on the PHINMS web site. If you have
    not requested the software using the web site, go to
    [www.cdc.gov/phin/phinms](http://www.cdc.gov/phin/phinms) , click on
    the PHINMS Installation link on the right navigation panel, and then
    follow the procedures in the Quick How To section.

3.  Open the executable file (.exe). The **PHINMS InstallShield Wizard**
    dialog opens:

    ![](media/image3.jpeg){width="2.7555555555555555in"
    height="1.8194444444444444in"}

4.  Click **Next**. The **End User Agreement** dialog (not shown)
    appears. Read the agreement and then select the **I accept the
    terms** radio button and then click **Next** to continue. The
    upgrade or fresh install dialog appears:

    ![](media/image4.jpeg){width="2.8368055555555554in"
    height="1.867361111111111in"}

5.  Indicate whether you want to upgrade from a previous version (2.1 or
    a 2.5 version), or whether you will install a "fresh" installation,
    which means no upgrade. Because most installations will be an
    upgrade, the next dialog assumes you have chosen an upgrade
    installation. After you have chosen an upgrade or a fresh
    installation, click **Next**. The **Upgrade** dialog appears:

    ![](media/image5.jpeg){width="2.8368055555555554in"
    height="1.8895833333333334in"}

6.  Recall the 2.1 Sender and 2.1 Receivers are upgraded separately. If
    you are upgrading the 2.1 Sender to 2.6, go through the installation
    for the software on the workstation on which you have loaded the
    Sender. You also have the options to upgrade from a 2.50 and 2.501
    to 2.6.00 on Tomcat server. This option also installs the Sender.
    The last option is to upgrade and run PHINMS 2.6 on application
    server other than Tomcat server. To demonstrate the most common type
    of installation, this example selects the Upgrade from a 2.1 Sender
    to a 2.6 Sender. Click **Next**. The sender.xml dialog appears.

7.  Enter the location of the sender.xml file or browse to find it.
    There is no need to copy and past the configurations. The
    installation wizard will do that for you. Click **Next** and then
    click **Finish**. The desktop icon is placed on the desktop for you.
    Click the desktop icon to start the PHINMS console.

8.  Use the **Sender Configuratio**n and the **Receiver configuration**
    icons on the console to complete the configurations for your PHINMS
    software. For help configuring the software, see the rest of this
    document and go to the PHINMS web site at
    [www.cdc.gov/phin/phinms](http://www.cdc.gov/phin/phinms). Read the
    Quick How Tos on the Installation page and the documents and the
    online help on the Support Page.

9.  Use the **Contact PHINMS** email link at the top of the PHINMS web
    site to ask questions and give your comments and suggestions.

# APPENDIX B -- SENDING A MESSAGE MANUALLY USING PHINMS CONSOLE {#appendix-b-sending-a-message-manually-using-phinms-console .unnumbered}

Your PHINMS Version 2.6.00 installation has two components -- the Sender
and the Receiver. This test verifies that the PHINMS Sender is able to
send an outbound message to a PHINMS Receiver server hosted at a peer
organization in the Public Health Information Network. This test
verifies the following:

-   Your PHINMS Sender is operational.

-   Your PHINMS Sender is able to send a message that is receivable by a
    PHINMS Receiver that is hosted at your peer organization.

Send a Message via the Console Message:

1.  Start the Console

2.  In the PHINMS Explorer on the left, select the Sender
    Queues-\>Transport-\>TransportQueue.

3.  Click on the "Message" icon on the left

4.  From the list of routes, select the route for your peer node.

5.  Enter a valid service in the Service field

6.  Enter a valid action in the Action field

7.  Select the file you wish to send by either entering its name or
    selecting the ellipsis and choosing the file

8.  Enter the destination file name. (Optional)

9.  Enter arguments needed for the receiving application (Optional)

10. If you wish to encrypt or sign your message then click on the
    Security Options Button. (Optional)

    Encrypting a message:

    1.  Select the "Encrypt Message" Check Box

    2.  Select whether you want to "use a certificate on your machine"
        or "use LDAP look up to find encryption certificate"

    3.  If using a certificate on your machine enter the certificate
        name or select the file by using the ellipsis. (Note: the file
        should be a certificate not a key store. The file suffix should
        be .pem or .cer. A .pfx is a keystore and will not work for this
        feature)

    4.  If doing an LDAP look up to the encryption cert then complete
        fill in the "Base DN" and "Common Name" for the certificate to
        be used on the corresponding LDAP address. (Note: The address
        can be changed the default CDC LDAP address has been completed
        for convenience)

        Signing a message:

```{=html}
<!-- -->
```
1.  Select the "Sign Message" Check Box

```{=html}
<!-- -->
```
11. Click "Ok" if in the "Security Options" Dialog

12. Click Send on the "Send Message" Dialog

***Note: Route-not-read manual messaging is not support for this
release.***

# APPENDIX C - PHINMS UPGRADE VALIDATION CHECKLIST {#appendix-c---phinms-upgrade-validation-checklist .unnumbered}

**Overview**

The new PHINMS Release (2.6.00) includes an "upgrade" feature to
facilitate easy upgrade from older versions of PHINMS. However, care
must be exercised by application owners that upgrade the PHINMS
software, to validate this process. This document provides a checklist
of things to do after you upgrade your PHINMS software to version
2.6.00.

**Manual inspection:**

After you apply the upgrade, run the PHINMS Console and manually inspect
the following:

-   Version of the Console \[Should be Version 2.6.00\]

-   Browse the following URL
    [http://\<host\>:5088/receiver/receivefile]() and verify that the
    right version of the PHINMS Receiver is running \[This should say
    "CDC PHIN-MS Version 2.6"\]

-   Click on "Snd Cfg" from the Console, and manually inspect the Sender
    Configuration by going through all the tabs

-   Click on the "Rcvr Cfg" from the Console, and manually inspect the
    Receiver Configuration

-   Queues -- make sure that the entries do not appear in red, and that
    the table contents are visible in the panel on the right. If they
    appear in red, then this means there is a database connectivity
    problem that needs to be debugged.

**Sender Upgrade Validation (Transport Level):**

-   Send a "ping" to yourself (Loopback)

-   Send a "ping" against CDC Ping Server

-   If your Sender is supposed to send to CDC, then send a test message
    to CDCStagingReceiver route (use service=default, action=message),
    and verify proper receipt \[check transport status\]

**Sender Upgrade Validation (Application Level):**

-   Have your application drop a message to the transport queue
    addressed to a test Receiver (e.g., if your Sender is supposed to
    send to CDC, then send this to the CDCStagingReceiver route).
    Contact your application partner to verify that the message was
    properly received, decrypted, parsed and processed by the
    application message handler.

**Receiver Upgrade Validation (Transport Level):**

-   Send a ping message to your Receiver via your web server proxy and
    verify that the Receiver received it and responded to it. View the
    logs to see if there are any errors.

-   Send a test message with encryption from your Sender via your web
    server proxy and verify that the Receiver received it and dropped it
    to the test worker queue after decrypting it.

**Receiver Upgrade Validation (Application Level):**

-   Have your application drop a message into the transport queue
    addressed to the route for your Receiver, and verify proper receipt
    and processing of the message by your application message handler.

**Notes on Troubleshooting:**

-   If your application has a dependency on the directory structure of
    PHINMS (e.g., to write outgoing files or file descriptors), you
    should note that the directory structure has changed in version 2.6,
    hence you may need to re-configure your application accordingly.

-   The relative URL of the PHINMS Receiver has changed since version
    2.1 (it is now /receiver/receivefile). If you were using
    /phinms21/receivefile before, you need to point your web server
    proxy to /receiver/receivefile. This change is external to PHINMS.