Jan 092014

Colectica Repository and Portal have many settings that can be adjusted by the system administrator. These include settings such as language sort orders, synonyms, item types to display, and appears within configuration. A developer creating Colectica Addins recently asked how this API could be used for storing settings in custom extensions.

The Repository settings consist of a key associated with an optional string and long integer values. There are four web service calls that can interact with the Repository Settings store.

// Removes the repository setting.
void RemoveRepositorySetting(string settingName);

// Sets the repository setting.
void SetRepositorySetting(RepositorySetting setting);

// Gets the repository setting.
RepositorySetting GetRepositorySetting(string settingName);

// Gets all of the repository settings.
Collection<RepositorySetting> GetRepositorySettings();

The Repository Setting class looks like this

public class RepositorySetting
    public string SettingName { get; set; }
    public string Value { get; set; }
    public long? LongValue { get; set; }

Our built in settings use this key value store, normally with a json representation of our settings stored as the value. Here is an example of how we could store synonyms for DDI item types using the settings API.

// A key defined somewhere in the class
string SingularItemTypeNamesKey = "Colectica:Portal:SingularItemTypeNames";

// Add some synonyms
Dictionary<Guid,string> names = new Dictionary<Guid,string>();
names.Add(DdiItemType.DdiInstance, "Project");

// Create the repository setting to store
RepositorySetting setting = new RepositorySetting();
setting.SettingName = SingularItemTypeNamesKey;
setting.Value = JsonConvert.SerializeObject(names);

// Create the web services client and set the setting
WcfRepositoryClient client = GetClient();

Similarly, here is an example of how you could retrieve the singular synonyms.

// Create the web services client and retrieve the setting
WcfRepositoryClient client = GetClient();
var setting = service.GetRepositorySetting(SingularItemTypeNamesKey);

if (setting == null || setting.Value == null)
    return new Dictionary<Guid, string>();

// If the setting exists, serialize it
var results = JsonConvert.DeserializeObject<Dictionary<Guid, string>>(setting.Value);

Best Practices

Use a unique key name. We suggest a colon separated key in the form Organization:Product:Description. For example, MyOrg:MyCustomProject:MySettingName.

Store many settings using a single key. For example, if you are storing translations you could store all of your translations in one key with all the data stored in json or xml in the value. Our example used a dictionary. You could also use lists, a custom class, etc. This allows you to minimize the number of web service calls over the network.

Cache your settings once they are retrieved. If the settings will be used multiple times, cache them in your program so you do not have to call the web services repeatedly.