Pearson
Always Learning

Overview

The Users and Enrollments SIS API combines both user creation and user enrollment operations. Using this system you can:

  • Create a user
  • Update user details
  • Enroll a user in a course
  • Drop a user from a course

Our Users and Enrollments API is based on the IMSGlobal Enterprise Specification v1.1. This page of documentation summarizes what you need to work with this API, but you can also read the Pearson LearningStudio Annotated Guide to the IMS Specification

Users and Enrollments are either synchronous or asynchronous depending on how many enrollments you need to process at once. If you do single-user-single-course operations, the ProcessSingleRequest operation can do that work immediately. If you want to send multiple-user changes or multiple-course enrollments through at once (including one user to many courses), the ProcessRequest operation will queue the operation and it will be completed within the next 24 hours. Using single operations, you can reflect changes in your SIS immediately in LearningStudio.

Accessing the User Management Service

LearningStudio requires a username and password to access the API web services. Your SCO representative should have provided you with the necessary credentials. These credentials are included in the SOAP header.

Element Description
Operation ProcessSingleRequest (for single-user operations)
ProcessRequest (for multiple-user batches)
End-point / URL https://campusapi.ecollege.com/UserManagement/v1_6/UserManagementServices.asmx
WSDL Download the WSDL file

Tip: If you are programming in .NET, use WSE 3.0 for communicating with Users & Enrollments services.

Request Header

All requests must include a WS-Security SOAP Header with the username and password for your campus' SIS system. Your SOAP library is likely capable of creating this header for you. For more information on the requirements, see SOAP API Security.

Below is a sample header for Users & Enrollments requests:

<header>
    <security mustunderstand="1">
        <timestamp id="...">
            <created>{UTC_TIMESTAMP}</created>
            <expires>{UTC_TIMESTAMP}</expires>
        </timestamp>
        <usernametoken id="...">
            <username>{USERNAME}</username>
            <password type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest">{PASSWORD_DIGEST}</password>
            <nonce>{RANDOM_VALUE}</nonce>
            <created>{UTC_TIMESTAMP}</created>
        </usernametoken>
    </security>
</header>

Request Body

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">
    <comments>Example Here</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
            ↳source
An arbitrary string identifying the source system. Standard practice is to use your client string. 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
    ↳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 and user passwords have been configured in the API settings to be "auto-generated".
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. Required
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/>
            <id/>
        </sourcedid>
        <userid password="plainTextPassword"/>
        <name>
            <n>
                <family/>
                <partname partnametype="Middlename"/>
            </n>
        </name>
        <demographics>
            <gender/>
            <bday/>
            <disability/>
        </demographics>
        <email/>
        <tel teltype="Voice"/>
        <ad>
            <street/>
            <street/>
            <locality/>
            <region/>
            <pcode/>
        </ad>
        <extension>
            <personproperty properytype="property1Name"/>
            <personproperty properytype="property2Name"/>
        </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/>
            <id/>
        </sourcedid>
        <grouptype>
            <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/>
            <id/>
        </sourcedid>
        <member>
            <sourcedid>
                <source/>
                <id/>
            </sourcedid>
            <role>
                <subrole/>
            </role>
        </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.

If you are working on the Sandbox Campus, you can use these role types for testing. These may be different from what you will use in production on your primary campus.

  • 1 = Professor
  • 2 = Student
  • 9 = Teaching Assistant
  • 5 = Dropped User

Complete Example

This is an example of a complete request body:

<enterprise>
  <properties lang="en" xml:lang="en">
    <comments/>
    <datasource>OurSIS-Version</datasource>
    <datetime>YYYY-MM-DDT07:00:00Z</datetime>
  </properties>
  <person>
    <sourcedid>
      <source>strata</source>
      <id>0123-123-234</id>
    </sourcedid>
    <userid password="abcd1234">arthurdent</userid>
    <name>
      <n>
        <family>Dent</family>
        <given>Arthur<partname partnametype="Middlename">Percy</partname></given>
      </n>
    </name>
    <demographics>
      <gender>male</gender>
      <bday>2014-01-01</bday>
      <disability/>
    </demographics>
    <email>arthurdent@student.strata.edu</email>
    <tel teltype="Voice">303-555-1234</tel>
    <ad>
      <street>10 Hereville Lane</street>
      <locality>Denver</locality>
      <region>CO</region>
      <pcode>80000</pcode>
    </ad>
    <extension>
      <personproperty properytype="assistiveTechnology">towel</personproperty>
    </extension>
  </person>
  <group>
    <sourcedid>
      <source>strata</source>
      <id>Spr14_Math_101.112233</id>
    </sourcedid>
    <grouptype>
      <typevalue>Call Number</typevalue>
    </grouptype>
  </group>
  <membership>
    <sourcedid>
      <source>strata</source>
      <id>Spr14_Math_101.112233</id>
    </sourcedid>
    <member>
      <sourcedid>
        <source>strata</source>
        <id>0123-123-234</id>
      </sourcedid>
      <role>
        <subrole>2</subrole>
      </role>
    </member>
  </membership>
