Touchpoint Instance

You can use a Touchpoint instance to manage access over the HTTP protocol. Refer the information provided here to know more about this.

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:

Provider

This mode provides access of clients to third party services. A client sends an HTTP request to the Touchpoint Instance (1), which in turn translates the request to the native language of the remote system and sends that to it (2). The remote system responds with the proper result to the Touchpoint Instance (3), which then transmits it back to the client (4) through HTTP.

As can be seen from this diagram, the Provider has a single input interface, represented by a URL on which you can send your requests (request-in URL). This URL is intrinsic, meaning that the Touchpoint Instance creates it and provides it to you.

Initiator

This mode provides transport of information between two ends. The Touchpoint Instance is the one that requests a piece of data from one system using the system dependent language (1) and then "pushes" this data through HTTP to several Data Destination System (2a, 2b) - HTTP servers capable of receiving data (for example, a Provider Touchpoint).

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 run time, 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.

Intermediary

This mode provides a forwarding service. The Intermediary Touchpoint Instance accepts requests (1) and then sends them to several Destinations through HTTP (2a, 2b). The Destinations respond to the Touchpoint Instance (3a, 3b), it merges their responses and transmits the result back to the caller (4).

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. You 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, you 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:

if one of the Destinations returns a successful response, it is returned to the caller;
if several Destinations return a successful response, the data in the response bodies is merged and returned with an HTTP code 200;
if all Destinations return failure responses, an error response with code 500 is returned to the caller. In its HTTP body, it will contain the following information for each Destination:
- Request to URL 'the URL of the Destination' failed.
- HTTP status: the returned HTTP error code
- HTTP body: the returned HTTP body

To change the merging behavior you 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 you must specify two more configuration items when setting up a Touchpoint Instance. These are:

Property Sheet of the Touchpoint. Each Touchpoint Instance is representing a specific Touchpoint Type, which means that every Touchpoint Instance has a specific configuration. It complies with the one defined by the Touchpoint Type (the Property Sheet Definition) and reflects the schema of the IBM® Security Directory Integrator Connector working with the remote system for this Touchpoint (known as the Service Connector).
Note: 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.
Admin state of the Touchpoint. This item is used for micro managing the state of the Instance. For example, you may want to disable a running Provider Touchpoint for a given period of time. Instead of deleting it, you can simply set its admin state to disabled. This way, when it is needed again, you only have to update its state to enabled, and it will be running again.
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, you 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 you 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:

Unavailable - when the Touchpoint Instance is intentionally disabled through its Admin state.
Available - when the Touchpoint is configured and its admin state is enabled.

The status of a Provider Touchpoint has one additional parameter. Besides the operational state, you 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:

Unavailable - the Touchpoint Instance is in this state if:
- it is not fully configured, meaning that it has no Destinations (request-out URLs);
- it is intentionally disabled, by setting its Admin state;
- its Service Connector has finished reading from the data source.
  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.
Available - when in this state, the Touchpoint Instance is actually reading data from the data source.

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.

Unavailable - the Touchpoint Instance is in this state if:
- it is not fully configured, meaning that it has no Destinations (request-out URLs);
- it is intentionally disabled, by setting its Admin state;
Available - when in this state, the Touchpoint admin state is enabled and it is actively forwarding its incoming requests to the Destinations.

Similarly to the Provider Touchpoint, the Intermediary has a request-in URL, which can be obtained from its Status Entry.