UploadUpload- ---Service V3.5Service V3.5Service V3.5 ... · . csv .xml … . csv .xml … Figure 1: File Upload Through the Internet This document describes how to use the new

UploadUploadUploadUpload----Service V3.5Service V3.5Service V3.5Service V3.5

Users’ GuideUsers’ GuideUsers’ GuideUsers’ Guide

Date: November 17, 2011

Author: Ralph Busse, Marcus Osdoba

Recipients: external Users

Serial No. 5

IT Investment Upload-Service – Users’ Guide

UploadService - Users Guide Last change: 18.11.2011 10:59:00

Copyright 2006@ Allianz Global Investors Page 2 of 57

Document History No. Release Date Author Change 1 2.1 13.04.2006 Busse Initial Version 2 3.0 12.07.2006 Busse Updates for Release 3.0 (Reply) 3 3.2 05.10.2006 Busse Updates for Release 3.2 (Publish, Revoke) 4 3.3 28.12.2006 Busse Updates for Release 3.3 (Rebranding) 5 3.5 17.11.2011 Osdoba Java6 notes and new certificates

Confidentiality

This document is considered confidential and must not be disclosed to any parties outside of this project.




Table of Contents 1 Objectives of the AllianzGI Upload-Service ..................................................................... 3 2 Technical Realization......................................................................................................... 3 3 Available Client Alternatives ............................................................................................. 3

3.1 Manual Upload with a Web Browser (Form-Based Web Interface).......................... 3 3.2 Java Transfer Program ............................................................................................... 3 3.3 Using Scripts or Generic Web Libraries .................................................................... 3

4 Preparative Actions ............................................................................................................ 3 5 Using the Form-Based Web Interface................................................................................ 3

5.1 Entry Page .................................................................................................................. 3 5.2 File Transfer Form ..................................................................................................... 3 5.3 File Review Form....................................................................................................... 3 5.4 File Publication Forms ............................................................................................... 3 5.5 Status Retrieval Forms ............................................................................................... 3 5.6 File Download Forms................................................................................................. 3 5.7 Password Change Form.............................................................................................. 3

6 Using the Java Command-Line Client ............................................................................... 3 6.1 Java Client Installation ............................................................................................... 3 6.2 Java Client Configuration........................................................................................... 3 6.3 Java Client De-Installation ......................................................................................... 3 6.4 Password Change with the Java Client ...................................................................... 3 6.5 File Transfer with the Java Client .............................................................................. 3 6.6 File Publication with the Java Client.......................................................................... 3 6.7 Status Changes with the Java Client .......................................................................... 3 6.8 General Options.......................................................................................................... 3

6.8.1 Connecting to the Test Environment.................................................................. 3 6.8.2 Verbose Output .................................................................................................. 3 6.8.3 Using an Alternative Configuration File............................................................ 3 6.8.4 Output Redirection ............................................................................................. 3 6.8.5 Printing the Version number .............................................................................. 3

7 Integrating the Java Client into a Program......................................................................... 3 7.1 Installing the Java Library.......................................................................................... 3 7.2 Configuring the Java Library ..................................................................................... 3 7.3 De-Installing the Java Library.................................................................................... 3 7.4 File Transfer Within a Java Program ......................................................................... 3

8 Certificates Installation ...................................................................................................... 3 8.1 Web Browser Certificate Maintenance ...................................................................... 3 8.2 Java Certificate Maintenance ..................................................................................... 3

9 User Account Guidelines ................................................................................................... 3 10 Error Handling................................................................................................................ 3

10.1 Server Errors .............................................................................................................. 3 10.2 Java Client Errors ....................................................................................................... 3

11 Known Issues ................................................................................................................. 3 11.1 Restrictions................................................................................................................. 3 11.2 Erroneous Behaviour.................................................................................................. 3

12 Annex 1: Example Configuration File UploadClient.properties.................................... 3




List of Figures Figure 1: File Upload Through the Internet ............................................................................... 3 Figure 2: Entry Page to the Form-Based Interface..................................................................... 3 Figure 3: Login Dialog............................................................................................................... 3 Figure 4: Successful Login Response ........................................................................................ 3 Figure 5: File Transfer Dialog.................................................................................................... 3 Figure 6: Browser-Specific File Selection Dialog ..................................................................... 3 Figure 7: Result Page for Successful File Transfer.................................................................... 3 Figure 8: Result Page for Successful File Transfer (4-Eye)....................................................... 3 Figure 9: Result Page for Failed File Transfer ........................................................................... 3 Figure 10: File Review Entry Dialog ......................................................................................... 3 Figure 11: List of Open Transactions......................................................................................... 3 Figure 12: File Review Dialog ................................................................................................... 3 Figure 13: Status Page After Accepting the File........................................................................ 3 Figure 14: Status Page After Rejecting the File......................................................................... 3 Figure 15: Notification Mail After Rejecting the File................................................................ 3 Figure 16: Extended File Review Dialog with Reply ................................................................ 3 Figure 17: Status Page After Reply............................................................................................ 3 Figure 18: Notification Mail After Reply .................................................................................. 3 Figure 19: File Publication Dialog ............................................................................................. 3 Figure 20: Status Page After Successful File Publication.......................................................... 3 Figure 21: Notification Mail After File Publication................................................................... 3 Figure 22: Query Response Showing a Revocable File............................................................. 3 Figure 23: Confirmation Dialog During File Revocation .......................................................... 3 Figure 24: Status Page After Successful File Revocation.......................................................... 3 Figure 25: Confirmation Dialog when Revoking an Already Downloaded File ....................... 3 Figure 26: Status Lookup with a Transaction Id ........................................................................ 3 Figure 27: Status Lookup Result Page ....................................................................................... 3 Figure 28: Status Request Using the Status Query Dialog......................................................... 3 Figure 29: Extended Query Result Page .................................................................................... 3 Figure 30: Select a Transaction for Download........................................................................... 3 Figure 31: Popup and File Chooser to Save the File.................................................................. 3 Figure 32: List of Available Files .............................................................................................. 3 Figure 33: Password Change Dialog.......................................................................................... 3 Figure 34: Result Page for Successful Password Change .......................................................... 3 Figure 35: Result Page for Rejected Password Change............................................................. 3 Figure 36 : Security Alert in the Case of an Unknown Certificate ............................................ 3 Figure 37: Server Certificate Detail Window ............................................................................ 3 Figure 38: Root Certificate Properties ....................................................................................... 3

