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");
Want content like this delivered to your inbox? Sign up for our newsletter!

Ryan Farley

Ryan Farley is the Director of Development for Customer FX and creator of He's been blogging regularly about SalesLogix, now Infor CRM, since 2001 and believes in sharing with the community. His new passion for CRM is Creatio, formerly bpm'online. He loves C#, Javascript, web development, open source, and Linux. He also loves his hobby as an amateur filmmaker.


  1. Hi Ryan,
    I recently discovered your articles and I find them very interesting and useful, thanks a lot. I’m texting you because I’m trying to read the value of a custom system setting in creatio from the client-side, but I noticed that even if my setting has the flag “Cached” it results undefined when I try to get the value using this code:
    var test = Terrasoft.SysSettings.cachedSettings.UsrSysSettingTest;
    while when I use the asynchronous way it works fine. Do you know why this is happening?

    Let me know.
    Thanks in advance,


    • Hi Luca,

      Cached system settings aren’t available at Terrasoft.SysSettings.cachedSettings until you’ve logged out and back in again. Once you log out and back in it should be available at Terrasoft.SysSettings.cachedSettings.


Submit a Comment

Your email address will not be published. Required fields are marked *