PartnerConnect Installation Guide

                            

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Revision History

 

Revision Number

Author

Date

Comments

1.0

Hubspan

04/09/2004

Initial Version

1.1

Hubspan

01/22/2007

Addition of payload cryptography

1.2

Hubspan

3/29/2007

Additional payload cryptography options added

1.3

Hubspan

4/23/2007

Mass Distribution added


Table of contents

1     Introduction.. 3

1.1     Supporting Documentation.. 3

2     PartnerConnect Solution.. 4

2.1     Components.. 4

2.2     PartnerConnect Data flow... 4

3     Technical Guide.. 5

3.1     System Requirements.. 5

3.2     Downloading PartnerConnect. 5

3.3     Installing & Configuring PartnerConnect. 5

3.4     Encrypting / Decrypting payload files.. 5

3.4.1     Encrypting with PKCS7 Example. 6

3.4.2     Decrypting with PKCS7 Example. 6

3.4.3     Encrypting with PGP Example. 6

3.4.4     Decrypting with PGP Example. 6

3.5     Configuration file (PCFTC.ini) optional settings.. 6

3.6     Create PartnerConnect data directory.. 10

3.7     Running PartnerConnect. 11

3.7.1     Manual Execution of PartnerConnect. 11

3.7.2     Mass Distribution File Sends. 14

3.7.2.1    Create the Distribution List Repository Directory. 14

3.7.2.2    Create a Distribution List Manifest File. 14

3.7.2.3    Synchronize Mass Distribution Mailboxes. 14

3.7.2.4    Mass Distribution Sends. 15

3.7.3     Installing PartnerConnect as a Service. 15

3.7.3.1    Executing Manual Commands While Running as Windows Service. 16

3.7.3.2    Configuration Changes While Running as a Windows Service. 16

3.8     Password Security Requirements.. 17

3.8.1     Password Strength. 17

3.8.2     Password Expiration. 17

3.8.3     Changing a Password.. 17

3.9     File Naming and Operating System Portability.. 17

3.9.1     Windows Operating Systems Restrictions. 17

3.9.2     PartnerConnect File Naming Standards. 18

3.10     File Versioning.. 18

3.10.1     Scenario 1: Conflict at Hubspan. 18

3.10.2     Scenario 2: Conflict at the Destination. 18

3.10.3     Conflict Avoidance and Resolution. 18

3.11     Production Architecture (Automated/Scheduled Execution) 19

4     Getting Help.. 20

5     Maintenance.. 21

5.1     Installing PartnerConnect Upgrades.. 21

 

 

1       Introduction

 

This document provides a technical guide to trading entities implementing document delivery solutions based on PartnerConnect.  PartnerConnect is a product offered by Hubspan that enables trading entities to transmit and receive files to and from other trading partners.  PartnerConnect offers a simple file exchange solution that is lightweight and easy to implement.

1.1      Supporting Documentation

 

·         Workspace Quick Start Guide - this document describes usage of the Hubspan online monitoring tool.

2       PartnerConnect Solution

 

This section provides a high level overview of the PartnerConnect solutions including major components and the interaction of these components.

2.1      Components

The PartnerConnect solution consists of two components: 

 

1)     The PartnerConnect client, a software package installed inside the trading entities firewall that sends and receives files over the Internet to and from the Hubspan service.

2)     The Hubspan service, a hosted service that facilitates the sending and receiving of files between trading entities over the Internet.

 

 

Internet

Trading Entity A

Trading Entity B

Business

System

Hubspan

Service

 

 

 PartnerConnect

        Client

 

Figure 1: PartnerConnect Solution Components

 

2.2      PartnerConnect Data flow

The PartnerConnect solution can send and receive files to and from trading entities. An example of the data flow for an outbound file sent to a trading partner is described below.

 

  1. Place outbound documents in PartnerConnect tohub directory – Either manually or programmatically, files will be placed in the appropriate PartnerConnect client tohub directory for delivery to a trading partner.
  2. Send document to Hubspan – The PartnerConnect client is invoked to transmit all files over a secure connection on the public Internet to the Hubspan service. If the document was successfully delivered to the Hubspan service, PartnerConnect removes the document from the tohub directory and archives the data in the tohubarchive directory. If network transmission problems prevent delivery of the document to the Hubspan service, the document remains in the given tohub directory so that re-transmission can be attempted. 
  3. Hubspan service delivery to Trading Partner – The Hubspan service receives the files and delivers them to the appropriate trading partner using the preferred delivery mechanism of that trading partner. Trading entities may or may not be using the PartnerConnect client.
  4. Hubspan Acknowledgement of Document Delivery – The Hubspan service returns an acknowledgement back to the PartnerConnect client software indicating the status of the document delivery.  The PartnerConnect client software logs the acknowledgement including any relevant error information if the delivery failed. 

3       Technical Guide

 

This section outlines installing and configuring the PartnerConnect client and details how to test it with the Hubspan service.

3.1      System Requirements

To run the PartnerConnect client, the computer and network it is connected to should meet the following technical requirements:

·         Intel compatible PC 500mhz or above

·         256 MB RAM

·         200 MB free disk space

·         Windows XP, 2000, NT, 98
Linux
Solaris (SPARC, x86)

·         Connectivity to the public Internet including the ability to transmit HTTP and HTTPS requests.

·         Business Software Systems– It must be possible for the routines you create to generate files from your existing business software systems to be able to access the installation of the PartnerConnect client and place files in the PartnerConnect Outbox. 

