Pearson
Always Learning

Overview

XML is one of two file types that are supported by the asynchronous ("batch") creation or modification of user and enrollment information in LearningStudio. See Batch File Rules and Batch File Submissions for an overview of the Batch File processing, such as required configuration, high-level data flow, file naming conventions, etc. See Delimited Files for a description of the other supported file type.

Extensible Mark-up Language (XML) is a global standard supporting data transfer and processing between systems. The Batch Files system adheres to the IMS Enterprise v1.1 XML schema for user and enrollment information. This is a standardized XML schema (XSD) defined to support the integration of education-specific technology between multiple Educational Partners and systems. See IMS Global Learning Consortium for more detailed information about the IMS Enterprise XML schema.

The information within this page addresses only what you will need to support the Batch Files system. Using this XML schema, you will have expanded functionality and finer control of the data to be updated in LearningStudio; however, you must be familiar with these standards to ensure that you understand the impacts of your changes.

Differences from Delimited Files

Following are some of the features supported within the XML file type that are not supported by the delimited file format:

  • Ability to modify a user's login information after the user record has been created - this feature is available only if the configuration Update User Properties is set to Yes.
  • Ability to create extended user fields
  • Ability to create custom user properties

Note: If your data file includes cumulative data (multiple transactions for the same user where some of the transactions have been previously applied), you cannot use the XML file type and must use the delimited file format for your batch data file. See Batch File Submissions for a description of cumulative files. See Delimited Files for more information about delimited files.

XML Element Structure, File Layout, and Details

The Pearson LearningStudio Annotated Guide to the IMS Enterprise Specification and eCollege Extensions document describes in detail the elements, attributes, structure, etc., required for the Batch API XML document.This page of documentation summarizes what you need to work with these files but we suggest reading through the official guide as well.

The request body for these services is is an XML document comprised a top-level element called enterprise, with at least four types of child elements under it:

The <properties></properties> element includes some basic information about the data being sent to LearningStudio.

<person></person> represents the details for a user - such as their name, email, password, etc.

<group></group> represents a LearningStudio course or an enrollable node's client sort string. Users must be enrolled in a course's node to be enrolled in the course, so if they are not already in the node, LearningStudio will enroll them in the parent node as well.

<membership></membership> represents a user's role in the group (either their node role or their course role). You'll use the Role IDs as specified below.

If doing a single-user request, there is only one of each of these elements under <enterprise></enterprise>. If doing a batch enrollment, you will include multiple <person></person>, <group></group>, and <membership></membership> elements. See the last section of this page for how to set up a batch request.

Note that these elements should always be in this order under <enterprise></enterprise>.

Properties

The properties element gives information about the data being sent to LearningStudio. The following table outlines the elements in the properties element. Remember, properties is a child of the top-level element, enterprise.

Element Description Required?
properties

Container for properties information.

Attributes:

lang
Identifies the language used for the data (optional)
Required
properties
    ↳comments
Any text that describes something about the transaction. Generally this is not used. Optional
properties
    ↳datasource
The source of the data. The element must be there but it needn't necessarily have a value. Required
properties
    ↳datetime
The data and time of the data creation. The element must be there but it needn't necessarily have a value. Required

Request Body Sample

Here is a text view of the properties element in context:

<enterprise><properties lang="en" xml:lang="en" xml:lang="en"><comments></comments><datasource>OurSIS-Version</datasource><datetime>YYYY-MM-DDT07:00:00Z</datetime></properties></enterprise>

Person

The person element defines all of the properties of a user (but nothing about their relationship to a course or to your online campus). The following table outlines the elements in the person element. Remember, person is a child of the top-level element, enterprise.

Element Description Required?
person Container for all person elements Required
person
    ↳sourcedid
Container for your system's identifier for this user. Required
person
    ↳sourcedid
            ↳id
Your system's identifier for this user (e.g., student ID number or primary key in your SIS). This is not used in LearningStudio other than to find and update the user through this API. Required
person
    ↳sourcedid
            ↳source
An arbitrary string identifying the source system. Standard practice is to use your client string. Required
person
    ↳userid

The username that the user will use in LearningStudio (also called the login ID). Even if you handle user management and will SSO into LearningStudio, a username is required.

Attribute:

password
Provide the user's plaintext password for signing into LearningStudio. This is optional if you'll be SSO-ing into LearningStudio.
Required
person
    ↳name
Container for the user's name information. Required
person
    ↳name
            ↳n
Container for the user's name information. Required
person
    ↳name
            ↳n
                   ↳family
