Skip to main content

Blackboard REST

Functionalities

Identity Integration 

Product Feature 

Supported 

Authenticate User 

No 

Validate User 

Yes 

Enable/Disable User 

Yes 

Reset Password 

Yes 

Expire Password Immediately 

No 

Expire Password by Date 

No 

Provisioning Integration 

Data Format 

Export 

Create 

Modify 

Delete 

Trigger 

User 

Yes 

Yes 

Yes 

Yes 

No 

Course 

Yes 

Yes 

Yes 

Yes 

No 

InstitutionRole 

Yes 

No 

No 

No 

No 

SystemRole 

Yes 

No 

No 

No 

No 

CourseRole 

Yes 

No 

No 

No 

No 

Prerequisites 

The following prerequisites must be satisfied in order to use Fischer Identity’s Blackboard REST connector: 

  • Get an Application Key and Secret Using a Blackboard Developer Account. 
  • Create REST API Integration. 

 

Get an Application Key Using a Blackboard Developer Account 

The following steps demonstrate how to create a REST API Integration: 

  1. Using a web browser, navigate to https://developer.blackboard.com/, and create a new developer account. 

 

  1. Accept Terms and Conditions. 

 

  1. Click the register button 

 

  1. After filling out the Register a new application form, click the Register application and generate API key button. 

 

  1. Save a copy of the Application key, Secret, and any additional information needed for your organization. 

 

⚠️ WARNING 

This is your only chance to save this information. Once navigating away from this screen, this information will be lost. 

 

 

Create REST API Integration 

Note: An Application ID is required in order to create a REST API Integration. 

The following steps demonstrate how to create a REST API Integration: 

  1. Login to Blackboard using an administrator account. 
  1. Navigate to the System Admin tab on the top-right corner of the navigation menu. 

 

  1. Navigate to REST API Integrations using the link provided in the Integrations section. 

 

 

  1. Click the Create Integration button.  

 

 

  1. Provide the Application ID and Learn User, then click Submit. 

 

 

Create the Blackboard REST connected system in the Admin UI 

The connected systems detail page is shown below. Only configurations which are specific to Blackboard REST will be documented below. For an overview of the configuration which are common to all connectors, please refer to our “Link to connected systems guide”. 

 

Connection Information 

 

Service URL 

The URL where the Blackboard API Server is hosted 

Client Id 

Client Id used for logon to the Blackboard API server. Use the Application Key described in the Prerequisites section above. 

Client Secret 

Client secret used for logon to the Blackboard API server. 

Connection Timeout 

Number of seconds to wait for completion of an API call to Blackboard before timing out. 

Creating the Blackboard REST connected system in Studio 

  1. Log in to the Workflow and Connectivity Studio and click Connectivity -> Add Systems on the menu bar. The Add Connected Systems window displays. 
  1. Select the Blackboard REST connected systems from the Type drop-down list. The default values display. 

 

  1. Enter the required information. Only configurations which are specific to Blackboard REST will be documented below. For an overview of the configuration which are common to all connectors, please refer to our “Link to connected systems guide”. 

Connection Information 

 

Service URL 

The URL where the Blackboard REST Server is hosted 

Client Id 

Client Id used for logon to the Blackboard API server. 

Client Secret 

Client secret used for logon to the Blackboard API server. 

Connection Timeout 

Number of seconds to wait for completion of an API call to Blackboard before timing out. 

 

Using the Connected System for Identity 

Perform these procedures to configure the connector: 

  • Connector Details for Identity 
  • Identity Password Management 

Connector Details for Identity 

This table lists values to enter when associating the Identity user with an existing user in the connected systems: 

Field 

System Attribute 

Example Value 

Account ID 

id 

_1408_1 

Login Id 

userName 

fischerUser 

 

Using the Connected System for Provisioning 

Perform these procedures to configure the connector: 

  • Configuring for Export 
  • Configuring for Import 
  • Connector Details for Provisioning 

Note: If the number of records to be processed exceeds one thousand, we recommend configuring the workflow to use bulk mode, which lowers the memory consumption of the system by streaming data to files. Because data is streamed for every task, performance of the workflow execution will be decreased due to increased read-write operations. See the Workflow and Connectivity Studio document for details on how to configure bulk mode. 

Configuring for Export 

Perform these procedures to configure the connector for data export: 

  • Configuring the Export Connector 
  • Configuring the Export Link 

From the Workflow and Connectivity Studio, select the Blackboard REST UserExport workflow listed under the projects folder if a workflow does not already exist, create an export workflow. See Workflow and Connectivity Studio for details on creating export workflows. 

