API: Import Data Values

Importing data values to Clear Impact Scorecard using the API.

Import Data Values

Parameters

  • id [int](Required) The unique Clear Impact Scorecard ID for the measure that data values are being imported for. You can find this ID by running an export on the measure list page.
  • actualValue [decimal] (Optional) An integer data value for the Actual Value. Up to 6 decimals.
  • targetValue [decimal] (Optional) An integer data value for the target. Up to 6 decimals.
  • actualValueDate [dateTime] (Required) Determines the time period to import the data value for. To import values for a specific time period, pick a date anywhere within that time period (i.e. Jan 2013 = 2013-01-01 through 2013-01-31 so you can enter any date in that timeframe like 2013-01-15 to import a value for Jan 2013). Should be formatted as YYYY-MM-DD.
  • comment [string] (Optional) A comment for the data value. Maximum length 255 characters. (Comment will be truncated if over 255)
  • measureType [string] (Optional) Deprecated as of 04/19/2020.  This is an outdated parameter that should only be used for legacy integrations.  It is used to determine if the id is for an Indicator or a Performance Measure. May be "i" for Indicator or "p" for Performance Measure.

Some things to know:

  • Dates should be entered in this format: YYYY-MM-DD
  • For % or $ metrics, do not include the symbols.
  • For % use the actual number not a decimal (i.e. 90% should be entered as 90)
  • For each value that exists in the import a new one will be created in Clear Impact Scorecard
  • If a value already exists for a measure and time period, the value will be overwritten with what is in the payload unless it is left blank.

Troubleshooting

The data values module has a few extra parameter requirements that may cause the import to fail, usually with an Error 304 (Not Modified)

  • You may only import one Actual Value into a single time period per import. If two of your data value parameters have the same date or are within the same time period date range for a measure the import will fail. (i.e. for annual measures 2014-01-01 and 2014-06-01 are both in the 2014 time period so if you have two data value parameters with those dates for the same measure the import will fail).
  • You cannot import data into calculated measures (Indicators or Performance Measures with a calculationId != 1). These are set up in the Clear Impact Scorecard software on the general tab of the edit view for each measure.

URL

https://api.resultsscorecard.com/api/datavalues/import

XML Input

<?xml version="1.0"?>
<DataValues>
<apiKey>eEIzvy0kCu017+D1VjjjI1f52Vmbm+VF2FvO</apiKey>
<siteCode>abc</siteCode>
<values>
<DataValue>
<actualValue>123</actualValue>
<actualValueDate>2013-11-20</actualValueDate>
<comment>comment: 0</comment>
<ID>26050</ID>
<measureType>i</measureType>
<targetValue>41598.380921932869</targetValue>
</DataValue>
<DataValue>
<actualValue>456.57</actualValue>
<actualValueDate>2013-12-20</actualValueDate>
<comment>comment: 1</comment>
<ID>26050</ID>
<measureType>i</measureType>
<targetValue>41598.380974664353</targetValue>
</DataValue>
<DataValue>
<actualValue>789</actualValue>
<actualValueDate>2013-10-20</actualValueDate>
<comment>comment: 2</comment>
<ID>26050</ID>
<measureType>i</measureType>
<targetValue>41598.380974664353</targetValue>
</DataValue>
</values>
</DataValues>

XML Output

<string xmlns="http://schemas.microsoft.com/2003/10/Serialization/">Import successful.</string>

JSON Input

{
"siteCode": "abc",
"apiKey": "eEIzvy0kCu017+D1VjjjI1f52Vmbm+VF2FvO",
"values": [
{
"ID": 26050,
"measureType": "i",
"actualValueDate": "2013-11-20T17:09:34.8550556Z",
"targetValue": 41598.381653414,
"actualValue": 1,
"comment": "comment: 0"
},
{
"ID": 26050,
"measureType": "i",
"actualValueDate": "2013-11-20T17:09:34.8550556Z",
"targetValue": 41598.381653414,
"actualValue": 1,
"comment": "comment: 1"
},
{
"ID": 26050,
"measureType": "i",
"actualValueDate": "2013-11-20T17:09:34.8550556Z",
"targetValue": 41598.381653414,
"actualValue": 1,
"comment": "comment: 2"
}
]
}

JSON Output

"Import successful."