Electronic Signature Version February Administrator Guide

Transcription

1 Electronic Signature Version February 2018 Administrator Guide

2 Copyright 2018 Axway All rights reserved. This documentation describes the following Axway software: Axway Electronic Signature No part of this publication may be reproduced, transmitted, stored in a retrieval system, or translated into any human or computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual, or otherwise, without the prior written permission of the copyright owner, Axway. This document, provided for informational purposes only, may be subject to significant modification. The descriptions and information in this document may not necessarily accurately represent or reflect the current or planned functions of this product. Axway may change this publication, the product described herein, or both. These changes will be incorporated in new versions of this document. Axway does not warrant that this document is error free. Axway recognizes the rights of the holders of all trademarks used in its publications. The documentation may provide hyperlinks to third-party web sites or access to third-party content. Links and access to these sites are provided for your convenience only. Axway does not control, endorse or guarantee content found in such sites. Axway is not responsible for any content, associated links, resources or services associated with a third-party site. Axway shall not be liable for any loss or damage of any sort associated with your use of third-party content.

3 Contents Preface 7 Who should read this guide 7 Electronic Signature documentation set 7 Related documentation 7 Support services 7 Training services 8 Accessibility 9 Screen reader support 9 Support for high contrast and accessible use of colors 9 1 Overview 10 Introduction 10 Installation configurations 10 EBICS Client functionality 11 Electronic Signature functionality 11 Electronic Signature processing 11 Financial Integration products 12 2 Using Electronic Signature with Interchange 13 Prerequisites 13 Configure Interchange 13 Send EBICS requests using MMD files 14 MMD XML file examples 14 Inline processing for Interchange/Electronic Signature integration 16 About inline processing 16 How to format PeSIT metadata for Electronic Signature 17 Copy the JAR file 18 Configure Interchange for inline processing 18 Configure Payment Status Report inline 19 Modify the default inline 19 Update payment status with PSR 20 About PSR 20 About PSR integration in Electronic Signature 20 Configure PSR integration with Interchange 21 Integrate Sentinel with Electronic Signature and Interchange 23 Introduction 23 Configure Electronic Signature for end-to-end Sentinel integration 24 Sentinel attribute names 24 Axway Electronic Signature Administrator Guide 3

4 3 Using Electronic Signature with Gateway 28 Prerequisites 28 Use Transfer CFT to connect to the back-end application 29 Behavior principles: User message 29 Send User message syntax 29 Fetch User message syntax 30 Configure Gateway to connect to Transfer CFT 30 Configure Gateway for Send and Fetch 30 Configure Gateway 30 Configure Transfer CFT 33 Update payment status with PSR 34 About PSR 34 About PSR integration in Electronic Signature 35 Configure PSR integration with Gateway 36 Limitation for Bank and Customer names 36 Integrate Sentinel with Electronic Signature and Gateway 37 Introduction 37 Configure Electronic Signature for end-to-end Sentinel integration 38 Sentinel attribute names 38 EBICS Client administration 42 About command lines 42 Syntax 43 Commands per use case 43 Parameter list 47 Import the TLS Bank certificate to the client keystore 49 General procedure to create an EBICS user 49 Deactivate a proxy server for a bank 50 Send and Fetch transactions with embedded EBICS Client 50 General behavior 50 Request definition 51 Explanation of tags 51 End of transfer callback variables 53 Use embedded EBICS Client with a DMZ proxy 54 About Secure Relay 54 Configure embedded EBICS Client for Secure Relay 54 Configure embedded EBICS Client with an HTTP proxy 56 4 Configure Electronic Signature 57 Directory structure 57 Configure security tokens 59 Example of config.cfg file contents 59 Edit the config.cfg file 60 Edit the configuration.properties file 61 Integrate Electronic Signature with Gateway and Sentinel 61 Axway Electronic Signature Administrator Guide 4

5 Configure log levels 62 Edit a secure connection between server and browser (TLS) 63 Create your keystore 63 Encrypt and save your keystore password 63 5 Control Electronic Signature 65 Command scripts 65 Start Electronic Signature 66 Connect to the Electronic Signature UI 66 Stop Electronic Signature 67 Check the Electronic Signature status 67 Install (or remove) the Electronic Signature Windows service 67 Start and stop Electronic Signature in Windows service mode 68 Start Electronic Signature 68 Stop Electronic Signature 68 6 Extend support to other formats 69 Payload parser 69 Modify the parser exit 69 7 Develop exits for Electronic Signature 71 About the exit framework 71 Overview 71 Description of exit framework API 71 Development 73 Prerequisites 73 Develop exits 74 Sample exit 77 8 Using PassPort with Electronic Signature 80 Introduction 80 Installation 80 Post-installation 81 Start Electronic Signature for the first time 81 Create Administrator and Signer users in PassPort 82 Update PassPort properties 82 Import Signer users from PassPort 82 Define users who will receive notifications 83 PassPort self-registration 83 Renew PassPort certificates 83 Default certificates provided by PassPort 83 Non-PassPort certificates 84 Axway Electronic Signature Administrator Guide 5

6 9 Purge payments in Electronic Signature 85 Introduction 85 Command syntax 85 Parameter usage 86 Database records 87 Appendix A: configuration.properties file 88 Electronic Signature configuration section 89 Database configuration section 90 UI configuration section 91 Parser configuration section 91 configuration section 92 Transporter configuration section 93 Interchange configuration section 94 PSR scanning configuration section 94 PassPort configuration section 95 Sentinel configuration section 96 Sizing section 97 Exit configuration section 97 EBICS Client section 98 Network configuration section 100 Axway Electronic Signature Administrator Guide 6

