Backend queries - CustomerID

Owned by ubisebastian
Last updated: 2019-11-11 by Arto VainiolehtoVersion comment

Backend queries

During user registration several HTTP-queries can be utilized to enrich user identity using information retrieved from external systems, e.g. CRM. The response messages are expected to contain XML formatted data in UTF-8 encoding.

Requests may include data from the ongoing registration that user has already given or other parameters such as the user interface language code. Backend calls are only used during registration workflows to

  1. validate the information that the user has given
  2. enrich user information based on input
  3. workflow control

A backend response may include a status code, error message and information about the user (attributes, roles etc.)

Support for fetching simple name-value pairs from the response XML message can be done with XPath expressions. Output parameters for a backend configuration should be configured in the file backend.properties.

Validation of user input

User input is communicated to the backend system as HTTP URL parameters. The backend system communicates the validation result as a HTTP status code or as a status code within the backend response XML message.

Enrichment based on user input

Enrichment is an extension to validation of user input. Ubisecure CustomerID may display messages, store user attributes, create and modify organization entities, create roles and create role assignments based on information communicated in the backend response XML message.

Workflow control

The backend system may control the registration workflow with status codes. Currently supported controls are ERROR, STOP and OK. ERROR indicates any errors in the user input and the user is allowed to correct any input. STOP causes the registration workflow to terminate. OK allows workflow to proceed normally.

Example of a backend request and response

Request (HTTP GET): 

http://localhost:7080/backend?Email=user@test.com&AccountNumber=111&authcode=123&locale=fi

Response:

<customer>
	<firstname>User</firstname>
	<lastname>Test</lastname>
	<contract>123456</contract>
	<status>OK</status>
	<error></error>
</customer>

Backend query configuration

See Backend query configuration - CustomerID for instructions how to configure performing a backend query. Follow this document further to learn how to perform a transformation for the backend query response.

Backend query response to Ubisecure CustomerID XML schema transform

Ubisecure CustomerID supports transforming backend query responses to Ubisecure CustomerID XML schema, which allows more complex user information enrichment scenarios.

Ubisecure CustomerID XML schema

Ubisecure CustomerID XML Schema can be used to import more complicated user data to the system when the XPath based parsing is insufficient. If the backend server does not natively support Ubisecure CustomerID XML schema, it is possible to apply an XSLT transformation to convert the message from backend format to Ubisecure CustomerID XML document. The backend response schema supports a wide range of operations for adding information to the Ubisecure CustomerID database. A high level overview of the XML schema is shown below. Please refer to messages.xsd and importer.xsd for exact details. Package can be downloaded from Ubisecure Extranet (CustomerID-XML-schema.zip).

A response document contains a root response element with children:

<m:Response> 
	<Add .../> 
	<Modify .../> 
	<Remove .../> 
	<m:Control status=""> 
		<m:Message .../> 
		<m:Action> 
			<m:Parameter .../> 
		</m:Action> 
	</m:Control> 
</m:Response>

Status codes

When using the Ubisecure CustomerID XML schema, status definition is done using the Control element in XML response instead of what is configured in the backend.properties file. The status attribute of the Control element in XML response should be used to control the workflow.

<m:Response> 
	<m:Control status="ok|stop|error|internal_error"/> 
</m:Response>

Displaying messages

A message for the user can be included in the Control element of the response in two ways. You should either define a language key or give the message directly optionally with localization.

Direct message

<m:Response> 
	<m:Control> 
		<m:Message xml:lang="en">Invalid username</m:Message> 
	</m:Control>
</m:Response>

Language key

<m:Response> 
	<m:Control> 
		<m:Message key="backenderrormessagekey"></m:Message> 
	</m:Control>
</m:Response>

If a language key is given then it will be searched from messages_xx.properties file without adding any prefix or postfix to it.

The message will be shown as an error message if there is an error in the backend response.

Storing user attributes