List of Tables Table 1: Summary of Web Form Pages ..................................................................................... 3 Table 2: Query Result Icons....................................................................................................... 3 Table 3: Java Client Configuration Parameters.......................................................................... 3 Table 4: Server Errors ................................................................................................................ 3 Table 5: Client Errors................................................................................................................. 3




1 Objectives of the AllianzGI Upload-Service The AllianzGI file upload service is a secure channel for transferring data files from an external supplier to Allianz Global Investors (AllianzGI) in Frankfurt, Germany. It complements and replaces the current transfer mechanisms via fax, email, and DreMove and allows for both manual and automated transfers from various environments and operating systems. This automation reduces the manual effort on both sides while increasing both efficiency and security. Starting from Release 3.0, Upload Service includes a restricted download functionality, allowing AllianzGI to update the transferred files and send them back to the supplier. In addition, Release 3.2 supports a pure download to transfer single files from AllianzGI to the supplier.

AllianzGI

web server

External Supplier

security system

web- browser

Java- client

firewall

Internet

*.csv *.xml

…

*.csv *.xml

…

Figure 1: File Upload Through the Internet

This document describes how to use the new service for transferring files to AllianzGI. This encompasses a short introduction into the technical realization as well as installation hints and usage guides for the web and Java interfaces. This document does not discuss the underlying business workflows. Structure and content of the transferred files, transfer scheduling, and error recovery actions are beyond the scope of this document. Please refer to other documentation or contact AllianzGI if necessary.




2 Technical Realization The system has been designed to fulfil the following requirements:

• Minimum installation and configuration effort for the external supplier. • Supports both manual and automated upload. • Once automated upload is set up, all transfers can be executed without manual interaction. • Only registered custodians may transfer data. • The originator of a transferred file can always be identified. • Authentication and authorization is based on password-protected user accounts and

performed for each upload. • The external supplier may choose between personalized accounts for individual upload

and generic accounts without password aging for automated processing. • The service fulfils auditing requirements by logging each upload with date, time, user

name and file name. • The client may operate behind a firewall. • The connection is encrypted. • The service can be used with a standard web browser or with a Java application program.

The upload is based on the standardized HTTPS protocol. As a consequence, the external supplier may deploy the upload service without installing any client software, by simply filling out some web form in a plain Internet browser. An additional Java client allows for automated transfer from within application programs or operating system scripts.

The actual transfer occurs over an encrypted Internet connection. A web server at AllianzGI in Frankfurt, Germany receives the file, checks the submitter’s credentials and passes the file on to the subsequent internal processing units. The submitter obtains a status message whether the submission was successful or not.

The requirements regarding file contents and file names are defined by the respective project that is responsible for further processing. File names are automatically checked during transfer and files that do not match the requirements are rejected.




3 Available Client Alternatives External suppliers have different possibilities to transfer files to the upload service. Manual upload can be performed with a simple web browser. Integration into existing scripts and programs can be performed with a Java program library.

3.1 Manual Upload with a Web Browser (Form-Based We b Interface)

The upload service provides a set of static form pages. These pages allow for file transfer by simply filling out the forms in a plain web browser. The transfer result is presented as a web page in the browser.

System Requirements

• Any system architecture with a web browser • Access to the files being transferred • Access to the Internet, possibly through a proxy server

Required Software Installation

• No specific Software • Any standard web browser supporting 128-bit encryption may be used.

Configuration

• No specific configuration necessary • If necessary, the web browser must be configured to use the supplier’s proxy server • The Internet address may be bookmarked in the browser




3.2 Java Transfer Program Automated file transfers can be performed with a facile Java program. User name, password, and file name are specified as command line parameters and the program connects to the server and transfers the file. In addition to command line and script processing the Java class can be integrated with other Java programs. The Java client is delivered in two variants:

1. as a pure Java Library (requires an existing JRE 1.6 installation) 2. as a full run-time environment (containing a pre-configured local JRE 1.6, the package is

very big (>35 MB) and works only for Microsoft Windows)

System Requirements

• Any system architecture with Java run-time environment (JRE 1.6) • Access to the files being transferred • Access to the Internet, possibly through a proxy server

Required Software Installation

• The software delivered by AllianzGI must be extracted to a local or shared directory

Configuration

• The location of the Java interpreter must be defined in the environment variable JAVA_HOME . (Not required for the pre-configured, full client version.)

• Optional configuration of a proxy server in the configuration file. • Optional configuration of a default user name in the configuration file.

Notes

• Temporary Internet connections must be established before starting the Java program. The Java program itself does not support automated dialling etc.

• Transfers with the Java client are subject to the same password aging rules as manual transfers. Usage of dedicated functional users may alleviate this problem, although regular password changes are recommended for functional users as well.

3.3 Using Scripts or Generic Web Libraries The HTTPS transfer of form data may as well be performed from within other web tools, like, e.g., wget or curl. Such solutions are not supported by AllianzGI and will always be performed at the supplier’s own risk.




4 Preparative Actions In order to use the upload service, the following actions have to be performed in advance:

1. Contact the responsible business department at AllianzGI. 2. Clarify file names, file content, transfer schedules, and error handling. 3. Arrange the details for test transfers. 4. Apply for the necessary user accounts for both test and production.1 5. Receive, install, and configure the client software

The test phase is usually performed with a single, dedicated test user.

In the production environment, there exist two different options regarding user accounts. The first option is to create a personal user account for each employee who should perform uploads. Current security policies require that personal passwords be changed once every 90 days. When 90 days pass without a password change, the user account is locked until the password is changed. The second option is to create a single functional user account for file transfer. Functional user accounts should change their passwords at the same rate. In contrast to personal accounts, this change is not enforced by the system, which alleviates problems with automated transfers. Due to the potential risk of having an unchanging password stored in the file system, a risk acceptance may be required for this solution.

