ImportCategories |
This routine enables you to import codes and descriptions for category questions.
Input
Parameter |
Description |
user |
Currently logged-in user as returned from Login |
xmlCatsInput |
XML string containing specification of new/updated categories |
public static ImportResult ImportCategories(UserProperties user, string xmlCatsInput, ref string xmlReport) |
Output
· Return code indicating success or failure
· xmlReport - XML string containing details of any errors that occurred
Example of the XML representation of categories to import.
Note that the XML file may include updates for more than one study.
<macrostudies> <macrostudy name="Demostudy40"> <questions> <question code="Centre" sort="0"> <categories> <category code="104" value="London" active="true"/> <category code="209" value="Bristol" active="true"/> <category code="273" value="Leeds" active="true"/> </categories> </question> <question code="Investigator" sort="2"> <categories> <category code="801" value="Dr Peter Pan" active="true"/> <category code="813" value="Dr Robinson Crusoe" active="false"/> </categories> </question> </questions> </macrostudy> </macrostudies> |
The schema for the above XML is as follows:
<macrostudies> <macrostudy name="Demostudy40"> <questions> <question code="Centre" sort="0"> <categories> <category code="104" value="London" active="true"/> <category code="209" value="Bristol" active="true"/> <category code="273" value="Leeds" active="true"/> </categories> </question> <question code="Investigator" sort="2"> <categories> <category code="801" value="Dr Peter Pan" active="true"/> <category code="813" value="Dr Robinson Crusoe" active="false"/> </categories> </question> </questions> </macrostudy> </macrostudies> |
For each category item, the category code identifies the category item to be updated, and the item will be processed as follows:
· If the code does not exist, a new category item is created.
· If the code already exists, the existing item is updated according to the values given.
· If the item is identical to an existing item, it is ignored.
The sort attribute for a category question is optional and may have the following values
· 0 = No sorting. New values are added to the end of the current list.
· 1 = Alphanumeric on category code. After all the changes have been done to the current question, items are sorted alphanumerically on code.
· 2 = Alphabetic on category value. After all the changes have been done to the current question, items are sorted alphabetically on value.
The ImportCategories routine returns an integer code of type API.ImportResult indicating the overall result of the operation, 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 item, that item will be ignored but other valid category updates will normally still be saved.
Code |
Value |
Description |
0 |
Success |
Operation completed successfully |
1 |
InvalidXML |
The XML input could not be read because it was incomplete or contained invalid syntax |
2 |
NotAllDone |
Some of the updates were not done. The return string is an XML error report |
3 |
PermissionDenied |
The user does not have permission to perform this action |
4 |
Error | Specified eForm was not found |
99 |
Unknown |
An unexpected error occurred during category import - the return string is not XML in this case, but is simply a text string containing error details |
Code |
Value |
Description |
1 |
StudyLocked | The updates could not be applied because the study is in use |
2 |
StudyDoesNotExist |
Named study does not exist |
3 |
QuestionDoesNotExist |
The specified question does not exist in the study |
4 |
QuestionNotOfTypeCategory |
The specified question is not of type category |
5 |
InvalidCategoryCode |
The specified category code is not valid, e.g. it contains invalid characters |
6 |
InvalidCategoryValue |
The specified category value contains invalid characters |
7 |
InvalidActive |
The value of the Active attribute is not true or false |
8 |
InvalidXML |
Incomplete or invalid XML, e.g. missing code or value |
If the return code is greater than 0, the returned XML string contains one or more error messages. Each error message has an integer message type (attribute MsgType), the values of which are listed in the table below. The MsgDesc attribute contains text describing the error, and the StudyName, QuestionCode and Category attributes describe which code failed. For example:
<macrocaterrors> <macrocaterror msgtype="1" study="Demostudy40" msgdesc="Study DemoStudy is in use by another user"/> <macrocaterror msgtype ="3" study="Demostudy40" question="xyz" msgdesc="Question does not exist in study"/> <macrocaterror msgtype ="4" study="Demostudy40" question="DOB" msgdesc="Question is not of type category"/> <macrocaterror msgtype ="5" study="Demostudy40" question="Trt" categorycode="3r" msgdesc="Invalid category code: 3r"/> </macrocaterrors> |
The schema for the above XML is as follows:
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="macrocaterrors"> <xs:complexType> <xs:sequence> <xs:element ref="macrocaterror" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="macrocaterror"> <xs:complexType> <xs:attribute name="msgtype" use="required" type="xs:byte"/> <xs:attribute name="study" use="required" type="xs:string" /> <xs:attribute name="question" use="optional" type="xs:string" /> <xs:attribute name="msgdesc" use="required" type="xs:string"/> <xs:attribute name="categorycode" use="optional" type="xs:string" /> </xs:complexType> </xs:element> </xs:schema> |