API Guide

S2. Standard XML Schemas

2.1. ServiceRequest XML Envelope The ServiceRequest XML envelope is used for Services that require Method parameters to be passed as XML in the Request Input Stream.

<ServiceRequest
    ServiceName=““ 
    ServiceMethod=““ 
    RequestDate=““ 
    RequestId=””
    SecurityToken=””
    UserName=”” >

    <RequestUser 
        UserId=““ 
        UserName=““ 
        FirstName=””
        LastName=””
        Email=””
        ExternalId=””
        ExternalRef=””
        ExternalData=””
        ExternalFlags=””  
    />

    <RequestParameters>
        <Parameter Name=”” DataType=”string”></Parameter>
        <Parameter Name=”” DataType=”number”></Parameter>
        <Parameter Name=”” DataType=”xml”>
            <someXmlStructure>
            </someXmlStructure >
        </Parameter>
        <Parameter DataType=”cdata”>
            <![CDATA[Some interesting data .]]>
        </Parameter>
        <Parameter Name=”” DataType=”file” FileName=”” ContentType=”” FileExtension=”” IsBase64=””>
        Base64 or text data.
        </Parameter>
    </RequestParameters>

    <RequestData>… varies by method ….</RequestData>

</ServiceRequest>

ServiceRequest Node Attributes

Attribute Data Type Required Allowable Values Sample Description
ServiceName String Yes MyXDOCService Name of the Service Class being invoked.
ServiceMethod String Yes GetContainer Name of the Method being invoked.
RequestDate Date Yes 20091201T154300 UTC Timestamp of the Request.
RequestId String 12345 Unique generated GUID of the Request. This may be used tracing calls between applications.
SecurityToken String Arbitrary security token specified by the Integrated Application
UserName String john.smith User logon name of the user context of the request.

RequestUser Node Attributes

Attribute Data Type Required Allowable Values Sample Description
UserId String Yes 1234567891231 XDOC internal id of the user context of the request.
UserName String Yes john.smith User logon name of the user context of the request.
FirstName String John User first name.
LastName String Smith User last name.
Email String john.smith@gmail.com User email.
ExternalId String For externally managed users, the id of the user in the external system.
ExternalRef String Arbitrary data set on the user object by the external system.
ExternalData String Arbitrary data set on the user object by the external system.
ExternalFlags Long 0 Arbitrary data set on the user object by the external system.

Request Parameter Node Attributes

Attribute Data Type Required Allowable Values Sample Description
Name String Yes Container Parameter Name.
DataType String Yes string, bool, date, integer, long, number, xml, cdata, file String Parameter Data Type.
ContentType String application/pdf Required for file data types
FileName String somefile.pdf Source file name.
FileExtension String pdf Required for file data types
IsBase64 Bool 0,0 1 Indicates if the data is base64 encoded.

2.2. ServiceResponse XML Envelope All Methods must return their result data wrapped in a common Response XML envelope. This gives XDOC a consistent way to interpret success or failure and retrieve the result data from the method, as well as provides data that can be useful for debugging the integration.

<ServiceResponse 
    ServiceName=““ 
    ServiceMethod=““ 
    RequestDate=““ 
    RequestId=““ 
    Success=“1” 
    ResponseDate=““ 
    ResultCode=““ 
    ResultInfo=““ 
    ResultMessage =““ >
    <ResponseData>… varies by web method…</ ResponseData >
    <ResponseTrace>Error stack trace in the event of an error</ResponseTrace>
</ ServiceResponse>
Attribute Data Type Required Allowable Values Sample Description
ServiceName String Yes MyXDOCService Name of the Service Class being invoked.
ServiceMethod String Yes GetContainer Name of the Method being invoked.
RequestDate Date Yes 20091201T154300 UTC Timestamp when the Request was received.
RequestId String 12345 Unique generated GUID of the Request. This may be used tracing calls between applications.
Success Bool Yes 0,1 1 “True” or “1” indicates the method was successful. “False” or “0” indicates failure.
ResponseDate Date Yes 20091202T164523 UTC Timestamp when the Response was completed.
ResultCode Int 0 0 for success, an error code if an internal error occurred, or any other Integrated Application specific code identifying some condition.
ResultInfo String UserNotFound A short label corresponding to the ResultCode. Usually only used for errors.
ResultMessage String Usually blank for success, and an error message on failure.

Response XML Notes:

  • Success is generally always set = 1, unless there is some kind of critical error that occurred in the Integrated Application. It is never used to indicate Application Logic conditions.

Standard Result Codes and Conditions:

  • Note: The following result codes should be used for common error conditions as noted. These are purposefully intended to correspond to standard HTTP result codes.
Result Code Condition / Description
400 The Method being requested does not exist.
401 The Requested Method requires a user context, which could not be determined.
403 Security Token is not valid or not authorized.
404 Some required Application object does not exist. E.g.: User does not exist. Message or object being requested does not exist. Etc.
405 Unauthorized access. The Invoking user does not have permission to access the object or Method.
500 Unexpected Error occurred. View the ResponseTrace XML node for detailed Error Stack Trace information.
501 The Method cannot be completed because it is missing one or more required fields or objects. E.g.: Container, etc.