Independent of password aging, every password may be changed at any time.

1 Existing user accounts, like, for example, for ICR or dit-Partner, should be re-used and can be authorized for the upload service.




5 Using the Form-Based Web Interface Manual upload through the form-based web interface does not require any software installation. A standard web browser can be used to transfer data to AllianzGI’s upload service. The supplier only has to fill user name and password into a web form and select a file from the file system. By pressing the submit button, this file will be transferred to AllianzGI. Another form allows changing the password. The following figures show all relevant web pages for a demonstration project. The concrete project pages may differ from this layout.

5.1 Entry Page Figure 2 shows the top-level entry page to the form-based interface. It provides some general information and allows for navigating to different online forms. From this page you reach, beneath others, all necessary forms for file transfer and password change, as described below.

Figure 2: Entry Page to the Form-Based Interface




The public production URL for the entry page is:

https://webservice.allianzglobalinvestors.de/Uploa dService/PROJECT/

The Intranet production URL for the entry page is:

https://upload.intradit.net:5101/UploadService/PRO JECT/

The public integration test URL is:

https://i-webservice.allianzglobalinvestors.de/Upl oadService/PROJECT/

The Intranet integration test URL is:

https://i-upload.vi.intradit.net:5101/UploadServic e/PROJECT/

In all cases, the string PROJECT must be replaced with the name of the concrete project to which you are transferring your files. Users having access to the AllianzGI Intranet should use the internal addresses in order to improve performance and security.

The following table summarizes the addresses of all relevant form pages:

Content Integration Test Production

Public Server https://i-webservice. allianzglobalinvestors.de

https://webservice. allianzglobalinvestors.de

Intranet Server https://i-upload.vi.intradit.net:5101 https://upload.intradit.net:5101

Entry page /UploadService/PROJECT/MainDialog

Login /UploadService/PROJECT/LoginDialog

File Transfer /UploadService/PROJECT/UploadDialog

File Review (internal) /UploadService/PROJECT/ReviewTidDialog

Status Lookup /UploadService/PROJECT/LookupDialog

Extended Status Query /UploadService/PROJECT/QueryDialog

File Publication (internal) UploadService/PROJECT/PublishDialog

File Download /UploadService/PROJECT/DownloadDialog

Password Change /UploadService/PROJECT/ChangePwdDialog

Table 1: Summary of Web Form Pages

When running behind a firewall, the supplier’s administrators are responsible for configuring the web browser’s proxy settings.




5.2 File Transfer Form File transfer is performed in two steps. Figure 3 shows the login form. After entering a user id and a password and pressing the Login button, the server will check the credentials and begin a working session. The green Login bar will be replaced with a red Logout bar and user information is printed in the lower left corner (see Figure 4).

Figure 3: Login Dialog

The user id corresponds to the user’s account name at AllianzGI’s security system. It is delivered to the user via email or pin letter once the account has been created. The user id should be entered without the domain part (i.e. internal or external). The password field hides the entered password such that no one can read it while it is typed in.




Figure 4: Successful Login Response

After successful login, files can be transferred to AllianzGI. Figure 5 shows the file transfer form.




Figure 5: File Transfer Dialog

In order to upload a file, the complete file name including path must be entered in the File Name field. A Browse button beneath the entry box allows for browsing the local file system (see Figure 6). The selected file name is automatically entered into the entry box. The button labels and the general layout depend on the locally installed browser.




Figure 6: Browser-Specific File Selection Dialog

By clicking on Upload , the file is transferred to AllianzGI. After successful processing, the browser will display a success page as shown in Figure 7. It reports the user name, the file name and the file size in bytes. An additional transaction id allows for tracking the file’s processing status.

Figure 7: Result Page for Successful File Transfer

When the receiving project is configured to follow the 4-eye principle, the result page will contain an indication that the file is kept at an intermediate location and must be accepted by a so-called Controller (Figure 8).




Figure 8: Result Page for Successful File Transfer (4-Eye)

When the transfer fails a corresponding error message is returned to the supplier. In the case of connection problems, the error display depends on the browser. Errors detected by the server, however, will be presented in the upload form’s upper area. Figure 9 shows an example for an empty file error. A list of possible error messages is given in Section 10.




Figure 9: Result Page for Failed File Transfer

Attention: The browser does not report an error when the selected file does not exist. Instead it will transfer an empty file to the server. In order to detect this error, the server will always reject empty files. Any submitted file must contain at least one byte of data.




5.3 File Review Form File review for files that are to be transferred using the 4-eye principle is currently performed by AllianzGI staff only. Therefore, the menu item Review Files is not available for external users. When a file has been transferred to the server, the responsible controllers receive an email with information about the new file. By clicking on a hyperlink in the email, the controller reaches the file review form where he can review the file and decide to accept or reject it (Figure 10).

Figure 10: File Review Entry Dialog

After entering the current transaction id in the entry page, the controller is presented the actual review page. When the exact transaction id is not known, the controller may use the Show All button to get a list of all open transactions (Figure 11). The links in the list lead directly to the corresponding review page.




Figure 11: List of Open Transactions




Figure 12 shows the review page with detailed file information and all necessary review buttons.

Figure 12: File Review Dialog

By clicking on Show , the file is opened and can be checked by the controller. When the content is unobjectionable, the controller will click on Accept to transfer the file to the final target location (Figure 13).




Figure 13: Status Page After Accepting the File




When the controller decides to reject the file, he enters an explanation into the comment field and clicks on Reject (Figure 14). The file will be deleted from the intermediate location and the supplier is informed by email about the rejection (Figure 15).

Figure 14: Status Page After Rejecting the File

Figure 15: Notification Mail After Rejecting the File




When the project is configured for combined up/download, the file review dialog enables the controller to modify the submitted file and send it back to the submitter (Figure 16).

