Вы находитесь на странице: 1из 20

Misys FusionBanking Loan IQ

API Web Service User


Guide
© Misys Limited, or a member of the Misys group of companies, 2015
All Rights Reserved. Confidential - Limited Distribution to Authorized Persons Only, Pursuant to the Terms
of the License Agreement pursuant to which you were granted a license for this software. This software is
protected as an unpublished work and constitutes a trade secret of Misys Limited, or a member of the
Misys group of companies, Head Office: One Kingdom Street, Paddington, London W2 6BL.

More Information
Need more information? Read more about our products at http://www.misys.com/products.aspx. Or contact
your local Misys office at http://www.misys.com/contact-us.aspx.

Feedback
Do you have comments about our guides and online help? Please address any comments and questions
to your local Misys representative.
Document Revision History

Version Date Description of Revision(s)

7.3 8/22/2014 Added API Server TCP Backlog parameter to ls2app.ini file – page 13

TBD 5/05/2014 Updated API Server TCP Backlog parameter to ls2app.ini file – page 13

All 6/06/2016 Updated API XML Request and Response format – page 7

© Misys | 6/9/2016 | API Web Service User Guide i


Table of Contents

1. Introduction .......................................................................................................................................... 1
1.1. Overview ........................................................................................................................................ 1
2. Using the Loan IQ API Web Server .................................................................................................... 3
2.1. Prerequisites .................................................................................................................................. 3
2.2. Installation and Configuration ........................................................................................................ 3
2.2.1. Invoke the Proxy Process ....................................................................................................................... 3
2.2.2. TCP API Web Service Execution ........................................................................................................... 3
2.2.3. Install the API Web Service in HTTP Mode ............................................................................................ 4
2.2.4. Additional Configuration ......................................................................................................................... 4
3. Communicating with the Loan IQ XML API Server ........................................................................... 5
4. Configure the API XML Client for HTTP Connection ........................................................................ 6
5. XML Format for the Loan IQ API Web Service .................................................................................. 7
5.1. XML Request Format .................................................................................................................... 7
5.2. XML Response Format................................................................................................................. 8
5.3. SOAP Header User Identification .................................................................................................. 9
5.4. Permissible Input Data Types ....................................................................................................... 9
6. Error Management ............................................................................................................................. 11
7. Web Service Configuration ............................................................................................................... 13
7.1. Configure LS2APP.INI File .......................................................................................................... 13
7.2. General Parameters .................................................................................................................... 13
7.3. JMS Parameters .......................................................................................................................... 14
7.4. Sample LS2APP.INI File ............................................................................................................. 14
8. JMX Monitoring of Loan IQ Web Services....................................................................................... 15

© Misys | 6/9/2016 | API Web Service User Guide ii


Introduction

1. Introduction
Misys FusionBanking Loan IQ (hereinafter referred to as Loan IQ) clients require the ability to modify
application data from external sources. The safest way to do this is through the Loan IQ application itself,
thus ensuring all necessary business validation is enforced and all data is correctly updated on the
database. The Loan IQ API Server is a Windows application that allows users to modify data via an XML
client interface. On successfully logging into the Loan IQ API server, the user listens on a specified
TCP/IP port for XML encoded requests and replies with XML encoded responses.

The Loan IQ API server processes the request by communicating with an Application Server and
database. These independent logical servers (API server, Application Server, Database and XML Client)
may or may not exist on the same physical server. As the number of TCP/IP interfaces increase the
communication overhead also increases.

1.1. Overview
The Loan IQ API Web Service supports the existing API server operation and also provides improved
performance capabilities by using a custom-configured Tomcat web server.
The XML client connects to the proxy server using TCP/IP port 9000 and gets assigned a unique port
number for the duration of the connection. Information exchange between client and server is by means
of XML encoded requests and responses. The proxy server establishes a connection to the HTTP server
using SOAP protocol. When a connection has been established with the client, the HTTP server extracts
the XML data from the SOAP body and creates a thread to a separate API instance - each instance is a
separately preconfigured Tomcat worker.
Each API instance can then connect to the Loan IQ database in one of two ways:
 Via a TCP/IP connection to the Application server (conventional operation),
or
 Via the Misys Jack Rabbit JDBC Connector (new functionality).

© Misys | 6/9/2016 | API Web Service User Guide 1


Introduction

This architecture supports the legacy operation of using a separate Application server to connect to the
database as well as using a JDBC connector (running on the same JVM as the web server). The
operation is seamless to the end user and is backwardly compatible with older Loan IQ releases. This
solution also allows external applications to avail of the WDSL interface on the HTTP server, thereby
providing the ability to extend the scope of the current functionality.

