The Touchpoint protocol is a provisioning protocol which gives access to TDI Connectors and AssemblyLines through HTTP. When we create a Touchpoint, you get a "proxy" through which to work with a remote system. Once the Touchpoint is created and configured, you only send HTTP requests and you are completely isolated from the specifics of that system.
The sections below provide details about the different concepts associated with Touchpoints:
The Touchpoint Server is the application that stores information about the defined Touchpoints in the particular domain. The Touchpoint Server is used to control the remote Touchpoint instances. It is responsible for their configuration, starting and stopping. The Touchpoint Server is provided as a service running inside the TDI Server.
Clients of the Touchpoint Server are using the Atom Publishing Protocol to access details for the Touchpoint Providers, Touchpoint Types and Touchpoint Instances. For more details on the defined schema see section Touchpoint Schema.
A Touchpoint Provider is a server on which the Touchpoint Server is creating the Touchpoint Instances. In our case a Touchpoint Provider can be any TDI Server version 7.1 or later. The Touchpoint Server is only able to work with TDI Servers, as any other Touchpoint Provider is not supported.
The Touchpoint Server is shipped as an add-on to the TDI Server. It runs in the server’s JVM which enables it to communicate with the server through the Local Server API. This is why the TDI Server has been registered as a local Touchpoint Provider by default. In order to register a Touchpoint Provider, representing a remote TDI Server, use the RMI settings of the remote server. The registration for both a Local and a Remote Server is performed in the standard Touchpoint Server configuration file.
No user interface panels to configure the Touchpoint Server or Touchpoint Providers currently exist in the Configuration Editor or the Webadmin tool, AMC. All configuration must be done by means of XML configuration files.
For more details see section Touchpoint Configuration.
Once registered the Touchpoint Provider cannot be changed through the Atom interfaces. Additionally the Atom interface hides some of the details specifying the connection the remote TDI Server. Those details are only used by the Touchpoint Server in order to communicate with the Touchpoint Provider and are not meant to be seen by the clients of the protocol.
A Touchpoint Type is an abstract notation that provides meta-information for each Touchpoint Instance and determines its behavior. Every Touchpoint Instance has exactly one Touchpoint Type, while there is no limit to how many Touchpoint Instances can be created for a particular Type.
There are three categories of Touchpoint Types:
When creating a Touchpoint Instance, we need to provide the configuration of the Connector that will communicate to the third-party system. If a standard Touchpoint Type is used, this means providing the configuration of the corresponding TDI Connector. For custom Types provide configuration for the Service Connector of the custom Template. Finally, for virtual Types no configuration is needed as Intermediary Touchpoint Instances rely only on HTTP Components for performing their task.
How do you find out what parameters are needed to create a Touchpoint Instance? For this purpose the Touchpoint Server supports Property Sheet Definitions - XML documents providing information for the schema of a TDI Component. To obtain the URL of the Property Sheet Definition, send a HTTP GET request to the URL of the particular Touchpoint Type. It defines the required connector parameters, their default values, as well as other useful information needed when configuring a Touchpoint Instance.
In general, the information provided by Property Sheet Definitions is similar to the one available when configuring a Connector in TDI's Config Editor (except for parameter descriptions). For more details on Property Sheet Definitions and their usage see section Property sheet definitions.
By nature, a Touchpoint Instance represents a proxy that enables access to a remote service over the common HTTP protocol. However, the communication flow varies significantly, depending on the role of the Touchpoint Instance. Here are more details for the supported Touchpoint roles:
As can be seen from this diagram, the Provider has a single input interface, represented by a URL on which we can send your requests (request-in URL). This URL is intrinsic, meaning that the Touchpoint Instance creates it and provides it to you.
To achieve this, the Initiator is allowed to have multiple output interfaces - request-out URLs where the available data is sent. These destination points (also referred to as Destinations) can be added or removed from the Initiator at runtime, which gives a lot of flexibility for distributing data between systems. The Initiator starts working when its first request-out URL is added and stops when all of them are removed. By default the Initiator Touchpoint sends data to all of its Destinations, disregarding their responses. This behavior can be modified (for example, to stop the Initiator, if any of the Destinations fails to receive the data) by editing the base Template or providing a custom one.
For a Client Application, the Intermediary looks like a Provider giving access to some third party system, while for the Data Destination Systems it is an Initiator sending data.
The Intermediary Touchpoint has a single input interface - request-in URL and multiple output ones - request-out URLs. We configure the output interfaces the same way as for the Initiator role, and the input interface is similar to the Provider's one (meaning its URL is set by the Touchpoint Server). In its simplest form, the Intermediary Touchpoint does not modify the forwarded data but you may provide such logic by editing the base Touchpoint Template or by providing a custom one.
Another specific characteristic of the Intermediary Touchpoint can be noticed when it acts as a proxy for accessing several Providers. As mentioned above, we can interact with this complex system as if it was a simple Provider. However, there is an explicit need to merge the responses returned from the end Providers. The default available logic is:
To change the merging behavior we need to edit the Touchpoint Template used.
For more details on the communication protocol between the Client and the Touchpoint, see section Touchpoint Instance communication protocol.
Besides the above mentioned roles specify two more configuration items when setting up a Touchpoint Instance. These are:
The Intermediary Touchpoint does not use a Service Connector for its working, so no such configuration information is needed for it. When setting up such Touchpoints, users should send an empty property sheet, as any provided parameters will just be ignored.For more information about the Property Sheets format see section Instance Configuration.
Another possible use case is for the Intermediary and Initiator roles. As soon as you add the first Destination to such Touchpoints, they start working (and presumably sending data). Additional Destinations can be added later on, but this may lead to data lost as some of the data will already be sent. To solve this, we can create such Touchpoints with disabled admin state (preventing them from starting) and add as many Destinations as needed. When the configuration is done, you can change the state to enabled, and the Touchpoint will start sending data to all the Destinations.
After creating the Touchpoint Instance we can access its current Operational state. There are two different states a Touchpoint can be in and their meaning varies with the role of the Instance.
A Provider Touchpoint Instance has the following states:
The status of a Provider Touchpoint has one additional parameter. Besides the operational state, we can get the request-in of the Touchpoint - the URL address where you send your request so that the Provider Touchpoint can communicate them to the remote system.
An Initiator Touchpoint Instance has the following states:
This specific case is due to the behavior of the Service Connector of the Initiator Touchpoint Instance. If this Connector is a standard Iterator, it will read its configured data source and when done will stop, thus stopping the whole Touchpoint. However, in the case of Change Detection or JMS Connectors, it will continue to wait for new data and the Touchpoint Instance will keep running indefinitely (and staying Available). In this case it should be stopped explicitly by deleting it or setting its Admin state to disabled.
As mentioned above, the Intermediary Touchpoint Instance in essence is a combination of a Provider and an Initiator Touchpoint Instance. This is reflected on its status as well.
Similarly to the Provider Touchpoint, the Intermediary has a request-in URL, which can be obtained from its Status Entry.
When a Touchpoint Instance is started, the Touchpoint Server creates a TDI configuration and starts it as a temporary TDI ConfigInstance on its associated Touchpoint Provider (TDI Server). The TDI Configuration is based on a base Template provided with the Touchpoint Server. The path to this template file is specified in the Touchpoint Server configuration, the default being TDI_install_dir/etc/TouchpointTemplate.xml. It is placed on the Touchpoint Server side and is a general template not associated with a particular TDI Server. The configuration of each Touchpoint Instance is the one that is filled into the base template before it is started as a ConfigInstance.
The default base template contains the following structure:
Using this technique, only one HTTP Server Connector is needed for communicating with all of these Touchpoints which mean only one TCP port should be opened (by default this is 1097). This avoids possible firewall problems that can occur if a large amount of random ports needs to be opened.
The ProviderServer AssemblyLine uses the following TDI Components:
A Touchpoint AssemblyLine should have only one Service Connector (or none, as is the case with Intermediary). If several are provided, they all will have the same configuration.
sendToDestinations(work, mergeResponsesCallback)This method is provided by the Sender Script Component located in the library of the base Template. Besides the entry that will be sent, it requires a callback function that is used to merge the responses from each Destination. See section Touchpoint Instance for details on the default merging behavior of the Intermediary Touchpoint.
Touchpoint AssemblyLines should have only one Service Connector (or none, as is the case with Intermediary). If several are provided, they all will have the same configuration.
sendToDestinations(work, null)The same call is used by the Intermediary Touchpoint Instance. The only difference is that here no callback function for merging the responses from the different Destinations is provided. See section Touchpoint Instance for details on the default merging behavior of the Initiator.
Notes:
The Touchpoint Server handles the GenericServiceConnector differently, depending on the Touchpoint Type:
The Communication procedure is as follows:
The base Touchpoint Template provides a properly configured MemoryProperties Store. Every time a Touchpoint is created the Touchpoint Server checks if the MemoryProperties is missing and if so, adds it to the configuration. Thus, if we do not configure this Store in your custom Templates the default one will still be available. On the other hand, if you modify the MemoryProperties to alter the communication behavior (for example, use a Properties Connector, so that the Destination URLs are persisted to a file), the Touchpoint Server will not overwrite their new configuration.
The request-error URL is not used by default; it is only provided to the TouchpointTemplate for you, so we can enhance the default error recovery mechanism or implement a custom one.
Custom templates let you provide complex/customized behavior in an AssemblyLine and expose it as a new Touchpoint Type. The default base template is used for direct provisioning of TDI Components and an Intermediary Touchpoint without requiring you to know anything about what is happening under the hood of TDI. However, you may want to add more logic and/or Connectors to a Touchpoint Instance than a single Component. For this purpose the Touchpoint Server accepts custom templates to facilitate new custom Touchpoint Types and behavior.
A custom template's structure should be like the one of the base Template. However, if we do not need your custom Touchpoint Type to support all Touchpoint roles you may provide only a subset of the AssemblyLines. The minimum requirements for each role are:
The base Template's ProviderServer AssemblyLine is used to delegate request to all Touchpoint Instances. Thus, even if a ProviderServer AssemblyLine exists in a custom template, it won't be used by the Touchpoint Server. The one of the base template will be used instead.
The MemoryProperties Store is not listed, because if missing, it will be added by the Touchpoint Server.
If you try to create a Touchpoint Instance in a role which requirements are not fulfilled by the custom Type's Template an Exception will be thrown.
You must keep in mind these important points when editing the base Touchpoint Template or creating a custom one.