Configure the Export Connector 

  1. In the Design pane, double-click the export object (the first object after the Start object). The Configure Data Source window displays: 

 

  1. From the Configure Plug-In tab, set the properties as required: 

Associated Connected System 

Select the connected System from the list. The export will be done from this connected system 

Data Formats 

Select the type of data format to use: User (Default) 

DeltaExportMode 

Select the type of attribute to export if a change takes place (this works in conjunction with ExportMode when DeltaExport is selected): 

  • OnlyChangedAttributes - Performs a partial export of only the changed attributes from the last time the query was run.  
  • ChangedAndMandatoryAttributes (default) - Performs a partial export of both changed and mandatory attributes from the last time the query was run. Mandatory attributes are exported whether they have been changed or not.  
  • AllAttributes - Performs a full export of all attributes that contain a value. 

DynamicConnectedSystem 

Select the global variable to use as the dynamic connected system name. This works in conjunction with DynamicConnectedSystemOption when GlobalVariable is selected. 

DynamicConnectedSystemOption 

Select how to control Dynamic System Support (DSS):  

  • None - There will not be any Dynamic System Support. 
  • Transaction-SystemName - The value of the Transaction-SystemName attribute in data will be used as the dynamic connected system. The connected system name must be passed as the value of the attribute Transaction-SystemName; if it is missing in data, the operation will fail. 
  • GlobalVariable - Select a global variable to use as the dynamic connected system name from the property DynamicConnectedSystem. 

GetUserById 

Provide the id of the User to export entry. 

 

GetCourseById 

Provide the id of the Course to export entry. 

 

GetRoleById 

Provide the id of the Role to export entry. 

 

ExportMode 

Select the type of data to export: 

  • FullExport - Exports all attributes 
  • DeltaExport - Exports changed, mandatory, or all attributes, depending on the DeltaExportMode property setting. 

Filter 

Specify search criteria to determine the objects to be exported from the Blackboard REST Connected System. Use the Set Filter button that becomes active to create a filter. See the Set Filter section for additional information. 

MaxResults 

Select the maximum number of results that can be returned. 

ResultsPerPage 

Configuration to control the items to be fetched per page. 

 

  1. (Optional) Select the Attributes tab. Only the standard attributes display: 

 

 

Modify schema attributes using these buttons: 

Add 

Add additional attributes to the list. The Add New attribute dialog displays. 

 

Note: Only attributes that are present in the business Object schema can be added. If they are not in the business Object schema they will be disregarded.  

Export 

Export the schema list to an XML file. 

Import 

Imports the schema list from an XML file. 

Reset Schema 

Resets the schema definition to the default schema prepackaged with the IDM Suite, plus any global variable added. 

 

  1. (Optional) Select the Appearance tab to change how the Connected System object displays in the Design pane. 
  1. Click OK and save any changes and return to the Workflow and Connectivity Studio window. 

Configure the Export Link 

  1. In the Design pane, double-click the export link between the export object (the first workflow object after the Start object) and the Data Mapper object. The Configure Link window displays. 

  

 

Source Attributes 

Select the attribute to export 

Selected Attributes 

Displays default attributes and those attributes that have been selected from the Source Attributes. 

 

Note: The check boxes are used only for delta export operations. These checked attributes will always be exported whether they were changed or not. Usually, the attributes that are selected as mandatory attributes help in identifying or verifying an entry when completing mapping functions. 

Format 

Displays the Format Date window to specify a data/time format to be applied to the selected date type attribute, for example, StartDate. During export, the attribute’s value is converted to the specified format. See the Format Date steps below for additional information. 

 

Note:  

  • The format button is only enabled for date attributes. 
  • The Refresh Schema button on the Configure Data Source Window’s Attributes tab must be used to refresh the schema and enable the Format button for date attributes. 

Advanced Settings 

Displays the Configure Attributes window for configuring advanced settings for attributes. See the Configure Attributes window on page 39 for additional information. 

 

  1. From the Attribute Selection tab, select attributes to export. 
  1. (Optional) Click the Format button to specify a data/time format to be applied to the selected date type attribute. The Format Date window displays. 
  1. Select the include Time check box to add the timestamp with the date. 
  1. Select the 24-hour or the 12-hour option button and then select the required date/time format. 
  1. Click OK to save the selected format. The configure Link window displays. 
  1. Click Ok to save any changes and return to Workflow and Connectivity Studio window. 
  1. Deploy the workflow by selecting Deploy New Deployment. See the Workflow and Connectivity Studio documentation for details of deployment options. 
  1. Manage and run the deployed workflow from the Admin UI Server tab. See the documentation for details. 

 

Configuring for Import 

