Business API guidelines. General steps for normal installation and installation via silent install, and a description of the most common functions

Transcription

1 General steps for normal installation and installation via silent install, and a description of the most common functions

2 Contents General... 3 New bank key must be installed after installation of Business API... 3 What are we going to install?... 3 Clean machine... 3 Business Online is used on the machine... 3 The machine already has MQ installed... 3 Silent install via Command line... 4 What is a silent install?... 4 Action... 4 Language... 4 Placement of programme files... 4 Without e-safekey... 4 Installlevel (without the IBM MQ Series client)... 5 Examples of silent install... 5 Installation of Business API... 5 Standard installation with e-safekey and MQ Danish language... 5 Without e-safekey MQ is installed Danish language... 5 Without e-safekey and MQ Danish language... 5 Installation of e-safekey... 5 Standard installation of e-safekey... 5 Description of the most common functions... 6 Sending files... 6 Receiving files... 6 Communication... 6 Security... 7 Overview of file types for retrieval from the bank... 7 Flow diagrams... 9 Send file to the bank... 9 Retrieve list of files from the bank Retrieve the file from the bank Creation of security user

3 General The installation covers Business API IBM MQ Series Client and E-Safekey (security component) All mentioned will usually be installed on an empty machine, but in certain cases, it is necessary or desirable to leave some parts out of the installation. The following describes the options. If Business PC 5.0 is installed on the machine it is recommended to contact Customer Support for further instructions. Contact Customer Support on (At local charge) or by mail on customersupport@danskebank.dk. New bank key must be installed after installation of Business API After the installation of Business API it may be necessary to update the public key, ddbpub1.mst, that is being used in connection with the communication with the bank. If the key has not been automatically updated it can be done here. What are we going to install? Clean machine For this scenario, we assume that IBM MQ Series Client is not installed E-Safekey is not installed In this situation, both parts must be installed. Recommended (not required) order: or just 1. e-safekey 2. Business API, including IBM MQ Series 1. Business API, including IBM MQ Series and e-safekey The components are installed automatically when a normal installation is selected Business Online is used on the machine For this scenario, we assume that IBM MQ Series Client is not installed If Business online is used on the machine, e-safekey will already be installed on the machine and must, therefore, not be installed. The installation programme will take this into consideration The machine already has MQ installed If there is an MQ installed on the machine please contact Customer Support. In this case, a channel definition file will need to be created, which will handle existing applications as well as Business API. 3

4 Silent install via Command line The following section gives a brief introduction to silent install. What is a silent install? In contrast to an ordinary installation, a silent install happens totally without interfaces. The installation starts by activating MSIexec.exe with a number of parameters (via a command line / command prompt). See the examples later. Action The type of action to be executed, is given as the first parameter: /i = Installation /x = Uninstall the parameter is followed by the full path to the MSI file. (See example) Language It may seem unnecessary to choose the language, when an installation must occur silently, but the programme is registered under Add / Remove programmes and if a user subsequently wants to uninstall along this path, the language selected during installation will be shown in the interface. The language is defined in a so-called transform, where 1030.mst = Danish 1033.mst = English 1044.mst = Norwegian 1053.mst = Swedish Parameter Data: Example: TRANSFORMS <full path>\<transform package> TRANSFORMS = D:\1030.mst Placement of programme files As standard, programme files are placed in the following programme path: <ProgramFilesFolder>\Danske Bank\Business PC - and there is usually no reason to change this. However, it can be done: Parameter: INSTALLDIR Data: full path Example: INSTALLDIR= E:\External programmes\banks\danske Bank\BPC Without e-safekey If e-safekey is installed as a part of the Business API installation, it happens in the form of a nested install, with ARPSYSTEMCMPONENT=1, which means that e-safekey does not appear in Add / Remove programmes. If you want to install e-safekey alone, this can usually happen via a separate installation set-up. If this is done before the installation of Business API, you do not need to do anything, but if Business API is 4