7 Preface This guide describes how to administer Electronic Signature. The guide includes details of the different configuration files. Who should read this guide This guide is intended for administrators who integrate and manage Electronic Signature in their production environment. It is assumed that you have a good understanding of networks and Java environments. Electronic Signature documentation set To find all available documents for this product version: 1. Go to 2. In the left pane Filters list, select your product or product version. Note Customers with active support contracts need to log in to access restricted content. Related documentation The following reference documents are available on the Axway Documentation portal at Axway Supported Platforms Lists the different operating systems, databases, browsers, and thick client platforms supported by each Axway product. Axway Interoperability Matrix Provides product version and interoperability information for Axway products. Support services The Axway Global Support team provides worldwide 24 x 7 support for customers with active support agreements. support@axway.com or visit Axway Support at Axway Electronic Signature Administrator Guide 7

8 Preface Training services Axway offers training across the globe, including on-site instructor-led classes and self-paced online learning. For details, go to: Axway Electronic Signature Administrator Guide 8

9 Accessibility Axway strives to create accessible products and documentation for users. This documentation provides the following accessibility features: Screen reader support on page 9 Support for high contrast and accessible use of colors on page 9 Screen reader support Alternative text is provided for images whenever necessary. The PDF documents are tagged to provide a logical reading order. Support for high contrast and accessible use of colors The documentation can be used in high-contrast mode. There is sufficient contrast between the text and the background color. The graphics have the right level of contrast and take into account the way color-blind people perceive colors. Axway Electronic Signature Administrator Guide 9

10 Overview 1 Introduction on page 10 Installation configurations on page 10 EBICS Client functionality on page 11 Electronic Signature functionality on page 11 Electronic Signature processing on page 11 Financial Integration products on page 12 Introduction Axway Electronic Signature is an optional product that can be used in Financial Integration. The Electronic Signature product includes an embedded EBICS Client. This new version is able to handle EBICS T as well as EBICS TS protocols. You must install Electronic Signature if you require EBICS Client functionality. The exact functionality depends on your license key and the installed options. Installation configurations Various installation configurations are possible depending on whether you require EBICS T or EBICS TS functionality and which file transfer product you are using. File transfer product For EBICS T, use: For EBICS TS, use: Axway Gateway EBICS Client (embedded in Electronic Signature) Electronic Signature + EBICS Client (embedded in Electronic Signature) Axway Interchange EBICS functionality in Interchange* Electronic Signature + EBICS functionality in Interchange* Axway Electronic Signature Administrator Guide 10

11 1 Overview * For information about the EBICS functionality in Interchange, refer to the Interchange documentation. EBICS Client functionality EBICS Client in Electronic Signature provides the support for the EBICS protocol in Gateway on the client side (typically in Financial Integration for corporates). The Electronic Signature product must be launched in order to start the embedded EBICS Client and to allow administration or transfers. Electronic Signature functionality Electronic Signature enables authorized users to sign and/or validate electronic payments. A transport user must be selected in the case of validation only payments. The UI includes two distinct parts. One is designed for signers (for example, the corporate treasurer) and the other for the administrator. Signers use a security token to sign payments. The administrator manages users and signing rules. Before being able to send a signed file, the end-user must initialize the connection with the bank. The Electronic Signature application provides services to manage this initialization. After initializing with a bank, a payment file can be sent to the Electronic Signature application, through the Communication layer, using the PeSIT protocol for example. A user can sign the payment file which is then sent to the bank. Electronic Signature processing The following figure shows the general workflow for payment files being processed by Electronic Signature. Axway Electronic Signature Administrator Guide 11

12 1 Overview Steps Description 1 A back-end application sends a payment file that has to be signed and validated before it is sent to the bank. 2 The incoming file is integrated into the electronic signature function. This suspends the routing process of the file. 3, 4 Authorized users view the file, validate, sign or reject it. This step is repeated until the required number of signatures has been reached. 5, 6 When the file has been signed, with the required number of signatures, it is sent via the Communication layer to the bank. Financial Integration products Electronic Signature is used as part of the Financial Integration solution with the following Axway products: Interchange (or Gateway) EBICS Server The Communication layer function is managed by either Interchange or Gateway. Several tasks (for installation, configuration and administration) depend on which of these two products you are using with Electronic Signature. Electronic Signature also requires an Oracle or MySQL database. Axway Electronic Signature Administrator Guide 12

13 Using Electronic Signature with Interchange 2 This chapter applies only if you are using Interchange as the communication layer for Electronic Signature. Prerequisites on page 13 Configure Interchange on page 13 Send EBICS requests using MMD files on page 14 Inline processing for Interchange/Electronic Signature integration on page 16 Update payment status with PSR on page 20 Integrate Sentinel with Electronic Signature and Interchange on page 23 Prerequisites Interchange must be installed (refer to the Interchange Installation and Prerequisites Guide). Interchange must be installed with a license key intended for non FIPS compliance usage. Configure Interchange This section explains how to configure Interchange for Electronic Signature. The information provided is just an example. You need to adapt this according to your own requirements. For full details about creating objects, refer to the Interchange Administrator Guide. 1. From the Interchange Start menu folder, launch the Admin shortcut. 2. In the System Management menu, create a Trading Engine (TE). 3. Run the Trading Engine. 4. Create a community. The Routing ID corresponds to the EBICS CustomerId of the remote Bank. 5. Define certificate usage. In the community definition, the signing certificate corresponds to the EBICS identification and authentication certificate. The encryption certificate corresponds to the EBICS encryption certificate. 6. Set up an integration pickup exchange for picking up messages from integration. This corresponds to the entry point where files to be sent in EBICS are deposited. This depends on the way Interchange is integrated to the back-end. Examples are: a simple directory scan, an integration through Integrator, an incoming PeSIT message, and so on. Axway Electronic Signature Administrator Guide 13