Perform these procedures to configure the connector for data import: 

  • Configure the import Connector 
  • Configure the Import Link 

From the Workflow and Connectivity Studio, select the Blackboard REST User Add, UserModify, or UserDelete workflow listed under the projects folder. 

If a workflow does not already exist, create an import workflow. See the “Workflow and Connectivity Studio” documentation for details on creating import workflows. 

Configuring the Import Connector 

  1. In the design pane, double-click the import object (the last workflow object). The Configure Data Source window displays: 

 

  1. From the Configure Plug-In tab, set these properties as required: 

Associated Connected System 

Select the connected system from the list. The import operation will be done to this connected system. 

Data Formats 

Select the type of data format to use. 

DynamicConnectedSystem 

Select the global variable to use as the dynamic connected system name. This works in conjunction with the DynamicConnectedSystemOption when GlobalVariable is selected. 

DynamicConnectedSystemOption 

Select how to control Dynamic System Support (DSS): 

None – there will not be any Dynamic System Support. 

Id 

Specify the attribute that contains the value used to uniquely identity the user account ID on the connected system. Blackboard REST supports id and userName as account Id. 

 

Note: This option is only available for the User data format. 

loginId 

Enter the attribute that contains the value used to uniquely identity the user account login ID on the connected system.  

 

Note: This option is only available for the User data format. 

 

  1. (Optional) Select the Attributes tab if ma attributes schema is to be modified. 
  1.  (Optional) Select the Appearance tab to change how the Connected System object displays in the Design pane. 
  1. Click OK to save any changes and return to the Workflow and Connectivity Studio window. 

Configuring the Import Link 

  1. In the design pane, double-click the import link between the import link between the Data Mapper object and the import object (the last workflow object). The Configure Link window displays: 

 

 

 

Source Attributes 

Select the attributes to import. 

Check for attribute-level auditing 

If auditing is enabled and these attributes below are checked, Provisioning will log all events for auditing purposes. 

Select Attributes 

Displays default attributes and those attributes that have been selected from the source Attributes. 

 

Note: The default attributes are those that are commonly used to create a new user. 

Format 

Displays the Format Date window to specify a data/time format to be imported to the selected date type attribute, for example, StartDate. During import, the attribute’s value is converted from the specified format to the system specific one. See the Format Date steps below for additional information. 

 

Notes:  

  • The format button is only enabled for date attributes. 
  • The Refresh Schema button on the Configure Data Source Window’s Attributes tab must be used to refresh the schema and enable the Format button for date attributes. 

Advanced Settings 

Displays the Configure Attributes window for configuring advanced settings for attributes. Under the Encrypted column, check the box of any attribute that needs to be encrypted. 

Under the Diff with Target column, check the box of any attribute to update using differencing (DiffWithTarget, AddDiffWithTarget, and RemoveDiffWithTarget). 

Key Attribute 

Select the attribute to be used as the key attribute for status processing and audit. 
  1. From the Attribute Selection tab, select attributes to import.  
  1. (Optional) Select the Appearance tab to change how the link displays in the Design pane.  
  1. Click OK to save any changes and return to the Workflow and Connectivity Studio window.  
  1. Deploy the workflow by selecting Deploy New Deployment. See the “Workflow and Connectivity Studio” documentation for details of deployment options. 
  1. Manage and run the deployed workflow from the Admin UI Server tab. See the “Identity Suite Administration” documentation for details. 

 

Configuration Details for Provisioning 

Configuration import properties id, loginId (User data format only) are used by the Provisioning Policy and IdentityHub features to populate the ACCOUNT_ID, and ACCOUNT_USERNAME columns of the FISC_USER_ACCOUNT table of the Product database. See the “Provisioning Policy” and “Provisioning Using the IdentityHub” chapters of the “Identity Suite Administration” documentation for details. 

 

Configuration Import Properties 

Identity Property 

System Attribute 

Id 

id (User data format) 

Login Id 

userName (User data format only) 

 

Connector Supported Data Formats 

User Data Format 

We can use this data format in import mode to manage users. User management includes add/modify/delete user; as well as manage user attributes, user course memberships, and observer/observee associations. 

The items in the MV (Multiple values), Export, Create, Modify, and Delete columns have these meanings: 

  • Y = Yes (Attribute is supported for this operation) 
  • N = No (Attribute is not supported for this operation) 
  • Y* = Required (attribute is mandatory for this operation) 
  • NA = Not Applicable 

Name 

MV 

Export 

Create 

Modify 

Delete 

Description 

id 

N 

Y 

N 

Y* 

Y* 

The primary ID of the user. 

uuid 

N 

Y 

