Entering subject data with the MACRO API

InputSubjectData

This routine enables you to enter data by sending an XML string containing the data.

Input

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

public static DataInputResult InputSubjectData(UserProperties user, string dataInputXml, ref string reportXml)

Output

· Return code indicating success or nature of failure

· reportXml - any data input failures are detailed in an XML string

Return to top

Setting the status of a blank response

You can set the status of a blank response to 'Missing' or 'Not Available' by adding the required status to the xml string:

The value attribute must be blank or omitted when setting the status.

Only a blank question with current status Missing (or new) can be set to Not Available.

Only a blank question with current status Not Available can be set to Missing.

If the question requires a Reason For Change, the following automatic RFC is applied:

“*** Status changed by an external application using the API”

Setting timestamps

When data is input using the API, response timestamps will normally be set according to the current time settings and time zone on the machine on which the API is running. It is possible to override this by including timestamp information in the input data using the Timezone and Timestamp attributes:

<Question Code="SA" Cycle="1" Value="01.28"

Timezone="GMT+03:00" Timestamp="2014/04/29 13:04:34"/>

Only one time zone can be set for each eForm and it must be specified in the first response for that eForm. So if any time zones are specified in subsequent responses for the eForm, those later time zones will be ignored.

Any specified time zone will only be applied to responses that have timestamps specified. So a response with no specified timestamp will be saved with the current server timestamp and time zone.

If the time zone is omitted, the server time zone will be used.

The Timezone value should be given as an offset from GMT.

Associating a laboratory with an eForm

You can specify a particular laboratory to be used with an eForm, using the Lab tag with a laboratory code, which will then be used to validate any laboratory questions on the eForm:

An error message will be returned if the laboratory code is not valid, e.g. if it does not exist or is not associated with the relevant site. In this case response values will still be processed, but laboratory question values will not be validated.

Note, however, that if an eForm already has a valid laboratory associated with it, and no laboratory (or an invalid laboratory) is specified in the XML, the existing laboratory will be used to validate laboratory questions.

Return to top

Input example

The XML input string is in the same format as returned from GetSubjectData().

<?xml version="1.0"?>

</Eform>

</Eform>

</Visit>

</MACROSubject >

The structure of an XML string for data input is identical to one for returned data, as shown above, except:

· the values of non-enterable (e.g. derived) fields should not be included (since they cannot be input)

· optional timestamps and laboratories may be specified

Return to top

Data entry return codes

The InputSubjectData routine returns a single integer code of type DataInputResult indicating the result, as listed in the table below. For return codes greater than 0, the returned string is an XML string containing one or more error messages, each with its own error code and text description, as detailed in the next section. If an error occurs for a particular data item, other valid data will still be added and saved.

Note that for an unexpected MACRO error (return code = -1), the returned string is not in XML format, but just contains details of the error.

Code	Value	Description
0	Success	No errors occurred; all data was added successfully, and no validations were fired (Warnings or Rejects)
1	InvalidXML	The XML input data could not be read because it contained invalid syntax
2	SubjectNotExist	The specified subject could not be found in the MACRO database
3	SubjectNotOpened	The specified subject could not be loaded. Details will be in the returned error report
4	DataNotAdded	Not all data was added successfully. Details will be in the returned error report. Note that some data may have been added. This return code is used even if only Warnings were fired on the data.

Return to top

Error codes

Code	Value	Description
1	InvalidXML	The XML input data was incomplete (e.g. questions or question values missing) or contained a syntax error
2	SubjectNotExist	The specified subject does not exist in the MACRO database
3	SubjectNotOpened	For some reason the specified subject could not be loaded. The reason is given in the message description
4	VisitNotExist	Either the named visit does not exist in the study, or the particular cycle of the visit does not exist for this subject
5	EFormNotExist	Either the named eForm does not exist in the study, or the particular cycle of the eForm within the current visit does not exist for this subject
6	QuestionNotExist	Either the named question does not exist in the study, or the particular question does not exist on the current eForm within the current visit for this subject
7	EFormInUse	Another MACRO user has this eForm open for data entry
8	VisitLockedFrozen	The visit has been locked or frozen by a data manager and therefore no data can be entered
9	EFormLockedFrozen	The eForm has been locked or frozen by a data manager and therefore no data can be entered
10	QuestionNotEnterable	Data cannot be entered for this question, which may be because it is locked or frozen, or it is a derived value, or it is disabled (its status is Not Applicable), or it is hidden
11	NoVisitEformDate	The eForm cannot be saved because the visit date or eForm date is missing
12	NoLockForSave	The eForm cannot be saved because another user is currently saving data for this subject
13	ValueRejected	A question value has been rejected, either because of an incorrect data type, or because of a “Reject” validation condition
14	ValueWarning	A warning validation has been fired
15	InvalidLab	A laboratory code has been specified which either does not exist or is not valid for the site
20	UserNoDataPermission	The user attempting to add or change data does not have the required permission to do so
21	DataError	General Data error
22	NoEformResponses	The user attempting to add or change data does not have access to the eForm, according to the eForm access rules
23	InvalidStatus	The status value given in the XML cannot be processed, which may be because it cannot be applied to the current response (e.g. status of Missing to a non-blank response), or it is specified in addition to a non-blank value in the XML, or it is an unrecognised status

If the DataInputResult return code is not "Success", the returned XML string contains one or more error messages. Each data error message has an integer message type (attribute MsgType), the values of which are listed in the table above. The MsgDesc attribute contains text describing the error. For example:

<DataErrMsg MsgType="6"

MsgDesc="Question screening[1]:cover[1]:hb[1] does not exist" />

<DataErrMsg MsgType="14"

MsgDesc="treatment[1]:blood[1]:wbc[1] The value is outside the

Laboratory's Normal Range (CLAP) 4 to 11" />

</MACROInputErrors>

Return to top