Configuration Tables

ThingWorx Model Definition in Composer > Modeling > Things > Configuration Tables

Configuration tables are used for Things, Thing Templates, Thing Shapes, Data Tables, streams, value streams, timers, schedulers,Industrial Thing Shapes, industrial gateways,mashup templates, projects, Thing Groups, notifications, blogs, wikis,gadgets,masters, and mashups to store values, such as 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. Configuration tables should not be used for storing dynamic data that gets updated frequently. This information is defined in a similar way to properties. To use configurations, 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.

Configuration table data is overwritten when importing by values stored in the file.

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 the supported entities, 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, describe 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 the entity has multiple configuration tables, you can control their position 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:

Configuration table definitions created by annotations do not appear in exported XML.

The following is an example of configuration table data exported as XML:

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 Add 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 Thing Template or Thing Shape level are propagated to Things that inherited the tables from their Thing Template or Thing Shape.

A new Thing entity inherits configuration data from its Data Shapes or Thing Template. However, after the Thing is created, it can no longer accept any data changes to the tables inherited from its Thing Template or Data 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 Thing Template and Data 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 does not inherit the change in data. ThingA keeps whatever data it has for configTable1. ThingA can also change the data on configTable1 and configTable2, and the change in data does not cascade to its Thing Template or Data Shape or other Things that have inherited this configuration table.

Was this helpful?