Retrieving and Setting System Settings in Client-Side and Server-Side Code in Creatio (formerly bpm’online)

The System Settings area in bpm’online is an extremely useful place to store your settings or things you’d like to give the user the ability to change in bpm’online. For example, in my last post I outlined how to make opportunity list rows green if the amount was greater than $3000, you could have that amount value be a system setting instead of hard-coding 3000. This way, an admin could tweak that easily without code changes. Let’s take a look at how to read those system settings from your code.

Reading System Settings from Client-Side Code

To read a system setting from client-side code we’ll use Terrasoft.SysSettings. This is a global object that does not need any mixins or imports into your code.

Terrasoft.SysSettings.querySysSettingsItem("UsrMyCustomSetting", function(myCustomSetting) {
    // do something
    console.log("UsrMyCustomSetting is: " + myCustomSetting);
}, this);

Realize that you’re getting the setting back in a callback. This is asynchronous. Something to keep in mind. Additionally, the type of the value given back will be based on the type of the setting. You’ll get back an int, string, Id/guid, datetime, etc to match what type your system setting is. This means, if your setting is a lookup type, the value returned will have be an object with a value and displayValue property.

Note, if your setting has the “cached” checkbox checked you can also read it directly from the Terrasoft object. Cached settings are loaded when the user logs in and available from here:

var myCustomSetting = Terrasoft.SysSettings.cachedSettings.UsrMyCustomSetting;

Reading System Settings from Server-Side C# Code

To read a System Setting from C# code, we’ll need a reference to the UserConnection. How you get that UserConnection can differ if we’re in a process or a configuration service. Note, this takes three parameters. First is the UserConnection, second the name (code) of the system setting you want to retrieve, and the third parameter is the default value to return in the case of something like the setting missing, etc.

From a Script Task in a Process

var settingName = "UsrMyCustomSetting";
var settingVal = Terrasoft.Core.Configuration.SysSettings.GetValue<string>(UserConnection, settingName, "");

From a configuration service

var settingName = "UsrMyCustomSetting";
var appConnection = HttpContext.Current.Application["AppConnection"] as AppConnection;
var settingVal = Terrasoft.Core.Configuration.SysSettings.GetValue<string>(appConnection.SystemUserConnection, settingName);

You will notice in the code above that GetValue takes a generic type to return the value in a specific type. Simply using GetValue, with no specification of type, will just return an object. However, you can specify the type to get back string settings as strings, int settings as ints, etc.

Setting a System Setting from Client-Side Code

Writing back a value to the System Setting is equally as easy. Here’s a sample in client-side code:

var postData = {
  sysSettingsValues: {
    "UsrMyCustomSetting": "My Value"
  }
};

Terrasoft.SysSettings.postSysSettingsValues(postData, function() {
  // callback when done
}, this);

Per-User Settings

You can also set it as a per-user setting using the isPersonal value in the post data. For example:

var postData = {
  sysSettingsValues: {
    "UsrMyCustomSetting": "My Value"
  },
  isPersonal: true  //note: this is a per-user personal setting value for the current user only
};

Terrasoft.SysSettings.postSysSettingsValues(postData, function(result) {
  if (result.success) { }
  // callback when done
}, this);

Setting a System Settings from Server-Side C# Code

To set a System Setting from C# code, we just need to call the following, passing a UserConnection, the setting name (code) and the value to set:

var settingName = "UsrMyCustomSetting";
Terrasoft.Core.Configuration.SysSettings.SetValue(UserConnection, settingName, "some value");