REDCap

REDCap API Documentation

Method Name

Import User Roles

Description

This method allows you to import new user roles into a project while setting their privileges, or update the privileges of existing user roles in the project.

URL

https://chi-redcap.dshs.texas.gov/redcap/api/

Supported Request Method

POST

Permissions Required

To use this method, you must have API Import/Update privileges *and* User Rights privileges in the project.

Parameters (case sensitive)

Required

token
The API token specific to your REDCap project and username (each token is unique to each user for each project). See the section on the left-hand menu for obtaining a token for a given project.

content
userRole

format
csv, json, xml [default]

data
Contains the attributes of the user role to be added to the project or whose privileges in the project are being updated, in which they are provided in the specified format. All values should be numerical with the exception of unique_role_name, role_label and forms. Please note that the 'forms' attribute is the only attribute that contains sub-elements (one for each data collection instrument), in which each form will have its own Form Rights value (see the key below to learn what each numerical value represents). Most user privilege attributes are boolean (0=No Access, 1=Access).

Missing attributes: If a user role is being added to a project in the API request, then any attributes not provided for a user role in the request (including form-level rights) will automatically be given the minimum privileges (typically 0=No Access) for the attribute/privilege. However, if an existing user role's privileges are being modified in the API request, then any attributes not provided will not be modified from their current value but only the attributes provided in the request will be modified.

Data Export: 0=No Access, 2=De-Identified, 3=Remove Identifier Fields, 1=Full Data Set
Form Rights: 0=No Access, 2=Read Only, 1=View records/responses and edit records (survey responses are read-only), 3=Edit survey responses
Other attribute values: 0=No Access, 1=Access.

All available attributes:

unique_role_name, role_label, design, alerts, user_rights, data_access_groups, reports, stats_and_charts, manage_survey_participants, calendar, data_import_tool, data_comparison_tool, logging, email_logging, file_repository, data_quality_create, data_quality_execute, api_export, api_import, api_modules, mobile_app, mobile_app_download_data, record_create, record_rename, record_delete, lock_records_customization, lock_records, lock_records_all_forms, forms, forms_export

JSON Example:

[{"unique_role_name":"U-2119C4Y87T","role_label":"Project Manager",
"design":"0","user_rights":"1","data_access_groups":"1","data_export_tool":"0","reports":"1","stats_and_charts":"1",
"manage_survey_participants":"1","calendar":"1","data_import_tool":"0","data_comparison_tool":"0","logging":"0",
"file_repository":"1","data_quality_create":"0","data_quality_execute":"0","api_export":"0","api_import":"0","api_modules":"0",
"mobile_app":"0","mobile_app_download_data":"0","record_create":"1","record_rename":"0","record_delete":"0",
"lock_records_customization":"0","lock_records":"0","lock_records_all_forms":"0",
"forms":{"demographics":"1","day_3":"2","other":"0"}},{"unique_role_name":"U-527D39JXAC","role_label":"Data Entry Person",
"design":"0","user_rights":"0","data_access_groups":"0","data_export_tool":"0","reports":"1","stats_and_charts":"1",
"manage_survey_participants":"1","calendar":"1","data_import_tool":"0","data_comparison_tool":"0","logging":"0",
"file_repository":"1","data_quality_create":"0","data_quality_execute":"0","api_export":"1","api_import":"0","api_modules":"0",
"mobile_app":"0","mobile_app_download_data":"0","record_create":"1","record_rename":"0","record_delete":"0",
"lock_records_customization":"0","lock_records":"0","lock_records_all_forms":"0",
"forms":{"demographics":"1","day_3":"1","other":"0"}},
"forms_export":{"demographics":"1","day_3":"2","other":"1"}}]

CSV Example:

unique_role_name,role_label,design,user_rights,forms,forms_export
U-527D39JXAC,Data Entry Person,1,1,"demographics:1,day_3:1,other:1","demographics:1,day_3:2,other:0"
U-2119C4Y87T,Project Manager,0,0,"demographics:1,day_3:2,other:0","demographics:1,day_3:2,other:0"

XML Example:

<?xml version="1.0" encoding="UTF-8" ?>
<users>
   <item>
      <unique_role_name>U-527D39JXAC</unique_role_name>
      <role_label>Data Entry Person</role_label>
      <user_rights>1</user_rights>
      <design>0</design>
      <forms>
         <demographics>1</demographics>
         <day_3>2</day_3>
         <other>0</other>
      </forms>
      <forms_export>
         <demographics>1</demographics>
         <day_3>0</day_3>
         <other>2</other>
      </forms>
   </item>
</users>

Optional

returnFormat
csv, json, xml - specifies the format of error messages. If you do not pass in this flag, it will select the default format for you passed based on the 'format' flag you passed in or if no format flag was passed in, it will default to 'xml'.
NOTE: Does not apply when importing as a background process (i.e., backgroundProcess=true). When using a background process, success:true (upon success) or success:false (upon failure) will be returned in the appropriate format (csv, json, xml).

Returns

Number of user roles added or updated

General API Info

Supported Methods