© Misys | 6/9/2016 | API Web Service User Guide 2


Using the Loan IQ API Web Server

2. Using the Loan IQ API Web Server


The Loan IQ API Web Server is based on a custom-configured deployment of a Tomcat Web server.
When Loan IQ is installed with Tomcat, there are a number of configuration files that need to be edited to
ensure the correct operation of Tomcat in the Loan IQ deployment (See Loan IQ 7.2 Installation Guide).
To enable Web Services you need to configure the ls2app.ini file (See Web Service Configuration).

2.1. Prerequisites
The following list contains the prerequisites required for correct deployment of the Loan IQ Web services.
 Java Runtime Environment (JRE) 7
 Tomcat 7.0
 Loan IQ Database up and running
 Misys Jackrabbit or Loan IQ Application Server

2.2. Installation and Configuration


The Loan IQ API Web Service is deployed as a war file that is installed in the webapps directory, under
the name liq_apiWebService.war.

Note: If there is already a directory named liq_apiWebService on your Tomcat web server, then the war
file has been deployed already.

2.2.1. Invoke the Proxy Process


The Loan IQ API Web Service supports legacy XML communication via a proxy process. This proxy
process is created by the running the executable ApiServer.exe in the Loan IQ Server directory. The
process should be auto-started by the procmon.exe process, but it can be started with the option -port
<portnumber>.
For example:
ApiServer.exe - port 9000
If no argument is provided the proxy service defaults to port 9000.
The URL which the proxy will submit to is specified in the URL entry in the API Web Service section of
ls2app.ini.

2.2.2. TCP API Web Service Execution


