Requesting subject data with the MACRO API

GetSubjectData

GetCDISCSubjectData

These routines enable you to request data by sending an XML string containing details of the data required. For both routines, MACRO will return the data as an XML string. Each request for data from MACRO must include a MACRO user object, representing the currently logged in user, as returned from the login procedure.

Input

Parameter	Description
user	Currently logged-in user as returned from Login
dataRequestXml	XML string specifying the MACRO subject details and the names of the data items required

Requesting data in MACRO format:

public static DataRequestResult GetSubjectData(UserProperties user, string dataRequestXml, ref string returnedDataXml)

Requesting data in CDISC format:

public static DataRequestResult GetCDISCSubjectData(UserProperties user, string dataRequestXml, ref string returnedDataXml)

Output

· Return code indicating success or nature of failure

· returnedDataXml - if the request succeeds, an XML string containing requested data values is returned. When using GetCDISCSubjectData this will be a CDISC-compliant string

Input example

The following XML request string returns data for the subject with label "N3001" at site "london" for study "Demostudy40". The data requested is the specified questions from the Cover and Demography eForms in the Screening visit; all the data from the Treatment visit; and all the data from the ECG1 form in the Followup visit.

<?xml version="1.0"?>

</Eform>

</Eform>

</Visit>

</Visit>

</MACROSubject >

The following XML requests data for subject with ID 3 at site "london" for study "Demostudy40".

<?xml version="1.0"?>

</Visit>

</Visit>

</MACROSubject >

Note that:

· If no eForms are specified in a visit, all responses on all eForms in that visit will be returned

· If no questions are specified for an eForm, all responses on the eForm will be returned

· If no visits are specified, the entire set of data for the subject will be returned

· If no cycle is specified, cycle = 1 is assumed

· Cycle=0 means all cycles

Return to top

Output examples

For the first of the above XML request strings, XML output such as the following will be returned.

<?xml version="1.0"?>

</Eform>

</Eform>

</Visit>

<!— All data from treatment visit and eForm ECG1 in the followup visit follow similarly… -->

</MACROSubject >

For date questions, a "Standard Value" attribute is also returned – this is the date represented in standard Microsoft format, as a decimal number where the integer part is the number of days since 31 Dec 1899, and the decimal part is the fraction of the day. This value is independent of the MACRO date format specified for the question. If the value is copied and pasted into an Excel spreadsheet with format date/time, the formatted date value can be seen.

Return to top

Requesting status details

You can also use the API to retrieve the various status details for given subjects/visits/eForms/questions. To do this, add the following optional Scope attributes to the MACROSubject node in the input XML string, specifying which status and which object statuses are required, i.e. Subject, Visit, eForm or Question:

· StatusScope – Data Status

· LFScope – Lock / Freeze Status

· DCRScope – DCR Status

· SDVScope – SDV Status

· NoteScope – Note Status

The value of the attribute may be one of the following:

· Subject – The appropriate status will be output for Subject level only

· Visit – The appropriate status will be output for Subject and Visit levels only

· Eform – The appropriate status will be output for Subject, Visit and Eform levels.

· Question – The appropriate status will be output for all scope levels, i.e. Subject, Visit, Eform and Question.

StatusOnly. If this optional attribute is set to true, and a status scope has been specified, then data values will be suppressed from the output, and status values will only be retrieved down to the level specified.

For example, to request the DCR status of all questions on the Cover sheet in the Screening visit for a Demostudy40 subject, use the following XML request string:

</Visit>

</MACROSubject>

In the XML output string, the requested status will be shown as the following attribute names:

· Status - if StatusScope specified

· LFStatus – if LFScope specified

· DCRStatus – if DCRScope specified

· SDVStatus – if SDVScope specified

· NoteStatus – if NoteScope specified

Return to top

Examples

This XML input string requests the subject status for subject Demostudy40/london/23:

and gives the following output, including the Status attribute(s) in the relevant nodes:

This XML input string requests the lock status and DCR status for the subject and visits for subject Demostudy40/ruthin/OFN 158X:

and gives the following output:

</MACROSubject>

Return to top

Data request return codes

The Subject data request routines return an integer code as type DataRequestResult indicating the result, as listed in the table below.

Code	Value	Description
0	Success	Retrieval was successful
1	InvalidXML	Input XML could not be read
2	SubjectNotExist	Specified subject was not found
3	SubjectNotOpened	Specified subject could not be opened
4	InvalidUserCredentials	User does not have permission to access this study/site

Return to top