14 2 Using Electronic Signature with Interchange 7. Set up an integration delivery exchange for routing received messages to integration. Delivery exchange for routing received messages to integration corresponds to the way to retrieve messages fetched in EBICS. Those files must go to the back-end (Integrator for example). 8. Set up a pickup/delivery exchange. In order to communicate with a bank using EBICS, the message protocol must be set to EBICS. 9. Configure inline processing. See Inline processing for Interchange/Electronic Signature integration on page 16. Note that this step is important for integration with Electronic Signature. 10. Create a partner for the community. The partner corresponds to the EBICS Bank that you want to exchange with. The Routing ID corresponds to the EBICS HostId of the remote Bank. 11. Set up EBICS communication between the community and the partner: In Partner detail, set up a delivery exchange. In order to communicate with a bank using EBICS, the message protocol must be set to EBICS. EBICS Bank Settings: Choose the protocol version of the bank (France is H003). Choose Signature version. Electronic Signature handles only A005 signature version. Configure the HTTP settings: Enter the URL of the remote EBICS bank. Delivery exchange name: Enter a meaningful name for this delivery exchange. Save your delivery exchange. 12. Import TLS/SSL certificate of the remote EBICS Server: Go to your community, click certificates, and TLS/SSL trusted root certificates. Add this TLS/SSL certificate. For more information about configuring Interchange, refer to the Interchange documentation. Send EBICS requests using MMD files In Interchange, MMD XML files can be used as an alternative to inline processing. In order to use this method, you need to create a File system-type Integration pickup and place the XML files in the location defined for the pickup. Interchange will parse the files and trigger the send or fetch EBICS request. MMD XML file examples Send <?xml version="1.0" encoding="utf-8"?> <MessageMetadataDocument documentid="test_b2" protocol="generic"> Axway Electronic Signature Administrator Guide 14

15 2 Using Electronic Signature with Interchange <Metadata name="from" type="string">customer</metadata> <Metadata name="to" type="string">bank</metadata> <Metadata name="message.waitupdate" type="string">true</metadata> <Metadata name="ebics.action" type="string">send</metadata> <Metadata name="ebics.ordertype" type="string">ful.pain sct</metadata> <Metadata name="ebics.domain" type="string">geopost</metadata> <Metadata name="ebics.sender" type="string">fi-ap</metadata> <Metadata name="ebics.amount" type="string">1000</metadata> <Metadata name="ebics.operationnb" type="string">2</metadata> <Metadata name="message.comment" type="string">business comment</metadata> <MessagePayloads> <Payload id="idfd "> <MimeContentType>text/plain</MimeContentType> <Location type="filepath">c:\pain xml</location> </Payload> </MessagePayloads> </MessageMetadataDocument> where: From is the EBICS HostId of the Bank To is the EBICS customerid message.waitupdate is "true" if the send has to go via Electronic Signature ebics.action is the EBICS request action type (send or fetch) ebics.ordertype is the full EBICS order type ebics.domain is the domain of the payload. The domain is the organizational entity within a company. ebics.sender is the sender of the payload. The sender is the application that initiates a payment flow. ebics.amount is the global amount of the payment that is displayed in the Electronic Signature UI (optional). If a value is specified here it will override the amount parsed from the payload. ebics.operationnb is the number of operation of the given payment file. This value is displayed in the Electronic Signature UI (optional). If a value is specified here it will override the number of operations parsed from the payload. ebics.user.userid is the EBICS userid of the transport user (optional) message.comment is any business information that might help the treasurers to sign a payment. This value is displayed in the Electronic Signature UI (optional). Axway Electronic Signature Administrator Guide 15

16 2 Using Electronic Signature with Interchange Payload id is the id of the payload, this parameter is mandatory Location type is the location and type of payload Fetch <?xml version="1.0" encoding="utf-8"?> <MessageMetadataDocument documentid="test_b2" protocol="generic"> <Metadata name="from" type="string">customer</metadata> <Metadata name="to" type="string">bank</metadata> <Metadata name="ebics.action" type="string">fetch</metadata> <Metadata name="ebics.ordertype" type="string">fdl.camt ara</metadata> <Metadata name="ebics.user.userid" type="string">user</metadata> </MessageMetadataDocument> where: From is the EBICS HostId of the Bank To is the EBICS customerid message.waitupdate is "true" if the send has to go via Electronic Signature ebics.action is the EBICS request action type (send or fetch) ebics.ordertype is the full EBICS order type ebics.user.userid is the EBICS userid of the transport user Inline processing for Interchange/Electronic Signature integration This section provides information about inline processing for Interchange/Electronic Signature integration. About inline processing Payment files are sent to the Electronic Signature application, through Interchange, using the PeSIT protocol for example. Inline processing ensures that Electronic Signature parses the most recent version of the payload. It also enables Electronic Signature to obtain the path of the payload in case of integration different from MMD (Message Metadata Document). Axway Electronic Signature Administrator Guide 16