Figure 16: Extended File Review Dialog with Reply

The controller opens the file using the Show button. He performs all desired changes and stores the file in the local file system. Back in the Review form, the changed file can be selected using the Browse button and can be sent back to the submitter by clicking on Reply (Figure 17). This reply does not transfer the file directly to the submitter but informs him by email that the new file is available for download (see Figure 18).




Figure 17: Status Page After Reply

Figure 18: Notification Mail After Reply




5.4 File Publication Forms File publication works similar to file upload, except that files are submitted by employees of AllianzGI and are downloaded by the external suppliers. Figure 19 shows the dialog for the Publish Files menu item.

Figure 19: File Publication Dialog

In order to publish a file, the complete file name including path must be entered in the File Name field. A Browse button beneath the entry box allows for browsing the local file system. The selected file name is automatically entered into the entry box. The button labels and the general layout depend on the locally installed browser.

By clicking on Publish , the file is transferred to the server and stored in the download area of a specific supplier. There are different ways to determine the correct supplier:




1. The workflow definition on the server contains a rule to determine the supplier from the file name.

2. The workflow definition on the server specifies a fix supplier for all publications within this workflow.

3. The supplier is explicitly specified in the Target Unit box.

If Target Unit is set to autodetect and the server fails to determine the supplier, the file is not published and a corresponding error message is displayed. The same is true when the file does not match the workflow’s naming requirements. When the supplier can be determined and the file name is correct, the file is stored on the server and the supplier is notified by email about the new file (Figure 21). The email address to be used can either be stored in the workflow definition on the server or it can be passed explicitly by filling the Target Mail entry box.

The Comment field may be used to pass an additional file description to the supplier.

After successful publication, the browser will display a success page as shown in Figure 20. It reports the submission details and the transaction id that can be used for tracking the file’s processing status.

Figure 20: Status Page After Successful File Publication




Figure 21: Notification Mail After File Publication

When the transfer fails a corresponding error message is displayed. In the case of connection problems, the error display depends on the browser. Errors detected by the server, however, will be presented in the upload form’s upper area. A list of possible error messages is given in Section 10.

Attention: Just like in the upload case, every published file must contain at least one byte in order to detect nonexistent files.




Revoking a Published File A Controller may revoke an outdated or wrongly published file in order to remove it from the download area. For this purpose, the corresponding transaction must be sought via Single Lookup or Status Query (see Section 5.5) or via Download Files �� Show Unread/All (see Section 5.6). The result pages display a trashcan icon beneath every revocable file (Figure 22).

Figure 22: Query Response Showing a Revocable File




A click on that icon displays the following confirmation dialog where the controller has to approve the revocation and may insert a remark that explains the revocation reason (Figure 23).

Figure 23: Confirmation Dialog During File Revocation




After clicking on Revoke , the file is removed from the server and the response page shown in Figure 24 is displayed. Depending on project configuration, the file is either moved to an archival area or is completely removed from the file system. In either case the file not available for download anymore. The revocation cannot be undone.

Figure 24: Status Page After Successful File Revocation




If the file to be revoked has already been downloaded by the supplier, a corresponding warning message is displayed in the top area of the confirmation dialog (Figure 25). The revocation can nevertheless be performed. The controller is responsible for informing the supplier about the revocation.

Figure 25: Confirmation Dialog when Revoking an Already Downloaded File




5.5 Status Retrieval Forms The menu item Single Lookup allows retrieving the current status of a specific transaction. After inserting the transaction id in the lookup form (Figure 26) the complete transaction history is returned on the result page (Figure 27).

Figure 26: Status Lookup with a Transaction Id




Figure 27: Status Lookup Result Page




The menu item Status Query allows formulating more complex state requests. After entering all conditions (Figure 28), the result page shows the list of all matching transactions (Figure 29). Transaction details are shown by following the hyperlinks on the result page.

Figure 28: Status Request Using the Status Query Dialog




Figure 29: Extended Query Result Page

Both the Single Lookup detail page and the Status Query result list may contain icons to perform actions on the respective files. The available actions depend on file status, workflow capabilities, and user permissions.

Icon Action

Presents the transaction details in a new browser window. This functionality is convenient when multiple result files are to be processed. Using the web browser’s history navigation may be cumbersome in the context of query results. The standard hyperlink beneath the icon shows the transaction details in the current window.

Presents the selected file (Download)

Presents the review dialog for this transaction

Presents the revoke dialog for this transaction

Table 2: Query Result Icons




5.6 File Download Forms In the case of combined up/download the controller may send an edited version of the submitted file back to the submitter. The submitter is informed by email about the available file (see Figure 18). In order to retrieve the file, the submitter inserts the transaction id in the download form and clicks on Download (Figure 30). This opens a dialog that allows for opening or saving the file (Figure 31).

Figure 30: Select a Transaction for Download

Figure 31: Popup and File Chooser to Save the File

Alternatively, both the complete list of available files and the list of unread files can be displayed by clicking on Show All or Show Unread , respectively (Figure 32).




Figure 32: List of Available Files




5.7 Password Change Form Figure 33 shows the password change form. The user must enter the account name and the current password in the fields User Id and Old Password . The new password must be entered twice in the New Password fields in order to avoid typing errors in the obscured input fields.

Figure 33: Password Change Dialog

By clicking on ChangePwd the password change request is sent to AllianzGI. The browser will then display a success or failure page (Figure 34, Figure 35). For safety reasons, any open session is automatically closed.




Figure 34: Result Page for Successful Password Change

Figure 35: Result Page for Rejected Password Change




AllianzGI security guidelines make several demands on the format of valid passwords. These are given in Section 8. Please note that the password change function can still be used when the login is blocked after exceeding the password aging limit.




6 Using the Java Command-Line Client An optional Java client allows for automated file transfer. Every call to the program will transfer a given file and return a status code. By integrating the program into a scheduled batch script, the file transfer can be fully automated. There are two scripts for running the Java client:

• upload.bat for Microsoft Windows • upload.sh for the Unix Bourne Shell (sh)

