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:
* These tree nodes are available in certain cases. For details see the table below.
In the above schema the following variables are used:
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.
The table below describes the allowed operations for each resource. Additionally the following points are applicable for the whole resource tree:
Resource | GET | POST | PUT | DELETE |
---|---|---|---|---|
Service Document | Retrieves the Service Document which contains a list of the available services. The URL to the Touchpoint Providers Feed is set as "href" attribute to a collection that belongs to the category "connectivity-provider". | N/A | N/A | N/A |
1. Feed: Touchpoint Providers
Categories (term: scheme): connectivity-provider: http://www.ibm.com/xmlns/prod/scmp#resource |
Retrieves the list of Touchpoint Provider Entries. All entries are references to the actual Entry Documents representing the available Touchpoint Providers. | N/A | N/A | N/A |
1.1 Entry: Touchpoint Provider | Retrieves a Touchpoint Provider Entry the way it was configured in the Touchpoint Server configuration file. This Entry provides some additional details in the <{http://www.ibm.com/xmlns/prod/scmp}:data/> element. The link to the Touchpoint Types Feed is provided using a link with relation "http://www.ibm.com/xmlns/prod/scmp#touchpoint" | N/A | N/A | N/A |
1.1.1 Feed: Touchpoint Types
Categories (term: scheme): touchpoint: http://www.ibm.com/xmlns/prod/scmp#resource |
Retrieves the list of Touchpoint Type Entries. These entries are complete copies of the actual Entry Documents representing the Touchpoint Types. | N/A | N/A | N/A |
1.1.1.1 Entry: Touchpoint Type
Categories (term: scheme): touchpoint: http://www.ibm.com/xmlns/prod/scmp#resource resource-type: http://www.ibm.com/xmlns/prod/scmp#aspect A term uniquely identifying a Touchpoint Type: http://www.ibm.com/xmlns/prod/scmp#touchpoint-type |
Retrieves a Touchpoint Type Entry. The URL to
the Touchpoint Instance Feed is provided as a link with relation "http://www.ibm.com/xmlns/prod/scmp#instance-feed"
The URL to the Property Sheet Definition XML is provided as a link with relation "http://www.ibm.com/xmlns/prod/scmp#property-sheet-definition". Note:
The virtual Touchpoint Type does not have a Property Sheet
Definition, because no Connectors need to be configured for Intermediary
Touchpoints. |
N/A | N/A | N/A |
1.1.1.1.1 Feed: Touchpoint
Instances
Categories (term: scheme): touchpoint: http://www.ibm.com/xmlns/prod/scmp#resource |
Retrieves the list of Touchpoint Instance Entries. All entries are references to the actual Entry Documents representing the available Touchpoint Instances. | Creates a new Touchpoint Instance Entry. The entry MUST contain a data element that contains the Touchpoint Instance's configuration. The entry must contain a category from the "http://www.ibm.com/xmlns/prod/scmp#touchpoint-role" scheme. | N/A | N/A |
1.1.1.1.1.1 Entry: Touchpoint
Instance
Categories (term: scheme): touchpoint: http://www.ibm.com/xmlns/prod/scmp#resource provider-tp OR initiator-tp OR intermediary-tp: http://www.ibm.com/xmlns/prod/scmp#aspect A term uniquely identifying a Touchpoint Type: http://www.ibm.com/xmlns/prod/scmp#touchpoint-type |
Retrieves the Touchpoint Instance Entry. This
Entry contains three links to the resources that describe the Touchpoint
Instance:
|
N/A | Updates the Touchpoint Instance entry. The provided entry must contain the complete copy of the Entry Document and not just the changes. This operation cannot change the role of the Touchpoint Instance. This operation restarts a running Touchpoint Instance in order to reconfigure it. | Deletes the Touchpoint Instance Entry. |
1.1.1.1.1.1.1 Feed: Touchpoint Destinations | Retrieves the Touchpoint Instance Destinations Feed. This Feed could contain multiple Touchpoint Instance Destination Entries. | Creates a new Touchpoint Instance Destination Entry. It MUST contain a data element configuring the request-out URL to the Destination. | N/A | N/A |
1.1.1.1.1.1.1.1 Entry: Touchpoint
Destination
Categories (term: scheme): tp-destination: http://www.ibm.com/xmlns/prod/scmp#resource |
Retrieves the Touchpoint Destination Entry that contains the request-out URL to the remote HTTP Service in the <{http://www.ibm.com/xmlns/prod/scmp}:data/> element. This entry provides a link with relation "edit" to enable updates/deletes on this resource. | N/A | Updates the Touchpoint Instance entry. The provided entry must contain the complete copy of the Entry Document and not just the changes. This operation cannot change the role of the Touchpoint Instance. This operation does NOT restart a running Touchpoint Instance in order to alter the request-out URL. | Deletes the Touchpoint Destination Entry. |
1.1.1.1.1.1.2 Entry: Status
Categories (term: scheme): touchpoint: http://www.ibm.com/xmlns/prod/scmp#resource status: http://www.ibm.com/xmlns/prod/scmp#aspect |
Retrieves the Touchpoint Instance Status Entry
which describes the operational state of the particular Touchpoint
Instance. It is contained inside the <{http://www.ibm.com/xmlns/prod/scmp}:data/>
element.
Note:
For Provider and Intermediary Touchpoints
the status also contains one request-in URL, which should be used
by clients when querying the Touchpoint. |
N/A | N/A | N/A |
1.1.1.1.2 XML: Property Sheet Definition | Retrieves the Property Sheet Definition for the selected Touchpoint Type. It holds the schema of a TDI Connector in the form of an XML document. | N/A | N/A | N/A |
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
This configuration data specifies:
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.
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.
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.
The Provider Touchpoint handles HTTP methods described in the following table:
HTTP Method | URL Query Parameters | Connector mode | HTTP Request Content | HTTP Response Content | HTTP Response Code |
---|---|---|---|---|---|
GET | - | Iterator | - | all Entries found | "200 OK" if at least one Entry was found
"404 Not Found" if no Entries are found |
GET | link criteria | Lookup | - | all Entries found | "200 OK" if at least one Entry was found
"404 Not Found" if no Entries are found |
POST | - | AddOnly | Entry to be added | - | "201 Created" if the operation was successful |
PUT* | link criteria | Update | Entry with updated attributes | - | "201 Created" if the Entry did not exist and
was added
"204 No Content" if a single Entry matches the link criteria and the Entry was updated successfully |
DELETE | link criteria | Delete | - | - | "204 No Content" if the operation was successful (the operation will fail if multiple Entries match the link criteria) |
(*) 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.
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.
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.
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>
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:
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:
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.
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.