Configurator API

This section provides the technical details for integrating an external application, called a configurator applet, with the touchatag service, using the Configurator API.

This API comes in two flavors: a SOAP and a REST interface. Both offer the same functionality, so feel free to choose the technology that suits you the best.

On both interfaces authentication is possible using Basic Authentication or OAuth. Both the SOAP and REST endpoints are reachable over http or https, when using Basic Authentication we recommend using https, for OAuth this is not needed.

It is assumed that the developer knows how the flow of the touchatag application configuration wizard works, and has used some of the example applications available at www.touchatag.com.

In order to integrate an external application with the touchatag service, the application developer needs to communicate the URL of the web application to touchatag (support@touchatag.com). touchatag will on its turn send the necessary credentials to the application developer to be able to authenticate the integration calls.

In order to integrate an external application with the touchatag service, the user has to enrole as a developer on the http://www.touchatag.com/user/ site.

After this in your dashboard you get an extra tab named developer. There you can create new configurator applications by providing a name, a description and the location of your configurator template. After creating an api-key and secret are automatically generated for your application. These are to be used as your O-Auth credentials when communicating with the ACS server.

Configuring a touchatag application consists of 4 steps:

1. Selecting the type of application
2. Editing the details of the selected application
3. Choosing one or more tags to associate with the application
4. Confirmation

In step 1 all available applications will be visible.

In order to make an externally hosted application visible, the external application server needs to be registered in the touchatag system. This is currently a manual process (mail to support@touchatag.com), but will be automated in the future.

<!-- TODO update to developer self-registration -->

When the user moves to step 2, the external application server will be addressed.

1. The user selects an application and goes to step 2 of the touchatag application-configuration wizard.

2. The touchatag server presents a webpage with an i-frame that is linked to the external application server. The web page made available by the external web server should comply with the following rules in order to be imbedded nicely into the touchatag wizard:

• Width = 330 pixels
• Height = free

3. The i-frame connects to the external application server and sends a temporary transactionId as a parameter in the URL (the external application server temporarily stores this ID)The parameter that will be added to the web application URL for communicating this ID is ?configurationTransactionId=<ID(string)>

4. The external application makes a request to the ACS server to retreive the applicationConfig providing the transactionId [SOAP | REST]

5. The touchatag server responds with the applicationConfig data. This response may contain an empty value in case the considered application is being created based on an empty application where none of the configurable fields has pre-provisioned values. Alternatively, in case the user is starting from an application that has pre-configured values, or in case the user is editing one of his existing applications, the applicationConfig data will contain the previously stored data.

6. The external application server provides the html page to show in the i-frame to the user browser. The external application server uses the retrieved applicationConfig data to correctly render the html page (including the pre-set values for the application parameters).

7. The user edits the application configuration page and confirms to go to step 3. With this confirmation, the browser sends the new application configuration data to the external application server. This application configuration data contains the values of all the fields that the user has edited during Step 2 of the application configuration wizard.

8. The external application server uses the user input to decide (= external application logic) which actions to bind to the tags, and then sends a specification describing the new application together with the new applicationConfig and transactionId to the ACS server. [SOAP | REST]

9. When the touchatag server receives the specification and applicationConfig, the user is moved to step 3 of the application creation wizard.

Note that the web application developer can freely choose the programming language, in which the external web application is written.