N 

N 

N 

A secondary unique ID for the user. Used by LTI launches and other inter-server operations. 

externalId 

N 

Y 

Y 

Y 

N 

An optional externally-defined unique ID for the user. Defaults to the userName. 

dataSourceId 

N 

Y 

Y 

Y 

N 

The ID of the data source associated with this user. This may optionally be the data source's externalId using the syntax "externalId:math101". 

userName 

N 

Y 

Y* 

Y 

N 

The userName property. 

studentId 

N 

Y 

Y 

Y 

N 

The user's student ID name or number as defined by the school or institution. 

educationLevel 

N 

Y 

Y 

Y 

N 

Value can be: 'K8', 'HighSchool', 'Freshman', 'Sophomore', 'Junior', 'Senior', 'GraduateSchool', 'PostGraduateSchool', or 'Unknown'. 

gender 

N 

Y 

Y 

Y 

N 

Value can be: ‘Female’, ‘Male’, or ‘Unknown’. 

birthDate 

N 

Y 

Y 

Y 

N 

The birth date of this user. 

created 

N 

Y 

N 

N 

N 

The date this object was created 

modified 

N 

Y 

N 

N 

N 

The date this object was modified 

lastLogin 

N 

Y 

N 

N 

N 

The date this user last logged in. 

institutionRoleIds 

Y 

Y 

Y 

Y 

N 

The primary and secondary institution roles assigned to this user. The primary institution role is the first item in the list, followed by all secondary institution roles sorted alphabetically. 

systemRoleIds 

Y 

Y 

Y 

Y 

N 

The system roles (the administrative user roles in the UI) for this user. The first role in this list is the user's primary system role, while the remaining are secondary system roles. Values can be: 'SystemAdmin', 'SystemSupport', 'CourseCreator', 'CourseSupport', 'AccountAdmin', 'Guest', 'User', 'Observer', 'Integration', or 'Portal'. 

availability -> available 

N 

Y 

Y 

Y 

N 

Values can be: ‘Yes’, ‘No’, or ‘Disabled’. 

name -> given 

N 

Y 

Y* 

Y 

N 

The given (first) name of this user. 

name -> family 

N 

Y 

Y* 

Y 

N 

The family (last) name of this user. 

name -> middle 

N 

Y 

Y 

Y 

N 

The middle name of this user. 

name -> other 

N 

Y 

Y 

Y 

N 

The other name (nickname) of this user. 

name -> suffix 

N 

Y 

Y 

Y 

N 

The suffix of this user's name. Examples: Jr., III, PhD. 

name -> title 

N 

Y 

Y 

Y 

N 

The title of this user. Examples: Mr., Ms., Dr 

job -> title 

N 

Y 

Y 

Y 

N 

The user's job title. 

job -> department 

N 

Y 

Y 

Y 

N 

The department the user belongs to. 

job -> company 

N 

Y 

Y 

Y 

N 

The company the user works for. 

contact-> homePhone 

N 

Y 

Y 

Y 

N 

The user's home phone number. 

contact-> mobilePhone 

N 

Y 

Y 

Y 

N 

The user's mobile phone number. 

contact-> businessPhone 

N 

Y 

Y 

Y 

N 

The user's business phone number. 

contact-> businessFax 

N 

Y 

Y 

Y 

N 

The user's business fax number. 

contact-> email 

N 

Y 

Y 

Y 

N 

The user's email address. 

contact -> webPage 

N 

Y 

Y 

Y 

N 

The URL of the user's personal website. 

address -> street1 

N 

Y 

Y 

Y 

N 

The street address of the user. 

address -> street2 

N 

Y 

Y 

Y 

N 

An additional field to store the street address of the user. 

address -> city 

N 

Y 

Y 

Y 

N 

The city the user resides in. 

address -> state 

N 

Y 

Y 

Y 

N 

The state or province the user resides in. 

address -> zipCode 

N 

Y 

Y 

Y 

N 

The zip code or postal code the user resides in. 

address -> country 

N 

Y 

Y 

Y 

N 

The country the user resides in. 

locale -> id 

N 

Y 

Y 

Y 

N 

The locale specified by the user. This locale will be used anywhere the user is allowed to customize their locale; courses may force a specific locale, overriding the user's locale preference. 

locale -> calendar 

N 

Y 

Y 

Y 

N 

The calendar type specified by the user. Values can be: 'Gregorian', 'GregorianHijri', 'Hijri', or 'HijriGregorian' 

locale -> firstDayOfWeek 

N 

Y 

Y 

Y 

N 

The user's preferred first day of the week. Values can be: Sunday', 'Monday', or 'Saturday'. 