The user's last name (family name). Required
person
    ↳name
            ↳n
                   ↳given
The user's first name (given name). Required
person
    ↳name
            ↳n
                   ↳partname
Use this element with an attribute & value of partnametype="Middlename" for the user's middle name. Optional
person
    ↳demographics
Container for the user's demographic information. Optional
person
    ↳demographics
            ↳gender
Use either male or female. Optional
person
    ↳demographics
            ↳bday
The user's birthdate in YYYY-MM-DD format. Optional
person
    ↳demographics
            ↳disability
A freetext description of the user's disability. Optional
person
    ↳email
The user's email address. If you want LearningStudio to send any email (either on enrollment or from inside a course), this element should be included. Optional
person
    ↳tel
The user's telephone number. Use with an attribute of teltype="Voice". This updates the user's daytime phone record in LearningStudio. Optional
person
    ↳adr
Container element for the user's address. Optional
person
    ↳adr
            ↳street
The user's street address. Repeat for additional street lines (e.g., apartment number). The first instance of this element is saved as Street Line 1, second instance as Street Line 2, etc. Optional
person
    ↳adr
            ↳locality
The user's city. Optional
person
    ↳adr
            ↳region
The user's state (US/Mexico), province (Canada), or other regional identifier. Optional
person
    ↳adr
            ↳pcode
The user's postal code. Optional
person
    ↳extension
Container element for extended user properties. Extended user properties are primarily used in our Enterprise Reporting product rather than day-to-day LearningStudio usage. Optional
person
    ↳extension
            ↳personproperty
Use one of these elements for every extended user property you're writing or updating. Use an attribute of propertytype="{key}" for the property's name (e.g., "MothersMiddleName"). Optional

Request Body Sample

Here is a text view of the person element in context:

<enterprise><person recstatus="nul"><sourcedid><source></source><id></id></sourcedid><userid password="plainTextPassword"></userid><name><n><family></family><partname partnametype="Middlename"></partname></n></name><demographics><gender></gender><bday></bday><disability></disability></demographics><email></email><tel teltype="Voice"></tel><ad><street></street><street></street><locality></locality><region></region><pcode></pcode></ad><extension><personproperty properytype="property1Name"></personproperty><personproperty properytype="property2Name"></personproperty></extension></person></enterprise>

Group

A group can be used to identify either a course or an enrollable node. The following table outlines the elements in the group element. Remember, group is a child of the top-level element, enterprise.

Element Description Required?
group Container for all group elements Required
group
    ↳sourcedid
Container for your system's identifier for this course or enrollable node. Required
group
    ↳sourcedid
            ↳source
If this group is a course, use your client string as the value.

If this group is an enrollable node, used ECLG.

Required
group
    ↳sourcedid
            ↳id
Either:
  • The course call number
  • The client sort string (e.g., strata.business.)
Required
group
    ↳grouptype
Container for the elements that define what kind of group this is (course or enrollable node). Required
group
    ↳grouptype
            ↳typevalue
If this group is a course, use Call Number as the value.

If this group is an enrollable node, used Enrollable Node as the value.

Required

Request Body Sample

Here is a text view of the group element in context:

<enterprise><group><sourcedid><source></source><id></id></sourcedid><grouptype><typevalue></typevalue></grouptype></group></enterprise>

Membership

The membership element defines the relationship between a person and a group. The following table outlines the elements in the membership element. Remember, membership is a child of the top-level element, enterprise.

Element Description Required?
membership Container for all membership elements Required
membership
    ↳sourcedid
Container for your system's identifier for the group. Required
membership
    ↳sourcedid
            ↳source
This element should exactly match the group \ sourcedid \ source value for the group you're enrolling the person into. Required
membership
    ↳sourcedid
            ↳id
This element should exactly match the group \ sourcedid \ id value for the group you're enrolling the person into. Required
membership
    ↳member
Container for the user and user role being enrolled in the group. Required
membership
    ↳member
            ↳sourcedid
Container for your system's identifier for the person. Required
membership
    ↳member
            ↳sourcedid
                   ↳source
This element should exactly match the person \ sourcedid \ source value for the person you're enrolling into the group. Required
membership
    ↳member
            ↳sourcedid
                   ↳id
This element should exactly match the person \ sourcedid \ id value for the person you're enrolling into the group. Required
membership
    ↳member
            ↳role
Container for your system's identifier for the person. Required
membership
    ↳member
            ↳role
                   ↳subrole