17 2 Using Electronic Signature with Interchange Inline processing performs the following functions: Reads and interprets the metadata from the transfer (PI 99 in the case of PeSIT) and adds it to the message in Interchange before being picked up by Electronic Signature in the delivery exchange Copies the payload to an Interchange temporary directory so that it is available for Electronic Signature ready for a user to sign the payment The general workflow for payment files is explained in Overview on page 10. In this figure, inline processing takes place inside Interchange between steps 1 and 2. How to format PeSIT metadata for Electronic Signature The PeSIT PI 99 metadata must be formatted as follows: key = value Each part of the data is separated by the semi-colon character (;) Example: ebics.action=send; ebics.ordertype=ful.pain.xxx.cfonb160.dco; message.waitupdate=true; ebics.domain=geopost; ebics.sender=fi-ap; PayloadId=IDYZ1234;message.comment=Business Data where: message.comment is optional metadata that might help treasurers when signing a payment. Axway Electronic Signature Administrator Guide 17

18 2 Using Electronic Signature with Interchange Copy the JAR file The inline processing jar file is <Electronic_Signature_install_ dir>\devkit\inline\fex-es-inline.jar. Copy the jar file into the Interchange jars folder: <Interchange_install_dir>\jars. Configure Interchange for inline processing Configure PeSIT inline Proceed as follows to configure a community in Interchange to use inline processing with Electronic Signature for PeSIT. 1. Click Message handler on the navigation graphic at the top of the community summary page. 2. Click the task Add a new message processing action. 3. Choose an attribute for the condition and click Next. 4. Specify an operator and value that is always true. This ensures that the inline processing is always performed. Example: "From exists". 5. Select Perform inline processing via a Java class. 6. Complete the fields: Parameter Description Class name Enter the following name: com.axway.fex.es.inline.pesitintegration Parameter Enter the name of the temporary directory where the payload file is to be copied. Example: c:\my_temporary_folder\ The inline process creates a file name with syntax "file_coreid" for each payload. This ensures that files are unique and cannot be overwritten. 7. Click Finish. Now, continue with the configuration of Interchange (see Configure Interchange on page 13). Axway Electronic Signature Administrator Guide 18

19 2 Using Electronic Signature with Interchange Configure Payment Status Report inline Proceed as follows to configure a community in Interchange to use inline processing with Electronic Signature to update the payment status. 1. Click Message handler on the navigation graphic at the top of the community summary page. 2. Click the task Add a new message attribute definition with criteria. 3. Click Add attribute. 4. Enter ebics.ordertype in the text field and click Add. 5. Click Cancel to go back to the Message handler processing page. The previous action added the required attribute to the list of available attributes. 6. Click the task Add a new message processing action. 7. Choose the attribute ebics.ordertype for the condition and click Next. 8. Leave the Operators as "Equals" and "Constant" and specify in the text field of the value, the payment status report order type. Example: "FDL.camt ara" and click Next. 9. Select Perform inline processing via a Java class 10. Complete the fields: Parameter Class name Description Enter the following name: com.axway.fex.es.inline.psrintegration Parameter Enter the name of the Electronic Signature PSR Incoming directory where the fetched payment status report file is to be copied Example: c:\axway\electronicsignature\psr\incoming 11. Click Finish. Modify the default inline The default inline implementations can be modified. The samples located in <Electronic Signature_install_dir>\devKit\inline are delivered for custom development: 1. Ensure that you have maven installed and the command line mvn is on the system path environment variable. 2. Enter: mvn clean install. The build creates a target directory where the compiled class and a new fex-es-inlinesample-{version}.jar file are generated. 3. Copy the newly-generated jar file into the Interchange jars folder: <Interchange_ install_dir>\jars. Axway Electronic Signature Administrator Guide 19

20 2 Using Electronic Signature with Interchange Update payment status with PSR This section explains how to configure Interchange in Financial Integration to retrieve Payment Status Report (PSR) data for EBICS payments and then use the PSR to update the payment status displayed in Electronic Signature. About PSR The Payment Status Report (PSR) is a file generated by the EBICS Server after every EBICS transaction (payment file sent). The PSR file contains the final status of a transaction at the bank side. Three types of Payment Status Reports are supported along with their corresponding parsers: Payment Transfer Status Parser (PSRv2) Payment Transfer Status Parser (HAC/PSRv3) Payment Transfer Status Parser (PTK) By default, Electronic Signature is configured to support Payment Status Report PSRv2 with the file format FDL.camt ara. Therefore, to use the other payment status report types along with their parsers, you need to configure them. About PSR integration in Electronic Signature PSR integration in Electronic Signature enables business users to view the up-to-date status of the payments they have sent as found in the PSR. To achieve this, the following actions are performed: Interchange fetches PSR files from the EBICS Server at regular intervals The fetched files are placed in a monitoring directory configured in Electronic Signature Electronic Signature parses the retrieved files. A parser must be configured according to the PSR file format used (In the Admin tab file format section). Electronic Signature updates the payment status displayed in the UI, based on the unique EBICS order id generated in the transaction Detailed description of PSR parsing and status update: After a PSR is fetched, it is stored in the delivery pickup configured in Interchange Electronic Signature monitors this directory Electronic Signature parses the file retrieved and extracts the PSR(s). A file may contain several PSRs. Corresponding PSR entries are created in the database (HostID, CustomerID, OrderType, OrderId, Date, Result) Electronic Signature selects orderid in Interchange based on the coreid and the send status Axway Electronic Signature Administrator Guide 20

