ThingWorx Model Definition and Composer > Configuration Tables
  
Configuration Tables
Configuration tables are used for Things, Thing Templates, Thing Shapes, and Mashups to store values, like property values that do not change often. The most common use of configuration tables is to store credentials and host information for an external resource. This information is defined in a similar way to properties. To use configurations, you define a configuration table with a name and description and indicate if it can store multiple rows. Similar to properties, some configuration values have aspects associated with them.
You can define a configuration table using one of the following:
Composer user interface
Java annotations
XML import/export
REST API
Defining a Configuration Table in Composer
On a thing, thing template, thing shape, or mashup, you can define a configuration table by doing the following:
1. Choose More > Add Configuration Table.
The Add Configuration Table screen appears.
2. Enter a name for the configuration table.
Names are case-sensitive.
3. In the Description field, you can add text that describes the purpose or functionality of the configuration table.
4. Select a data shape for the configuration table.
The chosen data shape must have a primary key field.
5. If you want the configuration table to display more than one row of data, select the Allow Multiple Rows checkbox.
6. If there are multiple configuration tables on this thing, thing template, thing shape, or mashup, you can control the position of them by entering a number in the Ordinal field.
The position cannot be changed after the configuration table has been added.
7. Click Done.
The configuration table appears on the Configuration page.
8. To delete a configuration table, click the Delete button.
Defining a Configuration Table by Adding Annotations on Java Classes
You can create configuration tables by adding annotations on Java classes. For more information, see the ThingWorx Platform API documentation for com.thingworx.metadata.annotations.ThingworxConfigurationTableDefinition.
For example, the following code snippet shows the configuration table definitions located above the class definition:
@ThingworxConfigurationTableDefinitions(tables = {
@ThingworxConfigurationTableDefinition(
name="ConfigTableExample1",
description="Example 1 config table", isMultiRow=false,
dataShape = @ThingworxDataShapeDefinition( fields = {
@ThingworxFieldDefinition(name="field1",
description="",baseType="STRING"),
@ThingworxFieldDefinition(name="field2",
description="",baseType="NUMBER"),
@ThingworxFieldDefinition(name="field3",
description="",baseType="BOOLEAN"),
@ThingworxFieldDefinition(name="field4",
description="",baseType="USERNAME"),
} ) ),
@ThingworxConfigurationTableDefinition(
name="ConfigTableExample2",
description="Example 2 config table", isMultiRow=true,
dataShape = @ThingworxDataShapeDefinition( fields = {
@ThingworxFieldDefinition(name="columnA",
description="",baseType="STRING"),
@ThingworxFieldDefinition(name="columnB",
description="",baseType="NUMBER"),
@ThingworxFieldDefinition(name="columnC",
description="",baseType="BOOLEAN"),
@ThingworxFieldDefinition(name="columnD",
description="",baseType="USERNAME"),
} ) )
})
public class GoodByeThing extends Thing {
}
Defining a Configuration Table through XML Import/Export
You can also define configuration tables on things, thing templates, thing shapes, and mashups through XML imports. The following example is a configuration table definition for an entity exported as XML:
<ConfigurationTableDefinitions>
<ConfigurationTableDefinition category="TemplateConfigTables"
dataShapeName="MyDS" description="Template Config Table" isHidden="false"
isMultiRow="true" name="ConfigTableOnTemplate" ordinal="2" source="REST"/>
</ConfigurationTableDefinitions>
* 
Configuration table definitions created by annotations do not appear in exported XML.
The following is an example of configuration table data exported as XML:
<ConfigurationTables>
<ConfigurationTable description="Template Config Table"
isMultiRow="true" name="ConfigTableOnTemplate" ordinal="2">
<DataShape>
<FieldDefinitions>
<FieldDefinition aspect.isPrimaryKey="true" aspect.tagType="ModelTags" baseType="STRING" description="" name="p1" ordinal="1"/>
<FieldDefinition aspect.isPrimaryKey="true" aspect.tagType="ModelTags" baseType="STRING" description="" name="p2" ordinal="2"/>
<FieldDefinition aspect.isPrimaryKey="true" aspect.tagType="ModelTags" baseType="STRING" description="" name="p3" ordinal="3"/>
</FieldDefinitions>
</DataShape>
<Rows>
<Row>
<p1>
<![CDATA[1]]>
</p1>
<p2>
<![CDATA[2]]>
</p2>
<p3>
<![CDATA[3]]>
</p3>
</Row>
</Rows>
</ConfigurationTable>
</ConfigurationTables>
Defining a Configuration Table for Things and Mashups Using the REST API
You can add configuration tables to things and mashups using REST API services. Every configuration table is associated with a data shape. The data shape for a multi-row configuration table must have a primary key. Once the configuration table is saved, its data shape cannot be changed; however, you can make changes on the data shape fields. You can add or delete a field from the data shape or change a field’s base type. Changing the base type could impact the data on the configuration table. For example, changing a string base type to integer could result in the loss of configuration table data.
The following image shows a configuration table definition using services on a thing in ThingWorx Composer:
The configuration table created above appears under the Configuration page for the thing in ThingWorx Composer as follows:
To add data to the configuration table, open the entity in edit mode and select the Add button next to the configuration table name.
Defining a Configuration Table for Thing Templates and Thing Shapes Using the REST API
To add configuration tables to thing templates and thing shapes, you can write a service on a thing that invokes the AddConfigurationTableDefinition REST API on the thing template. Below is an example of a user-defined service (AddConfigTableToTemplate) that adds a configuration table to a thing template (MyThingTemplate). Similarly, you can write a service to add a configuration table to a thing shape.
You can add data to the configuration table from ThingWorx Composer or with a service like the following:
Configuration Table and Configuration Data Inheritance
Configuration tables and their data that are created on thing template and thing shape entities are inherited by implementing a thing entity. Any definition changes made to the configuration tables at the template or shape level are reflected on things that inherited the tables from their template or shape.
A new thing entity will inherit configuration data from its shapes or template. However, after the thing is created, it will not take later data changes to its inherited tables from its template or shapes.
For example:
ThingTemplateA has configTable1
ThingShapeA has configTable2
ThingA is created, which is based on ThingTemplateA and implements ThingShapeA.
ThingA will inherit configTable1 and configTable2 with data from its template and shape respectively.
If ThingTemplateA changes configTable1 from singleRow to multiRow, then ThingA will reflect that change.
But if ThingTemplateA changes the data in configTable1, then ThingA will not inherit the change in data. ThingA will keep whatever data it has for configTable1. ThingA can also change the data on configTable1 and configTable2 and the change in data will not cascade to its template or shape or other things which have inherited this configuration table.