Specification

This material is intended to help software developers and highly-technical non-developers understand how create Specification documents that define custom touchatag applications.

Before reading this, you must be familiar with the concepts of the ACS Block System.

Overview

Specification documents let you devise new touchatag Applications using the ACS Block System.

The functionality of every touchatag Application available in the touchatag Application Catalog was defined by a corresponding XML document called a Specification. Each Specification document defines the logical procedure for an application, as well as the parameters the Application must use. Whenever an end user configures (or reconfigures) an Application through the touchatag dashboard, the changes are posted to the touchatag Application Correlation Service (ACS) in an updated Specification document.

For example, configuring touchatag's Web Link Application requires a URL parameter from the end user. The Application’s procedure results in an action that causes the end user's computer to open that web link (URL). When you configure a Web Link Application in the touchatag dashboard, the dashboard sends a complete Specification document to the ACS. (You can see an example of that Specification here.)

You can create your own Specifications to define touchatag Applications that use the Block System in completely new and innovative ways.

Each Specification is an XML document that you submit to the touchatag Application Correlation Service (ACS), either via the Specification Tool (used mainly for testing Specifications), or via the Configurator API (which allows you to create user-friendly configuration interfaces, and make your Applications sharable through the touchatag dashboard).

This page explains the key concepts for creating your own Specification documents. Start with the brief video introduction of the structure of a Specification document. Then, we recommend reading through the remaining key concepts as you explore the example Specification documents.

Key Concepts

Structural Overview

This video presents an overview of how Specification documents are structured.

Specification Structural Overview (on Vimeo).

Note As an overview, this video does not cover some of the possible possible structural variations for constructing specifications.

Structural Details

A Specification document has two major sections:

• application — defines a list of commands
• blueprint — defines a superblock that uses the standard Application Runtime Interface

These two sections can also be readily identified in the overall structure of the Specification document:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<specification xmlns="http://www.touchatag.com/schema/configurator/specification-1.0">
   <application>
      ...
   </application>
   <blueprint>
      ...
   </blueprint>
</specification>

Note the following XML elements:

• XML preamble — is an optional XML preamble indicating the type of XML and its encoding. Please note that although this preamble is not required, we do require UTF-8 encoding.
• specification — forms the root element of a Specification. Note The schema permits blueprint as a top level element as well, but this is currently not yet supported.
• xmlns — defines the namespace (or schema) to use for all elements within specification (http://www.touchatag.com/schema/configurator/specification-1.0).
• application — covers the definition of Commands.
• blueprint — covers the definition of the Application's main Superblock. In this case it must be used to define a Superblock that adheres to the Application Runtime Interface.

Application Section

The application section of the specification covers the definition of commands. It follows the following structure:

...
<application>
	<command id="commandId" name="Launch the first action"/>
	...
	<command id="otherId" name="Launch the other action"/>
</application>
... 

An application can define multiple commands and MUST at least define 1 command. If there is only a single command, it is commonly called default, but you are free to choose this identifier. The name attribute is used in the tag association screen and allows a more meaningfull message for the user.

Blueprint Section

The blueprint section of the Specification defines the Application's main superblock, which makes up the bulk of a Specification.

Note The blueprint element is a general construct for defining superblocks. This provision exists so that eventually you may define your own Superblocks and then re-use them by referencing them from various other Applications (or even other Superblocks). At this time, however, touchatag only supports the definition of an Application's main superblock.

Defining the Main Superblock

You can use the main superblock of an application in two ways. You can either reference an existing library application and simply configure its parameters, or you can define your own Application built of a custom assembly of blocks and superblocks.

The former case, referencing an existing library Application, only allows you to set the parameters for the Application by configuring the Application block's properties. You cannot change an existing library Application's execution flow. Although the Specification Schema allows you to add additional elements (such as interface, breakdown and wiringscheme, they will be ignored if you provide them. (There is no inheritance for blocks, so you either re-use in this fashion or you define your own application entirely.)

When defining a main superblock, there are three parts to compose:

• Properties — provide a top-level location for setting the configuration parameters for the superblock.
• breakdown — declares a list of block instances that the Superblock uses.
• wiringscheme — defines how the various pins of the different blocks in the breakdown link together to create an execution flow for the Superblock.

Each of these superblock elements is covered in its own section in this document.

Example: Main Superblock

Here is a basic example of an Application's main superblock as defined in a Specification.

...
<superblock id="urn:example:sample:message-app">
            <property name="Message"><text>Ta-dah!! Your tag has been read!</text></property>        
            <breakdown>
                <block id="ts" ref="urn:touchatag:block:text-source">
                    <property name="Value"><delegate as="Message"/></property>
                </block>
                <block id="m" ref="urn:touchatag:block:message"/>     
            </breakdown>
            <wiringscheme>
                <wire from="ts:out" to="m:in"/>
                <shunt from="m:out" to="action-out"/>
            </wiringscheme>
        </superblock>
...

• superblock id="*" — defines a new application (because the superblock element does not include a ref attribute referencing an existing Application from the ACS Block System Library). The Specification schema requires that you must assign an id, but because it is not currently used for anything, you can simply use * rather than give it a more descriptive id.
• property name="hellotext" — defines a property for the superblock called hellotext, allowing us to set the property's value once and then use the value in as many of the breakdown blocks as necessary.
• breakdown — lists all the blocks referenced in the wiringscheme, and assigns values to whatever properties those blocks may have.
• block id="ts" ref="urn:touchatag:block:text-source" — declares an instance of the text-source block type through its ref, and assigns the instance an id of ts, which must be unique within this superblock.
• property — configures the ts block's Value property.
• delegate as="hellotext" — assigns the Value property to use the value of the superblock's hellotext property (instead of directly assigning a value on the block itself).
• wiringscheme — defines the application's execution flow using of a mix of wire and shunt elements that connect the blocks' pins to one another.
• wire from="ts:out" to="m:in" — represents a wiring between the pins of two blocks using the proper Pin Endpoint identifiers.
• shunt from="m:out" to="action-out" — represents a wiring between the superblock's Application Runtime Interface and the pin of a block. Shunts and wires are explained further in the Wiring Scheme section.

Properties

Properties typically represent configurable parameters of a block, superblock or Application. They are set when the Application is configured, and remain the same until the Application is re-configured.

Properties on Library Blocks

Several blocks in the ACS Block System library have properties. For example, the text-source block has

a property named Value that provides the text value for the blocks out pin.

When declaring instances of blocks in a breakdown, you also set the value for any properties the block may have.

Defining Your Own Properties

You can define properties for your own Applications and superblocks. This allows you to set any necessary configuration parameters in a single place, and then re-use them wherever needed in the rest of the superblock or Application.

The Main Superblock Example's hellotext provides an example of a property set this way.

...
<block id="ts" ref="urn:touchatag:block:text-source">
                    <property name="Value"><delegate as="Message"/></property>
                </block>
...

Delegated Properties

Rather than explicitly assigning a value to a Property on a given Block, you can assign its value to be delegated from its parent block. This helps by moving important configuration parameters out of the breakdown to a top-level area so that changing their values is made much easier, especially if you need to use the same parameter in multiple constutient blocks.

The Main Superblock Example shows an example of this on the ts block's Value property:

...
<property name="Message"><text>Ta-dah!! Your tag has been read!</text></property>
...
<block id="ts" ref="urn:touchatag:block:text-source">
                    <property name="Value"><delegate as="Message"/></property>
                </block>
...

Property Naming

All properties are identified by a name. This name must be one or more alphanumeric characters, cannot begin with a number, and must be unique to the block in which it is declared. This can be described by the following regular expression:

[a-zA-Z][a-ZA-Z0-9]*

Or to be exact, it supports US-ASCII characters 0x30 -> 0x39; 0x41 -> 0x5A; 0x61 -> 0x7A.

Breakdown

The breakdown element of a superblock lists all blocks to be used in the Superblock's wiringscheme.

Each block instance is declared as a discrete XML element that references the block type (by it's unique identifier, or urn) and the id for the specific instance.

The breakdown shown in the Main Superblock Example show the declaration of two instances of different block types:

...
<breakdown>
                <block id="ts" ref="urn:touchatag:block:text-source">
                    <property name="Value"><delegate as="Message"/></property>
                </block>
                <block id="m" ref="urn:touchatag:block:message"/>     
            </breakdown>
...

Block Identifiers

Each instance of a block declared in the breakdown must have an id that uniquely identifies the instance for use in other parts of the specification.

The general notation is as follows:

namespace:identifier#shorthand

• namespace: Optional namespace which has the format urn:part1:...:partN. This can be used to scope your identifier.
• identifier: the actual identifier for the block (within the specified namespace)
• shorthand: An optional shorthand for the block identified by namespace:identifier

There is a special character, *, that can take the place of the namespace:identifier to indicate that the identifier is not really important and that it may be autogenerated. It will depend on context whether or not this autogenerated id is allowed. Also note that it is allowed to write #shorthand which will actually imply the *, so the normalized form of #shorthand is actually *#shorthand.

There is also a specially reserved namespace urn:touchatag:block, which is used to identify the touchatag block library. All references to touchatag blocks require this namespace.

Wiring Scheme

The Specification's Wiring Scheme defines the execution flow for the ACS Block System to follow in the execution of an Application (or superblock).

To create the functionality you desire your Application to have, you wire the pins of individual blocks together. This requires you to understand some basic concepts, including Spreading Activation, Pin Endpoint identifiers, and Wires and Shunts. Other important concepts include the Application Runtime Interface, options for Starting the Execution Flow, Splitting the Execution Flow, and Using Conditions.

Spreading Activation

The execution flow of the ACS Block System uses a technique based on Spreading Activation. It starts with one or more active pins providing input to one or more blocks. Each block's out pins become active only after all of the block's in pins have been activated. So for the execution of an application to complete, each subsequent block in the flow must receive data on all of its in pins, ultimately concluding by activating the action-out runtime interface.

If you do not supply a value to one of the pins of a block, the missing input will halt the execution flow of your application. For example, the http-request-builder block has six in pins (httpmethod-in, uri-in, params-in, credentials-in, mimetype-in, content-in). Until all six pins are activated, the block's out pin will not activate.

Note A superblock can contain multiple independent execution pathways, and thus may not necessarily require all its in pins to be activated before one or more of its out pins become active. This allows a superblock to accept criteria, apply conditions, and then activate only the appropriate out pin.

Pin Endpoint Identifiers

Pin Endpoint identifiers provide you a way to uniquely reference each pin of each block declared in the breakdown, as well as any pins into or out of the superblock parent. The general notation is as follows:

blockid:pinname

• blockid — is the id of the block to which the pin belongs.
• pinname — is the name of the pin.

When referencing the pin of a block declared in the breakdown, you must identify the block by its assigned id.

When referencing a pin that interfaces into or out of the parent superblock (such as one of the Application Runtime Interface pins of an Application's main superblock), you use the pin name only (without any blockid).

Wires & Shunts

As previously noted, all pins have a direction of either in or out. Each pin also has a type that defines what kind of data that it requires (if the pin's direction is in) or provides (if the pin's direction is out). To connect two pins, they must be of the same type. There are two types of wiring connections: wires and shunts.

Wires

A simple connection between the pins of two different blocks is called a wire. A wire always connects from the out pin of one block to the in pin of another, as was shown above in the Main Superblock example:

...
<wire from="ts:out" to="m:in"/>
...

Shunts

As explained above, Application blocks and Superblocks are assemblies of other blocks wired together to provide some kind of aggregate functionality. Because Applications and Superblocks function as aggregating constructs—that is, they use abstraction to simplify whatever internal complexity they contain—Applications and Superblocks have their own input and output pins.

When wiring a pin from one of these aggregating constructs to the pin of one of the blocks it contains, both pins will have the same direction. This requires you to use a shunt instead of a wire.

For example, the main superblock of an Applications always has a standard set of pins called the Application Runtime Interface. One of the pins, the action-out pin, is an out pin because it outputs the Application's action back to the client. However, to send out an action on the action-out pin, we must connect an internal block's out pin to the action-out pin. That's connects an out to an out. Therefore, we use a shunt, as we saw in the Main Superblock example:

...
<shunt from="m:out" to="action-out"/>
...

Note Notice that the Pin Endpoint identifier for the to attribute does not have a blockid? This indicates that the pin is part of the aggregating construct, which always requires a shunt.

Tees

Tee'ing is a practise where you connect more then one wire from or to one in or out pin.

    <wire from="ts:out" to="m1:in" />
	<wire from="ts:out" to="m2:in" />

Here we have two wires both from the same output-pin to two different input-pins. This can increase the re-use of certain blocks.

WARNING: We recommend only to use divergating tees (from one out-pin to multiple in-pins). Convergating tees (from multiple out-pins to one in-pin) will result in unpredictable behaviour due to the nature of the spreading activation model. Convergating tees should only be used with conditional wires to make sure only one of the wires will be activated.

Application Runtime Interface

Application blocks provide a set of predefined runtime interfaces that are implemented as in and out pins on the Application's main superblock.

You always use a shunt to connect any pins belonging to the Application Runtime Interface.

in Pins

These in-bound pins can provide initial contextual information at runtime that can be used by the Application as conditions for making logical decisions.

• client-user-in — provides the username configured on the touchatag client that invoked the Application.
• command-id-in — provides the id of the specific command that triggered the application (from the application section of the Specification).
• configuration-id-in — provides the unique id of the specific configuration of the Application that was invoked. (Each time you make a specific configuration of an application through the touchatag dashboard, that instance of the application is assigned a unique id. One possible use for this is to determine whether the Application was invoked from the original configuration, or a derivative that a user configured from your shared original.)
• tag-event-type-in — provides the type of Tag Event that triggered the application. The currently supported types of reader event are:
  • PUT — indicates that the tag has been placed on the reader, and has remained on the reader for more than 1.5 seconds.
  • REMOVE — indicates that the tag has been removed from the reader on which it had previously been PUT.
    • Note Use of the REMOVE event requires you to declare which event model to use for the Application. See "Event Model" for more information.
  • TOUCH — indicates that the tag has been briefly seen by the reader and is no longer on the reader.

Note Using the Application Runtime Interface's in-bound pins in your Wiring Scheme is optional. They can be ignored if your Application does not require any of the dynamic information that they provide.

out Pin

Currently, there is only one out-bound pin, which sends an action back to the initiating client system. Every application must result in an Action. This action is identified on the Superblock's action-out pin:

• action-out — assigns the action for the touchatag client to execute. (You must wire this output pin an internal block's action output. If you do not want the client to perform any action, there is a no-action block.)

Starting the Execution Flow

There are two sources of initial input data to start your application's workflow: the Application Runtime Interface in pins, and the self-activating out pins of certain blocks in the ACS Block System catalog.

A set of starting pins for the execution flow are provided by the Application Runtime Interfaces. The ACS activates these pins each time it invokes the Application. These are described in detail in the section "Application Runtime Interface".

You do not need to use any of the Application Runtime Interface in pins in order for your application to work. Certain blocks have out pins that are self-activating (for example, that of the text-source block). You can use one or more of these self-activating pins to trigger the Application's execution flow rather than (or in addition to) one of the Application Runtime Interface pins.

Splitting the Execution Flow

Spreading Activation does not restrict your execution flow to a single path from start to the finish. You can define several paths that run independently. This allows you to perform tasks actions such as logging events to a web server without adding latency (or any interuption) to the path that actually concludes with action sent back to the invoking client on the Application's action-out pin. There are two ways to split the execution flow in your application: initiate the flow using parallel paths, or split into parallel paths after execution flow has already started.

To start two or more independent paths of execution flow, simply start each path using a pin that will be automatically activated at runtime. This could be one of the in pins from the Application Runtime Interface, or the self-activating out pin of certain out-only blocks.

You can also split a single initial path into multiple parallel paths. To do so, connect an output pin more than once in your wiring scheme. For example, if you wanted to split the output from the out pin of a block id=ts to the in pins of two different blocks (id=m1 and id=m2), your wiring scheme would look like this:

    <wire from="ts:out" to="m1:in" />
    <wire from="ts:out" to="m2:in" />

In this example, when the pin ts:out gets activated, it will activate both m1:in and m2:in, allowing you to manage two separate execution pathways, one starting at block m1, the other at block m2. The Specification "Conditional Wires Example" shows this by shunting the command-id-in twice.

Using Conditions

You can use conditional logic to prevent a specific path of the execution flow from continuing.

As previously stated, all of a block's in pins must be activated before any of its out pins become active. By putting a condition attribute on a wire or shunt, you enable or disable based on the value of any pin that outputs a boolean value. This requires you to use the pin's proper Pin Endpoint Identifier with the condition:

    <wire from="ts:out" to="m1:in" condition="b:out" />

In the above example, the ts block's out pin wires to the in pin of the m1 block. The condition is set to the b block's out pin. So if the value of the b block's out pin is true, the wire works. If its value is false, then the wire does not work and the m1 block's pin never activates.

The Specification "Conditional Wires Example" shows two conditional wires, based on whether command-id-in matches a specific value.

Shunt the action-out Pin

The action-out pin part of the Application Runtime Interface is responsible for completing the transaction with with the invoking client system. If the invoking client system does not receive a final response from the ACS, it will report an error. Therefore, every Application's main superblock must conclude its execution flow by shunting the action-out pin with an action.

Various blocks can output an action, such as opening a web link or displaying a system tray message. However, if you do not want the invoking client system to perform any visible action, use the (including No Action) block.

Note An Application can output the action-out only once per tag transaction.

Event Model

Touchatag originally supported only two types of reader event: PUT and TOUCH. To use new event types, such as the REMOVE event, you must declare in your Specification the event model you wish to use for your application. Two models are currently supported.

• PUT_TOUCH — is the default for all applications that do not explicitly declare an event model. (This ensures backward compatability for all Applications.
• PUT_TOUCH_REMOVE — specifies that support for the REMOVE is required.

Implementation

You specify the event model in the application element of the Specification:

    <application eventModel="PUT_TOUCH_REMOVE">

The Specification example "TagEventTypes: TOUCH, PUT, REMOVE" shows how to implement for each of the three available event types.

Resource Identifiers

These placeholder values represent resource values within a running application. When a resource identifier is used, it will be replaced by it's runtime value when the application is triggered. You can check the Resource Identifier Blocks Example to see resource identifiers in action.

Following resource identifiers are currently supported:

• &touchatag.tag.id; - The tag's id. This is not guaranteed to be a unique.
• &touchatag.tag.hash; - A hash made of several attributes of the tag, this value is guaranteed to be unique.
• &touchatag.reader.id; - The reader's physical id. This is not guaranteed to be a unique.
• &touchatag.reader.hash; - A hash made of several attributes of the reader, this value is guaranteed to be unique.
• &touchatag.client.name; - The name of the touchatag software client from which the tag event occurred. You can set the name of a touchatag client in its options menu.

Note Touchatag strongly advises developers to use hash values rather than plain id values. Differences between manufacturers of various tags and readers can result in duplicate id values. Hash values are guaranteed unique.

Following blocks support or provide resource identifier replacement:

• resource-identifier-source
• text-resource-identifier-replacer
• resource-identifier-source
• text2textmap-resource-identifier-replacer
• textlist-resource-identifier-replacer
• uri-resource-identifier-replacer
• http-client
• http-client-app

Event Helper Block: tag-event-type-to-text

A special helper block called tag-event-type-to-text provides you a way to convert the native type of the tag-event-type-in runtime interface into a text data type.

Special Blocks

Certain blocks in the ACS Block System catalog perform special functions, such as storing data, or sending an e-mail, calling a web service, or ending an execution flow path.

Output-only Blocks

Certain blocks have only an out pin (no in pins). Such blocks typically output a value that was either supplied through a Property ("source" blocks), or was generated (e.g. random number or current time). The out pins of these blocks are always activated.

Input-only Blocks

Certain blocks only have an in pin. These "sink" blocks stop an execution flow from that block onwards.

Register Blocks

Register blocks, such as the integer-register, enable you to set a state between between several executions of an Application.

• Similar to an output-only block, the out of a Register block is self-activated — it does not require the block's in pin to be activated to provide the stored value.

You use the Register block's in pin to set the stored value.

XML Schema

The Specification document must adhere to the XML Schema for touchatag Specifications. The schema is available at http://www.touchatag.com/schema/configurator/specification-1.0.xsd.

We designed the Specification schema to maximize re-use and extensibility. The schema should aid in generating useful code through various XML binding frameworks that you may care to use.

Future Enhancements

The XML schema defines some elements that are not yet fully implemented in the touchatag ACS. These include:

• blueprint as the top-level element of a Specification document (rather than specification)
• interface element within the superblock element
• superblock elements within the breakdown element

Sample Code

Touchatag provides several example Specification documents to help you learn how to create Specifications. You can use many of them directly with little or no modification.

As a recommended starting point, the Message example provides a simple, easy-to-read Specification with explanatory annotations.

Troubleshooting

The following list provides a common set of things to check when your Specification does not work as expected:

• Have you validated your Specification against the XML schema?
• Are there any blocks that do not have their in pins wired or shunted?
• Does your wiring scheme conclude with a shunt to action-out?
• Does your wiring scheme include more than one action-out?