IService: Invoking Third Parties

Background

All QBO 3 classes derived from AbstractObject can be extended to invoke third party components or plugins via the IService interface. When calling AbstractObject.Invoke* methods, AbstractObject will check the configuration file for Service entries matching the operation. If one is found, a corresponding IService plugin is instantiated, and invoked with the method parameters.

Use cases include:

• • Invoke an IService from the front end (e.g. Options > Order Credit Report)

  • Invoke an IService from a workflow

  • Invoke an IService from a batch import

Use Case: LPS Appraisal Order

QBO Valuations systems can order appraisals from LPS via QDS as follows:

• • Valuation.ashx/LPSAppraisal?ID={ValuationID}

An appraisal order is not an instantaneous product; it will typically be a long running transaction involving steps like:

• • receiving a confirmation message from LPS

  • exchanging messages with LPS as the order progresses

  • receiving a final product, or

  • cancelling the order

From the perspective of the third party, they should be able to submit data to QBO in an easy to understand RESTful manner, like this:

• • {some url}/Confirmation?{some parameters}

  • {some url}/Message?{some parameters}

  • {some url}/Product?{some parameters}

Though a series of pipes, levers, and valves, setting an IService configuration entry to use the 'qbo.Service.QDS.QDSExchange' class will result in:

• • creation of a ServiceRequest record as the third party is being invoked,

  • enabling postback to ServiceRequest.ashx/{Step} from the third party (QDS, in this case)

  • leveraging Import File Templates to handle importing the data received

The Valuation.config file contains an Service entry along these lines:

<Service Name="LPSAppraisal"

Type="qbo.Service.QDS.QDSExchange, qbo.Service.QDS"

ReturnType="Object"

RequestTransform="Templates/Mortgage/Valuation/Services/LPSAppraisal.xslt"

RequestMethod="Valuation/Select?ID={ID}"

ImportFileTemplate="QDS.LPS.OrderRequest.Response">

<Steps>

<Step Name="Confirmation" Type="qbo.Service.QDS.QDSExchange, qbo.Service.QDS"

ImportFileTemplate="QDS.LPS.Confirmation"

ResponseMethod="ImportFile/Response?ID={ImportFileID}"/>

<Step Name="Message" Type="qbo.Service.QDS.QDSExchange, qbo.Service.QDS"

ImportFileTemplate="QDS.LPS.Message"

ResponseMethod="ImportFile/Response?ID={ImportFileID}"/>

<Step Name="Product" Type="qbo.Service.QDS.QDSExchange, qbo.Service.QDS"

ImportFileTemplate="QDS.LPS.Product"

CompleteStep="true"

ResponseMethod="ImportFile/Response?ID={ImportFileID}"/>

</Steps>

</Service>

Use case: LCI Bankruptcy Search

LCI provides a web service for conducting bankruptcy searches and retrieving bankruptcy docket information. For this integration, we implemented two classes:

• • LCIReadObject: invoke the LCI bankruptcy search web service, and returns their native XML

  • LCIObject: invoke the LCI bankruptcy search web service, and routes the results through the QBO import framework via an Import File Template

To support these classes, we created the following:

• • Setup.LciBankruptcySearch.xml: setup package including Contact IService entries for the two classes noted above, credentials, and the import file template mapping LCI data structures to QBO data structures

Using the LCI IService plugin:

// Calling LCI directly from a QBO website with an ad-hoc user

Contact/Contact.ashx/LCIBKSearchRead?FirstName=John&LastName=Doe&USSSN=123456789&Address=123 Main Street&City=Anywhere&State=Ca&PostalCode=90210&Output=Xml

// Calling LCI directly from a QBO website with an existing QBO contact

Contact/Contact.ashx/LCIBKSearchRead?ID={ContactID}&Output=Xml

// Calling LCI directly, but wrap it in a custom QBO UI

Theme.ashx/Wrap?ClassName=Contact&Method=LCIBKSearchRead&ID={ContactID}&Transform=Templates/Service/Bankruptcy/Bankruptcy.LCISelect.xslt

// Calling LCI directly, transforming the results into QBO import-framework-ready XML

Contact/Contact.ashx/LCIBKSearchRead?ID={ContactID}&Output=Xml&Transform=Templates/Service/Bankruptcy/LCI.BankruptcySearch.XmlResponse.Import.xslt

// Okay those are some decent examples. Now let's really USE it.

// Search an actual borrower, and persist the Bankruptcy record to QBO

Contact/Contact.ashx/LCIBKSearch?ID={ContactID}&ParentObject=Loan&ParentObjectID={LoanID}

// Do the same thing, but don't make the user wait around for results

Contact/Contact.ashx/Queue/LCIBKSearch?ID={ContactID}&ParentObject=Loan&ParentObjectID={LoanID}

// Let's schedule this search every month

Contact/Contact.ashx/Schedule/LCIBKSearch?ID={ContactID}&ParentObject=Loan&ParentObjectID={LoanID}&Schedule=Monthly on the 1st at 3:00am

// Let's schedule a monthly sweep of all our contacts that don't have an existing BK

Contact/Contact.ashx/Schedule/BatchQueue?Filter=NoActiveBK&Operation=LCIBKSearch&Schedule=Monthly on the 1st at 3:00amasdf

Configuration

There configuration classes associated with an IService entry include:

• Service: this maps an operation to an IService-plugin

  • Name (string): name of the service (e.g. 'LPSAppraisal')

  • BaseService (string): name of a another Service to copy settings from

  • Type (System.Type): name of an assembly that implements the IService interface (i.e. the 'plugin' to us)

  • RequestMethod (string): method to invoke to get data prior to transmitting a request

  • RequestTransform (string): relative path to a transform (XSLT) file use to transform the output of RequestMethod priot to passing to a third party

  • LogData (bool): if true, plugins should use verbose logging; otherwise clients should use minimal logging

  • ImportFileTemplate (string): name of an Import File Template to process inbound data against

  • ReturnType (OperationReturnType): defines the return type of the initial call to the Service (e.g. Object, DataReader, XmlReader, Void)

  • Async (bool): true if the operation is async, false otherwise. 

• ServiceStep: this defines a postback operation for a third party to make for asynchonous operations

  • Name (string): name of a postback step (e.g. 'Confirmation')

  • Type (System.Type): name of an assembly that implements the IService interface (i.e. the 'plugin' to us)

  • Method (string): method to invoke with the postback data

    • Parameters (string): parameters to pass to Method (leverage string substitution)

    • Listeners (string): TBD

  • ImportFileTemplate (string): name of an Import File Template to process inbound data against

  • ResponseMethod (string): a method signature to run for responding to the postback (e.g. return the results of an import)

  • CompleteStep (bool): true to mark an async operation complete

Callbacks

Service Request