API Guide

S2. Service Method Listing

All Service Methods are invoked by XDOC using an HTTP Request Get method. The parameters passed to the URLs will be appended to the URL as Query String parameters with the following conditions.

  • Any user passwords parameters passed on the Query String can optionally be encrypted using standard AES encryption. The AES encryption settings are configurable and must be set identical in both XDOC and the External System. See section 4 below for AES encryption configuration information.

2.1. Method Invocation Each Service Method can have its own HTTP URL endpoint and can be configured to pass the parameters in any of the methods indicated above. Example:

/securityservice/lookupUser.jsp?SecurityToken=&AppId=XDOC&UserName=jsmith

2.2. Method Listing The table lists the Methods invoked. All methods return Data Fields which contain user attributes plus any error codes and messages if applicable. The format required for the return data, and the data fields expected are listed in Section 3.

SecurityToken and App Id are optional and are defined by the External System as required.

Method Input Parameters Notes
AuthenticateUser SecurityToken
AppId
UserName
UserPassword
Validates the Username and Password and returns the User object attributes if successful.
LookupUser SecurityToken
AppId
UserName
Looks up the User information and returns the User object attributes if the user exists.

2.3. Method Result Data The Service endpoints can return result data in any of the following formats.

  • XML
    • If the method is successful, must contain a <User> node.
    • The User data fields can be either attributes of the <User> node, or sub-nodes.
    • If returning error messages, use the standard <ServiceResponse> envelope schema.
  • JSON

Regardless of the result data format returned by the External System, all of the following conditions must be true for XDOC to consider the method call to be successful (authorized / valid user):

  • HTTP Result Code = 200 (OK)
  • The ExternalId data field must be non-empty.

2.4 Method Result Data Format Examples

2.4.1 XML Result Data Examples

<!-- User node with attributes -->
<User 
   UserName="jsmith"
   FirstName="John"
   LastName="Smith"
   Email="jsmith@axacore.com"
   Profile="Manager"
   ExternalId="1234567" />
<!-- User node with sub-nodes -->   
<User>
   <UserName>jsmith</UserName>
   <FirstName>John</FirstName>
   <LastName>Smith</LastName>
   <Email>jsmith@axacore.com</Email>
   <Profile>Manager</Profile>
   <ExternalId>1234567</ExternalId>
</User>
<!-- Error with result information -->   
<ServiceResponse
   Success="0"
   ResultCode="4000"
   ResultMessage="Invalid Password">
   <ResponseTrace>
   <![CDATA[
   Stack Trace error information...
   ]]>
   </ResponseTrace>
</ServiceResponse>

2.4.2 JSON Result Data Example

<!-- User JSON object -->
{
    "UserName": "jsmith",
    "FirstName": "John",
    "LastName": "Smith",
    "Email": "jsmith@axacore.com", 
    "Profile": "Manager", 
    "ExternalId": "1234567" 
} 
<!-- Error JSON object with result information -->   
{
    "Success": "0",
    "ResultCode": "4000",
    "ResultMessage": "Invalid Password",
    "ResponseTrace": "Stack Trace error information"
}

2.4.3 Name Value Pairs (ini) Result Data Example

<!-- User information  -->
[user]
UserName=jsmith
FirstName=John
LastName=Smith
Email=jsmith@axacore.com
Profile=Manager 
ExternalId=1234567 
<!-- Error result information -->   
[result]
Success=0
ResultCode=4000
ResultMessage=Invalid Password
ResponseTrace=Stack Trace error information