Retrieve calculation data tutorial

In this tutorial, you will use the Varicent Incentives REST APIs to retrieve results from a specific calculation in your model.

Prerequisites

You have created calculations. For more information on creating calculations, see Calculations.
You have run a full model calculation to make sure the results in the model are up-to-date.
You have obtained your Varicent API Key as outlined in REST API authentication and headers.

Overview

In this tutorial, we'll be using the following REST API calls to retrieve data:

Get calculation list: This call gets the ID of the calculation that contains the data that you want to retrieve.

Get calculation data: This call gets the data from a calculation.

Retrieving the calculation ID

First, use the Varicent Incentives REST API call to retrieve a list of all the calculations.

Make the following request:

GET /api/v1/calculations

For example,

curl -X GET -H "Authorization: Bearer API_KEY" 
-H "Model: YOUR_CLIENT_MODEL” 
-H "Content-Type: application/json" 
https://YOUR_ICM10_API_SERVER_ADDRESS/api/v1/calculations

You can use the following parameters to filter the return response:

Parameter	Description
filter	Supported fields are: `name`: the calculation name. `type`: the calculation type, such as category, timeshift, sorting, and mathematical. The supported operations are: Equal matching `name=admin`. This is strict and case-sensitive. Starts with `name^admi`, or ends with `name$min`. This is case-insensitive. Equal matching within a list, such as `userType=Admin\\,Web`. This is case-insensitive. Interval matching, such as `date=[2015-09-22\\,2015-09-25]`, supports the mathematics notation for inclusive/exclusive bounds, `[a\\,b]`, `(a\\,b)`, or a mix `(a\\,b]`. Intervals also support open-ended bounds, `(a\\,]`. Not equal matching `name<>admin`. This is strict and case-sensitive. Is contained in `name⊇dmi`. This is case insensitive. NULL checks, such as `name=NULL` or `name<>NULL`. Only equal and not equal operators are supported. You can use multiple filters on one attribute. The filter query also supports the use of an operator. Complete filter definitions, as described above, are expected on both sides of the operator. The column filtered must be the same on both sides of the operator. Supported operators are: AND `&&`, OR `\|\|`. To define a filter on multiple attributes, separate each filter statement with `;`. The following is an example using the filter parameter: GET /api/v1/calculations?filter=name=All Payouts

Parameter

Description

filter

Supported fields are:

name: the calculation name.
type: the calculation type, such as category, timeshift, sorting, and mathematical.

The supported operations are:

Equal matching `name=admin`. This is strict and case-sensitive.
Starts with `name^admi`, or ends with `name$min`. This is case-insensitive.
Equal matching within a list, such as `userType=Admin\\,Web`. This is case-insensitive.
Interval matching, such as `date=[2015-09-22\\,2015-09-25]`, supports the mathematics notation for inclusive/exclusive bounds, `[a\\,b]`, `(a\\,b)`, or a mix `(a\\,b]`. Intervals also support open-ended bounds, `(a\\,]`.
Not equal matching `name<>admin`. This is strict and case-sensitive.
Is contained in `name⊇dmi`. This is case insensitive.
NULL checks, such as `name=NULL` or `name<>NULL`. Only equal and not equal operators are supported.

You can use multiple filters on one attribute. The filter query also supports the use of an operator. Complete filter definitions, as described above, are expected on both sides of the operator. The column filtered must be the same on both sides of the operator. Supported operators are: AND `&&`, OR `||`.

To define a filter on multiple attributes, separate each filter statement with `;`.

The following is an example using the filter parameter:

GET /api/v1/calculations?filter=name=All Payouts

In the response body, find the calculation containing the data that you want to retrieve, and note the ID.

{
    "parentBlockId": 2175,
    "calculationId": 633,
    "name": "Final Payment YTD by Team",
    "isFavourite": false
},
{
    "parentBlockId": 2174,
    "calculationId": 663,
    "name": "Final Payouts YTD",
    "isFavourite": false
},
{
    "parentBlockId": 157,
    "calculationId": 545,
    "name": "Final Periodic Payout",
    "isFavourite": false
},

Retrieving calculation data

Next, use the ID obtained from the Get list of calculations call to retrieve the calculation data from Varicent Incentives.