21 2 Using Electronic Signature with Interchange Electronic Signature selects the corresponding entry in the PSR which has been stored in the database The payment status is updated based on what is stored in the PSR Updated payment status If the server has accepted the payment then the payment status will be updated to ACCEPTED. If the server has rejected the payment, due to a wrong signature or compression error or any asynchronous error, then the payment status will be updated to REFUSED. You can see the reason the payment was rejected in the audit part. Note that if the text is longer than 255 characters it will be truncated to fit 255 characters. To view the full text, refer to the payment status report file received. If an error occurred during the transaction from Interchange to EBICS Server the payment status will be updated to IN ERROR. To view the full text, refer to the payment status report file generated in the <ES_INSTALLATION_DIR>/psr/<DONE_DIRECTORY> directory. Configure PSR integration with Interchange Fetch a PSR file 1. Configure Interchange for EBICS transfers. 2. Create an XML file based on the following example: <?xml version="1.0" encoding="utf-8"?> <MessageMetadataDocument documentid="test_b2" protocol="generic"> <Metadata name="from" type="string">customer</metadata> <Metadata name="to" type="string">bank</metadata> <Metadata name="ebics.action" type="string">fetch</metadata> <Metadata name="ebics.ordertype" type="string">fdl.camt ara</metadata> <Metadata name="ebics.user.userid" type="string">user</metadata> </MessageMetadataDocument> 3. Change the BANK/CUSTOMER/USER as required. The value of the metadata ebics.user.userid corresponds to the transport user used for fetching the PSR. If the Bank has defined the PSR handler as user-based then the transport user used for sending payments must be specified. If no transport user has been explicitly defined, then the first signer is used as a transport user and this user must be specified in the fetch XML file. Axway Electronic Signature Administrator Guide 21

22 2 Using Electronic Signature with Interchange Configure Interchange integration delivery The PSR files need to be placed in a folder reserved for PSR files only. There are two ways to do this: One file system integration delivery or Two file systems integration delivery. One file system integration delivery Edit the file system integration delivery. In the Message attributes tab create a new attribute ebics.ordertype and add this new attribute to the selected list. By doing this every EBICS file will be placed in a folder identified by the ebics.ordertype under the directory name specified in the file system settings. If the incoming message does not have the ebics.ordertype metadata then it will be placed in the file system directory. Example File system directory: C:/Axway/Interchange/data/in/ebics (all the files that do not have the ebics.ordertype metadata are placed here) PSR files go in: C:/Axway/Interchange/data/in/ebics/FDL.camt ara HPB files go in: C:/Axway/Interchange/data/in/ebics/HPB Two file systems integration delivery The first integration delivery needs to be the default one with no delivery criteria. For the second one, select a file system directory different from the first integration delivery and add a delivery comparison criteria: ebics.ordertype equals FDL.camt ara PSR fetch scheduling PSR files need to be fetched regularly in order to update the payment status in Electronic Signature. Create a script that will copy the XML file with the fetch PSR command in the configured pickup directory of Interchange. For Windows you can use the scheduler task. For example you can add a new task to execute the previously-created script every 60 seconds. PSR inline Create a new inline process that will copy the fetched PSR in the monitoring directory of Electronic Signature and rename the file BANK#CUSTOMER#ORDERTYPE#ID.xml. The bank, customer and ordertype are metadata found in the Message and the id is a counter or an identifier to ensure unique file names. The ordertype indicates to Electronic Signature which parser to use for the incoming PSR. This must be configured in the File format tab in Administration. Axway Electronic Signature Administrator Guide 22

23 2 Using Electronic Signature with Interchange Integrate Sentinel with Electronic Signature and Interchange This section explains how to configure Electronic Signature to send events to Sentinel. Introduction By default, Interchange sends events to Sentinel. These events represent the EBICS T (Transport only) flow. However, these events give no indication as to whether a payment has been signed or not. To overcome this you can configure Electronic Signature to send events to Sentinel in addition to the events sent from Interchange. These events represent the EBICS TS (Transport and Signature) flow. Electronic Signature sends events for: ES_PENDING The payment has been sent to Electronic Signature awaiting signature. ES_SIGNED The payment has been signed in Electronic Signature and sent back to Interchange integration. ES_REJECTION The payment has been rejected in Electronic Signature. Electronic Signature, by default, uses XFBTransfer as tracking object. The tracking object with the object version can be configured in the configuration.properties file. The Sentinel tracked object is XFBTransfer. Each time a message has a change in transfer state, Interchange or Electronic Signature generates and sends an XFBTransfer notification message to Sentinel. The following figure shows the flow of notification messages between Electronic Signature, Interchange and Sentinel. Axway Electronic Signature Administrator Guide 23

24 2 Using Electronic Signature with Interchange Configure Electronic Signature for end-to-end Sentinel integration You need to select the Sentinel monitoring option when you install Electronic Signature. Sentinel attribute names The following table shows Sentinel attribute names used by Electronic Signature and the messages sent to the Sentinel Server for different events. In this table, ES represents Electronic Signature. Attribute name CREATIONDATE CREATIONTIME CYCLEID DIRECTION Description Event creation date (dd/mm/yyyy) Event creation time (hh:mm:ss) CycleID of EBICS transfer: I for Initial CycleID sent by Interchange ES for Electronic Signature CycleID (core ID of payload) EB for EBICS CycleID Direction of transfer: E for Emission R for Reception ü ü ü ü I ES ES ES EB E E E E E ENDDATE Transfer end date ü ü (dd/mm/yyyy) ENDTIME Transfer end time ü ü (hh:mm:ss) Axway Electronic Signature Administrator Guide 24