The LearningStudio Role ID for this user. See the "Role Types" section below. Required

Request Body Sample

Here is a text view of the membership element in context:

<enterprise><membership><sourcedid><source></source><id></id></sourcedid><member><sourcedid><source></source><id></id></sourcedid><roletype><subrole></subrole></roletype></member></membership></enterprise>

Role Types

LearningStudio defines roles in a very granular fashion, tailored to the needs of each EP and the standard role types for role are not specific enough. Your Strategic Customer Operations team can provide the specific role IDs to use for your campus.

If you want to unenroll a user from a course or node, you use this same approach, but set the Role ID to the "Dropped User" value for your campus. Your SCO team will provide this.

Batching Many Records in One File

To batch together many users or enrollments, include multiple person and group elements, one for each user or course. Then you will have a membership element for each person-group combination.

Always place the elements in the order specified above, and group them by element type; that is, all the persons should come first, followed by the groups and the memberships. Here's a sample file layout. The id attributes are not part of the standard, they merely demonstrate the relationships..

<enterprise><properties></properties><person id="A"></person><person id="B"></person><person id="C"></person><group id="1"></group><group id="2"></group><group id="3"></group><memebrship id="A-1"></memebrship><memebrship id="A-2"></memebrship><memebrship id="A-3"></memebrship><memebrship id="B-1"></memebrship><memebrship id="B-2"></memebrship><memebrship id="B-3"></memebrship><memebrship id="C-1"></memebrship><memebrship id="C-2"></memebrship><memebrship id="C-3"></memebrship></enterprise>

Complete XML File Samples

The following sections contain samples of XML data files to support typical types of processing.

Batch Enrollment

<!--The example below is a sample batch enrollment where 5 users are enrolled in a course -->
<enterprise xmlns="http://schemas.ecollege.com/Common/2006/01/ims_epv1p1.xsd"><properties><datasource></datasource><datetime></datetime></properties><person><sourcedid><source>gbtestc</source><id>user1</id></sourcedid><userid password="password">user1</userid><name><fn></fn><n><family>Test</family><given>User1</given></n></name><email>User1@test.edu</email></person><person><sourcedid><source>gbtestc</source><id>user2</id></sourcedid><userid password="password">user2</userid><name><fn></fn><n><family>Test</family><given>User2</given></n></name><email>User2@test.edu</email></person><person><sourcedid><source>gbtestc</source><id>user3</id></sourcedid><userid password="password">user3</userid><name><fn></fn><n><family>Test</family><given>User3</given></n></name><email>User3@test.edu</email></person><person><sourcedid><source>gbtestc</source><id>user4</id></sourcedid><userid password="password">user4</userid><name><fn></fn><n><family>Test</family><given>User4</given></n></name><email>User4@test.edu</email></person><person><sourcedid><source>gbtestc</source><id>user5</id></sourcedid><userid password="password">user5</userid><name><fn></fn><n><family>Test</family><given>User5</given></n></name><email>User5@test.edu</email></person><group><sourcedid><source>gbtestc</source><id>ACCT4430JB</id></sourcedid><grouptype><typevalue level="">Call Number</typevalue></grouptype><description><short></short></description></group><membership><sourcedid><source>gbtestc</source><id>ACCT4430JB</id></sourcedid><member><sourcedid><source>gbtestc</source><id>user1</id></sourcedid><idtype></idtype><role><subrole>2</subrole><status></status></role></member><member><sourcedid><source>gbtestc</source><id>userh2</id></sourcedid><idtype></idtype><role><subrole>2</subrole><status></status></role></member><member><sourcedid><source>gbtestc</source><id>user3</id></sourcedid><idtype></idtype><role><subrole>2</subrole><status></status></role></member><member><sourcedid><source>gbtestc</source><id>user4</id></sourcedid><idtype></idtype><role><subrole>2</subrole><status></status></role></member><member><sourcedid><source>gbtestc</source><id>user5</id></sourcedid><idtype></idtype><role><subrole>2</subrole><status></status></role></member></membership></enterprise>

Course Enrollment

<!--The example below is a course enrollment. If the user does not already exist, they will be implicitly created.
 User will be created in the LearningStudio system and enrolled in the specified course.-->