3.2      Downloading PartnerConnect

Contact Hubspan Customer Support for information on how to receive the PartnerConnect Client package. This package is a platform specific package distributed as a single file.

 

Platform

Distribution

Windows XP, 2000, NT, 98

PartnerConnect_V##B###b####_ Win32.zip

Linux

PartnerConnect_V##B###b####_LinuxX86.tar.gz

Solaris (SPARC, x86)

PartnerConnect_V##B###b####_ SolarisSPARC.tar.gz

PartnerConnect_V##B###b####_SolarisX86.tar.gz

 

Note:  The # symbol above indicates Hubspan build versioning information for the PartnerConnect product.

 

3.3      Installing & Configuring PartnerConnect

The following instructions can be used to install the PartnerConnect client:

 

1.     Unzip Installation File – Use a tool such as WinZip to unzip the installation file to a directory on the computer that you will run the software on, such as:  c:\PartnerConnectClient\.  From this point onwards in this guide, “%InstallDirectory%” refers to the directory that the installation file has been unzipped to. 

 

2.     Edit Configuration File - The configuration file located in %InstallDirectory%\config is where the client specifies site-specific values and choices.  The configuration file is named PCFTC.ini (PCFTC_test.ini for testing).  You must set the client_login, client_password, smtp_server, and reporting_address entries in the file to properly run PartnerConnect.      

 

3.4      Encrypting / Decrypting payload files

Partner Connect supports the encryption/decryption of payload files using either PKCS7 or PGP cryptography standards.  Cryptography operations require several supporting configuration settings.  Because encryption/decryption may be configured differently per trading partner the following configuration scheme will be used. 

 

[CRYPTOGRAPHY_CONFIGURATION_OPTION].[TRADING_PARTNER] = [SETTING]

 

The following are examples of how cryptography might be configured for various scenarios.

3.4.1     Encrypting with PKCS7 Example

 

send_encrypt_type. TEST_BUS = PKCS7

send_encrypt_pkcs7_certificate.TEST_BUS = D:/TEST_BUS_A.CER

send_encrypt_pkcs7_algorithm. TEST_BUS = 3DES

3.4.2     Decrypting with PKCS7 Example

 

receive_decrypt_type. TEST_BUS = PKCS7

receive_decrypt_pkcs7_keystore. TEST_BUS   = D:/MY_BUS.P12

receive_decrypt_pkcs7_password. TEST_BUS   = PASSWORD

3.4.3     Encrypting with PGP Example

 

send_encrypt _type. TEST_BUS = PGP

send_encrypt_pgp_public_keyring.TEST_BUS = D:/PUBRING.GPG

send_encrypt_pgp_algorithm.TEST_BUS  = TRIPLE_DES

send_encrypt_pgp_public_key_userid.TEST_BUS  = MY_USER_ID

3.4.4     Decrypting with PGP Example

 

receive_decrypt_type. TEST_BUS = PGP

receive_decrypt_pgp_keyring. TEST_BUS   = D:/SECRING.GPG

receive_decrypt_pgp_password.TEST_BUS  = MY_PASSWORD

3.5      Configuration file (PCFTC.ini) optional settings

The following are the supported options that are configurable within PartnerConnect.

 

Entry

Usage

client_login/client_password

The login and password the client should use to login to the Hubspan system.

(Provided by Hubspan)

client_url

The Base URL to use to contact the Hub

(Provided by Hubspan)

smtp_server

Host name or IP Address of the SMTP Server

reporting_level

Choices are "SUCCESS" or "ERROR".  Default value of "ERROR". "SUCCESS" means that an email message will be sent every time the application runs with an indication of the success or failure of that run. "ERROR" means that an error email will be sent only when the application encounters a problem. Also allows levels as named by Log4J (OFF, FATAL, ERROR, WARN, INFO, DEBUG, TRACE, ALL)

reporting_address

A recipient email address (or list of recipient email addresses comma separated), that should get the success or error emails

reporting_from

(optional) The value used for the “From” address of the error emails and alerts generated by PartnerConnect.  The default value is “PartnerConnect”.

report_service_change

(optional) Values: true or false.  Flag that indicates if an email should be sent every time the Partner Connect Service starts up or shuts down.  This email will be sent to the reporting_address.

data_directory

Name of the directory where data exchanged with the Hubspan system resides.

log_directory

Name of the directory where Audit Log Files are to be written

client_proxy

(optional)  If the Client uses a proxy server, the proxy information.  The proxy address (IP Address or host name) and port formatted as: "address:port".  Examples: "192.168.0.15:8080" or "proxy.mydomain.com:8080".

proxy_login

(optional)  If the Client uses a proxy server with basic or NTLM authentication, the proxy login name.

proxy_password

(optional)  If the Client uses a proxy server with basic or NTLM authentication, the proxy password.

proxy_authhost / proxy_authdomain

(optional)  If the Client uses a proxy server with NTLM authentication, the user account's host and domain.  Both host and domain must be specified for NTLM.

socket_timeout

(optional; default=60)  The amount of time (in seconds) that PartnerConnect will keep an HTTP Socket open to the Hub without activity during a send or receive.

max_retries

(optional; default=5)  Each file send or receive attempt will be re-tried up to this number of times (within a single run of an application) before an error is reported.

client_auth_keystore_file

