API: Import Data Values

Importing data values to Clear Impact Scorecard using the API.

Import Data Values

Parameters

  • actualValue [decimal](Optional) An integer data value for the Actual Value. 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)
  • 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 list pages or on the edit view of an individual measure.
  • measureType [string](Required) Used to determine if the id is for an Indicator or a Performance Measure. May be "i" for Indicator or "p" for Performance Measure.
  • targetValue [decimal](Optional) An integer data value for the target. Up to 6 decimals.

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."