Touchpoint Schema

Touchpoint Server communication protocol

This section specifies the communication protocol between the Touchpoint Server and a client that is using it for provisioning of Touchpoint Instances. This section does not describe the communication between a client and the Touchpoint Instance itself.

The Touchpoint Server is providing access to the various resources that are involved in the definition of a Touchpoint Instance. The representation of these resources is in a tree-like form. The access to each resource is done using Atom documents over the HTTP/HTTPS protocol.

This is the schema used by the Touchpoint Server:

Figure 1. Touchpoint server schema tree

* These tree nodes are available in certain cases. For details see the table below.

In the above schema the following variables are used:

• tp_server_host - this is the host address the Touchpoint Server is listening on
• tp_server_port - this is the port the Touchpoint Server is listening on (defaults to 1098)
• context_root - this is the context root under which the Touchpoint Server application is available (defaults to "tp")

The navigation of the tree is done in a ReSTful way, meaning that client applications should only know the entry point (that is, the URL of the Service Document) and the type of references (Atom links) the Touchpoint Server defines for accessing each of the nodes in the resource tree. These references (URLs) are automatically generated by the Touchpoint Server. Once obtained, the URLs will stay the same until the Touchpoint Server is updated to a newer version. This implies that client applications can "remember" the obtained URLs between updates of the Touchpoint Server, but should work their way back to the particular resource URL if the Touchpoint Server is updated.

According to the protocol specified in the table below, the following steps should be performed in order for a client application to navigate to the Touchpoint Instance Feed starting from the Service Document.

1. Send an HTTP GET request to the Service Document URL. This will return the Service Document from which the Touchpoint Providers Feed URL could be obtained.
2. Send an HTTP GET request to the Touchpoint Providers Feed URL. This will return the Feed Document from which the Touchpoint Provider Entry Reference URL could be obtained.
3. Send an HTTP GET Touchpoint Provider Entry Reference URL. This will return the Entry Document representing the particular Touchpoint Provider. This Entry contains the URL to the Touchpoint Type Feed.
4. Send an HTTP GET request to the Touchpoint Type Feed URL. This will return the Feed Document containing complete copies of all the Touchpoint Type Entries valid for this context. From a Touchpoint Type Entry the client application can obtain the Touchpoint Instance Feed URL.

The table below describes the allowed operations for each resource. Additionally the following points are applicable for the whole resource tree:

• Each entry has a link with relation "self" that points to the standalone Entry Document.
• Resources that accept HTTP methods PUT and DELETE have a link with relation "edit". All such request should be sent to that link (URL).
• Every request to the Touchpoint Server is annotated with the HTTP ETag response-header as defined by the HTTP specification. The ETag value can be used in conjunction with the request-headers If-Match, If-None-Match and If-Range to let the Touchpoint Server know what the client application's preconditions are before servicing the request.

Touchpoint Configuration

This section describes the schema of the configuration data that one must provide in order to configure and start a Touchpoint Instance.

Every configuration data element is placed inside a <data> element within the Atom document. The namespace this data element must belongs to is: http://www.ibm.com/xmlns/prod/scmp

Instance Configuration

This configuration data specifies:

• Role that the Touchpoint Instance will be running in. The Touchpoint Instance relies on this data to decide which AL from the template to use. In the atom document below, it is denoted by the "{role}" token.in the category element. Its supported values are provider-tp, initiator-tp and intermediary-tp.
• Admin state of the created Touchpoint Instance. It is marked by the "{admin_state}" token in the Atom document. The supported values are enabled and disabled.
• Property Sheet XML containing the configuration parameters for Touchpoint Instance's Service Connector. The {param_name} is determined by the Property Sheet Definition of the chosen Touchpoint Type for standard Types or the Property Sheet Definition of the Service Connector for custom Types. The "{param_value}" is determined by the user depending on the wanted configuration. Besides configuration parameters, you can also set the mode of the Service Connector by setting a parameter with {param_name} equal to "$initMode" and a string value with the mode name (for example, Iterator, AddOnly). For details about this parameter see section Property sheet definitions.
• The two parameters {TouchpointID} and {version} are provided in order to allow you to specify additional information for the particular Touchpoint Instance, which has meaning for the creator only. The creator is responsible for ensuring these values are valid in the context of the client application. These values are not interpreted by the Touchpoint Server in any way, it only persists them.

