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.
Caution: All operations on the Repository must be performed through this API - rather than directly accessing the physical file - since the Repository's underlying file structure may change over time. This API is guaranteed to remain compatible with future versions of the Data Repository. It is used by all Workflow tasks dealing with the Repository.
Data repository structure
The table below lists the different levels in the repository and what their names corresponds to:
| The term ... | ... is the same as an Excel ... |
... is the same as a Database ... |
| Group | Sheet | Table |
| Key | Column | Field |
| KeySet | Row | Record |
Note: Group and key names are case-insensitive.
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. |
|
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. |
|
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. |
|
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. |
|
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". |