Common Data

Common Data is a custom data storage facility that may be used by various LinkServer components and plugins to perform specific operations, such as data replication, data sharing and configuration management.

The Common Data container is like a database, built of tables, supporting the following operations:

Every Common Data container is represented by a Common Data context. There are two types of containers:

There is just one Global Container in LinkServer. Its path is simply common. It's usually used to store data that should be accessible by all users or Data Terminals in the system (see examples below).

User Containers are owned by LinkServer users. Every uses has his own Common Data context with a path like users.USER_NAME.common. A user can use his Common Data Container to store data that should be shared between his Data Terminals or Groups, such as a logo file that all Devices should display. See Uses of Common Data for details.

In this case, common tables are created by the system administrator manually, from scratch, to contain some custom data that is not automatically generated or used by LinkServer components. This can be, for example, an inventory of equipment belonging to the company. This table may contain the description and location of each piece of equipment, person responsible to it etc. The administrator could allow users to view or edit it. It can be later referred from different parts of the system. For example, you could create a query showing how many pieces of equipment are under the responsibility of every system user.

In this case, the common table contains a "master value" for a certain property of all group members. The group monitors the common table for changes, and when changes are detected, the group rewrites a certain property for all group members according to the contents of the common table. This is easy, because the various property values of a context are represented by a Data Table, just like the common table.

In this scenario, the common table isn't created from scratch by adding fields and records. Rather, it has to be created using the "Create New Table from Variable" action, which takes the value of a user-specified context variable and creates a new common table with the same format and contents.

The common table's Format must match (or extend) the format of the property whose whose master value it contains. So it must contain all fields defined for that property, but may also contain additional fields. The common table's name must be be the same as the name of the linked property -- this allows the group to find this common table and propose it to be used.

Like in the previous scenario, the common table contains a "master value" for a certain property of several Data Terminals. LinkServer monitors changes in the common table and when these changes are detected it takes the "master" common table and copies it to several Data Terminals.

Just like in the "Integration With Groups" use case, the common table is created based on the value of a context variable, but here we're using a Data Terminal context variable. Same rules apply to the name and format of common table.

For example, let's say our Devices have a "Checklist Table" setting, containing a list of things that should be checked by the Device operator after device startup. This Checklist Table should be same (or almost the same) for all Devices in the facility. Thus, we can create a Common Table that will contain "master" Checklist Table.

The creation process is quite simple. Note that this is a hypothetical example -- you might not have Devices with this exact setting. It's here just to give you a general idea of what the process looks like. This is how you would do it in AggreGate Client, had you had Devices with such a table:

1. Drag any Device node () in System Tree and drop it on the Global Common Data node ().

2. Select Checklist Table from the drop down list:

ls_common_data_checklist_1

3. A new Common Table will be created and shown in the System Tree:

ls_common_data_checklist_2

4. Now, a new master Checklist Table will be written to all Devices. You could open the settings of any Device and see that its Checklist Table setting is not editable anymore. Instead, a button fills the row, with a label saying "Using common data table":

ls_common_data_checklist_3

5. You can click this button to see what data was written from Common Table to the Device:

ls_common_data_checklist_4

If it is necessary to exclude particular checklist items from some Devices, see the Record Permissions section to figure out how to do this.

Every common table is actually a single Data Table. Its format is specified by its fields property, and can be changed using "Edit Properties" action. The number of records is limited by the minimum and maximum values defined in the Table Info property. Records in the table can be reordered.

When the table format (field format, to be precise) are changed while the table already contains some data, LinkServer does its best to preserve existing data and convert it to the new format. In most cases data in the table is not changed. For example, if an Integer field was converted to String, values in this fields are converted to strings. But if a String field was converted to Integer, not every string value of field may be converted to integer number and some data may be lost. This is why you should avoid changing table structure if it contains important data.