All following examples are based on the Windows version and can easily be adapted to the Unix world by changing the path separators from \ to /. Instead of using the shell scripts like:

upload.bat [Parameterliste]

it is also possible to call the java interpreter directly:

java -jar UploadClient.jar [Parameterliste]

Both call types can be executed manually or included in shell scripts or cron jobs.

6.1 Java Client Installation The Java client is delivered in two different versions. The simple client (UploadClient.zip , 2 MB) requires an existing Java installation (at least JRE 1.6). The big client (UploadClientJRE.zip , 23 MB) is only available for Microsoft Windows and contains a complete, pre-configured Java run-time environment.

Both clients are delivered as zip files that must be extracted to a local or shared directory (e.g. C:\Program Files\UploadClient (for Windows) or /usr/local/uploadclient (for Unix)).

6.2 Java Client Configuration For running the simple Java client the environment variable JAVA_HOME must be set to the local Java installation. The full Java client uses a relative path to the included Java interpreter. The script must be started within the installation directory. When it shall be run from different places, it must be adapted accordingly.

The client uses an optional configuration file UploadClient.properties . It is processed automatically when it is found in the current directory. The following parameters may be defined:




Parameter Description Default.User Meaning:

Default user name. Will be used when no user name is given on the command line.

Example: Default.User=doejohnc

Default.Pwd Meaning: Default user password. Will be used when no user password is given on the command line. AllianzGI discourages the use of this field, as it is a security leak. This field will not be updated durin g a password change.

Example: Default.Pwd=secret

Default.Project Meaning: Default project name. Will be used when no project name is given on the command line.

Example: Default.Project=MyProject

System.http.proxyHost Meaning: Host name of a proxy server for the http protocol. This setting is required when the client is located behind a firewall. Although all data transfer is performed using the https protocol, http is required for establishing the initial connection.

Example: System.http.proxyHost=myproxy.mydomain.com

System.http.proxyPort Meaning: Port number of a proxy server for the http protocol (see System.http.proxyHost ). This setting is required when the client is located behind a firewall. Common ports are 80 and 8080.

Example: System.http.proxyPort=80

System.https.proxyHost Meaning: Host name of a proxy server for the https protocol. This setting is required when the client is located behind a firewall.

Example: System.https.proxyHost=myproxy.mydomain.com

System.https.proxyPort Meaning: Port number of a proxy server for the https protocol (see System.https.proxyHost ). This setting is required when the client is located behind a firewall. Common ports are 80, 8080, 443, and 8443.

Example: System.https.proxyPort=443

System.https.proxyUserName Meaning: User name to be used when the proxy server requires authorization.

Example: System.https.proxyUserName=John.Doe

System.https.proxyPassword Meaning: Password to be used when the proxy server requires authorization (see System.https.proxyUserName ).

Example: System.https.proxyPassword=MyProxyPassword




Parameter Description System.javax.net.ssl.\ trustStore

Meaning: Name of a dedicated Java trust store when the default trust store at %JAVA_HOME%\jre\lib\security\cacerts shall not be used.

Example: System.javax.net.ssl.trustStore=cacerts

System.javax.net.ssl.\ trustStorePassword

Meaning: Trust store password, required when it differs from the default Java trust store password (see System.javax.net.ssl.trustStore ).

Example: System.javax.net.ssl.trustStorePassword=MyStorePassword

Table 3: Java Client Configuration Parameters

The configuration file is optional. The first three parameters can also be defined as command line parameters (user name, password, and project; see below). The other parameters can be defined as Java system properties by removing the System. prefix and passing them with -D to the Java interpreter.

Example:

java –Dhttps.proxyHost=myproxy.mydomain.com -Dhttps.prox yPort=443 \ -jar UploadClient.jar –user doejohnc –pwd secret –project myproject \ –file C:\transfer\AllianzGI_test_060929.csv

Listing 1: Passing Configuration Parameters on the Command Line

The pre-defined start scripts do not support passing system properties. They need be adapted for that purpose.

An empty configuration file is contained in the client package and can be adapted to the local requirements (see Section 12).

6.3 Java Client De-Installation The Java client is de-installed by removing all extracted files. The program does not perform any configuration changes at other locations.

6.4 Password Change with the Java Client The script is called with three parameters: the user name, the current password, and the new password. An additional project parameter is required when there is no default project defined in the configuration file (see Section 6.2).

The following example changes the password of user doejohnc from secret to moresecret:

upload.bat –user doejohnc –oldpwd secret –newpwd mo resecret

Listing 2: Password Change Command Line

Notice: For specifying the current password, –pwd may be used instead of –oldpwd as well.

Please see Section 8 for password format requirements and Section 10 for a list of error messages.




6.5 File Transfer with the Java Client The script is called with three parameters: the user name, the password, and the file name. An additional project parameter is required when there is no default project defined in the configuration file (see Section 6.2). An optional comment may be passed in addition.

The following example transfers the file C:\transfer\AllianzGI_test_060929.csv for user doejohnc with password secret for project myproject:

upload.bat –user doejohnc –pwd secret -project mypr oject \ -comment "daily transfer" –file C:\transfer\Allian zGI_test_060929.csv

Listing 3: File Transfer Command Line

Notice: The key word –file is optional; the last parameter will automatically be interpreted as a file name. Parameters containing spaces must be included in quotes, as usual.

The Java client writes standard messages to the standard output channel and error messages to the standard error channel. For later analysis, both output can be redirected to files. In addition, the program returns a status code that may be analyzed with the ERRORLEVEL command in DOS and the $?2 shell variable in Unix. See upload.bat and upload.sh for examples. The list of status codes is given in Section 10.

6.6 File Publication with the Java Client File publication to a download directory is very similar to the file upload case. The only difference is that a supplier and a target email address can be specified to determine the correct location and recipient for the file:

upload.bat –user doejohnc –pwd secret -project mypr oject \ -targetunit mgr1 –targetmail [email protected] \ –comment "daily report for download" \ –publish C:\transfer\AllianzGI_test_publish.csv