5 installed first, (or the order can be random) you must reject the installation of e-safekey. You do this by setting the parameter SKIP_ESAFEKEY: Parameter: Data: Example: Note: SKIP_ESAFEKEY 0 (Default) e-safekey is installed if necessary and possible 1 e-safekey is not installed SKIP_ESAFEKEY=1 If e-safekey was installed earlier in an independent set-up, the programme must be uninstalled before installation of the new version can be executed. Installlevel (without the IBM MQ Series client) The use of Business API requires that IBM MQ is installed on the machine. If a MQ client is not already installed on the machine, you do not need to do anything - it will be installed default at installlevel 100. If an MQ client is already installed the INSTALLLEVEL should be given as a value between 2-99, which will prevent MQ being installed, as the installlevel for the two features in the installation have been set as shown below. Feature Installlevel BPC_API_Main 1 MQ_Client 100 See under Examples how the parameter is indicated. NOTE: A typical error will be to state INSTALLEVEL, it must be INSTALLLEVEL Examples of silent install In the following examples of silent install (parameter /q ) it is assumed that there is an installation file on the machine s D drive: If the parameter /q is omitted, the user interface will be shown as normal. Installation of Business API Standard installation with e-safekey and MQ Danish language msiexec /i "D:\Business PC 5.0 API.msi" TRANSFORMS="D:\1030.mst" /q Without e-safekey MQ is installed Danish language msiexec /i "D:\Business PC 5.0 API.msi" TRANSFORMS="D:\1030.mst" SKIP_ESAFEKEY=1 /q Without e-safekey and MQ Danish language msiexec /i "D:\Business PC 5.0 API.msi" TRANSFORMS="D:\1030.mst" INSTALLLEVEL=50 SKIP_ESAFEKEY=1 /q Installation of e-safekey The installation of e-safekey is always with an English user interface, which is why you must state TRANSFORMS. Standard installation of e-safekey msiexec /i "D:\e-Safekey.msi" /q 5

6 Description of the most common functions Sending files The function SendFile method (SecureExchange) is used when files are sent to the bank. Upon sending files to the bank via the Business API, you will receive a host reference. When you get this reference back, you know that the bank had received the file. Whether the format and content are correct does not matter in relation to the Business API, as its only task is sending and receiving files. The host reference is therefore not an acceptance that the content of the file can be read by the bank, but only that the bank has received a file and that the file transmission procedure has been carried out correctly. At present, you can see the status of the file on Danske Banks web interface, Business Online. Receiving files Files are received via the Business API with the help of SendFileRequest method (SecureExchange). (See the help file BPC>PI.chm). Using the method SendFileSurveyRequest (SecureExchange), you get presented with the contents of your mailbox in the bank. With the help of the parameters Creation- Time and RequestID you can retrieve the relevant file. The two parameters, and other things, are presented in the overview file (FileSurvey) of the contents of the customer s mailbox. The FileSurvey file is a semi-xml file and consists of: - type: Max. 8 characters, alphanumerical - description: Max. 36 characters, alphanumerical - free text: Max. 180 characters, alphanumerical NOT USED - time when file was created: 10 characters e.g (yymmddhhmm) - format: Max. 20 characters, alphanumerical - received before: 1 character Y/N - size: (calculated) up to requestid or delivery number: Max. 10 characters, alphanumerical - dispatch number: Max. 10 characters IS ALWAYS XXXXXXXXXX The file overview can look like this, where there is a credit file ready to be retrieved, named hrch 5: <Type>KRE</Type> <Description>hrch 5</Description> <Text /> <CreationTime> </CreationTime> <Format /> <ReceivedBefore>N</ReceivedBefore> <SizeInBytes> </SizeInBytes> <RequestID> </RequestID> <DeliveryNumber>XXXXXXXXXX</DeliveryNumber> On page 9, you can see all the types (<Type>) and their content. Communication The API uses IBM Message Queing (IBM MQ) to exchange data between Danske Bank and the customer. The Communication module communicates via port 1414, which has to be opened outbound. The communication programme (IBM Message Queing) performs a name call to mq.businessedi.biz on port The returnport is assigned dynamically. 6