25 2 Using Electronic Signature with Interchange Attribute name EVENTDATE Description Event date (dd/mm/yyyy) ü ü ü ü ü FILENAME File name of payload ü ü ü ü ü ISALERT ISEND LOCATION MACHINE Indicates if transaction is in an alert state. 0 = not alert 1 = alert, not resolved 2 = alert, resolved Indicates whether the transaction is completed. 0 = transaction not completed 1 = transaction completed 2 = transaction rejected or in error Machine from which events come (host name) Machine hosting the event sender (host name) or or 2 ü ü ü ü ü ü ü ü ü ü MONITOR Event sender INTR ES ES ES INTR MONITORVERSION PRODUCTNAME PRODUCTOS Event sender version and build Name of event sender: I = "Interchange" ES = "Electronic Signature" Name of the OS running on the machine ü ü ü ü ü I ES ES ES I ü ü ü ü ü Axway Electronic Signature Administrator Guide 25

26 2 Using Electronic Signature with Interchange Attribute name PROTOCOL RECEIVERID RETURNCODE Description Protocol: E = EBICS O = Original other protocol Routing ID of receiver (Host ID) Message type: -1 = rejected 0 = unknown 1 = request 2 = receipt 3 = request and receipt O E E E E ü ü ü ü ü 1 or or -1 RETURNMESSAGE Rejection reason ü ü ü SENDDATE SENDERID Event date (dd/mm/yyyy) Routing ID of sender (CustomerID) ü ü ü ü ü ü ü ü ü ü SENDTIME Event time (hh:mm:ss) ü ü ü ü ü SIGNENTITYOBJECTID EBICS User ID of sender or rejector separated by semi-colon ü ü ü STATE Event state: INT ESP ESS ESR or INT INT = Interchange ESE event ESP = ES_PENDING ESS = ES_SIGNED ESR = ES_ REJECTION ESE = ES_ERROR Axway Electronic Signature Administrator Guide 26

27 2 Using Electronic Signature with Interchange Attribute name TRADEDESTINATION TRADEDESTINATIONALIAS TRADEORIGINATOR TRADEORIGINATORALIAS Description Host ID for outbound message Customer ID for inbound message Host ID for outbound message Customer ID for inbound message Customer ID for outbound message Host ID for inbound message Customer ID for outbound message Host ID for inbound message ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü TRADEREQUESTTYPE EBICS file format ü ü ü ü ü TRADESERVICE EBICS Order type ü ü ü ü ü USERID EBICS User ID of last sender or rejector ü ü ü ü Axway Electronic Signature Administrator Guide 27

28 Using Electronic Signature with Gateway 3 This chapter applies only if you are using Gateway as the communication layer for Electronic Signature. After installing Electronic Signature with Gateway as communication layer, you have to configure Gateway in order to make the link with the back-end application. Prerequisites on page 28 Use Transfer CFT to connect to the back-end application on page 29 Behavior principles: User message on page 29 Configure Gateway to connect to Transfer CFT on page 30 Configure Gateway for Send and Fetch on page 30 Update payment status with PSR on page 34 Integrate Sentinel with Electronic Signature and Gateway on page 37 EBICS Client administration on page 42 Send and Fetch transactions with embedded EBICS Client on page 50 Use embedded EBICS Client with a DMZ proxy on page 54 Prerequisites Gateway must be installed (refer to the Gateway Installation and Prerequisites Guide). Gateway must be installed on the same machine as Electronic Signature. Sentinel Universal Agent must be installed on the same machine as Electronic Signature. Axway Electronic Signature Administrator Guide 28

29 3 Using Electronic Signature with Gateway Use Transfer CFT to connect to the back-end application The installation package includes a set of sample files that enable you to link Gateway and Electronic Signature to Transfer CFT to connect to the back-end application. The sample files that are provided in the installation package enable you to: Automate a Send request (for example, to EBICS Server) Automate a scheduled Fetch and send result to a Transfer CFT monitor Automate a Fetch request and send the received file (for example, a PSR file) to a Transfer CFT monitor This section describes a generic implementation. You should adapt it to your specific internal application requirements. Behavior principles: User message The provided scripts are based on the User message parameter that can be used with the PeSIT or FTP protocols. Send User message syntax <ordertypebl>#<bankid>#<customerid>#<systemid>#<useridtransport>#<paylo adid>#<domain>#<sender>#<amount>#<nb_operations>#<comment> where: <ordertypebl> is the full EBICS order type (for example FUL.pain ict). <bankid> is the EBICS HostId of the Bank. <CustomerId> is the EBICS customerid. <SystemId> is the EBICS userid of the user used as systemid (optional). <useridtransport> is the EBICS userid of the transport user (optional). <PayloadId> is the id of the payload, this parameter is mandatory. <Domain> is the domain of the payload. The domain is the organizational entity within a company. <sender> is the sender of the payload. The sender is the application that initiates a payment flow. <amount> is the global amount of the payment that is displayed in the Electronic Signature UI (optional). If a value is specified here it will override the amount parsed from the payload. Axway Electronic Signature Administrator Guide 29

