Data Repository API

The Data Repository is a permanent structure to store data that can then be reused, modified or augmented at a later time, by different processes.
The Data Repository can be accessed at runtime by the Push To Repository plugin and other tasks (see Data Repository) and at design time via the Data Repository Manager.
This topic explains how to access the Data Repository in script.

For a quick start, turn to this How-to: Interacting with the Data Repository API.

Data repository structure

The table below lists the different levels in the repository and what their names corresponds to:

T​​​he term ...​​​​	... ​is th​​e sa​​​me as an Excel ...	... is the s​​ame as a Database ...​​
Gr​oup	Sheet	Table
Key	Column	Field
KeySet	Row	Record

API Reference

Obtaining an instance of the Repository Object

The Data Repository is accessed via a COM object that exposes methods to store and retrieve data within the Repository.

JavaScript

var repoObject = new ActiveXObject("RepositoryLib.WorkflowRepository");

VB Script

set repoObject = CreateObject("RepositoryLib.WorkflowRepository")

In each example in this documentation, the object repoObject is deemed having been obtained through the above call to the COM object.

The default Repository is always stored at the same location (see Where to find the Data Repository).
The ConnectionString property allows to create an instance of the Repository at another location; see ConnectionString.

Using a JSON parameter or return value

Whenever a parameter or return value is defined as a JSONStringArray type, that JSON array is itself a string. Since a JSON array internally defines double quotes as the delimiter for each element, you must enclose the entire string in single quotes. Alternatively, you can escape the double quotes inside the JSON Array.

For instance, the following calls to AddGroup() are correct:

repoObject.AddGroup("MyGroup",'["FirstKey", "SecondKey"]');
repoObject.AddGroup("MyGroup","[\"FirstKey\", \"SecondKey\"]");

But the following is incorrect:

repoObject.AddGroup("MyGroup","['FirstKey', 'SecondKey']");

Many methods require using the JSONStringArray type but JSON is not natively supported in VB Script. Therefore, for those methods, only JavaScript sample code is provided. There are many resources on the Web that propose ways of implementing JSON parsing in VB Script so you can implement whichever you see fit. However, using JavaScript is highly recommended.

Repository management methods

Name	Description
CheckRepository	Verifies the integrity of the repository and recovers unused space left by deleted keysets. Similar to packing a database, the operation is non-destructive but it does require exclusive access to the Repository. You should therefore only perform this operation when you know for sure no other process is accessing the Data Repository.
ClearRepository	Deletes all groups, keys and keysets from the repository, returning it to a blank state. Use with caution!
ClearGroupData	Deletes all keysets inside GroupName while retaining the existing key structure.
ClearAllData	Delete all keysets in all groups, while retaining the existing key structure.
ConnectionString	Creates/opens a Repository to read from and write to at a custom location. Set ConnectionString to a string containing a full path and file name.
Version	Returns the version of the DLL library used by the Repository.

Group methods

Name	Description
AddGroup	Creates a group named GroupName and optionally creates keys listed in keyNames. The keyNames parameter may be empty.
ListGroups	Retrieves the list of all group names in the Repository, stored in a JSONStringArray..
RemoveGroup	Deletes the group named GroupName, along with all its keysets and keys.
RenameGroup	Renames group oldName to newName. While this operation has no impact on the data stored in the specified group, it does require any plugin and/or script that uses oldName to be modified to refer to newName.

Key Methods

Name	Description
AddKey	Adds key KeyName to group GroupName. KeyName must not already exist in the specified group. Note that this method only adds a key name to the group, not a key value. See AddValue() for information on how to set a value for a key.
ListKeys	Retrieves the list of all Key names and data types in Group GroupName, stored in a JSONStringObject. You should use JSON.Parse() to convert the string into an actual JavaScript object. You can then use the for…in construct to list the different properties for that object (i.e. the keys in the group).
RemoveKey	Removes existing key KeyName from group GroupName. The key to remove must exist in the group, otherwise an error is raised. All values for the key, in all keysets for the group, are removed. Note that when the Group contains a large number of KeySets, this operation may take a while.
RenameKey	Renames key oldName to newName in group GroupName. While this operation has no impact on the data stored in that Group, it does require any plugin and/or script that uses oldName to be modified to refer to newName.

Value Methods

Name	Description
AddValue	Creates a new KeySet by assigning Value to the key KeyName in Group GroupName. Note that KeyName must exist in GroupName, otherwise an error is raised. See AddKey() for information on adding a key to a group. Upon successful completion, the method returns the ID of the newly created KeySet.
GetValue	Performs a lookup in group GroupName and retrieves the first value for key KeyName that matches Condition. The condition is specified using basic SQL WHERE syntax. The Condition may be left empty in which case the very first value found for the specified KeyName is returned.
SetValue	Updates multiple keysets in group GroupName by setting the key KeyName to Value for all keysets that match Condition. The condition is specified using basic SQL WHERE syntax. The Condition may be left empty in which case all keysets in GroupName are updated. Note that KeyName must exist in GroupName, otherwise an error is raised. The method returns an array of the keyset ID's that were updated ( [1,2] ), or an empty array ( [] ) if no keysets were updated.
SetValueByID	Updates KeyName with Value in group GroupName, where the keyset's ID matches the ID parameter. KeyName must exist in GroupName, otherwise an error is raised. The method returns the ID of the keyset that was updated or -1 if the keyset was not updated. Note that this method is functionally equivalent to using SetValue() with its Condition parameter set to "ID=ID".

KeySet methods

Name	Description
AddKeySets	Inserts a new keyset inside GroupName and assigns values to keys as specified in KeyValues. Every key specified in KeyValues must exist otherwise an error is raised. However, it is not required to specify all available keys in KeyValues. Only the keys specified are updated in GroupName while unspecified keys are set to an empty string.
GetKeySets	Retrieves Keys values in GroupName for keysets that match Condition. When an asterisk * is passed as the Keys parameter, all keys are retrieved. When Condition is left empty, all keysets are retrieved.
RemoveKeySets	Deletes all keysets in GroupName that match Condition. The condition is specified using basic SQL WHERE syntax. Condition may be left empty, in which case all keysets in GroupName are deleted. The method returns the number of keysets that were deleted.
RemoveKeySetByID	Deletes the keyset whose ID equals ID from GroupName. Returns 1 if successful, 0 otherwise. Note that this method is functionally equivalent to using RemoveKeySets() with its Condition parameter set to "ID=ID".