SOAP File Transfer. Specification

Transcription

1 SOAP File Transfer Specification Version Sep-2015

2 Date Version Description 18-Aug Original Version 30-Aug Added section on sample code 30-Jun Added FAQ section 03-Jul ilink administration documentation added 01-Sep Updated for new layout 04-Apr Updated TLS to v1.2 minimum Page 2

3 Table of Contents 1 Introduction Quick Start Requirements ilink connectivity setup Upload File Service Upload File Request Upload File Response Download Files Service Download Files Request Download Files Response Sample Code Protecting Your Certificate NET Sample Code Java Sample Code Appendix A Upload File Example HTTP Request HTTP Response Appendix B Download Files Example HTTP Request HTTP Response Appendix C Westpac HTTPS addresses Test Environment Production Environment Appendix D FAQ Page 3

4 1 Introduction This document defines Westpac s WIBS SOAP file transfer protocol. The SOAP file transfer protocol allows partners to transfer files securely and reliably over the internet. It provides a standard mechanism for transport using existing infrastructure (such as web servers, proxy servers and firewalls). Communication uses standard TCP/IP ports to prevent the need for network changes. SSL is used to provide encryption of data between partners, and authorisation assures the identity of each partner. The intended audience of this document are software developers who wish to implement this messaging protocol. Knowledge of SOAP, HTTP and SSL is assumed. This document gives an English description of the SOAP services provided. This is followed by example messages for reference. Page 4

5 2 Quick Start Customer task Westpac task 1. Qvalent implementation consultant creates an ilink test account for the customer s technical contact. 2. Customer contact completes ilink connectivity form in test ilink. 3. Customer develops SOAP connectivity solution 4. Qvalent implementation consultant configures file routing. 5. Customer undertakes testing in the test environment. 6. Once customer is satisfied that testing is complete a sign off is required to progress into production. 7. Qvalent implementation consultant creates an ilink production account for the customer s technical contact. 8. Customer contact completes ilink connectivity form in production ilink. 9. Qvalent implementation consultant configures file routing. 10. Customer tests the SOAP connection in the live environment. 11. Once this testing is successful customers can perform low value live testing of the other Westpac products that are being implemented. Page 5

6 3 Requirements To use the Westpac SOAP file transfer services, you will need a SOAP client that supports the following standards: SOAP TLS 1.2 or higher Your SOAP library should also be able to generate client side stubs to simplify your coding. Page 6

7 4 ilink connectivity setup In the early stages of your Westpac project you will be asked to provide the contact details of the IT person who will be responsible for setting up your SOAP connection. Once these details are received you will be provided with an ilink login to enter your IP addresses. The ilink connectivity process has the following steps 1. The Qvalent implementation consultant will provide the user s technical contact with a login to the ilink test instance. 2. Fill in the setup connectivity form and submit 3. Notify your Qvalent and Westpac implementation managers that you have completed the connectivity form 4. The Qvalent implementation consultant will configure the file routing and notify all stakeholders when this is done 5. User to send and receive test files to confirm the SOAP connection 6. Once the Qvalent implementation consultant has received confirmation that all relevant testing has been completed steps 1 5 will need to be repeated in the production environment. 4.1 ilink URLs Test Production Setup connectivity form To setup your connectivity, click the Connectivity menu option at the top of the screen, then press the Setup Connectivity button. The Setup Connectivity will be displayed where you can enter the following details: PGP Key If you have elected to PGP encrypt files sent to Westpac, upload your PGP key here. Otherwise, this field will not be shown on the screen. IP addresses The WIBS solution has a white list of IP addresses accepted for each user. Users need to provide the IP address or addresses that their incoming requests will be coming from, this is the external IP address taking into account any proxy servers or other externally facing network infrastructure. This can be found by logging on to ilink on your server and taking the browser address shown in the IP addresses section of the connectivity form. After you press Save, you will see the WIBS server details on the Setup connectivity page. Westpac s key this is the public key that you will need to use to decrypt the files you receive from WIBS. This will only be displayed if encryption is enabled. Your key - You can use these fields during testing to confirm which keys you have loaded into ilink. This will only be displayed if encryption is enabled. Page 7

