Service Request

This section provides information related to usage, configuration and functionality of Service Requests. It covers the concepts of Inbound, Outbound and Nested configurations. It also explains the various IService plug-ins.

Updates


10/7/2013 - Full Duplex

Summary

IService has been refactored to support the concept of full duplex with inbound and outbound messages:
  • Both inbound and outbound messages can be registered as top level (or parent) configuration entries and as child entries to a parent. This allows bi-directional communication and assoicating child messages with parent messages.
  • A new plug-in for inbound messages has been added (qbo.Service.InboundService.InboundRequest) which caters specifically to inbound data to QBO systems.
  • Ability to dynamically bind child ServiceRequests to parent ServiceRequests. AbstractServiceRequest will now dynamically bind a child ServiceRequest to it's parent based on Query lookup. qbo.Service.InboundService.InboundRequest will also bind for inbound requests
  • Services and Service Steps can be invoked from their native HttpHandler using a nested operation. For example, if the Valuation.config contained a Service entry called FNCOrder and a child step called StatusUpdate, Status update can be invoked by accessing /Valuation/Valuation.ashx/FNCOrder/StatusUpdate. Previously, Service Steps had to be invoked by /Import/ServiceRequest.ashx/{StepName}/ServiceRequestID=x
  • Service entries are now more flexible such that:
    • Processing is now split between RequestMethod and ResponseMethod. The purpose of RequestMethod and ResponseMethod are transposed depending if the step is an inbound or outbound step. For example:
      • InboundStep.RequestMethod - action to take on inbound data
      • InboundStep.ResponseMethod - method to produce/query response output. Can be optionally transformed with InboundStep.ResponseXslt
      • OutboundStep.RequestMethod - method to produce/query raw outbound data. Can be optionally transformed with OutboundStep.RequestXslt
      • OutboundStep.ResponseMethod - action to take once plug-in is invoked. In the outbound scenario, the data is transmitted and some type of response/acknowledgment has been received. The ResponseMethod can take further action such as execute an import on the acknowledgment or do nothing
    • Step response output can be controlled. The method, transform and OutputType can be configured or disabled
  • ServiceRequest panel has been added to PanelGeneric in Theme.Core
  • qbo.Import.dll has been extended to contain specialized methods which cater to IService:
    • ImportFile/ImportByObject?Template='x' - Used by InboundService, this method will invoke an ImportFileTemplate and dynamically bind a ServiceRequest Object/ObjectID to the ImportFileTemplate.AppliesTo object if the ImportLog shows 1 object matching that was inserted. It can also validate the ImportLog and located any objects that failed during import
    • ServiceRequest/Import?ServiceRequestID={ServiceRequestID} - Used by Outbound Services, this is used for importing synchronous response data. This method will fire the Import associated with the ServiceRequest.ImportFile when an outbound step accesses a remote endpoint and receives a response. This applies to use cases such as ordering a credit report and importing the credit response data or ordering a AccurintSearch and importing the response.
  • Logging ability has been added. By specifying Logging=true in parameters, ETL logging will log data for the key events when the plug-in is processing. This is essential for troubleshooting.
  • Test Harness - a test harness can be accessed at '/Import/ServiceRequest.ashx/InboundTest'. This will allow both inbound and outbound Services to be tested. This in conjunction with logging abilities eases development challenges.

Changes to all IService configuration properties:

The following changes are required to make IService entries compatible with the code base in trunk:
    • Method - Rename to RequestMethod
    • Parameters - Deprecated. Remove.
    • Listeners - Deprecated. Remove.
    • EndPoint - New. Stores endpoint value. See Outbound Requests.
    • RequireStream - New. Used for Inbound Services, this instructs HttpHandler to make the inbound stream accessible to the RequestMethod

Outbound IService entries using qbo.Service.HTTP.HttpExchange, qbo.Service.HTTP

    • Method changes to RequestMethod. Retain ClassName/Operation
    • ResponseMethod - set to "ServiceRequest/Import?ServiceRequestID={ServiceRequestID}". This must be present for post submission import to execute.
    • ReturnType - ensure "Object"
    • EndPoint - consider moving out of Xslt and adding

Steps Registered under a Service configuration that are intended for Inbound Data

The older pattern for registering a step under a parent step with the intent of accepting inbound data is to invoke the step by accessing:

/Import/ServiceRequest.ashx/{StepName}ServiceRequestID=x

The step configuration Xml was very limited. This example was for SCRA Product registered in Contact.config:

<Step Name="Product" Type="qbo.Service.HTTP.HttpExchange, qbo.Service.HTTP, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"
              RequestMethod="" 
              ImportFileTemplate="QDS.Product.SCRA" 
              ResponseMethod="ImportFile/Result?ID={ImportFileID}"
              CompleteStep="true" />

Steps can now be invoked by invoking their native handler and nesting the operation name. For the above example, the endpoint would be:

/Contact/Contact.ashx/SCRASearch/Product?ServiceRequestID=x

The configuration Xml is much more specific:

<Step Name="InboundProduct" Type="qbo.Service.InboundService.InboundRequest, qbo.Service.InboundService, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"
              RequestMethod="ImportFile/ImportByObject?Template=QDS.Product.SCRA" 
              ImportFileTemplate="QDS.Product.SCRA"
              ReturnType="XmlReader" 
              RequireStream="true" 
              ResponseMethod="ImportFile/ImportResultXml?ImportFileID={ImportFileID}"
              ResponseTransform="Templates/Logging/ImportLog.ImportResult.xslt"
              CompleteStep="true" />

Explanation of configuration attributes reveals:

  • Type - new plug-in specifically built for inbound requests
  • RequestMethod - new Import method built to Import Xml and bind the ServiceRequest to the first Object imported that matches ImportFileTemplate.AppliesTo
  • RequireStream - used to pass the Inbound Stream to the plug-in. For InboundRequests that use Xml imports this is always true
  • ResponseMethod - method signature  to produce response data. Method must have same return type specified in ReturnType property. 
  • ReturnType - In most cases XmlReader as the IService will return Xml Data representing the Import results
  • ResponseTransform - XsltTransform for data produced by ResponseMethod. The standard Xslt is specified above
See Inbound Services for more detail

Parent Steps Registered that are intended for Inbound Data

Services can now be registered as inbound services. See Inbound Service section. The common uses cases are for external systems such as QDS to submit Xml. Both inbound and outbound steps can nested under these services.