The backend response can alter user attributes in the ongoing registration process. This can be achieved with one or more Action elements in the Control element which can contain information about the user as follows:

<m:Response> 
	<m:Control> 
		<m:Action> 
			<m:Parameter name="user.firstname"> 
				<Value>Firstname</Value> 
			</m:Parameter> 
		</m:Action> 
	</m:Control> 
</m:Response>

Or using the Modify operation element with current-user in the type attribute:

<m:Response> 
	<Modify type="current-user"> 
		<Replace name="firstname"> 
			<Value>Firstname</Value> 
		</Replace> 
	</Modify> 
</m:Response>

Create roles and create role assignments

The Ubisecure CustomerID XML schema supports several operations which alter the database. In addition to aforementioned Modify, the Add operation can be used to create roles in the system as follows:

<m:Response> 
	<Add type="role" entityName="Company/Admin" errorAction="continue"/> 
	<Modify type="current-user"> 
		<Add name="role"> 
			<Role>Company/Admin</Role> 
		</Add> 
	</Modify> 
</m:Response>

And in conjunction with the Modify operation roles created can be assigned to the user registering to Ubisecure CustomerID.

Create organizations 

As seen above the Add element has a type attribute. That attribute defines the type of the entity, which will be created. In addition to roles organizations can be created similarly:

<m:Response> 
	<Add type="organization" entityName="Company" errorAction="continue">
		<Attribute name="friendlyName"> 
			<Value>Example Friendly Name</Value> 
		</Attribute>
		<Attribute name="customattribute">
			<Value>Attribute value</Value>
		</Attribute>
	</Add>
</m:Response>

The errorAction attribute defines a control flow instruction. The Add statement fails with error and causes processing to stop if the entity already exists. With errorAction="continue" the error is ignored and processing continues with the next statement.

XSLT transformation

Refer to http://www.w3.org/TR/xslt for complete details of the XSLT language. Command Line Transformation Utility (msxsl.exe) can be used to test an XSL transformation. http://www.microsoft.com/en-us/download/details.aspx?id=21714

Defining the XSLT document for backend

Path to the XSLT document to be used in with a specific backend is configured in the backend.properties as follows:

customerdata.transform = <path-to-xslt-document>

Input parameters and HTTP status code

The input parameters that are communicated to the backend and the HTTP status of the backend response are available as top-level parameters to the stylesheet. Parameter namespaces:

  • Input parameters 
    http://schema.ubisecure.com/customerid/messages#input  
  • HTTP status 
    http://schema.ubisecure.com/customerid/messages#http  

Input parameter names are defined by the input configuration entry in backend.properties.
Example:

customerdata.input = { "user.email": "Email", "user.accountnumber": "AccountNumber" }

defines input parameter names "Email" and "AccountNumber".
HTTP status parameter names:  

  • statusCode 
    the numeric HTTP status code: 200, 401 etc 
  • statusMessage 
    http status text: "OK", "Not Found", etc. 
  • URI 
    the URL of the request 

 Example:

<xsl:stylesheet version="1.0"
	xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
	xmlns="http://schema.ubisecure.com/customerid/importer"
	xmlns:m="http://schema.ubisecure.com/customerid/messages"
	xmlns:http="http://schema.ubisecure.com/customerid/messages#http"
	xmlns:input="http://schema.ubisecure.com/customerid/messages#input"
>
	<xsl:param name="http:statusCode" />
	<xsl:param name="input:Email" />
	<xsl:param name="input:AccountNumber" />
	<xsl:template match="/">
		<xsl:choose>
			<xsl:when test="$http:statusCode != 200">
				<m:Response>
					<m:Control status="INTERNAL_ERROR" />
				</m:Response>
			</xsl:when>
			<xsl:otherwise>
				<xsl:call-template name="response" />
			</xsl:otherwise>
		</xsl:choose>
	</xsl:template>
	<xsl:template name="response">
	...
	</xsl:template>
</xsl:stylesheet>

Ubisecure Privacy Policy & Cookie Statement