(optional) This value is used if Mutual (Client) authentication is desired for SSL transfers.  This value will point to the keystore file that contains the private/public keystore.  This file is required to be in the PKCS12/PFX/JKS formats.

client_auth_keystore_password

(optional) Password to retrieve keys from the keystore for

Mutual (Client) SSL authentication.

client_auth_keystore_format

(optional)  The format of the keystore used for Mutual (Client) SSL authentication.  The valid options are PKCS12, P12, PFX, or JKS.

client_auth_keystore_alias

(optional)  The alias of the key to use within a keystore, for the purpose of Mutual (Client) SSL authentication.

send_encrypt_type. [TRADING_PARTNER]

(optional) Determines which encryption method to use when sending files.  The encryption options are PGP/PKCS7

send_encrypt_pkcs7_min_key_size.[TRADING_PARTNER]

(optional) If a minimum encryption strength standard is required for sending documents then this can mandate that a minimum threshold is met.  Will default to 2048.

send_encrypt_pkcs7_certificate.[TRADING_PARTNER]

(optional unless send_encrypt_type is set to PKCS7) The certificate issued by the receiving trading partner used to encrypt the payload prior to sending.

send_encrypt_pkcs7_algorithm.[TRADING_PARTNER]

(optional) The encryption algorithm for PKCS7.  The supported options are 3DES/ RC2/ AES128/ AES192/ AES256.  Will default to 3DES.

send_encrypt_pgp_algorithm.[TRADING_PARTNER]

(optional)  The encryption algorithm for PGP.  The supported options are TRIPLE_DES/BLOWFISH.  Will default to TRIPLE_DES.

send_encrypt_pgp_public_keyring.[TRADING_PARTNER]

(optional unless send_encrypt_type is set to PGP) Public key-ring storing the keys used for encryption.

send_encrypt_pgp_public_key_userid.[TRADING_PARTNER]

(optional unless send_encrypt_type is set to PGP) Key user’s id used to access a specific public key in the keyring.

send_encrypt_pgp_min_key_size.[TRADING_PARTNER]

(optional) If a minimum encryption strength standard is required for sending documents then this can mandate that a minimum threshold is met.  Will default to 2048.

receive_decrypt_type.[TRADING_PARTNER]

(optional) Determines which decryption method to use when receiving files PKCS7/PGP

receive_decrypt_pkcs7_keystore.[TRADING_PARTNER]

(optional unless receive_decrypt_type is set to PKCS7) The keystore used to decrypt payload received from a trading partner that has encrypted the payload.

receive_decrypt_pkcs7_password.[TRADING_PARTNER]

(optional unless receive_decrypt_type is set to PKCS7) The password allowing access to the keystore.

receive_decrypt_pkcs7_alias.[TRADING_PARTNER]

(optional)  The alias of the key in the keystore.

receive_decrypt_pgp_keyring.[TRADING_PARTNER]

(optional unless receive_decrypt_type is set to PGP) The secret key-ring used for decryption key storage.

receive_decrypt_pgp_password.[TRADING_PARTNER]

(optional unless receive_decrypt_type is set to PGPl) The password to access the secret key-ring.

time.interval.send

(optional)  The interval (in minutes) at which PartnerConnect will send to the hub, when installed as a Windows Service.  The default value is 15 minutes.

time.interval.receive

(optional)  The interval (in minutes) at which PartnerConnect will poll the hub to pick up files, when installed as a Windows Service.  The default value is 15 minutes.

time.interval.configure

(optional)  The interval (in minutes) at which PartnerConnect will verify its configuration with the hub, when installed as a Windows Service.  The default value is 720 minutes (12 hours).

org.quartz.scheduler.rmi.registryPort

(optional, default=2099)  When PartnerConnect is installed as a Service, this is numeric value of the port used for communication between PartnerConnect and its scheduler.  In the event this conflicts with another process running on the given port, this value must be changed.

 

Table 1: Configuration settings

 

 

# sample ini file for PartnerConnect Client

 

client_login      = SimulatorA-AppID

client_password   = password

client_url        = http://192.168.0.114:9000/fta

 

smtp_server       = dummy.smtpserver.com

reporting_level   = ERROR

reporting_address = dummy@hubspan.com

 

data_directory    = ../data

log_directory     = ../log

 

Figure 2: Sample Configuration File

3.6      Create PartnerConnect data directory

The local directory structure (data_directory) used by the PartnerConnect client is important as it controls routing of files that are sent and received.  The Configure application is used to configure the local directory structure for exchanging files with trading entities. The Configure application contacts the Hubspan system (via an HTTP/S web service) to get the list of trading entities that the client is authorized to exchange files with.  Then it compares this list to the directories in the local directory structure.  If any trading partner that the client is authorized to exchange files with does not have a corresponding directory, a directory will be created.  If a directory exists for a trading partner that the client is not authorized to exchange files with, the given directory will be removed.  If the directory to be removed has any files in it, an error message will be generated and the directory will not be removed.

 

To run the configure application at command prompt change to the /bin directory and execute the following command:

 

Configure

 

The data directory will contain three subdirectories named "tohub", "fromhub" and "tohubarchive".

·         "tohub" directory (and its subdirectories) is where files that are to be sent to the Hubspan system are placed. The "tohub" directory contains one directory for each trading partner the Client is exchanging files with.  Files placed in one of these directories are sent to the trading partner that the directory is named for.