courseMembership -> userId 

N 

Y 

N 

N 

N 

The primary ID of the user. 

courseMembership -> courseid 

 

 

N 

N 

N 

The primary ID of the course. 

courseMembership -> 

availability -> available 

N 

Y 

N 

N 

N 

Values can be: ‘Yes’, ‘No’, or ‘Disabled’. 

courseMembership -> 

bypassCourseAvailabilityUntil 

N 

Y 

N 

N 

N 

If present, this date signals that the user associated with this membership has special access to the course regardless of the course's availability setting prior to the moment specified by this field. After the date has passed, the membership will respect the course's availability. 

courseMembership -> childCourseId 

N 

Y 

N 

N 

N 

The primary ID of the child, cross-listed course, in which the user is directly enrolled. 

courseMembership -> user-> userName 

N 

Y 

N 

N 

N 

The userName property, shown in the UI. 

courseMembership -> courseRoleId 

N 

Y 

N 

N 

N 

The user's role in the course. Value can be: 'Instructor', 'BbFacilitator', 'TeachingAssistant', 'CourseBuilder', 'Grader', 'Student', or 'Guest'. 

courseMembership -> created 

N 

Y 

N 

N 

N 

The date this membership was created. 

courseMembership -> dataSourceId 

N 

Y 

Y 

Y 

N 

The ID of the data source associated with this course. This may optionally be the data source's externalId using the syntax "externalId:math101". 

courseMembership -> id 

N 

Y 

Y* 

Y* 

Y* 

The unique ID of this course/user relationship. You can use this field to add or remove user from course. 

courseMembership -> lastAccessed 

N 

Y 

N 

N 

N 

This date signals the date this membership was used; in other words, the last date the user accessed the associated course or content contained by that course. 

The recording of any activity which would lead to this date getting updated does happen asynchronously in batches. So, there may be some delay between an activity which would update this value and the availability of the new date. It is recommended when using this value to note that activity within the last 5 minutes may not be taken into account. 

observers -> id 

N 

Y 

N 

N 

Y* 

The user ID. This may be the primary ID, or any of the secondary IDs prefixed with the ID type. 

observers -> userName 

N 

Y 

N 

Y 

N 

The userName property, shown in the UI. 

observees -> id 

N 

Y 

N 

N 

N 

The primary ID of the user. 

observees -> userName 

N 

Y 

N 

N 

N 

The userName property, shown in the UI. 

 

Notes: 

  • Users with the 'SystemAdmin' role are only included in the results if the logged in user also has this role. 
  • When creating observer/observee relationships, the user to be observed must not have the OBSERVER system role. Similarly, the user to observe must have the OBSERVER system role. 

Course Data Format 

We can use this data format in import mode to manage courses, groups, and group members. Operations include add, modify, and delete. 

Name 

MV 

Export 

Create 

Modify 

Delete 

Description 

id 

N 

Y 

N 

Y* 

Y* 

The primary ID of the course. 

uuid 

N 

Y 

N 

N 

N 

A secondary unique ID for the course. Used by LTI launches and other inter-server operations. 

parentId 

N 

Y 

N 

N 

N 

The cross-listed parentId associated with the course, if the course is a child course. 

dataSourceId 

N 

Y 

Y 

Y 

N 

The ID of the data source associated with this course. This may optionally be the data source's externalId using the syntax "externalId:math101".  

hasChildren 

N 

Y 

Y 

Y 

N 

True or False. Whether the course has any cross-listed children. 

parentId 

N 

Y 

N 

N 

N 

The cross-listed parentId associated with the course, if the course is a child course. 

externalAccessUrl 

N 

Y 

Y 

Y 

N 

An entry point URL for this Blackboard instance. 

guestAccessUrl 

N 

Y 

Y 

Y 

N 

A guest entry point URL for this Blackboard instance. 

locale -> id 

N 

Y 

Y 

Y 

N 

The locale of this course. 

locale -> force 

N 

Y 

Y 

Y 

N 

True or False. Whether students are forced to use the course's specified locale. 

externalId 

N 

Y 

Y 

Y 

N 

An optional externally-defined unique ID for the course. Defaults to the courseId. Formerly known as 'batchUid'. 

enrollment -> type 

N 

Y 

Y 

Y 

N 

Specifies the enrollment options for the course. Defaults to InstructorLed. Values can be: 'InstructorLed', 'SelfEnrollment', or 'EmailEnrollment'. 

enrollment -> accessCode 

N 

Y 

Y 

Y 

N 

The enrollment access code associated with this course. May only be set if enrollment.type is SelfEnrollment. 

enrollment -> end 

