How to register a group or collection of asssessments (i.e. battery or profile) through the API
Syntax
- https://assessmentcenter.net/ac_api/2014-01/Batteries/ - returns a list of all profiles/batteries (i.e. OID and Name).
- https://assessmentcenter.net/ac_api/2014-01/Batteries/{OID}{.xml or .json} - returns an array forms that are contained in the profile/battery.
- https://assessmentcenter.net/ac_api/2014-01/BatteryAssessments/{OID}{.xml or .json} - returns an array of assessment tokens that represent registered forms.
Remarks
Profiles or Batteries are defined as a collection of forms that are intended to be administered sequentially. From the end user perspective, the profile or battery will seem like like one consistant form.
OID is the 'primary key' of the Profile/Battery.
Calling the BatteryAssessments/{OID} endpoint will produce the same results as calling the Assessments API for each form contained in the profile/battery. The API consuming application should track and iterate through the assessment tokens by calling the Participants endpoint. After an assessment is finished, immediately start the next assessment in the array.
If an UID parmeter is not used when calling the BatteryAssessments endpoint, then a random UID parameter will used. UID parameters are required for Scored Batteries. (see below)
https://assessmentcenter.net/ac_api/2014-01/BatteryScore/{OID}/{UID}{.xml or .json} - returns the results of the battery with an overall battery score.
BatteryScore endpoint ONLY applies to a batteries that have a registered event in the dbo.FormEvent table.
Utility score
The only battery scoring event is in the class MSS.UtilityScoreEventSinks.MSS.UtilityScore.EventSinks and it has and EventOID='82AFF363-F204-42F0-BE9D-75EDE5203EE3'
This event creates an utility score based on theta scores for the following domains:
- Cog Function Abilities
- Depression
- Fatigue
- Pain Interference
- Physical Function
- Sleep Disturbance
- Ability to Participate Social
The BatteryScore endpoint can also be used to create an utility score for the above seven domain by POSTing the theta values for these domains and setting the OID = Guid.Empty and UID ='82AFF363-F204-42F0-BE9D-75EDE5203EE3'
The below curl example will produce the following JSON object.
curl --location --request POST 'https://assessmentcenter.net/ac_api/2014-01/BatteryScore/
00000000-0000-0000-0000-000000000000/
82AFF363-F204-42F0-BE9D-75EDE5203EE3.json?
theta_cog=-0.0538298498110291
&theta_dep=1.82443972771865
&theta_fat=1.33194767840655
&theta_pain=1.67117887262497
&theta_phys=-1.57530758245269
&theta_sleep=1.18278374986392
&theta_social=-1.34773132608718' \
{
"PROPr": "0.095",
"Cognition_utility": "0.846",
"Depression_utility": "0.455",
"Fatigue_utility": "0.64",
"Pain_utility": "0.494",
"Physical_utility": "0.537",
"Sleep_utility": "0.58",
"Social_utility": "0.589",
"Forms": []
}
API Home
Try it!
Sample code for https://assessmentcenter.net/ac_api/2014-01/Batteries
<script langauge="javascript" src="jquery-1.7.1.min.js"></script>
<script language="javascript" src="crypto.js"></script>
<script type='text/javascript' version='1.3'>
var Server = https://assessmentcenter.net/ac_api;
function listBatteries(){
$.ajax({
url: Server + "Batteries/.json",
cache: false,
type: "POST",
data: "",
dataType: "json",
beforeSend: function(xhr) {
var bytes = Crypto.charenc.Binary.stringToBytes(UserID +":"+ Token);
var base64 = Crypto.util.bytesToBase64(bytes);
xhr.setRequestHeader("Authorization", "Basic " + base64);
},
success: function(data) {
var container = document.getElementById("Content");
var batteries = data.Battery;
for (var i=0; i < batteries.length; i++){
var mybattery = document.createElement("div");
mybattery.innerHTML="<input type='checkbox' name='" + batteries[i].OID + "' id='"+ batteries[i].OID + "'/>" + batteries[i].Name + "<br />";
container.appendChild(mybattery);
}
},
error: function(jqXHR, textStatus, errorThrown){
alert('listForms: ' + jqXHR.responseText + ':' + textStatus + ':' + errorThrown);
}
}
)
}
using System;
using System.Collections;
using System.Configuration;
using System.IO;
using System.Net;
using System.Web;
using System.Text;
using System.Text.RegularExpressions;
public class TestHarness
{
static void Main(string[] args)
{
string REGISTRATIONID ="31839849-ECE0-4F5E-BEAE-3D655ED65E31"; // Sample registration -- replace with your RegistrationID
string TOKEN ="F3738486-5A7D-41EF-8044-DCBAF800E2D4"; // Sample token -- replace with your TokenOID
// Request assessment tokens for the 8 forms that make up the PROMIS-29 Profile/Battery v2.0
string API_URL = "https://assessmentcenter.net/ac_api/2014-01/BatteryAssessments/784C754E-8707-4AF6-82DA-553BAFED59B2.xml";
string authstring = Convert.ToBase64String(Encoding.ASCII.GetBytes(String.Format("{0}:{1}", REGISTRATIONID, TOKEN)));
ServicePointManager.Expect100Continue = false;
Byte[] postbytes = Encoding.ASCII.GetBytes(string.Empty);
WebClient client = new WebClient();
client.Headers.Add("Authorization", String.Format("Basic {0}", authstring));
client.Headers.Add("Content-Type", "application/x-www-form-urlencoded");
byte[] resp = client.UploadData(API_URL, "post", postbytes);
Console.WriteLine(Encoding.ASCII.GetString(resp));
}
}
Request:https://assessmentcenter.net/ac_api/2014-01/Batteries/784C754E-8707-4AF6-82DA-553BAFED59B2.json
Response:
{
"Forms": [
{
"FormOID": "C81F5920-D9DB-48F7-A0AD-A6F2A4BF6D36",
"Name": "PROMIS SF v1.0-Physical Function 4a",
"Order": "1"
},
{
"FormOID": "6C13662F-179A-45AD-A8DF-16843D902E28",
"Name": "PROMIS SF v1.0-Anxiety 4a",
"Order": "2"
},
{
"FormOID": "597A9B24-5B5C-487D-9606-451355DC6E3D",
"Name": "PROMIS SF v1.0-Depression 4a",
"Order": "3"
},
{
"FormOID": "2E25400B-9373-4631-B769-2E4D466EED04",
"Name": "PROMIS SF v1.0-Fatigue 4a",
"Order": "4"
},
{
"FormOID": "795B07C1-067E-4FBD-9B60-A57985E69B5D",
"Name": "PROMIS SF v1.0-Sleep Disturbance 4a",
"Order": "5"
},
{
"FormOID": "B730F00E-C958-4654-85C1-0931A7289322",
"Name": "PROMIS SF v2.0 - Ability to Participate Social 4a",
"Order": "6"
},
{
"FormOID": "C3305A82-E1AA-4E88-9F4D-E9C8099C296F",
"Name": "PROMIS SF v1.0-Pain Interference 4a",
"Order": "7"
},
{
"FormOID": "7ED97248-872A-451B-A281-D93B9866A591",
"Name": "PROMIS-Global Pain",
"Order": "8"
}
]
}
Request:https://assessmentcenter.net/ac_api/2014-01/BatteryAssessments/784C754E-8707-4AF6-82DA-553BAFED59B2.xml
Response:
<?xml version="1.0" encoding="utf-8"?>
<BatteryAssessments>
<Assessment OID="a5b891d3-3ab4-4b20-bbf0-86f386004f1a" UID="" Expiration="10/2/2016 5:36:05 PM" />
<Assessment OID="9630e27b-d76d-4ff8-9d9a-4063f85dd2cd" UID="" Expiration="10/2/2016 5:36:05 PM" />
<Assessment OID="7800fa13-283f-4ab8-9c89-b2904c7c721a" UID="" Expiration="10/2/2016 5:36:05 PM" />
<Assessment OID="7965ebce-3226-4a90-a576-5506f5e0fdee" UID="" Expiration="10/2/2016 5:36:05 PM" />
<Assessment OID="93ea8f62-488f-4bb5-b8e3-d33759b86e84" UID="" Expiration="10/2/2016 5:36:05 PM" />
<Assessment OID="df9faf02-b040-44a3-a03a-55cf1f32b418" UID="" Expiration="10/2/2016 5:36:05 PM" />
<Assessment OID="acaf3408-8cc5-4868-9a3f-62cceb567f88" UID="" Expiration="10/2/2016 5:36:05 PM" />
<Assessment OID="3c3fbe39-35c6-4a0d-bb91-47ad3fbc6a26" UID="" Expiration="10/2/2016 5:36:05 PM" />
</BatteryAssessments>