·         "fromhub" directory (and its subdirectories) is where files that came from the Hubspan system are placed.  The "fromhub" directory contains one directory for each trading partner the Client is exchanging files with.  Files sent by a trading partner to the Client will be placed in the directory that is named for that trading partner.

·         "tohubarchive" directory (and its subdirectories) is where files that were successfully sent to the Hubspan system are placed. The "tohubarchive" directory contains one directory for each directory in the "tohub" directory.  Files will be moved into this directory after they have been successfully sent to the Hubspan system.  (PartnerConnect applications will never delete files in this directory structure.)

 

Directory structure example:

 

C:\PartnerConnect                                       <- The install directory
C:\PartnerConnect\data                                              <- The root directory
C:\PartnerConnect\data\tohub
C:\PartnerConnect\data\tohub\TPA                            <- Files in this directory are sent to trading partner A
C:\PartnerConnect\data\tohub\TPB                            <- Files in this directory are sent to trading partner B

C:\PartnerConnect\data\tohub\TPC                           <- Files in this directory are sent to trading partner C
C:\PartnerConnect\data\tohubarchive
C:\PartnerConnect\data\tohubarchive\TPA               <- Files in this directory were sent to trading partner A
C:\PartnerConnect\data\tohubarchive\TPB               <- Files in this directory were sent to trading partner B

C:\PartnerConnect\data\tohubarchive\TPC               <- Files in this directory were sent to trading partner C
C:\PartnerConnect\data\fromhub
C:\PartnerConnect\data\fromhub\TPA                       <- Files in this directory are from trading partner A
C:\PartnerConnect\data\fromhub\TPB                       <- Files in this directory are from trading partner B
C:\PartnerConnect\data\fromhub\TPC                       <- Files in this directory are from trading partner C

 

The Configure application can be run again at any time.  If the trading partner wants to connect to another trading partner at a later time, they will need to run the configure application again to get this update on their environment. 

3.7      Running PartnerConnect

There are two ways to run PartnerConnect:

1.     Manually executing PartnerConnect commands

2.     Installing it to run as a Windows Service

 

3.7.1     Manual Execution of PartnerConnect

 

NOTE: All examples provided here are for production environments. To use PartnerConnect in test mode one should configure PCFTC_TEST.INI and use the *TEST versions of the command lines shown below.

 

The following instructions can be used to execute the PartnerConnect client manually.  In production environments these same instructions may be scripted and run on a scheduled basis.

 

1.     Test Internet Connectivity – On the machine on which the PartnerConnect client is installed open a browser and verify the machine is able to connect to the Internet.

 

2.     Secure Configuration – After filling in the PCFTC.ini file (or the test version) it is a good practice to secure your configuration.  Securing your configuration will require a password that abides by the requirements laid out below in section 3.8 below.

 

secureConfigFile.bat

·         Securing the PCFTC.ini configuration file.  The PartnerConnect configuration file may contain data sensitive information such as the service login and keystore password.  PartnerConnect provides a mechanism to secure (encrypt) the configuration file.  To secure simply execute the secureConfigFile command with a password.  You will be prompted to enter a password so that the operation can complete.  Note:  Please see the implications to the send, receive, and configure processes based on whether or not your configuration is encrypted.

 

3.     Send files – To send a file, place one or more files in the trading partner subdirectory under the “tohub” directory.  The Send application is then used to send files to the Hubspan system. The Send application will communicate with the Hubspan system via HTTP/s. In the event you have encrypted your configuration, you will be prompted for a password.  If you are running your PartnerConnect instance via some automated process, you may also specify a password by adding the common option –password [password].  Once a file has been successfully sent it is then moved to the appropriate “tohubarchive” directory. 

 

The Send application can be used in one of the following ways:

·         Send all files.  By invoking the Send application with no command line arguments, all files that are found under the "tohub" directory will be sent to the Hubspan system. 

send.bat

·         Send files to a specific trading partner.  By invoking the send application with one command line argument: the name of a trading partner, all files that are waiting to be sent to the named trading partner will be sent to the Hubspan system.  No other files will be sent.  If the command line argument is not the name of a trading partner, an error message will be created.

send.bat TPA

·         Send a specific file.  By invoking the send application with two command line arguments: the name of a trading partner and the name of a file, the named file waiting to be sent to the named trading partner will be sent to the Hubspan system.  No other files will be sent.  If the first command line argument is not the name of a trading partner or the second command line argument is not the name of a file waiting to be sent to that trading partner, an error message will be created.

send.bat TPA fileone.txt

·         Send selected files.  By invoking the send application with two command line arguments: the name of a trading partner and a file name pattern containing wild card characters, those files waiting to be sent to the named trading partner that match the file name pattern will be sent to the Hubspan system.  Files not matching the file name pattern or not waiting to be sent to the named trading partner will not be sent.  If the first command line argument is not the name of a trading partner an error message will be created.  If no files match the file name pattern, no files will be sent and no error message will be created.  NOTE: Some operating systems or shells try to expand wildcards into a list of files before invoking PartnerConnect.  For these operating systems and shells, it may be necessary to escape the wildcards so they are passed to PartnerConnect intact.

send.bat TPA *.txt

 

4.     Receive files - The Receive application is used to receive files from the Hubspan system. Files are pulled from the Hubspan system and placed in the appropriate “fromhub” directory.  The local directory will be checked to make sure there is sufficient space left on the drive for the file before the download begins.  If there is not enough space, an error email will be created and sent and the Receive application will stop processing. The Receive application will communicate with the Hubspan system via HTTP/s.  In the event you have encrypted your configuration, you will be prompted for a password.  If you are running your PartnerConnect instance via some automated process, you may also specify a password by adding the common option –password [password].

 