</enterprise>

Executing the Operation: Single and Batch Operations

If you want to perform the operation with a single user and single enrollment, you will have a payload like the previous section with a single properties,person,group, and membership element under the top level enterprise element. Setting up your SOAP client with the Users and Enrollments endpoint and WSDL, you'll use the ProcessSingleRequest method.

If you want to send a batch request with multiple users and enrollments, you will use the batch request method, ProcessRequest. This applies to any request that involves multiple persons or groups, including one person to many groups, or many groups to a single person.

Creating the Batch Request

The format of a batch request is virtually the same as a single request, except you will 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/>
  <person id="A"/>
  <person id="B"/>
  <person id="C"/>
  <group id="1"/>
  <group id="2"/>
  <group id="3"/>
  <memebrship id="1"/>
  <member id="A"/>
  <member id="B"/>
  <member id="C"/>
  <memebrship id="2"/>
  <member id="A"/>
  <member id="B"/>
  <member id="C"/>
  <memebrship id="3"/>
  <member id="A"/>
  <member id="B"/>
  <member id="C"/>
</enterprise>

Response

Single Operations

When using ProcessSingleRequest to process a single user-course enrollment, the API will return the enterprise payload, with the person and membership elements each holding an additional extension element. The additional element will be a string of XML, that when parsed, has the following elements.

Element Description
Result Top level element in the extension XML string. This element has an attribute of type, which contains "Success" when the operation was successful.
Result
    ↳Code
A result or error code for the user operation.
Result
    ↳Message
A result or error code for the user operation.

Sample Response

Here is what the above Complete Sample would look like when returned from a ProcessSingleRequest operation:

<enterprise>
  <properties lang="en" xml:lang="en">
    <comments/>
    <datasource>OurSIS-Version</datasource>
    <datetime>YYYY-MM-DDT07:00:00Z</datetime>
  </properties>
  <person>
    <sourcedid>
      <source>strata</source>
      <id>0123-123-234</id>
    </sourcedid>
    <userid password="abcd1234">arthurdent</userid>
    <name>
      <n>
        <family>Dent</family>
        <given>Arthur<partname partnametype="Middlename">Percy</partname></given>
      </n>
    </name>
    <demographics>
      <gender>male</gender>
      <bday>2014-01-01</bday>
      <disability/>
    </demographics>
    <email>arthurdent@student.strata.edu</email>
    <tel teltype="Voice">303-555-1234</tel>
    <ad>
      <street>10 Hereville Lane</street>
      <locality>Denver</locality>
      <region>CO</region>
      <pcode>80000</pcode>
    </ad>
    <extension>
      <!--[CDATA[ <Result xmlns="" type="Success"><Code>0</Code><Message>User created</Message></Result> ]]-->
    </extension>
  </person>
  <group>
    <sourcedid>
      <source>strata</source>
      <id>Spr14_Math_101.112233</id>
    </sourcedid>
    <grouptype>
      <typevalue>Call Number</typevalue>
    </grouptype>
  </group>
  <membership>
    <sourcedid>
      <source>strata</source>
      <id>Spr14_Math_101.112233</id>
    </sourcedid>
    <member>
      <sourcedid>
        <source>strata</source>
        <id>0123-123-234</id>
      </sourcedid>
      <role>
        <subrole>2</subrole>
        <extension>
          <!--[CDATA[ <Result xmlns="" type="Success"><Code>0</Code><Message>Course enrollment successful</Message></Result> ]]-->
        </extension>
      </role>
    </member>
  </membership>
</enterprise>

Note: If during pre-processing it is determined that the user already has the requested role in the course, no action will be taken and no additional extension element will be added to the membership element. If you see a extension element in the person element but no extension in the membership, you can determine that the user is enrolled. Any other outcome, will add the extension element with error code.

Batch Operations

When using ProcessRequest to process a single more than one user or enrollment action, the action is put into the processing queue the API will return a job ID for that queued operation. Here is a sample XML response from this operation:

<processrequestresponse xmlns="campusAPI.eclollege.com/UserManagement/V1.6">
  <processrequestresult>289460</processrequestresult>
</processrequestresponse>

Error Messages

For detailed information concerning possible error messages, see Common Error Codes.

3608 reads
Always Learning
Pearson