MACRO API

 

Importing user role associations with the MACRO API

ImportAssociations

 

This routine enables you to import study/site/user/role associations. Note that studies, sites, users and roles will not be created by this call, nor will study/site associations be set up. The specified study, site, user and role must all exist, and the site must be participating in the named study. If an association is to be added and it already exists it will be ignored. Likewise if an association is to be removed and it does not exist it will be ignored.

 

Input

Parameter

Description

user

Currently logged-in user as returned from Login

associationsXml

XML string containing specification of new/updated associations

 

public static ImportResult ImportAssociations(UserProperties user, string associationsXml, ref string reportXml)

 

Output

·       Return code indicating success or failure

·       reportXml - any failures are detailed in an XML string

 

 

Example input

The XML string contains Study/Site/User/Role associations, together with an action which specifies whether to add or remove this association:

 

<macroassociations>

        <macroassociation study="Demostudy40" site="london" user="ncj" role="DE" action="add"/>

        <macroassociation study="Demostudy40" site="bham" user="ncj" role="DE" action="remove"/>

        <macroassociation study="DINODRUGS" site="austria1" user="GordonG" role="DR" action="add"/>

        <macroassociation study="AllStudies" site="AllSites" user="theboss" role="SysAdmin" action="add"/>

</macroassociations>

 

The schema for the above XML is as follows:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">

       <xs:element name="macroassociations">

              <xs:complexType>

                     <xs:sequence>

                           <xs:element ref="macroassociation" maxOccurs="unbounded"/>

                     </xs:sequence>

              </xs:complexType>

       </xs:element>

       <xs:element name="macroassociation">

              <xs:complexType>

                     <xs:attribute name="study" use="required" type="xs:string"/>

                     <xs:attribute name="site" use="required" type="xs:string"/>

                     <xs:attribute name="user" use="required" type="xs:string"/>

                     <xs:attribute name="role" use="required" type="xs:string"/>

                     <xs:attribute name="action" use="required" type="xs:string"/>

              </xs:complexType>

       </xs:element>

</xs:schema>

Return to top

 

Import role associations return codes

The ImportAssociations routine returns an integer code as type ImportResult indicating the overall 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. If an error occurs for a particular association, that item will be ignored but other valid 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 currently logged-in user does not have "Change user access rights" permission

4

UnexpectedError  

An unexpected error occurred - the return string is not XML in this case, but is simply a text string containing error details

 

Return to top

 

Error codes

Code

Value

Description

1

StudyDoesNotExist

Named study does not exist

2

SiteDoesNotExist

Named site does not exist

3

UserDoesNotExist

Named user does not exist

4

RoleDoesNotExist  

Named role does not exist

5

Study/siteAssociationDoesNotExist

Named site is not participating in this study

6

InvalidAction

The value of the Action attribute is not add or remove

7

InvalidXML

Incomplete or invalid XML, e.g. missing attribute

 

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 above. The msgDesc attribute contains text describing the error. For example:

 

<macroassocerrors>

        <macroassocerror msgtype="1" study="Demostudy40" msgdesc="Study does not exist"/>

        <macroassocerror msgtype="4" study="Demostudy40" site="glasgow" user="hb" role="DataEntry" action="add" msgdesc="Role does not exist"/>

        <macroassocerror msgtype="6" study="DinoDrugs" site="turkey" user="SmithJ" role="DataEntry" action="addd" msgdesc="Invalid Action"/>

</macroassocerrors>

 

The schema for the above XML is as follows:

 

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">

       <xs:element name="macroassocerrors ">

              <xs:complexType>

                     <xs:sequence>

                           <xs:element ref="macroassocerror" maxOccurs="unbounded"/>

                     </xs:sequence>

              </xs:complexType>

       </xs:element>

       <xs:element name="macroassocerror ">

              <xs:complexType>

                     <xs:attribute name="msgtype" use="required" type="xs:byte"/>

                     <xs:attribute name="study" use="required" type="xs:string" />

                     <xs:attribute name="site" use="optional" type="xs:string" />

                     <xs:attribute name="user" use="optional" type="xs:string" />

                     <xs:attribute name="role" use="optional" type="xs:string" />

                     <xs:attribute name="action" use="optional" type="xs:string" />

                     <xs:attribute name="msgdesc" use="required" type="xs:string"/>

              </xs:complexType>

       </xs:element>

</xs:schema>

 

Return to top