<enterprise xmlns="http://schemas.ecollege.com/Common/2006/01/ims_epv1p1.xsd"><properties><datasource></datasource><datetime></datetime></properties><person><sourcedid><source>gbtestc</source><!--Required.  We recommend using the client sort string for the Campus--><id>1122534</id><!--Required. This must be a unique id. We recommend using the users id within your SIS--></sourcedid><userid password="password">eliasp</userid><!--Required for user creation, LoginID--><name><fn></fn><n><family>Student</family><!--Required for user creation, Last Name--><given>Test</given><!--Required for user creation, First Name--></n></name><email>teststudent@test.edu</email><!--Required for user creation, Email Address--></person><group><!--Required for any type of enrollment--><sourcedid><source>gbtestc</source><!--Required for course enrollment. We recommend using the client sort string for the Campus--><id>UNAPECTEST</id><!--Required for course enrollment. This will be the call number assigned to the course.--></sourcedid><grouptype><typevalue>Call Number</typevalue><!--Required for course enrollment. This must contain "Call Number"--></grouptype><description><short></short></description></group><membership><!--Required for any type of enrollment. Tells the service which person to enroll into a given group; think of a Course Roster.--><sourcedid><source>gbtestc</source><!--Required for course enrollment.--><id>UNAPECTEST</id><!--Required for user creation. This identifies the group users should be enrolled into--></sourcedid><member><sourcedid><source>gbtestc</source><!--Required. --><id>1122534</id><!--Required. This identifies the user that should be enrolled in the group above--></sourcedid><idtype></idtype><role><subrole>1</subrole><!--Required for course enrollment.  Denotes the LearningStudio Role ID; 1 is the Professor Role ID--><status></status></role></member></membership></enterprise>

User Course Drop

<!--The example below is a course enrollment drop. The drop is triggered by the Role ID 5 in the subrole.-->
<enterprise xmlns="http://schemas.ecollege.com/Common/2006/01/ims_epv1p1.xsd"><properties><datasource></datasource><datetime></datetime></properties><person><sourcedid><source>EPTest</source><!--Required.--><id>123456789</id><!--Required.--></sourcedid><userid password="ChangeMe">tStudent</userid><!--Required.--><name><fn></fn><n><family>Student</family><!--Required.--><given>Test</given><!--Required.--><partname partnametype="Middlename">Test</partname></n></name><email>teststudent@test.edu</email><!--Required.--><tel>3035555555</tel><adr><street>148 Main St</street><locality>Aurora</locality><region>CO</region><pcode>80015</pcode><country>USA</country></adr><extension><!--Example of using Extended User Properties--><personproperty propertytype="DegreeInterest">Business Administration - MBA</personproperty><personproperty propertytype="SchoolIDCode">Denver</personproperty><personproperty propertytype="StartDate">10/23/2008</personproperty></extension></person><group><!--Required for any type of enrollment--><sourcedid><source>EPTest</source><!--Required for course enrollment.--><id>201008.ACCT6480.001</id><!--Required for course enrollment. This will be the call number assigned to the course.--></sourcedid><grouptype><typevalue>Call Number</typevalue><!--Required for course enrollment. This must contain "Call Number"--></grouptype><description><short></short></description></group><membership><!--Required for any type of enrollment.--><sourcedid><source>EPTest</source><!--Required.--><id>201008.ACCT6480.001</id><!--Required .--></sourcedid><member><sourcedid><source>EPTest</source><!--Required. --><id>123456789</id><!--Required. This identifies the user--></sourcedid><idtype></idtype><role><!--Required for any type of enrollment process. Static.--><subrole>5</subrole><!--Required for drop of course enrollment.   5 is the Drop Role Id.--><status></status></role></member></membership></enterprise>

User Update

<!--The example below is a user property update. Any property set as updatable in the LearningStudio system is required.-->
<enterprise xmlns="http://schemas.ecollege.com/Common/2006/01/ims_epv1p1.xsd"><properties><datasource></datasource><datetime></datetime></properties><person><sourcedid><source>EPTest</source><!--Required.  We recommend using the client sort string for the Campus--><id>123456789</id><!--Required. This must be a unique id. We recommend using the users id within your SIS--></sourcedid><userid password="ChangeMe">tStudent</userid><!--Required if property updateable--><name><fn></fn><n><family>Student</family><!--Required if property updateable--><given>Test</given><!--Required if property updateable--><partname partnametype="Middlename">Test</partname><!--Required if property updateable--></n></name><email>teststudent@test.edu</email><!--Required if property updateable--><tel>3035555555</tel><!--Required if property updateable--><adr><street>148 Main St</street><!--Required if property updateable--><locality>Aurora</locality><!--Required if property updateable--><region>CO</region><!--Required if property updateable--><pcode>80015</pcode><!--Required if property updateable--><country>USA</country></adr><extension><!--Example of using Extended User Properties--><personproperty propertytype="DegreeInterest">Business Administration - MBA</personproperty><personproperty propertytype="SchoolIDCode">Denver</personproperty><personproperty propertytype="StartDate">10/23/2008</personproperty></extension></person></enterprise>