The Receive application can be used in one of the following ways:

·         Receive all files.  By invoking the Receive application with no command line arguments, all files that are waiting at the Hubspan system for the Client to pick up will be brought down from the Hubspan system and placed in the "fromhub" directory.  This is the way the Receive application will typically be invoked.

receive.bat

·         Receive files from a specific trading partner.  By invoking the Receive application with one command line argument: the name of a trading partner, all files that are waiting at the Hubspan system for the Client to pick up from the named trading partner will be brought down from the Hubspan system and placed in the "fromhub" directory.  No other files will be brought down.  If the command line argument is not the name of a trading partner, an error message will be created.

receive.bat TPA

·         Receive a specific file.  By invoking the Receive application with two command line arguments: the name of a trading partner and the name of a file, the named file waiting at the Hubspan system for the Client to pick up from the named trading partner will be brought down from the Hubspan system and placed in the "fromhub" directory.  No other files will be brought down.  If the first command line argument is not the name of a trading partner or the second command line argument is not the name of a file waiting at the Hubspan system from that group, an error message will be created.

receive.bat TPA filetwo.txt

·         Receive selected files.  By invoking the Receive application with two command line arguments: the name of an trading partner and a file name pattern containing wild card characters, those files waiting at the Hubspan system for the Client to pick up from the named trading partner that match the file name pattern will be brought down from the Hubspan system and placed in the "fromhub" directory.  No other files will be brought down.  If the first command line argument is not the name of a trading partner, an error message will be created.  If there are no files waiting at the Hubspan system that match the file pattern, no files will be sent and no error message will be created.  NOTE: Some operating systems or shells try to expand wildcards into a list of files before invoking PartnerConnect.  For these operating systems and shells, it may be necessary to escape the wildcards so they are passed to PartnerConnect intact.

receive.bat password TPA *.txt

 

·         Securing the PCFTC.ini configuration file.  The Partner Connect configuration file may contain data sensitive information such as the service login and keystore password.  Partner Connect provides a mechanism to secure (encrypt) the configuration file.  To secure simply execute the secureConfigFile command with a password.  NOTE: This same password will then need to be provided when executing the Configure/Send/Receive commands via the –password [password] command option.

secureConfigFile.bat password

 

·         Viewing a previously secured PCFTC.ini configuration file.  To convert the previously secured PCFTC.ini file to clear text for configuration validation or modification, execute the revealConfigFile command.  NOTE:  After modification the file will need to be re-secured with the secureConfigFile command.

revealConfigFile.bat password

5.     Review Execution Logs – Check the /log directory for any log entries on the client. Once you have checked the client logs you may then login to the Hubspan Workspace application to review the content and status of files that have been transmitted via PartnerConnect to the Hubspan service.  For more details on how to use the Workspace application to review transaction status, consult the accompanying Workspace Quick Start Guide documentation.  To receive a login account for the test Workspace application, contact Hubspan Client Services.  To receive access to the production Workspace application, contact Hubspan Customer Support.

 

6.     Maintain Password If you have encrypted your PCFTC.ini file via the secureConfigFile application, you will be required to update your password every 90 days.  You can simply do this using the Change Password application.

 

·         Change the Password for Encrypted Configuration.  This application will prompt you for the old password, the new password, and to confirm the new password.  If the old password is not correct, the new password does not match the confirmed new password, or the new password does not adhere to the password requirements laid out in Section 3.8.1, this application will fail to process successfully.

 

changePassword.bat

 

7.     Change Configuration – If you have password-encrypted your PCFTC.ini file via the secureConfigFile application, and you need to make changes to your configuration (e.g. your mail server changes IP addresses), you will need to un-encrypt your configuration to alter it.

 

·         View a previously secured PCFTC.ini configuration file.  This application converts the previously secured PCFTC.ini file to clear text for configuration validation or modification.  You will be prompted for the password to decrypt the PCFTC.ini file.  NOTE:  After modification the PCFTC.ini file will need to be re-secured with the secureConfigFile command.

 

revealConfigFile.bat

 

3.7.2     Mass Distribution File Sends

PartnerConnect has the ability to send a single file to the Hubspan Secure File Transfer System, and have it distributed to a list of destinations, regardless of the transport protocols used by each of the destination business systems.  This is accomplished by having PartnerConnect send a distribution list to Hubspan prior to a Mass Distribution send.  The distribution list is simply a list of recipients a given file should be sent to once it is successfully transferred to the Hubspan system.  The steps to begin distributing files through the Hubspan Secure File Transfer System are documented below.

3.7.2.1    Create the Distribution List Repository Directory

The first step to begin utilizing the Mass Distribution feature at Hubspan is to create the directory for the distribution list manifests. You must create a directory named “dlmanifests” at the root of the data directory mentioned in Section 3.6 above.  This directory is the repository for distribution lists, or lists of recipients to be sent to on a discrete file send.

 

Assuming your data directory was located as in the sample directory structure in Section 3.6 above, the path to the Distribution List Directory would look like:

 

C:\PartnerConnect\data\dlmanifests

3.7.2.2    Create a Distribution List Manifest File