2.3. Container XML Many of the Service Methods return information about the Business Entity in the Integrated Application. This is referred to as the Container and represents the IContainerInfo interface in the XDOC system. A container is intended to be a simple business object that has the following:

  • A minimal set of known attributes that XDOC is expecting and needs to function properly. These are the attributes in the node below.
  • An arbitrary set of other simple typed attributes. The node below.
  • Optional Security flags from the Integrated Application indicated if the user’s access to the object.
  • Zero or more lists of values that represent Master-Detail type Collections of simple object.

Following is sample Container XML representing a Loan from a Loan Processing System (Integrated Application).

<Container
    Key=””
    Reference=””
    Name=””
    Label=””
    Description=””>
    <Attributes 
        LoanNumber=”1234”
        LoanPurpose=”Cash-Out Refi” />
    <Security 
        ReadOnly=”0”
        HideDocumentImages=”0”
        Profile=”Underwriter”   />
    <Lists>
        <List Name=”BORROWER”>
           <ListItem Name=”Joe Smith” Value=”12345” />
           <ListItem Name=”Jane Smith” Value=”6789” />
        </List>
        <List Name=”BORROWER-PRIMARY”> 
           <ListItem Name=”Joe Smith” Value=”12345” />
        </List>
        <List Name=”BORROWER-COMBINED”> 
           <ListItem Name=”Joe Smith” Value=”12345” />
           <ListItem Name=”Jane Smith” Value=”6789” />
           <ListItem Name=”Joe and Jane Smith” Value=”1234456789” />
        </List>
    </Lists>
    <UserRoles>
        <UserRole RoleName=”Underwriter” RoleValue=”UW” UserName=”jsmith” UserDisplay=”John Smith” UserEmail=”jsmith@gmail.com” />
        <UserRole RoleName=”Broker” RoleValue=”BR” UserName =”jdoe” UserDisplay =”Jane Doe” UserEmail=”jdoe@gmail.com” />
    </UserRoles>
</ Container >

Container Node Attribute Reference

Attribute Data Type Required Sample Description
Key String Yes Abc123abc Primary Key of the Object in the Integrated Application. This is what XDOC stores as the pointer for a document.
Reference String Yes 12345 User Friendly Unique Identifier of the Object.
Name String Yes Smith, 12345 Common Full Name for the Object.
Label String 12345 Short Label for the Object. Used in compact UI layouts.
Description String Joe Smith, TX, 12345 Long Description of the Object.
Profile String Underwriter Indicates the role that the user is assuming for the Object.

Security Node Attribute Reference

Attribute Data Type Required Sample Description
ReadOnly Bool 0 Indicates if the object is in a read only state for this user, and the user should not be allowed to add/update/delete and document information
HideDocumentImages Bool 0 If set, tells XDOC to hide all document images. The user can still see the document list.
Profile String Underwriter The security profile to apply to the user when viewing documents for this object.

Attribute Node Reference

Attribute Data Type Required Sample Description
** Varies String LoanNumber LoanAmount The list of attributes is up to the Integrated Application. Note: Any date Attributes should be returned in UTC format.

Lists Node Attribute Reference

Attribute Data Type Required Sample Description
Name String Yes BORROWER Primary Key of the Object in the Integrated Application. This is what XDOC stores as the pointer for a document.

List Item Node Attribute Reference

Attribute Data Type Required Sample Description
Name String Joe Smith Display Label for the item.
Value String 12345 Value or “id” for the item. This should never change.

User Role Node Attribute Reference

Attribute Data Type Required Sample Description
RoleName String Yes Underwriter Role Display Name / Label.
RoleValue String Yes UW Value stored in the LOS database.
UserName String Jsmith Logon of the User assigned to this role for the Container.
UserDisplay String John Smith Display Name of the user.
UserEmail String jsmith@gmail.com Email of the user.

2.4. ContainerList XML A list of containers. Used primarily by search Methods that return lists of matching Containers.

<ContainerList>
   <Container />
   <Container />
</ContainerList>

2.5. SearchCriteria XML Represents a list of Search Criteria that the Integrated Application will use to search and return ContainerList XML or other Application specific result sets. This XML structure is used as input to various Service Methods. Note: This is a simple search criteria structure where the SearchField nodes are generally assumed to be a set of “And” conditions.

<SearchCriteria>
   <SearchField Code=”” Value=”” Operator=”” />
   <SearchField Code=”” Value=”” Operator=”” />
</SearchCriteria>

SearchField Node Attribute Reference

Attribute Data Type Required Sample Description
Code String Yes loanNumber Field to be searched.
Value String Value to be searched.
Operator String Yes Search Operator. See the list or Operators that should be supported by the Integrated Application.

Search Operator Reference

Operator Additional Notes Example pseudo SQL equivalent
= dbCol = value
!= dbCol != ?
> dbCol > ?
>= dbCol >= ?
< dbCol < ?
<= dbCol <= ?
startsWith dbCol like (? || ‘%’)
inList dbCol in (?)
notInList dbCol not in (?)
isEmpty nvl( length(dbCol),0) = 0
isNotEmpty nvl( length(dbCol),0) > 0
isNull dbCol is null
isNotNull dbCol is not null
daysNewerThan dbCol > (sysdate – ? days)
daysOlderThan dbCol < (sysdate – ? days)
fullText Full Text Search dbCol contains ?

2.6. List XML Represents a simple list of Name / Value pairs.

<List>
   <ListItem Name=”” Value=”” />
   <ListItem Name=”” Value=”” />
</List>