N 

Y 

Y 

Y 

N 

The date on which enrollment in this course ends. May only be set if enrollment.type is SelfEnrollment. 

enrollment -> start 

N 

Y 

Y 

Y 

N 

The date on which enrollments are allowed for the course. May only be set if enrollment.type is SelfEnrollment. 

availability -> available 

N 

Y 

Y 

Y 

N 

Values can be: ‘Yes’, ‘No’, ‘Term’, or ‘Disabled’. 

availability -> duration -> daysOfUse 

N 

Y 

Y 

Y 

N 

The number of days this course can be used. May only be set if availability.duration.type is FixedNumDays. 

availability -> duration -> end 

N 

Y 

Y 

Y 

N 

The date this course ends. May only be set if availability.duration.type is DateRange. 

availability -> duration -> start 

N 

Y 

Y 

Y 

N 

The date this course starts. May only be set if availability.duration.type is DateRange. 

availability -> duration -> type 

N 

Y 

Y 

Y 

N 

The intended length of the course. Possible values are: 'Continuous', 'DateRange', 'FixedNumDays', or 'Term'. 

closedComplete 

N 

Y 

Y 

Y 

N 

True or False. This status does not affect availability of the course for viewing in any way. closedComplete is valid for both Ultra and Classic courses. If an Ultra course is in closedComplete mode, updates are not possible. For a Classic course in closedComplete mode, updates are still possible (through Web UI but not through REST i.e. closed is enforced for original courses when updated through REST the same way Ultra courses are blocked) but new notifications are not generated. 

allowGuests 

N 

Y 

Y 

Y 

N 

True or False. Whether guests (users with the role guest) are allowed access to the course. Defaults to true. 

courseId 

N 

Y 

Y* 

Y 

N 

The course or organization ID. This may be the primary ID, or any of the secondary IDs prefixed with the ID type. 

description 

N 

Y 

Y 

Y 

N 

The description of the course. HTML compatible 

created 

N 

Y 

N 

N 

N 

The date this course was created. 

modified 

N 

Y 

N 

N 

N 

The date this object was last modified 

name 

N 

Y 

Y* 

Y 

N 

The name of the course. 

organization 

N 

Y 

Y 

Y 

N 

True or False. Whether this object represents an Organization. Defaults to false. 

termId 

N 

Y 

Y 

Y 

N 

The ID of the term associated to this course. This may optionally be the term's externalId using the syntax "externalId:spring.2016". 

ultraStatus 

N 

Y 

Y 

Y 

N 

Whether the course is rendered using Classic or Ultra Course View. Values can be: 'Undecided', 'Classic', 'Ultra', 'UltraPreview'. 

group -> availability->available 

N 

Y 

Y 

Y 

N 

Values can be: 'Yes', 'No', or 'SignupOnly'. 

group -> description 

N 

Y 

Y 

Y 

N 

The description of the group. This field supports Blackboard Markup Language. 

group -> externalId 

N 

Y 

Y 

Y 

N 

An externally-defined unique ID for the group. Defaults to a random UUID if not provided during create. 

group -> isGroupSet 

N 

Y 

Y 

Y 

N 

True or False. Whether or not this is a group set. 

group -> name 

N 

Y 

Y 

Y 

N 

The title of the group. 

group -> parentId 

N 

Y 

Y 

Y 

N 

The primary ID of the group's parent group set. 

group -> uuid 

N 

Y 

N 

N 

N 

A system-wide unique identifier created by Learn. 

group -> id 

N 

Y 

Y* 

Y* 

Y* 

The primary ID of the group. 

group -> member -> membershipModifyType 

N 

N 

Y* 

Y* 

Y* 

** Important ** 

  • Used to add or delete members from groups.  
  • Must include group -> id, course -> id, and group -> member -> userId. 
  • Values can be: ‘add’ or ‘delete’. 

group -> member -> userId 

N 

Y 

Y 

Y 

N 

The user Id associated with this GroupMembership. 

group -> enrollment -> limit 

N 

Y 

Y 

Y 

N 

Must be a number. The maximum allowed enrollment size for self-enrolled groups. 

group -> enrollment-> signupSheet -> description 

N 

Y 

Y 

Y 

N 

The description of the signup sheet This field supports Blackboard markup language. 

group -> enrollment -> signupSheet -> name 

N 

Y 

Y 

Y 

N 

The name of the signup sheet. 

group -> enrollment -> 

signupSheet -> showMembers 

N 

Y 

Y 

Y 

N 

True or False. Indicates whether or not members can be seen by others prior to signing up. 

courseMembership -> userId 

N 

Y 

N 

N 