The next step to start using Mass Distribution is creating a manifest file, which is a list of the trading entities you would like to distribute to.  If you have previously run the Configure routine, then the list of trading entities you are allowed to send to is the list of mailboxes that appear in the “tohub” directory at the root of the data directory.  The distribution list manifest is a list of valid mailboxes that PartnerConnect can send to.  Each valid mailbox should be on a separate line.  Thus, for the directory structure detailed in Section 3.6 above, a distribution list for all the valid recipients would look like:

 

TPA

TPB

TPC

 

A manifest file should be saved with the extension “.mfs”.  This allows the PartnerConnect software to correctly use the manifest file.  An example name for this above example manifest file is:

 

example.mfs

3.7.2.3    Synchronize Mass Distribution Mailboxes

Once a Mass Distribution manifest file exists in the distribution list repository directory, it is necessary to synchronize the rest of the mailboxes in the data directory.  This can be done by running the PartnerConnect Configure command, as described in Section 3.6 above.  Once the Configure command has been run with the above distribution list manifest, the resulting data directory structure will be:

C:\PartnerConnect                                                       <- The install directory
C:\PartnerConnect\data                                                              <- The root directory

C:\PartnerConnect\data\dlmanifests                            <- The root distribution list manifest directory

C:\PartnerConnect\data\dltohub                                   <- The root directory for distribution list sends

C:\PartnerConnect\data              \dltohub\example                    <- The directory for sending files to the “example” distribution list

C:\PartnerConnect\data\dltohubarchive\example         <- The archive directory for files sent to the “example” dl
C:\PartnerConnect\data\tohub
C:\PartnerConnect\data\tohub\TPA                            <- Files in this directory are sent to trading partner A
C:\PartnerConnect\data\tohub\TPB                            <- Files in this directory are sent to trading partner B C:\PartnerConnect\data\tohub\TPC                      <- Files in this directory are sent to trading partner C
C:\PartnerConnect\data\tohubarchive
C:\PartnerConnect\data\tohubarchive\TPA                               <- Files in this directory were sent to trading partner A
C:\PartnerConnect\data\tohubarchive\TPB                               <- Files in this directory were sent to trading partner B C:\PartnerConnect\data\tohubarchive\TPC                               <- Files in this directory were sent to trading partner C
C:\PartnerConnect\data\fromhub
C:\PartnerConnect\data\fromhub\TPA                       <- Files in this directory are from trading partner A
C:\PartnerConnect\data\fromhub\TPB                       <- Files in this directory are from trading partner B
C:\PartnerConnect\data\fromhub\TPC                       <- Files in this directory are from trading partner C

 

3.7.2.4    Mass Distribution Sends

Once the data directory has been synchronized, PartnerConnect is configured to send using the Mass Distribution functionality.  To send to the recipients of a distribution list manifest file, the user must simply copy the files to send into the corresponding dltohub directory.  For the example.msf manifest file from above, the user must copy the files to send into the following directory:

 

C:\PartnerConnect\data\dltohub\example                    <- The directory for sending files to the “example” distribution list

3.7.3      Installing PartnerConnect as a Service

PartnerConnect can be installed as a Windows Service to perform the Send, Receive, and Configure operations automatically.

 

Note: A Windows Service is a Process that runs in the background, while the machine it’s installed on is running.

 

The PartnerConnect Windows Service is a scheduler that runs the core PartnerConnect tasks: Send, Receive, and Configure.  These tasks run at configurable intervals, with the Send/Receive running every 15 minutes and Configure running every 12 hours, by default.

 

Optionally, the intervals that these tasks are run by the Scheduler are configurable.  To configure these parameters, edit the PCFTC.ini file.

 

time.interval.send = 15         - The interval (in minutes) that the Send task should be run

time.interval.receive = 20     - The interval (in minutes) that the Receive task should be run

time.interval.configure = 30 - The interval (in minutes) that the Configure task should be run

 

The following instructions can be used to install PartnerConnect as a Windows Service.

 

Note: If the Send/Receive/Configure tasks are to execute at a custom interval, the PCFTC.ini file needs to be edited and saved prior to Installing PartnerConnect as a service.

 

1.     Install PartnerConnect Windows Service – The InstallScheduler command in the “bin” directory of PartnerConnect should be used to install PartnerConnect as a Windows Service.

 

installScheduler.bat

 

2.     Shutdown PartnerConnect as a Service – Once PartnerConnect is installed as a Windows Service, it continues to run as long as the Computer it is installed on remains powered on.  As long as the Service is running, it will continue to execute the Send, Receive, and Configure tasks.

 

The PartnerConnect Windows Service can be stopped from performing these tasks automatically.  There are two ways to do this.

 

1.     Open the “Services” window from the “Administrative Tools”, find the PartnerConnect service, and click the Stop icon.

 

2.     Run the ShutdownScheduler script

 

shutdownScheduler.bat

 

3.     Startup PartnerConnect – If the PartnerConnect Windows Service has been shutdown, either from the “Services” window, or by running shutdownScheduler.bat, it may be started so automatic execution of the Send, Receive, and Configure tasks are resumed.

 

The PartnerConnect Windows Service can be started, if it had been previously shutdown.  There are two ways to do this.

 

1.     Open the “Services” window from the “Administrative Tools”, find the PartnerConnect service, and click the Start icon.

 

2.     Run the StartupScheduler script

 

startupScheduler.bat

 

4.     Uninstall PartnerConnect Windows Service – If PartnerConnect has been installed as a Windows Service, it may be uninstalled.  To perform uninstallation, run the uninstallScheuduler.bat command.

 