When you have copied the liq_apiWebService.war file to the webapps directory you can start the Loan
IQ API Web Service (liq_apiWebService) by executing tomcat.exe. The log4j logging framework provides
debugging information to assist in analyzing the web services operation.
To view the status of the process you can view the following files:
%TOMCAT_HOME%/logs/catalina.out
%TOMCAT_HOME%/logs/apiwebservice.log
The level of output sent to apiwebservice.log can be adjusted by configuring the following file:
%TOMCAT_HOME%/webapps/liq_apiWebService/WEB-INF/classes/resources/log4j.properties.xml.
To check that the Loan API Web Service is operating correctly, open your browser and point to the URL
of the Web Server location (http://<hostname>:port/liq_apiWebService/api/liq?wsdl).

© Misys | 6/9/2016 | API Web Service User Guide 3


Using the Loan IQ API Web Server

You should receive WDSL as shown below:


http://csaintam6420:8080/liq_apiWebService/api/liq?wsdl

2.2.3. Install the API Web Service in HTTP Mode


To install the API Web service in HTTP mode:
1. Ensure that the liq_apiWebService.war file resides in the TOMCAT-HOME\webapps directory.
2. Modify the following line in the TOMCAT-HOME/conf/catalina.properties file to specify the
server.dir environment variable:
shared.loader=${server.dir}/lib/*.jar,${server.dir}/ext/*.jar

2.2.4. Additional Configuration


No extra configuration should be required, however Tomcat needs to be restarted outside of the
procmon.exe process, the following parameters and environment variables are required:
 set SERVER.DIR='Path to Loan IQ Server directory'
 e.g.: set SERVER.DIR='C:\LoanIQ\Server'
The following JAVA_OPTS must be set prior to starting up Tomcat:
set JAVA_OPTS=-Xms256M -Xmx1024M -XX:PermSize=256m -XX:MaxPermSize=256m -
Dserver.dir='c:\LoanIQ\Server' -Dconcurrent.init=false

© Misys | 6/9/2016 | API Web Service User Guide 4


Communicating with the Loan IQ XML API Server

3. Communicating with the Loan IQ XML API Server


The client program communicates with the API Server using either a TCP/IP socket or HTTP connection
on a predefined port. The following is a description of actions that an API client and server perform after
their initial connection.
1. The API Server sends a Welcome message as a NULL terminated string.
2. The Client sends an XML encoded request as a NULL terminated string.
3. The API Server parses, validates, and executes the request. The result is converted into an XML
encoded response which is sent back to the client as a NULL terminated string.
4. The Server closes the connection.

© Misys | 6/9/2016 | API Web Service User Guide 5


Configure the API XML Client for HTTP Connection

4. Configure the API XML Client for HTTP


Connection
The Loan IQ API XML Client allows the user to access the API server using a windows interface. XML
Requests can be constructed in the Request window of the interface and sent to the API server. The
corresponding XML responses are returned by the server to the client interface and displayed in the
Response window.

To configure the client to connect to the server:


1. Open the liqapi.ini file found in the APITestTool directory. Add a field with the following:
Name = httpUrl
Value = http://ip-address:port-number/liq_apiWebService/api/liq
For Example:
httpUrl = http://localhost:8080/liq_apiWebService/api/liq
2. Select HTTP as the API Type in the Settings Menu

Note: Please refer to the Misys Loan IQ XML Client User Guide for information about installing and
running the API XML Client.

© Misys | 6/9/2016 | API Web Service User Guide 6


XML Format for the Loan IQ API Web Service

5. XML Format for the Loan IQ API Web Service


The following information contains some general rules for formatting data when using the API Web
Service.

5.1. XML Request Format


All XML submissions using SOAP standards must call a particular API, via it's named DTD file. The API
Server rejects all non-valid requests.

Request with good data


The following is an example of a client request with good data.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:api="http://api.ws.liq.misys.com/">
<soap:Header>
<api:userid>TRUSER01</api:userid>
</soap:Header>
<soap:Body>
<api:executeInsertCustomerComment>
<InsertCustomerComment customerRid="NL3R7HC8" title=
comment="This is an example of a comment by TRUSER02"/>
</api:executeInsertCustomerComment>
</soap:Body>
</soap:Envelope>

Request with bad data


The following is an example of a client request with bad data.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:api="http://api.ws.liq.misys.com/">
<soap:Header/>
<soap:Body>
<api:executeInsertCustomerComment>
<InsertCustomerComment messageID="1" apiUserId="TRUSER08"
timeout="?" apiOwnerId="?" apiOwnerType="?" customerRid="?" title="?"
comment="?" version="?"/>
</api:executeInsertCustomerComment>
</soap:Body>
</soap:Envelope>

© Misys | 6/9/2016 | API Web Service User Guide 7


XML Format for the Loan IQ API Web Service

5.2. XML Response Format


True Response
The following is a successful response to a request with good data:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns="http://api.ws.liq.misys.com/">
<soapenv:Body>
<executeInsertCustomerCommentResponse xmlns="">
<InsertCustomerCommentResponse
success="true">CustomerCommentRid="NCAEILE6"
CustomerRid="NL3R7HC8"</InsertCustomerCommentResponse>
</executeInsertCustomerCommentResponse>
</soapenv:Body>
</soapenv:Envelope>

False Response
The following is a successful response to a request with bad data:
<soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-
envelope">
<soapenv:Body>
<soapenv:Fault>
<soapenv:Code>
<soapenv:Value>soapenv:Server</soapenv:Value>
</soapenv:Code>
<soapenv:Reason>
<soapenv:Text>EWSAPI024 - Incorrect response from API
Server.</soapenv:Text>
</soapenv:Reason>
<soapenv:Detail>
<tns:Messages xmlns:tns="http://api.ws.liq.misys.com/">
<Message>Attribute "version" with value "?" must have a
value from the list "1.0 ".</Message>
<Message>Aborted because errors occurred during XML
validation</Message>
</tns:Messages>
</soapenv:Detail>
</soapenv:Fault>
</soapenv:Body>
</soapenv:Envelope>

© Misys | 6/9/2016 | API Web Service User Guide 8


XML Format for the Loan IQ API Web Service

5.3. SOAP Header User Identification


User identification can be passed into any SOAP XML request in order to run the given command as a
particular user. This is particularly useful when a creation, modification, or deletion event needs to be
tagged to particular identifier (likely an automated process). This can be accomplished in the following
manner:
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:api="http://api.ws.liq.misys.com/">
<soap:Header>
<api:userid>CRON01</api:userid>
</soap:Header>
<soap:Body>
<api:executeGetBusinessObjectInfo>
<GetBusinessObjectInfo rid="L3R7HC8" tableCode="CUS"/>
</api:executeGetBusinessObjectInfo>
</soap:Body>
</soap:Envelope>

5.4. Permissible Input Data Types


Included below are some general rules concerning how data is formatted when passed to the Loan IQ
API Server. Specific details are dependent on rules associated with a particular API call. These rules are
documented along with the appropriate DTD in documentation provided separately. The API server
expects syntactically valid, well-formed XML. Input attribute values may have blanks on the left or the
right, but need to conform to the following formats based on datatype:
 Boolean:
Y or N, upper or lower case
 Alphanumeric:
Any characters (even if not XML-allowed, for example, +), an empty string is not allowed for
alphanumeric characters that are defined as required
 Numeric:
<optional sign><at least an integer digit, or a single dot><if a dot, at least a decimal digit>.

Note: No space is allowed between the optional sign and the first digit.

 Integer:
<optional sign><at least a digit>.

Note: No space is allowed between the optional sign and the first digit.

 Date:
The suggested date format to be used to avoid possible misinterpretations is the ISO 8061 standard
of YYYY-MM-DD where:
YYYY is the year in the Gregorian calendar
MM is the month of the year between 01 (January) and 12 (December)
DD is the day of the month between 01 and 31.
For example, 2004-04-01 represents the first day of April in 2004.

© Misys | 6/9/2016 | API Web Service User Guide 9


XML Format for the Loan IQ API Web Service

Note: The Loan IQ legacy date formats listed below are also acceptable:

o MMM DD, YYYY or DD MMM YYYY


(For example, Dec 31, 2004 or 31 Dec 2004)
o MDY, DMY, or YMD , based upon the locale of the user's computer
(Where the year can be either 2 or 4 digits, and the delimiters between the month, day, and year
can be any sequence of non-alphanumeric characters)

© Misys | 6/9/2016 | API Web Service User Guide 10


Error Management

6. Error Management
In addition to the standard XML API Server Error Messages, the following messages are returned:
Message Description

EWSAPI001 Configuration file specified [&p0] does not exist.


EWSAPI002 Configuration file not specified.
EWSAPI003 Unable to find section [&p0] in the configuration file.
EWSAPI004 Error while reading [&p0] file.
EWSAPI005 Error while creating the parser [&p0].
WWSAPI006 Unable to create the API Connection [&p0].
WWSAPI007 Server not responding.
WWSAPI008 No LIQ Services having Service pattern [&p0] available.
EWSAPI009 IO Exception occurred during service lookup.

EWSAPI010 One or more mandatory parameters (APIServerHostName, PortNo, ServicePattern) not


specified in the configuration file.
WWSAPI011 No connection available for use in the connection pool.
EWSAPI012 APIServer server didn't respond.
EWSAPI013 Server returned an error message for the given request.
EWSAPI014 Unable to get API Connection.
EWSAPI015 Unknown error occurred. Error getting schema object.
EWSAPI016 Unknown error occurred while getting the API list.
EWSAPI017 Input message should confirm to SOAP 1.1 and SOAP 1.2 formats.
EWSAPI018 Server not initialized.
EWSAPI019 Either Loan IQ Application Server or Loan IQ API Server is not running.

EWSAPI020 Input XML does not confirm to namespace [&p0].


EWSAPI021 Internal Error.
EWSAPI022 Loan IQ API Servers are not responding after the retry.
EWSAPI023 Error from API Server.
EWSAPI024 Incorrect response from API Server.
EWSAPI025 Response Received from the API Server is not in the expected format.
EWSAPI026 Exception while getting the parsers from Athena.
EWSAPI027 Problem occurred while trying to get API List.
EWSAPI028 Exception while loading file About.xml.
EWSAPI029 IO Exception while loading schema.

EWSAPI030 Exception while loading schema from file [&p0].


EWSAPI031 Unable to clone the element

© Misys | 6/9/2016 | API Web Service User Guide 11


Error Management

Message Description

EWSAPI032 The retrieved schema from the API Server for the API [&p0] is not in the expected format.

EWSAPI033 The retrieved schema for the API [&p0] is incorrect.


EWSAPI034 Error while validating the schema for the Web Service.
EWSAPI035 Success attribute is not there in the <Response> element that is received from the API
Server.
EWSAPI036 API Web Service is busy.

EWSAPI037 No free connection is available in the connection pool.

© Misys | 6/9/2016 | API Web Service User Guide 12


Web Service Configuration

7. Web Service Configuration


The LS2APP.INI file contains startup information required by the API W eb Server in order to execute.
This information is contained in the [API Web Service] section.

7.1. Configure LS2APP.INI File


Configure the LS2APP.INI file with the following parameters:
[API Web Service]
URL = http://apihost.bank.com:8080/liq_apiWebService/api/liq
Users = LIQ_API01-LIQ_API03
API Server TCP Backlog = 1000

7.2. General Parameters


The following are general parameters that need to be configured:
Parameter Description

URL Host name of the machine on which the web service is being served from, or the
address of the load balancer if the web service is being load balanced across
multiple hosts. This value becomes the XSD URL in the generated WSDL allowing
extensibility for load balancing and non-internet access.
This parameter is also supplied to the Proxy Service as the HTTP end point for
HTTP POST requests
Users The list of users (logins) to be utilized in the request processing queue. Users can
be specified as a comma separated list e.g.:
Users = ADMIN01, ADMIN02, ADMIN03
Or users may be specified in a range, where a logical range can be deduced e.g.:
Users = ADMIN01-ADMIN03
Users may also be specified on a combination of the two:
Users = ADMIN01,ADMIN02-ADMIN05,ADMIN07
If not using in-memory database access (and therefore communicating to the
database via TCP), passwords may optionally provided in the form:
Users=ADMIN01:Password123,ADMIN02:Password456,ADMIN03
Passwords may not be specified in the range format.
API Server TCP Backlog The server ls2app.ini file now supports a new optional parameter:
API Web Service: This parameter controls setting for TCP Backlog in API Server.
Increase this setting to handle connection refused errors in your client program.
Default is 1000.
API Server TCP Backlog = 1000.
Pre-load Tables Optionally specify code tables to be loaded on startup, e.g.:
Pre-load Tables = User Function, API Function, Cost Of Funds Review Status,
System Parameter, Alias Type, GL Short Name, Language, Facility Type,
Currency, Expense, Branch, State, Country, Department, Legal Code, Customer
Description, Customer Status, Accrual End Date Rule, Accrual Period, Outstanding
Type

© Misys | 6/9/2016 | API Web Service User Guide 13


Web Service Configuration

7.3. JMS Parameters


The following parameters are required when the web service should also utilize JMS.
Parameter Description

jmsJNDIContext jms JNDI Context


jmsQueueConnectionFactory Name of the Queue's connection Factory.
jmsRequestQueueName Name of the request queue.

jmsResponseQueueName Name of the response queue.


jmsTimeoutMS Specifies the JMS timeout in milliseconds.
bindingFileDirectory Location of the binding file.
jmsThreadSize Number of threads available for processing JMS requests in the
web service. This is an integer value and the Default is 10. Optional

7.4. Sample LS2APP.INI File


[API Web Service]
URL = http://apiserver:8080/liq_apiWebService/api/liq
Users = LIQ_API
API Server TCP Backlog = 1000

[JAVA2SQL]
Resource=com.misys.liq.core.dbaccess.InProcessConnection

[JMS]
jmsJNDIContext = FS jmsQueueConnectionFactory = LIQQCF jmsRequestQueueName =
LIQRSP jmsResponseQueueName = LIQREQ jmsRequestLogQueueName = LIQLOGREQ
jmsResponseLogQueueName = LIQLOGRSP jmsTimeoutMS = 1000
bindingFileDirectory=file:/D:/APIWebService/Test/JMS

© Misys | 6/9/2016 | API Web Service User Guide 14


JMX Monitoring of Loan IQ Web Services

8. JMX Monitoring of Loan IQ Web Services


Loan IQ (7.2.6 and later) provides the administrator with the ability to monitor Loan IQ web services using
Java Management Extensions (JMX) technology. A tab is available in the System Administrator Notebook
allowing configuration and monitoring of web service parameters.
To monitor web services:
1. Login to Loan IQ online using a valid Administrator username and password.
2. Click the Nodes tab.
3. Select the target environment in the drop down menu.

The Admin tab provides the following administration details on the Loan IQ Web Service:

1. Running Since: This displays the start date and time of the Loan IQ web service.
2. Last Reset: This displays the last time the web service was reset.
3. Trace Level: This is the Log4j trace level for logging data on the application server:
 ALL - This has the lowest possible rank and is intended to turn on all logging.
 DEBUG - The DEBUG Level designates fine-grained informational events that are most
useful to debug an application.
 ERROR - The ERROR level designates error events that might still allow the application
to continue running.
 FATAL - The FATAL level designates very severe error events that will presumably lead
the application to abort.
 INFO - The INFO level designates informational messages that highlight the progress of
the application at coarse-grained level.
 OFF - The OFF has the highest possible rank and is intended to turn off logging.
 TRACE - The TRACE Level designates finer-grained informational events than the
DEBUG

© Misys | 6/9/2016 | API Web Service User Guide 15


JMX Monitoring of Loan IQ Web Services

 WARN - The WARN level designates potentially harmful situations.


4. Node Workers: This lists the application server node workers that have been configured and are
operating with the web service.

The Metric tab provides details on the API web service metric parameters. These are as follows:

1. Queued Count - The number of API function calls that have been queued to the API server.
2. In Progress Count - The number of API function calls that are currently in progress.
3. Request Count - The number of API requests.
4. Response Successful Count - The number of successful responses from the API server.
5. Response Error Count - The number of successful responses from the API server.

© Misys | 6/9/2016 | API Web Service User Guide 16