The POSTed Atom Document when creating a Touchpoint Instance Entry Resource is:

<entry xmlns="http://www.w3.org/2005/Atom">
	<id>{id}</id>
	<title>Touchpoint Instance Title</title>
	<author><name>Author Name</name></author>
	<content/>
	<category term="{role}" scheme="http://www.ibm.com/xmlns/prod/scmp#touchpoint-role" />
	<scmp:data 
xmlns:scmp="http://www.ibm.com/xmlns/prod/scmp" xsi:schemaLocation="http://www.ibm.com/xmlns/prod/scmp
http://localhost:1098/tp/schema/touchpoint.xsd" >
		<scmp:touchpoint>
			<scmp:admin-state>{admin_state}</scmp:admin-state>
			<touchpointID>{touchpoint_id}</touchpointID>
			<version>{version}</version>
			<scmp:propertySheet>
				<scmp:property propertyName="{param_name}">
					<scmp:value>{param_value}</scmp:value>
				</scmp:property>
				...	
			</scmp:propertySheet>
		</scmp:touchpoint>
	</scmp:data>
</entry>

Please note that an ID for the created Touchpoint Instance can also be provided in place of the "{id}" token. However, no matter what the passed value is, the Touchpoint Server will overwrite it with an automatically generated one. This way it guarantees the uniqueness of the Touchpoint Instance ID.

Destination Configuration

Both the Intermediary and Initiator Touchpoints require a Destination to be configured, before they become operational. Furthermore, they support multiple such Destinations and the ability to add and remove them at runtime.

This is done by POSTing an Atom Document on the Touchpoint Destination Feed URL of the created Touchpoint Instance. Keep in mind that no such URL is available for Provider Touchpoints. Here is how it should look like:

<entry xmlns="http://www.w3.org/2005/Atom">
	<scmp:data 
xmlns:scmp="http://www.ibm.com/xmlns/prod/scmp" xsi:schemaLocation="http://www.ibm.com/xmlns/prod/scmp
http://localhost:1098/tp/schema/touchpoint.xsd" >
		<scmp:destination>
			<scmp:request-out>{request-out_URL}</scmp:request-out>
			<scmp:request-error>{request-error_URL}</scmp:request-error>
		</scmp:destination>
	</scmp:data>
</entry>

As can be seen from this snippet, only the "{request-out_URL}" is needed for configuring a Destination; the "{request-error_URL}" is optional.

Touchpoint Instance communication protocol

This section describes the protocol used to communicate with a Touchpoint Instance. In most cases a Touchpoint Instance will be derived from the Touchpoint Template.

Provider Touchpoint

The Provider Touchpoint handles HTTP methods described in the following table:

(*) Note that there is a difference in the handling of the PUT method between our implementation and the HTTP 1.1 specification (http://tools.ietf.org/html/rfc2616#section-9.6). According to the HTTP specification, a PUT request is supposed to replace the whole resource. In our implementation if the entry exists we do not replace it as a whole, but only replace the specified attributes.

The Link Criteria for the Connector operations is derived from the query parameters of the requested URL. For example, a GET request with URL "http://localhost/mytp?username=jsmith" will result in a Lookup operation with link criteria "username=jsmith". Each query parameter corresponds to an EXACT match criterion. The criteria derived from multiple query parameters are combined using the 'AND' logic operator. For example: "?firstname=john&age=50" corresponds to ((firstname equals "john") AND (age equals "50")).

Query parameters are required for PUT and DELETE requests. POST requests are not expected to contain query parameters. If a GET request contains query parameters, it is translated to a Lookup mode operation. Otherwise it is translated to an Iterator mode operation.

On GET requests you can use an optional HTTP header named "X-TDI-TP-SizeLimit" to limit the number of returned Entries. The value of the header must be an integer larger than zero.

All HTTP Methods interpreted by the default Touchpoint Template are compliant with the HTTP Specification according their safety and idempotence characteristics.

Initiator Touchpoint

The Initiator Touchpoint Instance acts as an HTTP client. It has an Iterator Connector which produces Entry objects that the AssemblyLine sends to a configured Destination URLs. For each Entry it sends a single POST request, whose content is an XML representation of the Entry.

Intermediary Touchpoint

The Intermediary Touchpoint Instance is similar to both the Provider and Initiator roles. It accepts requests on a particular request-in URL as a Provider and sends the received data to multiple Destinations as an Initiator. Due to this forwarding functionality it can be used as moderator between several Touchpoint Instances from the other roles.

Representation of Entry objects as HTTP content

Example:

<tp:data xmlns:tp="http://www.ibm.com/xmlns/prod/tdi/711/tp">
	<tp:entry>
		<tp:attribute name="username">
			<tp:value><![CDATA[jsmith]]</tp:value>
		</tp:attribute>

		<tp:attribute name="mail">
			<tp:value>jsmith@ibm.us.com</tp:value>
			<tp:value>john.smith@gmail.com</tp:value>
		</tp:attribute>
	</tp:entry>
</tp:data>

The HTTP content must be encoded in "UTF-8". It must contain a single data element which can contain zero or more entry elements.

<?xml version="1.0" encoding="UTF-8"?>
<schema 
	targetNamespace="http://www.ibm.com/xmlns/prod/tdi/711/tp"
	elementFormDefault="qualified"
	attributeFormDefault="unqualified"
	xmlns=http://www.w3.org/2001/XMLSchema xmlns:tns=http://www.ibm.com/xmlns/prod/tdi/711/tp >

	<element name="data" type="tns:TouchpointDataType" />

	<element name="entry" type="tns:EntryType" />

	<element name="attribute" type="tns:AttributeType" />

	<element name="property" type="tns:PropertyType" />

	<element name="value" type="string" />

	<complexType name="TouchpointDataType">
		<choice minOccurs="0" maxOccurs="unbounded">
			<element ref="tns:entry" />
		</choice>
	</complexType>

	<complexType name="EntryType">
		<choice minOccurs="0" maxOccurs="unbounded">
			<element ref="tns:property" />
			<element ref="tns:attribute" />
		</choice>
	</complexType>

	<complexType name="AttributeType">
		<choice minOccurs="0" maxOccurs="unbounded">
			<element ref="tns:property" />
			<element ref="tns:attribute" />
			<element ref="tns:value" />
		</choice>
		<attribute name="name" type="string" use="required" />
		<attribute name="namespaceURI" type="anyURI" />
	</complexType>

	<complexType name="PropertyType">
		<simpleContent>
			<extension base="string">
				<attribute name="name" type="string" use="required" />
				<attribute name="namespaceURI" type="anyURI" />
			</extension>
		</simpleContent>
	</complexType>

</schema>

Touchpoint Status Entry schema

The status of the Touchpoint Instance can be retrieved by sending an HTTP GET request to the URL of the Status Entry as described by section Touchpoint Server communication protocol.

<entry xmlns="http://www.w3.org/2005/Atom"> 
    <id>Status ID</id>
    <link href="{touchpoint_instance_status_URL}" type="application/atom+xml;type=entry" rel="self"/>
    <category scheme="http://www.ibm.com/xmlns/prod/scmp#resource" term="touchpoint"/>
    <category scheme="http://www.ibm.com/xmlns/prod/scmp#aspect" term="status"/>
    <scmp:data 
xmlns:scmp ="http://www.ibm.com/xmlns/prod/scmp"
xsi:schemaLocation="http://www.ibm.com/xmlns/prod/scmp
http://localhost:1098/tp/schema/touchpoint.xsd" >
        <scmp:touchpoint-status>
            <scmp:request-in>{request-in_URL}</scmp:request-in>
            <scmp:op-state>{op-state}</scmp:op-state>
        </scmp:touchpoint-status>
    </scmp:data>
</entry>

The returned Atom Entry Document contains a <data> element that describes the status of the Touchpoint Instance. The data element belongs to the http://www.ibm.com/xmlns/prod/scmp namespace. It has the following syntax:

• {op-state} - is the string keyword describing the current state of the Touchpoint Instance as defined in section Touchpoint Instance.
• {request-in_URL} - is the URL for accessing Provider and Intermediary Touchpoint Instances.

Property sheet definitions

The Property Sheet Definition is an XML document that determines the schema of a Tivoli® Directory Integrator Connector. It can be obtained from a link inside the Touchpoint Type Entry (as described in section Touchpoint Server communication protocol).

Depending on the Touchpoint Type the Property Sheet Definition varies:

• For standard Types, it contains the schema of the TDI Connector corresponding to the Touchpoint Type.
• For custom Types, it contains the schema of the Service Connector in the custom Touchpoint Template.
• For the virtual Type (virtual://Intermediary) there is no Property Sheet Definition, as there is no third-party system to communicate to (this role relies solely on HTTP).

Besides the schema parameters of a TDI Connector the Property Sheet Definition contains the modes, supported by the Connector. They are stored as optional values for the propertyDefinition with name $initMode. Their values directly match the Connector mode names - "Iterator", "AddOnly", "CallReply", and so forth.

Here is an example Property Sheet Definition for the File Connector (Touchpoint Type system:/Connectors/ibmdi.LDAP):

<?xml version="1.0" encoding="UTF-8"?>
<propertySheetDefinition xmlns="http://www.ibm.com/xmlns/prod/scmp">
    <propertyDefinition required="true" hidden="false" readonly="false"
		 propertyType="string" multiple="false" 
       propertyName="ldapUrl">
        <label label="LDAP URL" lang="en"/>
        <!--one label for the different languages supported by TDI -->
    </propertyDefinition>
    <!--the rest of LDAP Connector's parameters -->
    <propertyDefinition required="false" readonly="false" propertyType="string" 
    multiple="false" propertyName="$initMode">
        <label label="$initMode" lang="en"/>
        <!--one label for the different languages supported by TDI -->
        <option>
            <value>AddOnly</value>
            <label label="AddOnly" lang="en"/>
            <!--one label for the different languages supported by TDI -->
        </option>
        <option>
            <value>Iterator</value>
            <label label="Iterator" lang="en"/>
            <!--one label for the different languages supported by TDI -->
        </option>
        <!--the rest of modes supported by the LDAP Connector -->
    </propertyDefinition>
</propertySheetDefinition>

To shorten the listing, only one of its configuration parameters and the $initMode property definition are included. As can be seen this Connector has a parameter named ldapUrl which is required and its value is a string. Also, its English label as can be seen in the CE is LDAP URL (the labels for the rest of the languages supported by Tivoli Directory Integrator are skipped). The $initMode parameter is also present, and as can be seen from its optional values this Connector supports both Iterator and AddOnly modes (and several others which are skipped).

Property Sheet Definitions significantly assist you when creating Touchpoint Instances, as you do not need to know the schema of the Connector in advance. Relying on their information, you can perform this task, much like you configure Connectors inside TDI's Configuration Editor - by seeing the needed parameters, checking their expected values (a string, a number or a set of predefined values) and providing them in the configuration.

XML Schema locations

An XML Schema document is provided for each scmp:data element. The document defines all elements which appear inside the scmp:data element.

The location of the schema document is specified in an xsi:schemaLocation (XML Schema Instance location) attribute defined on the scmp:data element. For example:

<scmp:data
	xmlns:scmp="http://www.ibm.com/xmlns/prod/scmp"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.ibm.com/xmlns/prod/scmp 
http://localhost:1098/tp/schema/tdi-connectivity-provider.xsd">

	<scmp:connectivity-provider>

The location of the schema is a valid URL which can be de-referenced by web clients: Any client of the Touchpoint Server can resolve the URL which appears inside the xsi:schemaLocation attribute and access the actual schema document.

Moreover if the schema contains a reference to another schema document (for example, via "import", "include" or "redefine" XML Schema element), the URL in the reference can be resolved by web clients to obtain the referred schema.