N 

The primary ID of the user. 

courseMembership -> courseid 

 

 

N 

N 

N 

The primary ID of the course. 

courseMembership -> 

availability -> available 

N 

Y 

Y 

Y 

N 

Values can be: ‘Yes’, ‘No’, or ‘Disabled’. 

courseMembership -> 

bypassCourseAvailabilityUntil 

N 

Y 

Y 

Y 

N 

If present, this date signals that the user associated with this membership has special access to the course regardless of the course's availability setting prior to the moment specified by this field. After the date has passed, the membership will respect the course's availability. 

courseMembership -> childCourseId 

N 

Y 

Y 

Y 

N 

The primary ID of the child, cross-listed course, in which the user is directly enrolled. 

courseMembership -> user-> userName 

N 

Y 

Y 

Y 

N 

The userName property, shown in the UI. 

courseMembership -> courseRoleId 

N 

Y 

Y 

Y 

N 

The user's role in the course. Value can be: 'Instructor', 'BbFacilitator', 'TeachingAssistant', 'CourseBuilder', 'Grader', 'Student', or 'Guest'. 

courseMembership -> created 

N 

Y 

N 

N 

N 

The date this membership was created. 

courseMembership -> dataSourceId 

N 

Y 

Y 

Y 

N 

The ID of the data source associated with this course. This may optionally be the data source's externalId using the syntax "externalId:math101". 

courseMembership -> id 

N 

Y 

Y* 

Y* 

Y* 

The unique ID of this course/user relationship. 

courseMembership -> lastAccessed 

N 

Y 

N 

N 

N 

This date signals the date this membership was used; in other words, the last date the user accessed the associated course or content contained by that course. 

The recording of any activity which would lead to this date getting updated does happen asynchronously in batches. So, there may be some delay between an activity which would update this value and the availability of the new date. It is recommended when using this value to note that activity within the last 5 minutes may not be taken into account. 

 

Note: Only users who belong to the targeted course can be added to the targeted course groups. 

InstitutionRole Data Format 

We can use this data format in import mode to manage InstitutionRoles. Operations include add, modify, and delete. 

The items in the MV (Multiple values), Export, Create, Modify, and Delete columns have these meanings: 

  • Y = Yes (Attribute is supported for this operation) 
  • N = No (Attribute is not supported for this operation) 
  • Y* = Required (attribute is mandatory for this operation) 
  • Y** = Conditionally Required. Depending on the action. The API requires this input 
  • NA = Not Applicable 

 

Name 

MV 

Export 

Create 

Modify 

Delete 

Description 

id 

N 

Y 

N 

Y* 

Y* 

The id associated with this institution role. 

roleId 

N 

Y 

N 

N 

N 

The String role key associated with this institution role. 

name 

N 

Y 

Y* 

Y 

N 

The title of this institution role. 

description 

N 

Y 

Y 

Y 

N 

The description of this institution role. 

custom 

N 

Y 

N 

N 

N 

Indicates if this institution role is custom. 

 

Note:  Users must have the entitlement 'system.institutionrole.MODIFY' to access this endpoint. 

SystemRole Data Format 

We can use this data format in import mode to manage SystemRoles. Operations include add, modify, and delete. 

The items in the MV (Multiple values), Export, Create, Modify, and Delete columns have these meanings: 

  • Y = Yes (Attribute is supported for this operation) 
  • N = No (Attribute is not supported for this operation) 
  • Y* = Required (attribute is mandatory for this operation) 
  • NA = Not Applicable 

Name 

MV 

Export 

Create 

Modify 

Delete 

Description 

id 

N 

Y 

N 

Y* 

Y* 

The id associated with this system role. 

roleId 

N 

Y 

N 

N 

N 

The identifier used to assign the system role. 

For system generated roles, this value will be one of AccountAdmin, CourseCreator, CourseSupport, Guest, Integration, Observer, Portal, SystemAdmin, SystemSupport, or User. 

 

For custom system roles, this will be the roleId entered during the creation of the role. Allowed characters for the custom roleId's are any letter, number, period, underscore and dash. 

name 

N 

Y 

Y* 

Y 

N 

The name of this role. 

description 

N 

Y 

Y 

Y 

N 

The description of this system role. 

custom 

N 

Y 

N 

N 

N 

Indicates if this system role is custom. 

 

Note:  Users must have the 'system.systemrole.manager.VIEW' entitlement. 

CourseRole Data Format 

We can use this data format in import mode to manage CourseRoles. Operations include add, modify, and delete. 