Listing 4: File Publication Command Line

File publication is only available to AllianzGI employees.

6.7 Status Changes with the Java Client The post processing unit within AllianzGI may use the Java client to update the status of a processed file in the database. Given a transaction id or an output file name, the corresponding database entry may be set to processed or to processingfailed. An additional comment can be passed to specify the failure reason.

upload.bat –user importer –pwd asecret -project myp roject \ -tid myproject200609291200123456 –status processed –comment "successfully processed by file importer"

Listing 5: Status Change Command Line

2This variable is used by the Bourne shell. Other shells may use different variables.




6.8 General Options The following paragraphs describe further command line options and program details.

6.8.1 Connecting to the Test Environment All calls to the Java client connect by default to the production environment. During the test phase, the additional parameter –test must be used on the command line in order to connect to the test server instead of the production server.

Example:

upload.bat –test –user doejohnc –pwd secret –project myproject \ –file C:\transfer\AllianzGI_test_060929.csv

Listing 6: Command Line for Transferring a File to the Test Server

Notice: When connecting to the test server, the Java client returns different return codes. In case of a successful file transfer, it does not return the OK status (0) but the Warning status (1) and prints the following message: “ Warning: The request was processed in the test environment. ”

6.8.2 Verbose Output When –verbose is specified on the command line, the Java client prints diagnostic output. Among other things, the connection handshake is logged and the complete server response is printed.

Example:

upload.bat –verbose –user doejohnc –pwd secret –project myproject\ –file C:\transfer\AllianzGI_test_060929.csv

Listing 7: Command Line for Transferring a File wit h Verbose Output

The above command will print the following output:

>>> Loading user properties from UploadClient.prope rties >>> Assigning system properties... >>> Performing file upload: >>> url = https://webservice.allianzglobalinvestors .de/UploadService >>> user = doejohnc >>> project = myproject >>> file = C:\transfer\AllianzGI_test_060929.csv >>> Sending file C:\transfer\AllianzGI_test_060929. csv for user doejohnc and project myproject. >>> Constructing request. >>> Service URL = https://webservice.allianzglobalinvestors.de/Upload Service >>> User Id = doejohnc >>> File name = C:\transfer\AllianzGI_test_060929 .csv >>> Sending request. >>> Connecting to https://webservice.allianzglobalinvestors.de/Upload Service >>> Response Code = 200 >>> Response Text = OK




>>> Request successfully processed. >>> Returned message content: -------------------------------------------- <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transit ional//EN"> <html> ... removed return page content ... </html> -------------------------------------------- >>> Done. Successfully sent 3231 bytes.

Listing 8: Example Output for the –verbose Flag

6.8.3 Using an Alternative Configuration File The parameter –propfilename filename can be used to specify an alternative configuration file to be used instead of the default configuration file UploadClient.properties.

Example:

upload.bat –propfilename C:\UploadClient\MySettings.properties \ –user doejohnc –pwd secret –file C:\transfer\Allia nzGI_test_060929.csv

Listing 9: Command Line for a File Transfer Using an Alternative Configuration File

6.8.4 Output Redirection As already mentioned, the Java clients prints output and error messages to the usual channels. These can be redirected into files for later analysis.

The standard and error output can be redirected into different files by calling:

command > output.log 2> error.log

They can be redirected into a common file by calling:

command > all.log 2>&1

By using >> instead of >, the output will be appended to an existing file instead of overriding the old content. Further comments regarding output redirection can be found in the scripts.

6.8.5 Printing the Version number The following call:

upload.bat –version

prints the Java client’s version number.




7 Integrating the Java Client into a Program The third alternative consists of integrating the Java client with an own Java application program (at least JRE 1.6). This allows for full integration into the existing infrastructure.

7.1 Installing the Java Library For using the upload client in an own Java application, the Java library archive UploadClient.jar must be added to the program’s class path. It is contained in both client packages and may be copied to any place (see Section 6.1). The full API documentation is provided in the client package (UploadClient-doc.zip ).

7.2 Configuring the Java Library The library need not be configured. All required parameters are passed as arguments to the different calls. The only exceptions are the proxy and trust store settings, which have to be passed as system properties on the command line or must be set explicitly by calling System.setProperty() in the outer Java program.

Attention: The standard configuration file UploadClient.properties is not evaluated when the Java library functions are called directly!

The following example listings show how to set some proxy settings on the command line, and within a program, respectively:

java –Dhttps.proxyHost=myproxy.mydomain.com -Dhttps.prox yPort=443 \ MyMainApplication

Listing 10: Proxy Configuration on the Command Line

class MyOtherApplication { public static void main(String[] arg) { ... System.setProperty("https.proxyHost","myproxy.myd omain.com"); System.setProperty("https.proxyPort","443"); ... } }

Listing 11: Proxy Configuration within a Program

The library does not distinguish between test and production settings. The correct service URL must be passed as a parameter to the library and the calling program is responsible for selecting the correct URL.

7.3 De-Installing the Java Library The Java library UploadClient.jar can simply be deleted. The program does not perform any configuration changes at other locations (see Section Error! Reference source not found.).




7.4 File Transfer Within a Java Program Program details are not contained in this document. Please check the API documentation or the German Users’ Guide.

The following example program gives an impression of how to transfer a file to AllianzGI:

public void transfer() { String url = "https://webservice.allianzglobalinvestors.de/UploadService"; String user = "doejohnc"; String pwd = "secret"; String project = "myproject"; String file = "C:/transfer/example_file_20050307.csv"; String comment = " example transfer"; System.setProperty( "https.proxyHost", "myproxy.mydomain.com"); System.setProperty( "https.proxyPort", "443"); try { UploadClient upload = new UploadClient(url, project); String tid = upload.uploadFile(user, pwd, file, comment); System.out.println( "Successfully sent file as tid " + tid + "."); } catch (UploadWarning ex) { System.out.println( "Request successfully processed but returned " + "an unexpected result: " + ex.getMessage()); } catch (UploadError ex) { System.out.println( "Caught server error: " + ex.getMessage()); } catch (IOException ex) { System.out.println( "Caught IOException: " + ex.getMessage()); } }