uninstallScheduler.bat

 

3.7.3.1    Executing Manual Commands While Running as Windows Service

When PartnerConnect is installed, and running as a Windows Service, the Send, Receive, and Configure tasks are triggered at specific intervals.  To perform one of these operations at an unscheduled time, you may run the wanted command by running its associated command file.

 

When PartnerConnect is running as a Service, and a task is run manually (by running send.bat, receive.bat, or configure.bat), instead of directly executing that task, the PartnerConnect Service will trigger that task to be run via its built-in scheduler.  If the task is manually run while the corresponding scheduled task is running, the manual execution will wait until the scheduled task completes before executing.

3.7.3.2    Configuration Changes While Running as a Windows Service

The configuration of a Windows Service occurs when the Service is installed.  Thus, modifications to the PCFTC.ini configuration file will not modify the behavior of the Windows Service installation.  In order for changes made to the PCFTC.ini file to take effect, the service must be re-installed.

 

When running PartnerConnect manually without the Windows Service being installed, the configuration in the PCFTC.ini file is loaded with each run.  However, if PartnerConnect is installed as a Windows Service, the PCFTC.ini configuration will not be reloaded when run.  This is due to the fact that a manual run simply triggers the PartnerConnect Service.  Thus, even when attempting to run manually while the PartnerConnect Service is installed, the Service must be reinstalled for configuration changes to take effect.

3.8      Password Security Requirements

To maximize the security of the PCFTC.ini configuration file, the user may encrypt the PCFTC.ini file via password-based encryption using the secureConfig command.  The password used to encrypt the PCFTC.ini file must adhere to the Hubspan-defined best practices for passwords.

3.8.1     Password Strength

The following are requirements for the strength of the password used to encrypt the PCFTC.ini configuration file:

 

1.   The passwords must have at least 8 alpha/numeric/symbol characters.

2.   The password must have at least 1 representative character from 3 of the 4 following groups:

a.   Lower case alpha characters

b.   Upper case alpha characters

c.   Numbers

d.   Symbols (non-alpha numeric characters)

3.   Must not include common character sequences such as:

a.   The same character repeated more than 3 times

b.   Alphabetic sequences such as “abcd”

c.   Number sequences such as “1234”

d.   Common keyboard sequences such as “asdf”

4.   Cannot contain spaces or other white space characters

5.   Cannot contain control characters

6.   Passwords cannot contain either quotes (‘) or double quotes (“)

7.   Passwords may not contain the following values that are configured in the PCFTC.ini file:

a.   client_login

b.   client_password

3.8.2     Password Expiration

The password used to encrypt the PCFTC.ini file must be changed every 90 days.  A warning will be sent when attempting the send, receive, or configure actions if there are 10 total days left for the validity of the given password.  If after 90 days, the password is not correctly reset, the send, receive, and configure actions of the PartnerConnect installation will not run.

3.8.3     Changing a Password

To change the password used to encrypt the PCFTC.ini file, go to the %InstallDirectory%/bin directory, and run changePassword.bat.  This will prompt you for the old password, and new password, and a confirmation that the second password is correct.

 

 

3.9      File Naming and Operating System Portability

To allow portability across various operating systems such as Windows, Mac OS X, and Unix/Linux variants, it is critical that a common set of file naming standards be observed.  These standards were developed with the file naming restrictions listed below in mind. 

3.9.1     Windows Operating Systems Restrictions

