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
- validate the information that the user has given
- enrich user information based on input
- 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
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.
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):
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:
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.
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.
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:
Or using the Modify operation element with current-user in the type attribute:
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:
And in conjunction with the Modify operation roles created can be assigned to the user registering to Ubisecure CustomerID.
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:
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.
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:
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 parameter names are defined by the input configuration entry in
defines input parameter names "Email" and "AccountNumber".
HTTP status parameter names:
the numeric HTTP status code: 200, 401 etc
http status text: "OK", "Not Found", etc.
the URL of the request