The items in the MV (Multiple values), Export, Create, Modify, and Delete columns have these meanings: 

  • Y = Yes (Attribute is supported for this operation) 
  • N = No (Attribute is not supported for this operation) 
  • Y* = Required (attribute is mandatory for this operation) 
  • Y** = Conditionally Required. Depending on the action. The API requires this input 
  • NA = Not Applicable 

Name 

MV 

Export 

Create 

Modify 

Delete 

Description 

id 

N 

Y 

N 

Y* 

Y* 

The unique identifier (Use for operations) 

roleId 

N 

Y 

N 

N 

N 

The identifier used to assign the course role to a course enrollment. 

For system defined course roles, this value will be one of Student, Instructor, TeachingAssistant, CourseBuilder, Grader or Guest. 

 

For custom course roles, this will be the roleId entered during the creation of the role. Allowed characters for the custom course roleId's are any letter, number, period, underscore and dash. 

nameForCourses 

N 

Y 

Y* 

Y 

N 

The role name presented to users when the course role is associated with a course. 

nameForOrganizations 

N 

Y 

Y* 

Y 

N 

The role name presented to users when the course role is associated with an organization. 

description 

N 

Y 

Y 

Y 

N 

Optional description of the course role. 

custom 

N 

Y 

Y 

Y 

N 

True or False. False if the course role exists as a system generated course role. True if the course role was created by an admin user. Both custom and system generated course roles can be modified, but only custom course roles can be deleted. 

actAsInstructor 

N 

Y 

Y 

Y 

N 

True or False. Implies access to unavailable courses, display in the Course catalog, and receiving email enrollment requests. 

Availability -> available 

N 

Y 

Y 

Y 

N 

Whether the course role is currently available to course enrollments, organization enrollments, both or neither. 

 

Valid values are: 

  • Course: Course Role is available to Course Enrollments. 
  • Organization: Course Role is available to Organization Enrollments. 
  • Both: Course Role is available to both Course and Organization Enrollments. 
  • None: Course Role is not available. 

 

Notes:   

  • If the logged in user has any of those course role entitlements for a Course where Course -> organization = false, then the user can see course roles where Availability -> Available = Course or CourseAndOrganization. 
  • If the logged in user has any of those course role entitlements for a Course where Course -> organization = true, then the user can see course roles where Availability -> Available = Organization or CourseAndOrganization. 

Set Filter 

In order to get specific data from the connected system, use the Filter export option. Filtering can be used during Lookup as shown in the next section. 

  1. Select the Filter option from the Export connector screen. Then click Set Filter. The below screen will be displayed. 

       

  1. The Attribute list shows the attributes that are available to filter for the selected data format. The attributes are specific for the data format. 
  1. The Comparison list shows the available operators for filtering. The available operators are: 
  1. Equal to 
  1. Greater than or equal to 
  1. Less Than 
  1. Contains 
  1. The value will be used to do the filtering in conjunction with the comparison operator.  
  1. The Condition List displays the following filtering conditions being configured: 
  1. Add will add the configured condition to the list of conditions 
  1. Delete will delete the highlighted condition from the list of conditions 
  1. Clear will clear the list of conditions 

Note: Every condition added to the list of condition is considered as an AND operation. Only one condition per attribute is allowed. As conditions are added to the list of conditions a filter will be displayed in the Filter Syntax The filter can be modified and created manually by checking the Edit Filter Manually check box. The manually created filter will go through a validation for the filter syntax. 

Lookup Data 

To lookup data from Blackboard, use the Lookup Data map rule. 

  1. Log in the Workflow and Connectivity studio and double-click the Data Mapper object on the Design pane. The Configure Data Mapper window displays. 
  1. Select the Lookup Data rule under the Mapping Rule column and then click the Source Value. 

The Configure Lookup window displays. 

                

  1. Select the Blackboard REST system from the Select System drop-down list. 
  1. In the Enter Lookup Prefix field, enter the prefix to be added to the lookup fields. 
  1. Select the Lookup Type (User, Course, SystemRole, InstitutionRole and CourseRole) from the drop-down list. 
  1. Select the lookup method By Id or By Filter.  
  1. Selecting By Filter the next field will change to Filter. Click the Build button to bring up the filter dialog. The Filter usage was explained earlier in section Set Filter. 
  1. Selecting the By Id changes the filed to the corresponding Id. Click Pick to select the Id value as attribute/variable/literal. 
  1. The Fields section is used to define the attributes to be exported from the lookup. 
  1. Select the Exit as Mapper Task Failed on Lookup Failure check box to exit the task with failed status on lookup failure. It will not process the succeeding entries and will ignore the already processed entries and will not return any data. This is selected by default. 
  1. Click OK.  

 

Was this article helpful?