ValueStore

The ValueStore can attach additional data to any DMS object. However, these are not searchable through filters but can be retrieved, modified, or deleted via the ValueStore API using their name.

In essence, anything in DMS can be used as an object. This includes documents, files, folders, users, groups, processes, search profiles, etc. The ID must be known, either in the GUID format of the internal Int64 ID or the LegacyGuid.

To set or delete values for an object, the user needs at least write access to the object.

Important: It is strongly recommended that the names for the values follow this schema: “..”. This helps avoid conflicts.

CRUD

Setting Values

object value = "an example";
Guid objectId = ...; // ID of the object to which the value should be set 
await dms.ValueStore.SetValue(objectId, "name-of-the-value", value);

The value is converted into a JSON string using NewtonSoft.Json before being transferred to the DMS server. The ValueStore can actually only store strings. If null is passed as a value, the method dms.ValueStore.DeleteValue(objectId, “name-of-the-value”) is called internally, and the value is deleted.

If the object already has a value with the specified name, it will be overwritten. The last access wins in this case.

Reading a Value

var value = await dms.ValueStore.GetValue<string>(objectId, "name-of-the-value");

The generic type specification is necessary because the value stored internally as a JSON string must be converted back to the actual type.

Deleting a Value

await dms.ValueStore.DeleteValue(objectId, "name-of-the-value");

If a value with the specified name exists, it will be deleted.

Query All Names for an Object

string[] valueNames = await dms.ValueStore.GetKeys(objectId);

From DMS 7.6.302

An overload of this method accepts a list of object IDs and returns a dictionary as a result. The key of the result is the object ID for which names were found. The value contains a string array with the names.

var objectIds = new [] { guid1, guid2 };
Dictionary<Guid, string[]> objectNames = await dms.ValueStore.GetKeys(objectIds);

No exceptions are thrown in case of problems. If you don't have access to a document or it doesn't exist, it simply won't be included in the result. The result only contains entries for objects that are readable by the user and also contain values for the ValueStore.

Error Handling

Any of the above calls (except for GetKeys(ids)) can cause errors. In this case, a ValueStoreException is thrown.

class ValueStoreException : Exception {
    public Guid ObjectId { get; }
    public string Key { get; }
    public ValueStoreResponses Result { get; }
}

The exception thus contains the object (the ID), as well as possibly the name of the value (Key). In the case of GetKeys, there is no unique key.

Additionally, the reason for the error is specified:

enum ValueStoreResponses {
    Success,
    KeyNotFound,
    ObjectNotFound,
    InsufficentAccessRights
}

Ab DMS 8.6.1

This method takes a list of object IDs and a name, and returns a dictionary as a result. A dictionary entry contains the object ID for which the name “keyName” was found and its value.

var objectIds = new [] { guid1, guid2 };
Dictionary<Guid, string> resultDictionary = await dms.ValueStore.GetValues(objectIds, keyName);

Another method takes a dictionary and returns a dictionary as a result.

The dictionary key of the input is the object ID, and the value of the dictionary entry is an object list of type ‘KeyValue’ (KeyValue[]). In the request, only the key in the KeyValue list is filled with the name to be queried; the value is null here. In the result dictionary, the values for each keyName are filled with the appropriate value.

var objKeyValues = new Dictionary<Guid, KeyValue[]>();  
foreach (var objectId in objectIds)  
{  
    objKeyValues[objectId] = new[] { new KeyValue { Key = keyName } }; // Multiple keyNames can be queried for an objectId.
}    

Dictionary<Guid, KeyValue[]> result = await GetKeyValuePairList(objKeyValues);

public class KeyValue  
{  
    public string Key { get; set; }  
    public string Value { get; set; }  
}