Common File Errors

The following are some of the more common errors encountered when submitting an XML data file.

Error Possible Causes Suggested Solutions
Special characters in file name The file name should be formatted as: ClientString_DD_MM_YYYY.xml. The file name cannot contain special characters such as ( ) , " " & @ and so on. Confirm file name is properly formatted and does not contain special characters.
Invalid file extension The XML data file must have a *.xml extension. Save file in correct format and with correct extension.
Missing required field Make sure all required fields contain data. An element may contain the wrong type of data.
  •  column has appropriate data.
  • If you are modifying an existing user's information, the login Id is required.
Unexpected or failed data updates.
  • Special characters, such as apostrophes, in data can cause the XML file to be processed incorrectly because they are seen as XML control characters.
  • Report special characters, if appropriate.
  • Escape required special characters
Invalid email address Each user must have only one email address.
  • Confirm that no more than one email address has been added for a user.
  • The email address must be fully qualified (for example, "john@institution.com"). The API will check for a valid email format.
  • The email address column cannot be left blank for a new user.
Large batch data file or cumulative file Large or cumulative files that are fomatted correctly should process successfully; however, they are prone to errors and system-time outs. Batch File Submission for suggestions/rules to help ensure proper processing of large data files or cumulative files.
File upload timed out File is too large or too complex. Connectivity may have been lost during transfer.
  • Break up large data files into more manageable sizes.
  • for more information).
  • Confirm that there were no issues with your network or connectivity during the file transfer.
  •  for suggestions/rules to help ensure proper processing of large data files or cumulative files.
Missing required element Make sure all required elements contain data. A data element may contain the wrong type of data.
  • If you adding a new user record, make sure all required data is provided.
  • If you are modifying an existing user's information, the login Id is required.
Missing password and auto-generate passwords is not enabled configuration is not set to Yes, you must provide a password for each new user.
  • Provide a valid password for each new user.
  •  configuration to Yes to auto-generate passwords for new users.
Invalid Login Id The login Id cannot contain any of the following special characters: % ] [ + < > ; " ' = : / | \ _ Confirm the login Id does not contain special characters.
Invalid Password The password cannot contain any of the following special characters: % ] [ + < > ; " ' = : / | \ _ Confirm the password does not contain special characters.
Invalid Role Id  for more information. Confirm the Role Id is set to one of the approved ennumerable values.
Specified Node Sort String is unenrollable Users cannot be enrolled in node unless the node is configured to be enrollable
  • Confirm node is enrollable.
  • Change value to enrollable node.
Failed attempt to drop user from node with section enrollments A user can only be dropped from a node when (1) they are not enrolled in any sections within that node, and (2) they are enrolled in at least one other node. Confirm user is not enrolled in any of the node's sections and/or is enrolled in another node.
Failed attempt to drop user from last enrollable node Dropping users from their last node causes them to no longer be associated with the Educational Partner. The API cannot drop a user from their last enrollable node.  
Login Id is not unique for explicit user creation The user has already been created in LearningStudio; the login Id in the data file is already in use and cannot be assigned to a new user.
  • Confirm that the login Id does not already exist in LearningStudio for another user.
  • Confirm that the user does not already have information in LearningStudio and thus should not be added as a new user.
Failed to drop a user who is not enrolled in the section The user is not enrolled in the section and a DROP (Role Id: 5) action is passed for the user. Confirm the correct section number was provided.
Failed to enroll a user when the add date is in the past  tab in the Administrative Pages UI.  
Failed to drop a user when the drop date is in the past  tab in the Administrative Pages UI.  
Professor enrollment attempted for a user already enrolled as a Student on the node For security purposes, a user that is enrolled in a node as a Student cannot be enrolled in a section as a Professor. Change the enrollment role for the user to the appropriate Role ID.
Failed to enroll a user in a section where the enrollment max has been reached  section of the Administrative Pages UI.  
Failed to enroll a user as a waitlist student where the waitlist max has been reached section of the Administrative Pages UI.  
Failed attempt to add/update an Admin role type For security purposes, the API will not create, enroll, or update an Administrator account. Confirm that the correct Role Id was used.
4267 reads
Always Learning
Pearson