7 Note, if a IBM MQ client already exists on the machine, the API installation will warn you. You should not install MQ in this case. Please contact Customer Support if this seen during the installation of the API. If the API is installed on a machine running Windows NT 4.0, Windows 2000, Windows XP or Windows server 2003, and that machine normally is logging on to the company s domain (if this exists), a local group called mqm (small letters) has to be created on the company s domain controller. No users need to be added to the group, and no special rights needs to be assigned to the group. If this group does not exist the API will bot be able to communicate with Danske Bank. No matter whether communication is handled via LAN og Modem. The API-installprogramme creates this group locally on the pc'en running the installation. (AddLocalGroup.dll),meaning that if the PC is a standalone, nothing else needs to be done.. If files are sent or received via the bank s officebanking system, Business Online, port 1414 is already open. Security The Business API uses the security component esafekey Classic which builds on the use of a public key and a private key. When communicating with the bank through Business API both personal or technical users are applicable. Read more here. Business API is ready to use when the Business API user is set up. To set up Business API you need to use the bank s site for key set up. On this site it is also possible to re-establish access to Business API in case of a blocked user-id or renew the private key. Read more about these options in the Getting started section. The path to the keys can be found in the registry. Path to public keys: HKEY_LOCAL_MACHINE\SOFTWARE\e-SafeKey Path to the user s keys: HKEY_LOCAL_MACHINE\SOFTWARE\e-SafeKey\Business Overview of file types for retrieval from the bank File type Messages from the bank Executed debits Executed credits List of entries Entries for reconciliation Balance on domestic accounts Balance currency/accounts in foreign banks Common paying in slip Account statement Telepay executed payments (Settlement return) Forward engagement Securities custody holding Currency rates Currency cross-rates Currency interest rates <Type> MFB DEB KRE PTO PTX SLI SLU FIK FIN TLP TRM VPD VKS VKK VRS 7

8 Multicurrency Interest Netting Account reconciliation Foreign notes (transfer abroad) Foreign notes (transfer from abroad) IMG Image Customer Account Posting Incentive programme Deposits IK BS Deposits with slips Deposits Personnel welfare department Cheque debiting list Handling list account to account Handling list cheques Handling list salaries List of issued cheques Customer number information BBS return file Telepay first time return (receive return) OCR from Bankgirot Lm from Bankgirot GI from Bankgirot AutoGiro from Bankgirot e-giro from Bankgirot AutoGiro with advice note e-giro with advice note LB from Bankgirot OCR file to Norway TIPS from Bankgirot E-Invoice from Bankgirot E-Giro AutoGiro E-Giro with advice note E-Giro accounts E-Giro business to business E-Giro e-invoice Image files from Bankgirot Folder feedback E-Invoice DK E-Invoice DK - Receipt IMN KAF OTU OFU IMG CAP INC IBK IKB IKO CHD KTO CHK LØN CUD KNR BBS TR1 OC LM GI AG AG LB OCN TIPS BIL FFE IIN IRC 8

9 Flow diagrams Send file to the bank SendFile Customer Danske Bank Init Logon SecureExchange SendFile method Host Event SendSucceed Event SendError Logoff Hostreference 9

10 Retrieve list of files from the bank FileSurvey Customer Danske Bank Init Logon SecureExchange SendFileSurvey Request Host Event Request- SurveySucceed Event Request- SurveyError Logoff Filesurvey 10

11 Retrieve the file from the bank FileRequest Customer Danske Bank Init Logon SecureExchange SendFile Request Host Event RequestFile Succeed Event RequestFile Error Logoff Requested file 11

12 Creation of security user CreateKey key Customer Danske Bank Init SecureExchange AdministrationCreateKey Createkey message Acknowledgement Host 12