Quandis Military Search Integration Guide

This is a guide for automating the integration of Quandis Military Search (QMS) using the Quandis Data Services Platform. It describes transmission protocols utilized, the QMS Military workflow, XML messaging and schema requirements. It will also outline general usage and common error types.

It is written for both prospective and new system integrators, consultants and other technical professionals interested in integrating with QMS.

Definitions

The following terms are referred to in this document.

Term Definition
Client, Clients Organizations requesting military search orders
Endpoint Web service or HTTP receiver that is exposed by an organization to receive inbound data
QBO Acronym for Quandis Business Objects. Generally refers to any module or component that has been created by Quandis.

Data Transmission

QMS sends and receives data via the public internet using HTTPS (2048 bit) protocol as the standard protocol. VPN connectivity is supported under special circumstances. QMS supports the following protocols:

  • SOAP (using HTTPS)
  • HTTP POST (RESTful)
  • sFTP

Preferred Transmission Patterns

QMS supports an event driven transmission model whereas the preference is for the originating system to push or invoke the target end point whenever there is a need to transmit data. This is opposite from the source system polling the target system endpoint to check if data is available at any given time. As a result, we require our partners to expose an end point such as a SOAP web service or HTTPS receiver.  The end point is generally public accessible with security controlled by IP restriction and BASIC authentication.

Service Connectors

QMS supports the above protocols as standard connectivity. In some scenarios, there is a requirement to connect to an existing web service or platform using a combination of protocols to satisfy non-standard connectivity requirements for a partner. QMS can also implement Service Connectors that will facilitate this.  The usage of Service Connectors is evaluated on a per implementation basis.

Additional Security Models

The following table describes the various protocols and security models used by QMS:

Protocol Security Model Notes
HTTPS (ApiKey) Include a custom HTTP header “X-ApiKey” containing your API access key. Primary security model used by QMS API integrations.
HTTPS (SOAP,REST) BASIC Authentication using HTTPS.
sFTP No additional security

FTP Exchange Model

The FTP file exchange model uses secure FTP to exchange data. Due to the nature of the FTP file exchange, integrations are addressed on an individual basis. Please refer to FTP Exchange Models for common implementations.

QMS Environments

The following table outlines the location of UAT and Production host values. Unless otherwise stated, all URL relative paths are the same for production with only the host value changed.

QMS Environment Host Notes
UAT https://uatscra.quandis.net/ All references in user guide point to UAT
Production https://scra.quandis.com/

Endpoints

During the lifecycle of a military search several events occur on the client and Quandis systems. A subset of these events requires communication of data between the various systems to facilitate order processing.

SCRA Request via API

The following endpoints are exposed by QMS for military search events:

Event Endpoint Description
Request SCRA Search https://uatscra.quandis.net/Military/Military.ashx/Search HTTP POST with XML payload.
See QMS Data Dictionary for request format and data points.
Pickup SCRA Results https://uatscra.quandis.net/Military/Military.ashx/Pop Pop results via HTTP GET to retrieve SCRA results.

Simple Pickup Model

Order Pickup

QMS exposes a stand-alone endpoint which allows clients to poll for completed orders. Product data is retrieved by invoking the endpoint. Upon invoking the pickup endpoint, each complete order is represented as a message in the pickup response and marked as received. Once the pickup list includes a given order, it is automatically removed from the list and will no longer be present in subsequent calls. Users have the option to embed product data in the pickup response or obtain a Resource Urn to access the product data at a later time.

Product Pickup

The pickup endpoint accepts the following optional parameters:

Parameter Description
MessageCount Allows for multiple messages to be downloaded at once. Allowed values: 1-5. Default value is 1 which implies one message will be returned when the pickup endpoint is invoked.
PayloadType Embeds product content or product pointer in pickup message. Enumerated: Content, ResourceUrn. Default is Content. See below for best practices.

Best Practices
The frequency is which to invoke the pickup method should be set by a schedule in accordance with given SLA requirements. Since the pickup method is a polling method, it will return a message list with a count ranging from zero to the number of available messages. The following table is suggests best practices for invoking the pickup endpoint:

Message Count Returned Frequency
0 If no messages are available, use the next run date on the predefined schedule performing the polling.
Greater than 0 If messages are available, invoke the pickup method as soon as the previous call completes and repeat until no messages are available to ensure all messages are retrieved.

The pickup model response allows for embedding of product data as a convenience or emitting a ResourceUrn which allows product to be accessed in a subsequent call. PayloadType usage guidelines are:

Payload Type Recommended Usage
Content (Embedded Product) Smaller payloads, smaller volume and when content is NOT processed during the pickup call. We recommend saving a copy of the content and processing at a later time.
ResourceUrn (Product Pointer) Larger payloads (due to multiple searches), larger volume with ability to use separate process to invoke the Product endpoint to download and process product a separate process. Also note the product can be obtained subsequent times by accessing ResourceUrn without invoking pickup method.

Practical Example: We suggest not to set MesageCount to 5 with PayloadType to Content and process data (saving file content, saving data to DBMS) during the pickup call in favor of MessageCount to 5 with PayloadType to ResourceUrn with separate calls to the product resource.

Client Notification / Product Pickup

QMS has the ability to notify the client product is ready for consumption and the client must invoke the product endpoint to obtain product data. Upon order completion, QMS will invoke the client endpoint submitting a Product Notification. The Product Notification contains a ResourceUrn binding to the product endpoint for subsequent product download. The client reserves the right to download the resource on their schedule. The ResourceUrn contains a reference to the Product endpoint and will return the Product Data format. This is the preferred approach for processing orders that contain multiple searches.

Callback Model

Callback Support

QMS can also be configured to post SCRA results to a specific endpoint as results become available. This substitutes the Pickup/Pop step but requires client-side security permissions and endpoint maintenance.

Batch Search

Batch Search via QMS Web Portal

QMS supports batch and ad-hoc file drops for larger search populations. Primary file submission practice is to submit ad-hoc via the QMS Web Portal.

  1. Login to Quandis Military Search
  2. Home > SCRA Search
  3. Drag and Drop or load document directly.
  4. Adjust settings if necessary.
  5. “Submit” when ready.

Batch Search via FTP File Exchange

File watchers can be configured to monitor an FTP location for pickup and processing of batch files. See FTP Exchange Models listed below.

Accepted file types include Excel and fixed-width text. See QMS Data Dictionary for templates.

Monitoring

QMS has the concept of monitoring via Buckets. This allows users to manage and schedule the monitoring of a population of borrowers for possible status and datapoint changes.

Monitored datapoints:

  • Status
  • Branch
  • Active Duty Start Date
  • Active Duty End Date

Managing Bucket Population via API

Monitoring requests support RESTful patterns to manage a Bucket population:

Event Endpoint
Add Borrower to Existing Bucket https://uatscra.quandis.net/Military/{Bucket}/AddContact/{LastName},{FirstName},{USSSN}, etc

Monitoring via QMS Web Portal

Bucket populations can also be managed via the QMS Web Portal. See QMS Data Dictionary for standard request and response formats.

Monitoring via FTP File Exchange

File watchers can also be configured to monitor an FTP location for pickup and processing of bucket files. See FTP File Exchange Models below.

FTP Exchange Models

Military search data can also be exchanged using secure FTP. In most cases, each implementation is slightly different. The following examples are the most common integration scenarios.

Quandis-Hosted FTP Model

The following model outlines the FTP file exchange process where Quandis hosts the FTP server.

Client-Hosted FTP Model

The following model outlines the FTP file exchange process where the client hosts the FTP server.

Parsing and Permutation Logic

QMS currently supports two permutation models: Simple and Advanced. With each model, subject data is parsed and prepared before permutation logic is applied. Visit our Parse and Permutation Guide for an in-depth explanation of our parse and permutation features.

Image Packages

Image Packages allow clients to define multiple package profiles of order options with the granularity to meet compliance requirements. This eliminates FTE and automates compliance requirements. See our Image Packages Guide for more information.

Direct File Access

The QMS API offers the ability to access file content. This is useful for on-demand access of images when clients choose to control which files or images to manage. The following file types are available for download using the API:

  • SCRA Certificates  (Includes all certificate types generated from image packages)
  • Zip Files
  • SCRA Product Files

Resource Url

GET api/v1/file/{id}

Resource Information

Response Format JSON, Xml
Authentication Required Yes
Rate Limited No

HTTP Headers

X-ApiKey {Provided by Quandis}

Parameters

Parameter Description Required Example
id Quandis unique file identifier Required 1

HTTP Status Codes

Status HTTP Status Code
Complete 200
Error 500

HTTP Response Headers

Content-disposition attachment; filename=”{File Name}”
Content-Length File Length

Body

{Image Content}

Quandis Military Search Integration Guide v 1.0.3

Last Updated By: Quandis Data Services – August 2019

Click here to add your own text