30 3 Using Electronic Signature with Gateway <Nb_of_operation> is the number of operation of the given payment file. This value is displayed in the Electronic Signature UI (optional). If a value is specified here it will override the number of operations parsed from the payload. <comment> is any business information that might help the treasurers to sign a payment. This optional value is displayed in the Electronic Signature payments comment column. Note that special characters (!,?, etc.) cannot be used. <CustomerId> and <AdditionalUserId1> are mandatory unless a default Customer and User are defined inside the Bank. Fetch User message syntax <ordertypebl>#<ebicsbankhostid>#<customerid>#<useridtransport>#<fromdat e>#<todate> where: <CustomerId> and <useridtransport> are mandatory unless a default Customer for the Bank and a default User for the Customer are defined. <FromDate> and <ToDate> are optional. They are defined in the format YYMMDD. Configure Gateway to connect to Transfer CFT See the following sections: Send and Fetch: Configure Gateway for Send and Fetch on page 30 Fetch PSR: Update payment status with PSR on page 34 Configure Gateway for Send and Fetch This section explains how you configure Gateway to detect a Send or Fetch request and trigger the related action. Sample scripts are supplied that use Gateway and Transfer CFT. Configure Gateway To execute a Send or Fetch from a Transfer CFT client, you require the following Gateway objects: Remote Site Application Local Site Axway Electronic Signature Administrator Guide 30

31 3 Using Electronic Signature with Gateway Model (only required for Fetch requests) Decision Rule You can either configure Gateway using sample scripts or configure Gateway manually. This section explains both methods. Configure Gateway using sample scripts The sample script obj_gateway_client_ebics[.bat.sh] creates all the required objects with the link to the required scripts. However you first need to customize the script. 1. Navigate to the Electronic Signature installation directory. 2. In the directory mft\install\client, locate the file obj_gateway_client_ ebics.bat (or.sh for UNIX). 3. Open the file in a text editor, and modify the following parameters: Parameter remote_cft_ebics_client_ address Modification Enter the Transfer CFT Server HostName. remote_cft_ebics_client_port Enter the Transfer CFT Server port number. ordertype bank Enter a Fetch OrderType. For example, HPB. EBICS Bank Host ID CustomerId EBICS Customer ID UserId EBICS User ID From FROM Date YYMMDD To TO Date YYMMDD 4. Save the file. 5. From the same directory, execute the script: Windows: obj_gateway_client_ebics.bat UNIX: obj_gateway_client_ebics.sh To delete all objects, use the script delobj_gateway_client_ebics.[sh bat] if the object name was not changed inside obj_gateway_client_ebics.[sh bat]. Axway Electronic Signature Administrator Guide 31

32 3 Using Electronic Signature with Gateway Configure Gateway manually Create the following Gateway objects: Remote Site This object is necessary only if you connect to Transfer CFT as a back-end application. In Gateway Navigator, create a new Remote Site object. Application In Gateway Navigator, create an Application object that specifies the record size, depending on your transfer requirements. This application is used inside the Decision Rule to trigger the right script. Local Site This object is necessary only if you connect to Transfer CFT as a back-end application. In Gateway Navigator, create a new Local Site object. Model (only for Fetch) In Gateway Navigator, create a Model to be included in the Decision Rule. This Model is used to send the fetched file back to a Transfer CFT monitor. By defining several Models and Decision Rules, you can access several Transfer CFT monitors. Decision Rule for Fetch In Gateway Navigator, create a Decision Rule that points to one of the scripts: Windows: EbicsFetchClient_GTW.bat UNIX: EbicsFetchClient_GTW.sh These scripts are located in the directory \mft\fetch For EBICS T: When you enter the script in the Gateway field, add the name of the Model to use and add one of the following parameters: test real The test or real value sets the communication mode with EBICS Server. Example on Windows: EbicsFetchClient_GTW.bat ModelName test Axway Electronic Signature Administrator Guide 32

33 3 Using Electronic Signature with Gateway For EBICS TS: See Update payment status with PSR on page 34. Decision Rule for Send In Gateway Navigator, create a Decision Rule that points to one of the scripts: Windows: EbicsSendClient_GTW.bat UNIX: EbicsSendClient_GTW.sh These scripts are located in the directory \mft\send For EBICS T: When you enter the script in the Gateway field, add one of the following parameters: test real The test or real value sets the communication mode with EBICS Server. Example on Windows: EbicsSendClient_GTW.bat test For EBICS TS: When you enter the script in the Gateway field, add the following parameters: real waitupdate The waitupdate indicates that the Send must wait for a signature. Example on Windows: EbicsSendClient_GTW.bat real waitupdate For more details about creating Gateway objects, refer to the Gateway documentation. Configure Transfer CFT The sample script cft_ebics_client.cfg creates the required objects on the Transfer CFT side. 1. Navigate to the Electronic Signature installation directory. 2. In the directory mft\install\client locate the file cft_ebics_client.cfg. 3. Open the file in a text editor, and modify the following parameters: Axway Electronic Signature Administrator Guide 33

34 3 Using Electronic Signature with Gateway Parameter SYST Modification Enter the type of platform. Example values: 'WINNT' 'UNIX' PROT Enter 'PESITANY' SAP Enter '6330' HOST Enter the Gateway HostName 4. Save the file. 5. From the same directory, execute the script: Windows: CFTUTIL #cft_ebics_client.cfg UNIX: Update payment status with PSR This section explains how to configure Gateway in Financial Integration to retrieve Payment Status Report (PSR) data for EBICS payments and then use the PSR to update the payment status displayed in Electronic Signature. About PSR The Payment Status Report (PSR) is a file generated by the EBICS Server after every EBICS transaction (payment file sent). The PSR file contains the final status of a transaction at the bank side. Three types of Payment Status Reports are supported along with their corresponding parsers: Payment Transfer Status Parser (PSRv2) Payment Transfer Status Parser (HAC/PSRv3) Payment Transfer Status Parser (PTK) By default, Electronic Signature is configured to support Payment Status Report PSRv2 with the file format FDL.camt ara. Therefore, to use the other payment status report types along with their parsers, you need to configure them. PSR type availability Fetch with PTK is only available for order types with three characters. Axway Electronic Signature Administrator Guide 34

