Document-Literal Web Services
For applications:
LinkIT
Describes the document-literal type web services available for LinkIT (the LeasePak Web Services API).
Overview
The document-literal web services include MsiAppOriginatorDocLit and MsiAppExtractor. These are wrapped, as well as being stateless (meaning they do not maintain any session information).
The following is an example of how a LeasePak API web service is created and used in Java:
// these are the required import statements to use the Apache Axis API
import org.apache.axis.client.Call;
import org.apache.axis.client.Service;
import org.apache.axis.encoding.XMLType;
// these imports are used to print out SOAP messages
import org.apache.axis.MessageContext;
import org.apache.axis.Message;
import org.apache.axis.AxisFault;
// more required imports
import javax.xml.namespace.QName;
import javax.xml.rpc.ParameterMode;
public class LPWebServiceTemplate {
// this is a method that allows you to print out the SOAP request and SOAP response
// useful for debugging
public static void printCallRequestResponse(Call lpcall) throws AxisFault {
MessageContext ctx = lpcall.getMessageContext();
Message requestMsg = ctx.getRequestMessage();
Message responseMsg = ctx.getResponseMessage();
System.out.println("SOAP REQUEST : " + requestMsg.getSOAPPartAsString());
System.out.println();
System.out.println("SOAP RESPONSE : " + responseMsg.getSOAPPartAsString());
System.out.println();
}
public static void main(String [] args) {
try {
String lpendpoint = "http://hostname:port/deployed_location/services/service_name";
// where hostname is the name of your host machine, port is your port number,
// deployed_location is the root directory where mPower is deployed, and
// service_name is the name of the web service (LPClient, LPApplication, MsiAppOriginator, etc.)
Service lpservice = new Service();
Call lpcall = (Call)lpservice.createCall();
// optional
//lpcall.setUsername([username]);
//lpcall.setPassword([password]);
lpcall.setTargetEndpointAddress( new java.net.URL(endpoint) );
lpcall.setProperty(lpcall.SESSION_MAINTAIN_PROPERTY,new Boolean(false));
lpcall.setUseSOAPAction(true);
// more work in Java for document literal web services
// in java we must describe the operation in more detail than a xml-rpc type web service
OperationDesc lpoper = new OperationDesc();
// set the operations name
lpoper.setName("lpoperName");
// where lpoperName is extractLessee, extractApplication, etc.
// setup a parameter description in the case of the Lessee record its lesseeNumber
ParameterDesc lpparam = new ParameterDesc(
new javax.xml.namespace.QName("http://client.web.msi", "keyNumber"),
org.apache.axis.description.ParameterDesc.IN,
new javax.xml.namespace.QName("http://www.w3.org/2001/XMLSchema", "string"),
java.lang.String.class, false, false);
// where keyNumber is the application number, Lessee number, etc. of the item you wish to extract
// add the parameter to the operation
lpoper.addParameter(lpparam);
// now we set the return type of the operation, by telling it its a string
lpoper.setReturnType(new javax.xml.namespace.QName("http://www.w3.org/2001/XMLSchema", "string"));
lpoper.setReturnClass(java.lang.String.class);
lpoper.setReturnQName(new javax.xml.namespace.QName("urn:MsiAppExtractor", "lpoperNameReturn"));
// where lpoperName is extractLessee, extractApplication, etc.
// we tell the service that the opertaion is a
lpoper.setStyle(org.apache.axis.constants.Style.WRAPPED);
lpoper.setUse(org.apache.axis.constants.Use.LITERAL);
lpcall.setOperation(lpoper);
lpcall.setProperty(org.apache.axis.client.Call.SEND_TYPE_ATTR, Boolean.FALSE);
lpcall.setProperty(org.apache.axis.AxisEngine.PROP_DOMULTIREFS, Boolean.FALSE);
lpcall.setSOAPVersion(org.apache.axis.soap.SOAPConstants.SOAP11_CONSTANTS);
lpcall.setOperationName( new QName("urn:mpower-", "lpoperName") );
Object result = lpcall.invoke(new Object[]{ new String("25") } );
printCallRequestResponse(lpcall);
// where lpoperName is extractLessee, extractApplication, etc.
} catch (Exception e) {
System.out.println(e.toString());
}
}
}
The web services use Web Service Definition Language (WSDL) to generate client proxy classes that allow the user to treat a web service (such as LPClient) as a local object. Refer to sample_wsdl_dl.java for a WSDL example (Java RMI/Apache Axis ) pertaining to the document-literal web services.
The document-literal services do not maintain any session data. Each object (MsiAppOriginatorDocLit, MsiAppExtractor) has its own connection to LeasePak and each object maintains a connection to the LeasePak XML driver until dsDisconnect() is called. Most errors (or SOAP exceptions) are caught and re-thrown so the program can close the connection. If an unexpected error occurs, connections and XML drivers could remain open and running. NetSol recommends checking for open connections and running drivers after receiving an error or exception, and reporting any occurrences of open connections or running drivers to MSI.
LPBookLease
LPBookLease allows you to perform a variety of functions on a booked lease, including getting the revolving credit limit of a master application or a booked lease using revolving credit, updating the revolving credit limit of a booked lease, and extracting various items of information from a booked lease.
API Reference
If you need additional information, Sun Microsystems maintains a Java developers' site at http://java.sun.com that includes API specifications, sample code and applications, and technical articles and tips.
Methods
LPBookLease contains several methods, including getCreditLimit, updateRevCreditLimit, and
extractBookLease. For more information, refer to the Java Call Reference. For the most current list of methods available, refer to host:port/service_name/services, where
host:port/service_name is the location where you've deployed your web service(s).
XML Inputs and Returns
getCreditLimit
This method requires a master application number or booked lease (with revolving credit) number. On failure it returns (example)
<?xml version="1.0"?><CREDLIT_LIMIT><ERROR>error message</ERROR></CREDLIT_LIMIT>
On success, it returns (example)
<?xml version="1.0"?><CREDLIT_LIMIT><INFO>1000.00</INFO></CREDLIT_LIMIT>
updateRevCreditLimit
In order to use this method, you will first need to obtain the 26-character checksum for the lease using
extractBookLease
This method uses an XML input file with the following DTD:
<!ELEMENT UPDATE_RLS_RCL (leaseNumber | revolvingCreditLimit | revolvCredEffDate | dlscksum | revolvingLineFee? )> <!ELEMENT leaseNumber (#PCDATA)> <!ELEMENT revolvingCreditLimit (#PCDATA)> <!ELEMENT revolvCredEffDate (#PCDATA)> <!ELEMENT dlscksum (#PCDATA)> <!ELEMENT revolvingLineFee (#PCDATA)>
Here is an example based on the above DTD:
<?xml version="1.0"?><UPDATE_RLS_RCL><leaseNumber>50</leaseNumber> <revolvingCreditLimit>10000000.00</revolvingCreditLimit> <revolvCredLimEffDate>112306</revolvCredLimEffDate> <dlscksum>75e17e5acb22908ff51c2bd971c87fb4</dlscksum> <revolvingLineFee>.0005</revolvingLineFee> </UPDATE_RLS_RCL>
where the date is in MMDDYY format and the dlscksum is the 26-character checksum obtained from extractBookLease.
On success this returns
<?xml version="1.0"?><UPDATE_RLS_RCL> <INFO>Lease updated.</INFO></UPDATE_RLS_RCL>
On failure this returns
<?xml version="1.0"?><UPDATE_RLS_RCL> <ERROR>error message</ERROR></UPDATE_RLS_RCL>
extractBookLease
This method takes a booked lease number as input. On success it returns (example)
<?xml version="1.0"?><BOOKLEASE_RECORD><leaseNumber>50</leaseNumber> <accruedPrincipalBalance>10000000.00</accruedPrincipalBalance > <portfolio>2</portfolio> <dlscksum>75e17e5acb22908ff51c2bd971c87fb4</dlscksum> <company>1</company><region>1</region> <office>1</office> </BOOKLEASE_RECORD>
On failure it returns (example)
<?xml version="1.0"?><BOOKLEASE_RECORD> <ERROR>error message</ERROR></BOOKLEASE_RECORD>
MsiAppOriginatorDocLit
MsiAppOriginatorDocLit allows you to load XML-format Client, Application, Asset, Insurance, Notebook, and User Defined Fields information into the LeasePak database. It also enables you to delete pending assets.
Supported Fields
The Supported Fields document lists the fields (and their LeasePak database column equivalents) you can use with MsiAppOriginatorDocLit.
API Reference
If you need additional information, Sun Microsystems maintains a Java developers' site at http://java.sun.com that includes API specifications, sample code and applications, and technical articles and tips.
Methods
MsiAppOriginatorDocLit contains only one method, createApplicationDocLit. For more information on this method, refer to
the Java Call Reference.
- public createApplicationDocLit(java.lang.String xmlDocument)
- Where xmlDocument is the entire contents (as a String) of the XML document containing the records
you wish to add to LeasePak. Call this when you want to update or add using the API username and password. This is a single synchronous,
stateless API call. No session needs to be sent or stored. Default policy is to add records only. Existing records will not be added
unless the XML element contains
<localAddUpdate>true</localAddUpdate>. This allows for greater control of which records get updated.The method throws
java.rmi.RemoteException.The available XML child elements within MSI_APP_ORIG are:
CUSTOMER_RECORD (none required, only 1 allowed) LESSEE_RECORD (at least one required, many allowed) GUARANTOR_RECORD (none required, many allowed) VENDOR_RECORD (none required, many allowed) BROKER_RECORD (none required, many allowed) APPLICATION_RECORD (none required, only 1 allowed) ASSET_DELETE (none required, only 1 allowed) ASSET_RECORD (none required, many allowed) INSURANCE_RECORD (none required, only 1 allowed) NOTEBOOK_RECORD (none required, only 1 allowed) UDF_FIELDS_RECORD (none required, many allowed)
Child elements are processed in the order specified above: all Customer elements first, then all Lessee elements, etc. If processing a child element results in an error or exception, no adds or updates are made for that element, and no further processing of child elements within the parent MSI_APP_ORIG element occurs.
localAddOnly
Any of the above child elements (with the exception of
ASSET_DELETE--see below) can contain thelocalAddOnlyelement when needed. For example:<LESSEE_RECORD> <localAddOnly>boolean</localAddOnly> </LESSEE_RECORD>
where boolean is either 'true' or 'false'. If 'true', the LeasePak record will only be added if the corresponding key number does not already exist. If 'false', LeasePak will either add a record to the database or update an existing record with a matching key number. If you do not include a
localAddOnlyelement, the default behavior is 'true'.ASSET_DELETE
Use this child element to delete all pending assets from an application:
<ASSET_DELETE> <appNumber>application_number</appNumber> </ASSET_DELETE>
where application_number is the application for which you wish to delete all pending assets.
XML Data Requirements
Data within the xmlDocument string must meet the following requirements:
- No empty elements. For example,
<appNumber></appNumber>in the XML string will throw an error; - No carriage returns, new line characters, or spaces between the closing tag of one element and the opening tag of the next.
Below is an example (in Java) of how to strip CR/NL and between-element spaces from your XML text:
String xml = new String(); // where xml is the XML document (as a String) containing the records you wish to add to LeasePak StringBuffer data = new StringBuffer(); BufferedReader reader = new BufferedReader(new StringReader(xml)); String res = reader.readLine(); while ( res != null ) { data.append(res.trim()); res = reader.readLine(); }
- No empty elements. For example,
MsiAppExtractor
MsiAppExtractor allows you to pass a Client (Broker, Customer, Guarantor, Lessee, or Vendor), application, or asset number and returns an XML document containing the Supported Fields that pertain to the type of record you are requesting.
API Reference
If you need additional information, Sun Microsystems maintains a Java developers' site at http://java.sun.com that includes API specifications, sample code and applications, and technical articles and tips.
Methods
MsiAppExtractor contains several methods, including extractApplication, extractAsset,
extractLessee, and extractVendor. For more information, refer to the
Java Call Reference. For the most current list of methods available, refer to
host:port/service_name/services, where host:port/service_name is the location where you've deployed your
web service(s). Below is an example of one of the methods.
- public extractLessee(java.lang.String, lesseeNumber)
- Where lesseeNumber is the Client number of the Lessee whose record you wish to extract. This method logs in as the api
user, spawns an XML driver, and does all the necessary checks to extract a Lessee record from the database. It will return either all
the supported fields in the LESSEE_RECORD or a SOAP fault. It will close the connection to the XML driver automatically.
The program stores a connection object in memory containing the socket connected to the XML driver.
dsConnectreturns true on success and false on failure.Throws
java.lang.Exception.Sample SOAP request:
<?xml version="1.0" encoding="UTF-8"?><soapenv:Envelope xmlns:soapenv="http ://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns: xsi="http://www.w3.org/2001/XMLSchema-instance"><soapenv:Body><ns1:extractLessee soapenv:e ncodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:ns1="urn:mpower-v53a"><ns2: lesseeNumber xmlns:ns2="http://client.web.msi">25</ns2:lesseeNumber></ns1:extractLessee></ soapenv:Body></soapenv:Envelope>
Sample SOAP response if Lessee exists:
<?xml version="1.0" encoding="utf-8"?><soapenv:Envelope xmlns:soapenv="htt p://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns :xsi="http://www.w3.org/2001/XMLSchema-instance"><soapenv:Body><extractLesseeResponse xmln s="urn:mpower-v53a"><extractLesseeReturn><?xml version="1.0"?><MSI_APP_ ORIG><LESSEE_RECORD><zipCode>90141 </zipCode><shortname>DEFA ULT DUMMY </shortname><useTaxExemptCode>NONE</useTaxExemptCode&g t;<company> 1</company><ssnBusinessID> </ssnBusine ssID><region> 1</region><name>default dummy < /name><address1>111 Anza Blvd </address1><lastPhon eUsed> </lastPhoneUsed><clientNumber> 25</clientNumber><age& gt;0</age><portfolio> 2</portfolio><noDependents>0</noDependent s><city>San Francisco </city><office> 1</office>< ;remittanceAddress>1 </remittanceAddress><state>CA</state><preno teSent>Y</prenoteSent></LESSEE_RECORD></MSI_APP_ORIG></extractLesseeR eturn></extractLesseeResponse></soapenv:Body></soapenv:Envelope>Sample SOAP response if Lessee does not exist:
<?xml version="1.0" encoding="utf-8"?><soapenv:Envelope xmlns:soapenv="htt p://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns :xsi="http://www.w3.org/2001/XMLSchema-instance"><soapenv:Body><extractLesseeResponse xmln s="urn:mpower-v53a"><extractLesseeReturn>java.rmi.RemoteException: java.lang.Exception: Cl ient record not found.</extractLesseeReturn></extractLesseeResponse></soapenv:Body></soape nv:Envelope>
XML document, returned as a string:
<?xml version="1.0"?><MSI_APP_ORIG><LESSEE_RECORD><age>0</age><portfolio> 2</portfolio><company> 1</company><name>Yogurt's-R-Us Yogurt Shop </name><address1>984 Pleasant Street </address1><city>Burlingame </city><lastPhoneUsed> </lastPhoneUsed><clientNumber> 79</clientNumber><office> 1</office><zipCode>94010 </zipCode><shortname>YOGURT'S-R-US </shortname><ssnBusinessID> </ssnBusinessID><region> 1</region><noDependents>0</noDependents><prenoteSent>N</prenoteSent><state>CA</state></LESSEE_RECORD></MSI_APP_ORIG>
PrincipalWUWD
PrincipalWUWD allows you to perform the 4 functions from the interactive LeasePak IBL Principal Adjustment [U0125]--Principal Write-Down, Principal Write-Down Reversal, Principal WriteUp, and Principal Write-Up Reversal--all using the API.
API Reference
If you need additional information, Sun Microsystems maintains a Java developers' site at http://java.sun.com that includes API specifications, sample code and applications, and technical articles and tips.
Methods
In order to use any of these methods, you will first need to obtain the current accrued principal balance for the lease or loan. You can do this by using the extractBookLease method of the Web service
LPBookLease.
PrincipalWUWD contains 4 methods: writeUp, writeDown, writeUpReversal, and
writeDownReversal. For more information, refer to the Java Call Reference. For the most current list of methods available, refer to host:port/service_name/services, where
host:port/service_name is the location where you've deployed your web service(s).
XML Inputs
The input element principalBalance refers to the current accrued principal balance before making the update to the lease or loan.
Below is the DTD for the writeUp and writeDown methods input file:
<!ELEMENT WUWD (leaseNumber | effectiveDate| bankCode? | amount |checkNumber? | principalBalance )> <!ELEMENT leaseNumber (#PCDATA)> <!ELEMENT effectiveDate (#PCDATA)> <!ELEMENT bankCode (#PCDATA)> <!ELEMENT amount (#PCDATA)> <!ELEMENT checkNumber (#PCDATA)> <!ELEMENT principalBalance (#PCDATA)>
Here is an example based on the above DTD:
<?xml version ="1.0"?><WUWD><leaseNumber>50</leaseNumber> <effectiveDate>072506</effectiveDate><bankCode>130</bankCode> <amount>100.00</amount><checkNumber>100</checkNumber> <principalBalance>1000000.00</principalBalance></WUWD>
On success this returns
<?xml version="1.0"?><WUWD> <INFO>success message</INFO></WUWD>
On failure this returns
<?xml version="1.0"?><WUWD> <ERROR>error message</ERROR></WUWD>
Below is the DTD for the writeUpReversal and writeDownReversal methods input file:
<!ELEMENT WUWDR (leaseNumber)> <!ELEMENT leaseNumber (#PCDATA)> <!ELEMENT principalBalance (#PCDATA)>
Here is an example based on the above DTD:
<?xml version ="1.0"?><WUWDR><leaseNumber>50</leaseNumber> <principalBalance>1000000.00</principalBalance></WUWDR>
On success this returns
<?xml version="1.0"?><WUWDR> <INFO>success message</INFO></WUWDR>
On failure this returns
<?xml version="1.0"?><WUWDR> <ERROR>error message</ERROR></WUWDR>
Additional Information
These are links to other documents providing additional information on the web services:
- Java Call Reference
- Java call reference including all methods used by LeasePak web services, presented as a self-contained set of HTML documents using frames.
- sample_wsdl_dl.java
- A WSDL example (Java RMI/Apache Axis , presented as an HTML document) of a document-literal web service.
- MsiAppOriginator Document Type Definition (DTD)
- The DTD for the MSI_APP_ORIG parent element and all children, preformatted within an HTML document. A plain text version is also available.
- Web Services API: Supported Fields
- API fields and their corresponding LeasePak database columns supported by the MsiAppOriginator web service for LinkIT.
- XML Sample: MSI_APP_ORIG/APPLICATION_RECORD
- A sample of the XML document used to create an application through the Web Services API, preformatted within an HTML document. A plain text version is also available.
LeasePak Documentation Suite
© by NetSol Technologies Inc. All rights reserved.
The information contained in this document is the property of NetSol Technologies Inc. Use of the information contained herein is restricted. Conditions of use are subject to change without notice. NetSol Technologies Inc. assumes no liability for any inaccuracy that may appear in this document; the contents of this document do not constitute a promise or warranty. The software described in this document is furnished under license and may be used or copied only in accordance with the terms of said license. Unauthorized use, alteration, or reproduction of this document without the written consent of NetSol Technologies Inc. is prohibited.