Listing 12: Java Example Program for the File Transfer

Other functions are available for sending byte arrays and data streams, for publishing a file for download, for status changes, and for changing the user’s password. Please see the Java documentation and the German Users’ Manual for details.




8 Certificates Installation Https encryption is based on server certificates. The certificates provide the encryption keys and guarantee authenticity of the service address. Both AllianzGI certificates (webservice.allianzglobalinvestors.de and i-webservice.allianzglobalinvestors.de) are issued from VeriSign, Inc. As certificates are only valid for a limited amount of time, some clients may have to update their trust stores in order to get the most recent certificate versions.

8.1 Web Browser Certificate Maintenance All current web browsers should accept the server certificates without further notice. When the system certificates installed with your browser are too old, however, the browser may ask you whether to accept the server certificate (see Figure 36).

Figure 36 : Security Alert in the Case of an Unknown Certificate

You have three options to proceed:

1. Accept the server certificate for this session only. Close the alert window by clicking on Yes.

2. Install the server certificate permanently. In order to install the certificate for this and all future sessions, click on View Certificate. A new windows pops up (Figure 37), where you can click on Install Certificate to permanently install the certificate in the browser’s trust store. In all future sessions, the certificate will be accepted without further notice.




Figure 37: Server Certificate Detail Window

3. Install the root certificate permanently. The better alternative is to permanently install the VeriSign root certificate instead of the actual server certificate. The root certificate has a longer lifetime and the browser will automatically accept all certificates signed by VeriSign. Instead of choosing Install Certificate in Figure 37, activate the Certification Path tab, select the root certificate, click on View Certificate, and select Install Certificate in the final window (Figure 38).

Figure 38: Root Certificate Properties




If the browser does not show an Install Certificate button, you can import the root certificates by double-clicking on the certificates files and following the Windows certificate installation process. See the next section for details about the certificate files.

The above actions represent the Internet Explorer’s mechanism. Other browsers may use different dialogs for performing the same actions.

8.2 Java Certificate Maintenance When using the Java client, you may get the following error message, when the installed root certificates are outdated:

javax.net.ssl.SSLHandshakeException: java.security.cert.CertificateException: Couldn't find trusted certificate

In this case, the VeriSign root certificates are newer than those stored in the Java trust store. In order to update the trust store, import the files VeriSign-Class3-PrimaryCA-G5.cer and VeriSign-Class3-ServerCA-G3.cer into the Java trust store. Both files are contained in the client distribution.

VeriSign-Class3-PrimaryCA-G5.cer:

VeriSign Class 3 Root Certificate Eigentümer: C=US,O=VeriSign, Inc.,OU=VeriSign Trus t Network,OU=(c) 2006 VeriSign,Inc. - For authorized use only,CN=VeriSign Class 3 Public Primary CertificationAuthority - G5 Aussteller: C=US,O=VeriSign, Inc.,OU=VeriSign Trus t Network,OU=(c) 2006 VeriSign, Inc. - For authorized use only,CN=VeriSign Class 3 Public Primary Certification Authority - G5 Seriennummer 18DAD19E267DE8BB4A2158CDCC6B3B4A Gültig ab: Nov 8 00:00:00 2006 GMT bis: Jul 16 23:59:59 2036 GMT Zertifikatfingerabdrücke:

SHA1: 4E:B6:D5:78:49:9B:1C:CF:5F:58:1E:AD:56:BE:3 D:9B:67:44:A5:E5

VeriSign-Class3-ServerCA-G3.cer:

VeriSign Class 3 International Server CA - G3 Inte rmediate Certificate Eigentümer: OU=VeriSign Trust Network,OU=Terms of use at htt ps://www.verisign.com/rpa (c)10,O=VeriSign, Inc. Aussteller: C=US,O=VeriSign, Inc., OU=VeriSign Tru st Network, OU=(c) 2006 VeriSign, Inc. - For authorized use only,CN=VeriSign Class 3 Publi c Primary Certification Authority - G5 Seriennummer 641BE820CE020813F32D4D2D95D67E67 Gültig ab: Feb 8 00:00:00 2010 GMT bis: Feb 7 23:59:59 2020 GMT Zertifikatfingerabdrücke: SHA1: B1:8D:9D:19:56:69:BA:0F:78:29:51:75:66:C2:5 F:42:2A:27:71:04

The corresponding issuer statement can be found at: https://www.verisign.com/repository/CPS/ The most recent VeriSign certificates can be directly downloaded from: http://www.verisign.com/support/install/intermediate.html

Note: Before January 1st 2012, the legacy certificates need to be installed, too. See Readme.txt.




The certificates are installed by adding them with the Java keytool to the Java trust store, which is located at %JAVA_HOME%\jre\lib\security\cacerts:

keytool -import -noprompt \ -file VeriSign-Class3-Primary-2028.cer \ -alias verisignclass3ca2028 -keypass changeit \ -keystore %JAVA_HOME%\jre\lib\security\cacerts -st orepass changeit keytool -import -noprompt \ -file Verisign-Class3-SecondaryCPS-2011.cer \ -alias verisignserverca2011 -keypass changeit \ -keystore %JAVA_HOME%\jre\lib\security\cacerts -st orepass changeit

Listing 13: Importing the new Certificates

The client package contains a script named make_truststore. It copies the Java trust store into the local directory and adds the new certificates. The resulting trust store can be copied back into the Java directory or may be used as a specific trust store by setting the corresponding configuration parameters System.javax.net.ssl.trustStore and System.javax.net.ssl.trustStore-Password (see Section 6.2). The default password used by Java is changeit and need not be specified in the configuration file.




9 User Account Guidelines Every user of the upload service gets a user account for authorization. Each user account consists of a domain prefix (usually internal or external), followed by a period and a unique account id. After successful account creation, the user will get the account name and the initial password with separate PIN letters. The initial password must be changed at the first login. The domain prefix need not be entered for login.

Password Rules

