How Can I Programmatically Retrieve Or Set Custom Variables

How Can I Programmatically Retrieve Or Set Custom Variables


This article explains how you can retrieve or set custom variables on users, teams, plans within your workspace using simple API calls.

Retrieve Custom Variables
To retrieve custom variables, follow these 2 steps:
  • Step 1 - Get Your API key
  • Step 2 - Retrieve Custom Variables

Step 1 - Get Your API Key 
To obtain your API key:
  • Login to your workspace
  • On the left pane, click on "Account > My Profile"
  • Click on the "Security" tab (if needed)
  • Copy the API key
  • Note: you must be full admin in your workspace

Step 2 - Retrieve Custom Variables
To retrieve custom variables
      "[{"name":"X", "value":1.1, "startDate":"2020-01-01T00:00:00", "endDate":"2020-02-01T00:00:00"},
       {"name": "Y", "value":"2020-01-01T00:00:00", "startDate":"2020-01-01T00:00:00", "endDate":"2020-02-01T00:00:00"},
       {"name":"Z", "value":"hello", "startDate":"2020-01-01T00:00:00", "endDate":"2020-02-01T00:00:00"}]"

Note: you can also query custom variables via OData via the CustomVariable entity. The /GetCustomProperties endpoint is provided for convenience.

Set Custom Variables
To set (replace all) custom variables, follow these 2 steps:
  • Step 1 - Get Your API key
  • Step 2 - Submit Custom Variables

Step 1 - Get Your API Key 
Refer to the same steps above.

Step 2 - Submit Custom Variables
To set (replace all) custom variables
    • The ID can be that of a system user, team, plan
  • Set HTTP header X-ApiKey to your API key
  • POST a JSON array, such as:
  • "[{"name":"X", "value":1.1, "startDate":"2020-01-01T00:00:00", "endDate":"2020-02-01T00:00:00"},
  • {"name":"Y", "value":"2020-01-01T00:00:00", "startDate":"2020-01-01T00:00:00", "endDate":"2020-02-01T00:00:00"},
  • {"name":"Z", "value":"hello", "startDate":"2020-01-01T00:00:00", "endDate":"2020-02-01T00:00:00"}]" 

Sample Code
The following samples show how to make calls (using C#):

// Retrieve custom variables from a user
// Get the user ID from OData
Guid id = new Guid("7812068d-b46f-46a7-aa91-c517b692dee0");
WebClient webClient = new WebClient();
webClient.Headers.Add("X-ApiKey", apiKey);
string result = webClient.DownloadString(url, json);
JArray jArray = JArray.Parse(result);
foreach (JToken jToken in jArray)
{
     dynamic d = jToken;
     Console.WriteLine(d.name.Value);
     Console.WriteLine(d.value.Value);
     Console.WriteLine(d.startDate.Value);
     Console.WriteLine(d.endDate.Value);
}

// Set (replace all) custom variables on a user
// Get the user ID from OData
Guid id = new Guid("7812068d-b46f-46a7-aa91-c517b692dee0");
var customProperties = new[] { new { name = "X", value = "test", startDate = new DateTime(2020, 01, 01), endDate =  new DateTime(2020, 02, 01) }, new { name = "Y", value = "#2020-06-01#", startDate = new DateTime(2020, 01, 01), endDate =  new DateTime(2020, 02, 01) }};
string json = JsonConvert.SerializeObject(customProperties);
WebClient webClient = new WebClient();
webClient.Headers.Add("X-ApiKey", apiKey);
string result = webClient.UpoadString(url, json);

Set Means Replace
When setting custom variables, all existing custom variables will be replaced. To add one custom variable, first retrieve all custom variables, add yours to the list, and set them all.

Getting IDs
To retrieve user, team, plan IDs, you can make OData API calls. User, team, plan IDs must be valid within your workspace.

To visually explore the API:
  • Login to your workspace
  • On the left pane, click on "Settings > Connections > OData API"
  • Alternatively, you can connect using a BI tool such as Microsoft Power BI to view entities


    • Related Articles

    • How Can I Programmatically Create Or Update Teams?

      This article explains how you can create or update teams using simple API calls. To add or remove users from teams, see this article. To add or remove custom variables from teams, see this article. Create Or Update Teams To create or update teams, ...

    • How Can I Programmatically Create Or Update Users?

      This article explains how you can create or update users using simple API calls. To add or remove users from teams, see this article. To add or remove custom variables from users, see this article. Create Or Update Users To create or update users, ...

    • How Can I Programmatically Add Or Remove Users From Teams?

      This article explains how you can add or remove users from teams using simple API calls. To do this, you will either create or delete team member records which represent membership of users within teams. Create Or Delete Team Members To add or remove ...

    • How Can I Set Reward Icons

      To set reward icons: Login to your workspace On the left pane, click on "Calculation > All Calculations" Open the calculation Click on the "Rewards" tab Search by payee name Click on the reward to edit it You can either use a static icon or a dynamic ...

    • Is There A Complete Formula Technical Reference?

      This article provides technical details about formulas. For some background information about formulas, click here. You can configure formulas to control different aspects of calculations, such as filtering, crediting, scoring, quota, custom, ...