8 Your credentials - The download queue ID will be included in your SOAP requests. This section also contains the details of the client certificate that you will use to authenticate with the WIBS server. IP Addresses lists the IP addresses allowed to access this connectivity. Page 8

9 5 Upload File Service The Upload File service allows you to upload a file to Westpac with associated metadata. 5.1 Upload File Request All parameters in the upload request are optional except for filecontent. Parameter Name fileid filetype mimetype Filename Parameter filecontent Description The unique identifier for this file. If present, this value must be unique for each file sent. If you cannot generate a unique identifier for each file, you should omit this parameter. If you do not know whether a file was transmitted successfully or not, you can resend it with the same fileid. Westpac will only process the fileid once. If the same fileid is received again, the file will be ignored by Westpac. This value should be used if you send different file types to Westpac. Your Westpac representative will provide the values you should use. If you only send one type of file, you can omit this parameter. The MIME type for the file if known, e.g. text/plain The name of the file uploaded if known, e.g. directentry txt Arbitrary meta-data parameter relating to this message. Normally you will only provide this information if your Westpac representative requests it. Each parameter is a name-value pair containing additional meta-data. The file contents encoded using base64. Your SOAP client must also provide a valid client certificate with the request. You will need to find out how to specify your client certificate information to your SOAP library. 5.2 Upload File Response If the upload succeeds, an empty response message will be received. If a certificate authentication error occurs, a HTTP 403 response will be received. If any other error occurs, a HTTP 500 response will be received containing a SOAP fault. 6 Download Files Service The Download Files service allows you to download any pending files with associated meta-data. 6.1 Download Files Request Parameter Name Description Page 9

10 Parameter Name queueid Description The unique identifier for queue to fetch files from. Your Westpac representative will provide you with this value. Your SOAP client must also provide a valid client certificate with the request. You will need to find out how to specify your client certificate information to your SOAP library. 6.2 Download Files Response If a certificate authentication error occurs, a HTTP 403 response will be received. If any other error occurs, a HTTP 500 response will be received containing a SOAP fault. Otherwise, the response will contain a number of file elements. If no messages were pending for you to download, no file elements will be present in the response. Each file element contains the following information. Parameter Name fileid filetype mimetype filename parameter filecontent Description The unique identifier for this file. This value will be unique for each file you download and you can use this value for duplicate checking. This value will be present if you receive file types from Westpac. Your Westpac representative will inform you of the applicable values (if any). The MIME type for the file if known, e.g. text/plain The name of the file uploaded if known, e.g. directentry txt Arbitrary meta-data parameter relating to this message. Normally you will only receive this information if you have discussed it with your Westpac representative. The file contents encoded using base64. Note that if a network error occurs while you are downloading the files, the same files will be sent to you again next time you make a download files request. However, if an error occurs in your system after you have received the files but before you have saved them to permanent storage, you will need to contact Westpac to resend the applicable files. Note that not all the pending files may be sent to you in the download files response due to size restrictions. You should keep sending polling the Download Files Service until you receive an empty response. This will ensure that you receive all pending files in a timely fashion. The following pseudo-code demonstrates this approach: 1. Send Download Files request and get receive response 2. If the response contains no files, stop 3. Otherwise, process the files in the response and repeat from step 1 Page 10