Each user account requires a password, which can be changed at any time. Passwords have to follow the following rules:

• It must be at least 7 characters long. • It must not contain sequences of three or more identical or consecutive characters. • It must not contain consecutive keyboard sequences (e.g., asdf) • It must contain at least one letter, one digit, and a special character. • It must not contain the account name. • Passwords cannot be re-used.

Password Aging

Each personal password has to be changed after at most every 90 days. When this change does not occur in time, the account will not allow file transfers until the password has been changed. The password change action from the upload menu is still operating and can be used to change the password even when it has expired. After a password change, the account can immediately be re-used for file transfers.

Under certain conditions, AllianzGI will provide functional accounts without password aging, i.e., the password will never expire. Nevertheless, it should be changed at regular intervals in order to reduce the risk that unauthorized persons get access to the password.

Account Locking

The account is automatically locked when a wrong password has been entered five times in succession. It is not possible to unlock the account by entering the correct password. In this case, the user must contact AllianzGI and ask for unlocking. Usually, the account will get a new random password that is sent out to the user with a PIN letter. If, on the other hand, the old password is still known – for example when a user has locked another user’s account by mistake – the old password can directly be re-instated without the need for a PIN letter. The account is immediately unlocked and can be used without further restrictions.

Due Diligence

Every user is responsible for thorough account handling. Account name and password should not be revealed to other persons. This information would enable any person to submit files to AllianzGI on behalf of the user and his company.




10 Error Handling

10.1 Server Errors The following table describes all possible errors issued by the web server. They will either be displayed in the browser window or written to the error output. Each error has an error number, a general description, a detail description, and an http status code.

Error Code

http Status General Description and List of Possible Causes

0 200 OK 101 500 Internal Server Error

• Could not connect to security system. Please try again later. • General security system fault. Please try again later. • Runtime error. Please try again later. • Could not store file to local directory. Server configuration problems: • Missing mandatory property: XXX • Invalid Boolean property (XXX) for key XXX. • Failed to verify temporary file location. • Failed to verify target file location. • Failed to read resource: XXX • Invalid mail recipient or sender. • Could not initialize UploadServletProperties. • Invalid numeric property (XXX) for key XXX

102 400 Incorrect or Missing Request Data (Bad Request) • Missing mandatory parameter: XXX • Confirmation password does not match original. Please try again. • Received empty file. Please check file name. • Missing file name. • File name does not meet naming requirements. • Could not parse request object. • Parameter XXX is not a file parameter. • Parameter XXX must not be a file parameter. • Unsupported command qualifier: XXX

103 413 Payload Too Big • The request was rejected because its size exceeds the allowed limit.




Error Code

http Status General Description and List of Possible Causes

104 401 Authorization Failed • Invalid login. • Password expired. Please change. • Account locked. Please contact AllianzGI. • Password rule violation: XXX • User XXX is not authorized for file upload. • Could not determine bank id for user XXX. • User does not have the required security level.

Table 4: Server Errors

10.2 Java Client Errors The Java client maps server errors to status codes and may report further errors.

Error Status Error Cause

0 OK Request successfully processed.

1 Warning Cause #1: Successful processing with unexpected result format. Cause #2: Successful processing in the test environment. Cause #3: No processing (when printing the version number).

2 Usage Wrong command line parameters.

3 Configuration Error Erroneous configuration file.

4 I/O-Error Errors while reading the configuration or transfer file; connection problems to the server.

5 Runtime-Error General run time fault.

101 Internal Server Error Server error (see above)

102 Incorrect or Missing Request Data Server error (see above)

103 Payload Too Big Server error (see above)

104 Authorization Failed Server error (see above)

Table 5: Client Errors




11 Known Issues

11.1 Restrictions In the current version, the following restrictions apply:

• Transferred files must not be empty (0 bytes) • Transferred files must not be bigger than 5 MB • The reply workflow allows at most one response per transaction. • Reply responses cannot be revoked.

11.2 Erroneous Behaviour Currently, we do not know of any erroneous behaviour in AllianzGI Upload Service.




12 Annex 1: Example Configuration File UploadClient.properties

The following listing shows an example of the optional configuration file UploadClient.properties.

# # Configuration file for the AllianzGI File Upload Service Client # ================================================= ============== # # File: UploadClient.properties # Copyright: Copyright (c) 2005-2006 # Company: Allianz Global Investors Kapitalanlage gesellschaft mbH, Frankfurt am Main # Date: 03.03.2005 # # ------------------------------------------------- --------- # Use the following two lines to define a default u ser and # default password. Insert the relevant data at the end and # remove the leading hash sign. # # WARNING: Using this feature is not recommended! # ------------------------------------------------- --------- #Default.User = #Default.Pwd = # ------------------------------------------------- --------- # Adapt and uncomment the following line to define the # project name for file submission. # ------------------------------------------------- --------- #Default.Project = testproject # ------------------------------------------------- --------- # Adapt and uncomment the following lines to config ure # proxy settings for local environment. # ------------------------------------------------- --------- #System.http.proxyHost = proxyhos t.domain.com #System.http.proxyPort = 80 #System.https.proxyHost = proxyhos t.domain.com #System.https.proxyPort = 443 #System.http.proxyUserName = proxyuse r #System.http.proxyPassword = proxypwd # ------------------------------------------------- --------- # Adapt and uncomment the following lines to config ure # a local trust store for the https connection. # ------------------------------------------------- --------- #System.javax.net.ssl.trustStore = cacerts #System.javax.net.ssl.trustStorePassword = changeit # ------------------------------------------------- --------- # EOF # ------------------------------------------------- ---------

Listing 14: Example Configuration File UploadClient.properties

Documents

UploadUpload- ---Service V3.5Service V3.5Service V3.5 ... · *. csv *.xml … *. csv *.xml … Figure 1: File Upload Through the Internet This document describes how to use the new

UploadUpload- ---Service V3.5Service V3.5Service V3.5 ... · . csv .xml … . csv .xml … Figure 1: File Upload Through the Internet This document describes how to use the new