Reference: (http://msdn.microsoft.com/library/default.asp?url=/library/en-us/fileio/base/naming_a_file.asp)

 

1.     The following characters are invalid as file or folder names on Windows using NTFS:  

·         / ? < > \ : * | " and any character you can type with the Ctrl key.

2.     In addition to the above illegal characters the caret ^ is also not permitted under Windows Operating Systems using the FAT file system.

3.     File and folder names may be up to 255 characters long with Windows using the FAT file system.

4.     File and folder names may be up to 256 characters long with Windows using the NTFS file system.

5.     The length of a full path under both systems is 260 characters.

6.     In addition to the characters listed above, the following conventions are also illegal:

·         Placing a space at the end of the name

·         Placing a period at the end of the name

7.     The following file names are also reserved under Windows:

·         com1, com2, com3, com4, com5, com6, com7, com8, com9, lpt1, lpt2, lpt3, lpt4, lpt5, lpt6, lpt7, lpt8, lpt9, con, nul, and prn.

·         Avoid these names followed by an extension (for example, NUL.tx7).

3.9.2     PartnerConnect File Naming Standards

Based on the restrictions listed above, the following list is a set of recommended file naming standards for the Secure File Transfer project:

1.     Limit file and directory names to the characters A-Z, a-z, 0-9, hyphen, underscore and space.

2.     Space (blank) character must not be leading or trailing.

3.     COM[0-9].*, LPT[0-9].*, NUL* and PRN* are invalid file names or directory names.

4.     File and directory name comparison should be case-insensitive (foo.txt == Foo.TXT == FOO.TXT)

5.     Limit filename to 64 characters because Hubspan PartnerConnect requires additional path parameters to indicate Sender and Recipient.  Total path may be up to 260 characters (including drive letter). E.g.  D:\<192-path-chars><64-chars-filename>NUL (64 char file name + 192 path characters + 4 characters = 260).

 

Important Note: The space (blank) character used in file names may not work on all operating systems.  To avoid possible failure during file transport, the trading partner and TE who wish to use this feature will need to ensure that both operating systems support this capability during the integration process. 

 

3.10   File Versioning

It is possible to exchange a file with the same filename multiple times.  Under certain conditions, this can cause a conflict between two or more instances of the file.  These scenarios are detailed below.

3.10.1  Scenario 1: Conflict at Hubspan

  1. The receiver of a file, trading partner A, is using an asynchronous method to download files such as PartnerConnect.
  2. Trading partner A uploads a file destined for trading partner B.  Before trading partner B downloads that file, trading partner A uploads another file with the same name.

3.10.2  Scenario 2: Conflict at the Destination

  1. Trading partner A sends a file to a trading partner B
  2. The trading partner B downloads the file to, or the file is uploaded to, their download directory.
  3. This file is NOT removed from the download directory.
  4. Trading partner A sends another file with the same name to trading partner B.
  5. The trading partner B downloads this new file to, or the file is uploaded to, their download directory.

3.10.3  Conflict Avoidance and Resolution

The most efficient way to resolve the conflicts described above is to avoid them altogether.  This can be achieved by requiring a unique filename for each file transmitted between trading partners.  A simple way to create unique file names would be to add a time/date stamp or a unique id number to a file name (e.g. myfile_20040403_1613.txt).

If unique file names are not used, a conflict resolution mechanism must be implemented.  There are two industry standard solutions. 

1.     Create a new version of the file by altering the filename (e.g. renaming myfile.txt, myfile(2).txt).

2.     Always overwrite the old file with the new one.

Overwriting is the only option currently supported by the Hubspan Transaction Delivery Network Service and PartnerConnect.

3.11   Production Architecture (Automated/Scheduled Execution)

Running PartnerConnect manually is suitable for testing or for sending limited quantities of production files.  Your business may decide to run PartnerConnect on an automated basis, but that you don’t want to install the PartnerConnect Windows Service.  This may be the case if you need to tightly integrate PartnerConnect with existing business processes.  To automate execution of PartnerConnect (without installing the PartnerConnect Windows Service), the following steps are needed:

 

  1. Server Installation – Install PartnerConnect on a computer that is always running, such as a server used to run backend business software systems.  The server will need to be connected to the internet to run any of the commands for configuration or sending/receiving files. 

 

  1. Scheduled delivery and pickup – Configure the Windows command scheduler or a third party scheduler utility to automatically place files at designated times and days that are appropriate for your business processes.  For example, if you have a warehouse management software system that generates packing lists at 10AM each weekday, it may be appropriate to generate files and deliver them to the PartnerConnect “tohub” at 10:30AM each weekday.

 

 

4       Getting Help

 

When your PartnerConnect solution does not function as designed, Hubspan provides resources to assist you with diagnosing and resolving the problems you encounter.  If your business encounters errors transmitting one or more production PartnerConnect files, you can open a case with Hubspan Customer Support through several methods:

 

·         Phone – US 1 (206) 838 5430  to report an incident with a Customer Support representative

·         Email – Email support@hubspan.com with the details of the errors you are encountering.

 

Note:  You should only open cases with Customer Support regarding issues with the production system.  Any implementation issues regarding test files should be communicated to Hubspan Client Services.

 

When opening a case with Customer Service, be sure to provide as much specific detail as possible about the error that is occurring such as:

 

1.     Trading Partner Identity –The organization IDs of the trading entities that you are transmitting files to/from, including any relevant Hubspan Account Codes used to identify business units within the trading partner that you are sending the files to.

2.     Filename –The name of the files containing the transaction batches that you are having trouble transmitting

3.     Date/Time Transmitted – The Date and Time (including time zone) that you transmitted the files you are inquiring about.

4.     Error Condition/Log – A detailed description of what actions the PartnerConnect system performed when the file in question was transmitted such any error messages recorded in the PartnerConnect error log.  If possible, you should also include information available in the Hubspan Workspace application regarding the delivery status of the files.

 

In preparation for opening a technical support case with Hubspan you can carry out several troubleshooting steps to isolate where the problem is occurring:

 

1.     PartnerConnect Client Software Status – Check the status of the PartnerConnect Client software after is has completed execution.  Review any technical error messages it returns, or whether it has stopped responding.  If an automated scheduler is being used to execute PartnerConnect, this information may be logged by the scheduler application.

2.     Files transmit status – Check the status of each file that is being sent.  Note which files remain in the PartnerConnect “tohub” directory and which have been moved to the “tohubarchive” directory.

3.     Client Log – Review the PartnerConnect log file for details regarding the processing of each transaction batch file.  If possible, you may want to try transmitting the failed transaction(s) on your test PartnerConnect system.

4.     Workspace – Login to the Workspace web application and check the status and content of the files you are investigating.

5       Maintenance

 

Over time, Hubspan may offer new versions of the PartnerConnect client software and the PartnerConnect service to provide additional functionality, support new types of files, and to address issues identified in previous versions.

5.1      Installing PartnerConnect Upgrades

When new versions of the PartnerConnect software become available from Hubspan, your implementation team should install the upgrade on a test PartnerConnect system.  This will permit your team to test and identify the impact the new software will have on your existing business systems before you start to use the upgrade to send production files.  When installing PartnerConnect Upgrades, be sure to first backup data such as configuration files, client log, and data directories. Follow closely the installation instructions that accompany the updated software.