11 7 Sample Code The developer pack includes sample code for.net and Java. This sample code gives you an idea of what is required to send and receive files using these two languages. The code is commented with TODO when you need to provide additional information before the sample code will work. 7.1 Protecting Your Certificate Your certificate file is used to authorise your requests to the WIBS SOAP server. Do not give your certificate file to anyone. Never your certificate in clear text. Always use a secure method to copy your certificate file to your server. 7.2.NET Sample Code You need to enter the following information before you can use the.net sample code: Your certificate s common name. A unique identifier for each uploaded file. A file name for each uploaded file. The location of the file contents to upload. Your download queue ID. You also need to install your certificate into the machine s certificate store and extract the common name: 1. Open a Command Prompt window. 2. Type mmc and press the ENTER key. Note that to view certificates in the local machine store, you must be in the Administrator role. 3. On the File menu, click Add/Remove Snap In. 4. Click Add. 5. In the Add Standalone Snap-in dialog box, select Certificates. 6. Click Add. 7. In the Certificates snap-in dialog box, select Computer account and click Next. 8. In the Select Computer dialog box, click Finish. 9. In the Add Standalone Snap-in dialog box, click Close. 10. On the Add/Remove Snap-in dialog box, click OK. 11. In the Console Root window, click Certificates (Local Computer) to view the certificate stores for the computer. 12. Optional. On the File menu, click Save or Save As to save the console file for later reuse. Page 11

12 13. Expand Certificates (Local Computer) and right-click Personal then select All Tasks then Import 14. In the Certificate Import Wizard click Next. 15. Press Browse and select the.pfx certificate file you downloaded then click Next. 16. Enter the certificate password and click Next. 17. Click Next then click Finish. 18. In the Console Root window, expand Personal then left click Certificates. Check that your certificate is displayed in the list. You will need to add the configuration from UploadTest.exe.config to your project s configuration file. 7.3 Java Sample Code You need to enter the following information before you can use the Java sample code: The file path to the.jks certificate file you saved. The password for your certificate file. A unique identifier for each uploaded file. A file name for each uploaded file. The location of the file contents to upload. Your download queue ID. Unlike.NET, you do not need to install the certificate. All you need to do is copy the certificate file to an appropriate place on your server. Page 12

13 Appendix A Upload File Example HTTP Request POST /services/messaging/uploadfile HTTP/1.1 Content-Type: text/xml; charset=utf-8 SOAPAction: "" Host: ws.support.qvalent.com:443 Content-Length: 429 <s:envelope xmlns:s=" xmlns:xsi=" xmlns:xsd=" xmlns=" </fileID><fileType>TEST1</fileType><fileName>test1.txt</fileN ame><filecontent>vghpcybpcybhihrlc3qgzmlszq==</filecontent></uploadfile></s: Body></s:Envelope> HTTP Response HTTP/ OK Content-Type: text/xml Date: Thu, 20 Aug :15:06 GMT Transfer-Encoding: chunked f1 <SOAP-ENV:Envelope xmlns:soap- ENV=" ENV:Body><qv:uploadFileResponse xmlns:qv=" P-ENV:Body></SOAP-ENV:Envelope> 0 Page 13

14 Appendix B Download Files Example HTTP Request POST /services/messaging/downloadfiles HTTP/1.1 Content-Type: text/xml; charset=utf-8 SOAPAction: "" Host: ws.support.qvalent.com:443 Content-Length: 320 <s:envelope xmlns:s=" xmlns:xsi=" xmlns:xsd=" xmlns=" ID>nathan2</queueID></downloadFiles></s:Body></s:Envelope> HTTP Response HTTP/ OK Content-Type: text/xml;charset=utf-8 Date: Thu, 20 Aug :15:07 GMT Transfer-Encoding: chunked 1b4 <s:envelope xmlns:s=" esresponse xmlns:ns0=" s0:file><ns0:fileid>e82fc b </ns0:fileid><ns0:filety pe>test1</ns0:filetype><ns0:filename>test1.txt</ns0:filename><ns0:fileconten t>vghpcybpcybhihrlc3qgzmlszq==</ns0:filecontent></ns0:file></ns0:downloadfil esresponse></s:body></s:envelope> 0 Page 14

15 Appendix C Westpac HTTPS addresses Test Environment Upload File URL: Download Files URL: Production Environment Upload File URL: Download Files URL: Page 15

16 Appendix D FAQ Q) I execute the downloadfile.cmd and receive the following error: Curl: (22) The requested URL returned error: 502 A) The file you are trying to fetch may have a space in its name. Contact Westpac and ask them to check that there is no space in the filenames being fetched. Page 16