35 3 Using Electronic Signature with Gateway Fetch with PSR v2 is only available for order type + file format, for example: FUL.xxxx.yyyy. Fetch with PSR v3 supports both order type and order type + file format. About PSR integration in Electronic Signature PSR integration in Electronic Signature enables business users to view the up-to-date status of the payments they have sent as found in the PSR. To achieve this, the following actions are performed: Gateway fetches PSR files from the EBICS Server at regular intervals using a Decision Rule. The fetched files are placed in a monitoring directory configured in Electronic Signature. Electronic Signature parses the retrieved files. A parser must be configured according to the PSR file format used (In the Admin tab file format section). Electronic Signature updates the payment status displayed in the UI, based on the unique EBICS order id generated in the transaction. Detailed description of PSR parsing and status update: After a PSR is fetched, it is stored in the directory configured in Gateway Electronic Signature monitors this directory Electronic Signature parses the file retrieved and extracts the PSR(s). A file may contain several PSRs. Corresponding PSR entries are created in the database (HostID, CustomerID, OrderType, OrderId, Date, Result) Electronic Signature selects the corresponding entry in the PSR which has been stored in the database The payment status is updated based on what is stored in the PSR Updated payment status If the server has accepted the payment then the payment status will be updated to ACCEPTED. If the server has rejected the payment, due to a wrong signature or compression error or any asynchronous error, then the payment status will be updated to REFUSED. You can see the reason the payment was rejected in the audit part. Note that if the text is longer than 255 characters it will be truncated to fit 255 characters. To view the full text, refer to the payment status report file received. If an error occurred during the transaction from Gateway to EBICS Server the payment status will be updated to IN ERROR. To view the full text, refer to the payment status report file generated in the <ES_INSTALLATION_DIR>/psr/<DONE_DIRECTORY> directory. Axway Electronic Signature Administrator Guide 35

36 3 Using Electronic Signature with Gateway Configure PSR integration with Gateway Fetch a PSR file In Gateway Navigator, create a Decision Rule that points to the script: Windows: EbicsPsrFetchClientWithParam_GTW.bat real <ordertype> <BANK> <CUSTOMER> <USER> <path_to_psr_dir> UNIX: EbicsPsrFetchClientWithParam_GTW.sh real <ordertype> <BANK> <CUSTOMER> <USER> <path_to_the_monitoring_dir> These scripts are located in the directory <FullPathName>/mft/Fetch where: <OrderType> is the full EBICS OrderType of the PSR (example: FDL.camt ara) <BANK> is the name of the EBICS Bank <CUSTOMER> is the name of the EBICS customer <USER> is the name of the EBICS user <path_to_psr_dir> is the path to the monitoring directory of Electronic Signature. This must be the same value as the psr.monitoring.directory property defined in the Electronic Signature configuration file: <FullPathName>/conf/configuration.properties. You need to create one Decision Rule for each Bank/Customer you have defined. The <USER> corresponds to a transport user. It can be omitted in the fetch XML file, in which case the default user for the BANK/CUSTOMER will be used. If the Bank has defined the PSR handler as user-based then the transport user used for sending payments must be specified. If no transport user has been explicitly defined, then the first signer is used as a transport user and this user must be specified in the fetch XML file. PSR fetch scheduling PSR files need to be fetched regularly in order to update the payment status in Electronic Signature. For example, you might want to fetch a PSR every 60 seconds. To do this, schedule the previouslycreated Decision Rules in a schedule-type Rule Table in the Event Management/Scheduling menu of the Gateway GUI. Limitation for Bank and Customer names When using Electronic Signature with Gateway, do not use the hash character '#' in Bank or Customer names. The PSR parser interprets the hash as a separator. Axway Electronic Signature Administrator Guide 36

37 3 Using Electronic Signature with Gateway Integrate Sentinel with Electronic Signature and Gateway This section explains how to configure Electronic Signature to send events to Sentinel. Introduction Automated EBICS Transfers are monitored by: Log messages inside Gateway Sentinel tracking In EBICS T (Transport only) with Gateway, you can enable Sentinel Monitoring to track the transfer coming from the back-end and have the link with the EBICS outgoing transfer. With Electronic Signature, you can also monitor the complete EBICS TS (Transport and Signature) flow. Electronic Signature sends event for: ES_PENDING The payment has been sent to Electronic Signature awaiting signature. ES_SIGNED The payment has been signed in Electronic Signature and sent back to Gateway integration. ES_REJECTION The payment has been rejected in Electronic Signature. Electronic Signature, by default, uses XFBTransfer as tracking object. The tracking object with the object version can be configured in the configuration.properties file. Each time a message has a change in transfer state, either Gateway or Electronic Signature generates and sends an XFBTransfer notification message to Sentinel. In Sentinel Monitoring, you can have a complete view of the initial transfer and of the EBICS transfer. The two events are linked to Sentinel with a Cycle link. The following figure shows the flow of notification messages between Electronic Signature, Gateway and Sentinel. Axway Electronic Signature Administrator Guide 37