The only exception to the above rule is field renaming. Field renaming is supported only it the table is empty (doesn't contain any data).

The common table's contents is stored in LinkServer database along with all other context properties.

The data contained in the common table can be viewed and edited using the Edit Data action.

When changes are made to the format or contents of a table, they're detected by other system components. For details, see Uses of Common Data (specifically, Integration with Groups and Integration with Data Terminals).

Two types of contexts are used to administer common data (and the tables containing it): one is the Common Data context, which serves as a container for several common tables. The other is the Common Data Table context, which holds the information for one common table.

There are actually two Common Data containers. Global Common Data shared among all the users and User Common Data specific to the particular user account.

ls_common_data

Field Description	Field Name
Table Name. Name of the common table context. It should conform to context naming conventions. This name is used to refer to this table from other parts of the system. Once the table is created, its name may not be changed.	name
Table Description. Textual description of the table. This is also a description of the Common Table context.	description
Minimal number of records.	minRecords
Maximal number of records.	maxRecords
Enable per-record permissions. Per-record permissions let you control which contexts access each and every record in the table (as opposed to controlling access to the whole table).	recordPermissions

Field Description	Field Name
Name. Unique name of the field.	name
Type. One of the types supported by the Data Table Record Format.	type
Description. Textual description of the field.	description
Default. Default value of the field.	default
Read-only.	readonly
Nullable. Indicates the field may contain NULL ("Not Set") values.	nullable
Key. Indicates that field is a key field.	key
Selection Values. List of possible values for this field.	selvals
Extendable Selection Values. Indicates that the field may contain values that are not listed in Selection Values.	extselvals
Help. Additional info about the field.	help
Editor/Viewer. Defines how the value of the field is edited. For example, Data Block fields may be edited using Image Editor, Sound Editor of generic File Editor.	editor

More info about field properties can be found here. These may be accessed via the fields variable.

There is a method to associate a set of permissions with every record in the common table. This feature is called "Per-record permissions" is may be enabled or disabled for a particular table by editing basic properties of a table.

Record permissions define which LinkServer contexts have access to this record. This feature is used in Integration with Groups and Integration with Data Terminals (See Uses of Common Data). When a group or Data Terminal context retrieves the contents of a common table, it only gets records to which it has permissions.

Example:

Let's say that the common table contains a checklist of actions to be performed with certain hardware devices on startup. This list is written to every device using the Integration with Data Terminals feature, causing the device's operator to complete all checkup items during device startup. Obviously, not all device types need the same items in the checklist. Sure, most of them may need an item such as "Swipe your ID card" (for a vehicle control system), but only some would need an item such as "Verify there are no leaks in hydraulics system". In a scenario like this, per-record permissions come in handy.

For every record in the this hypothetical Checklist table, we may specify a list of Devices (Device contexts, to be precise) to which it applies. We can even specify them as groups (see below). A given checkup item (record) will be written only to the Devices which are allowed to access it per this table.

Common table per-record permissions differ from user permission tables. A user's permissions define which contexts he may access, and which operations he may execute in every such context. In contrast, common table record permissions define which contexts may access a given record. Currently, this is only useful in the following scenarios:

For Integration with Groups, the permission list may contain only Group contexts. Only groups specified in the list will write this record for their members.

For Integration with Data Terminals, the permission list may contain Data Terminal contexts and Group contexts of Data Terminal groups. In the former case, the record will be accessible by a certain Data Terminal. In the latter case, it will be accessible by all Data Terminals in a group.

If you're trying to keep a table secure, you'd better control who can edit the table itself -- don't just set per-record permissions.

When per-record permissions are enabled, every record in table contains two additional fields:

The Access to record field has three possible values: Enabled, Disabled and Determined by permissions. When access is Enabled, per-record permissions are switched off for this record, and every group or Data Terminal has access to it. When access is Disabled, no groups and Devices will receive this record when retrieving the table's contents. And when the field it set to Determined by permissions, you can set a list of groups or Devices which will have access to this record. If a user is allowed to edit the table itself, he may modify per-record permissions.

When the Integration with Devices feature is used to work with a common table, the permission list may contain not only ordinary Data Terminal contexts, but also Data Terminal groups . When a Data Terminal group is added to the permissions list of a specific common table record, all of its members will have access to this record.