Integrations Documentation

The Person Management Service (PMS)

This service is used to affect Brightspace user accounts.

Implemented operations

deletePerson
replacePerson
readPerson

Preferred First and Last Names

Clients using LIS 2.0 can include and maintain users preferred names using XML tags in an LIS integration. Below are the rules that IPSIS follows when the SIS is allowed to overwrite a user’s preferred names in Brightspace:

If LIS has an empty preferred first name for a user who has a preferred first name in Brightspace, delete preferred first name.
If LIS has an empty preferred last name for a user who has a preferred last name in Brightspace, delete preferred last name.
If LIS has the preferred name block, and it only includes preferred last name, do nothing with preferred first name and update preferred last name in Brightspace.
If LIS has the preferred name block, and it only includes preferred first name, do nothing with preferred last name and updated preferred first name in Brightspace.
When the Preferred Name block is missing from the request, delete the first and last preferred names.
If LIS has the preferred name block and first and last name is present, overwrite preferred first or last name in Brightspace.

Note: The Preferred NameType contains the preferred name information of a user, and may be sent alongside the rest of the name and partname as part of a Person object.

For clients using IPSIS V1.0:

PersonRequestPreferredFirstAndLastNameOptionalTranslator can go anywhere in the list.
ReplaceUserPreferredFirstNameNoUpdateHandler and ReplaceUserPreferredLastNameNoUpdateHandler must go before ReplaceUserSaveLMSHandler

About the deletePerson operation

The deletePerson operation is used to delete users from Brightspace.

Process flow: deletePerson

When a LIS deletePerson request is received, the adapter obtains the unique id for the user from the sourcedId field of the request directly, without the use of a pluggable translator.
Once the Person Id has been obtained, the IPSIS Platform handlers configured for IDeleteUserHandler are used to process the request.
The LIS response is generated from the handler response.

Sample deletePerson request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"

     xmlns:ims="http://www.imsglobal.org/services/lis/mms2p0/wsdl11/sync/imsmms_v2p0">

   <soapenv:Header>

      <ims:imsx_syncRequestHeaderInfo>

         <ims:imsx_version>V1.0</ims:imsx_version>

         <ims:imsx_messageIdentifier>1234</ims:imsx_messageIdentifier>

      </ims:imsx_syncRequestHeaderInfo>

   </soapenv:Header>

   <soapenv:Body>

      <ims:deletePersonRequest>

         <ims:sourcedId>Demo_User</ims:sourcedId>

      </ims:deletePersonRequest>

   </soapenv:Body>

</soapenv:Envelope>

deletePerson request header and body fields

Request header fields

For more information, refer to the topic Using LIS v2.0 Services > Request and response headers.

Request body fields

The adapter accepts the following fields in the request:

Property	LIS Request Mapping	Required
Code	deletePersonRequest.sourcedId	Yes

Sample deletePerson response

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">

   <s:Header>

      <h:imsx_syncResponseHeaderInfo

          xmlns:h="http://www.imsglobal.org/services/lis/mms2p0/wsdl11/sync/imsmms_v2p0"

          xmlns="http://www.imsglobal.org/services/lis/mms2p0/wsdl11/sync/imsmms_v2p0"

          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

          xmlns:xsd="http://www.w3.org/2001/XMLSchema">

         <imsx_version>V1.0</imsx_version>

         <imsx_messageIdentifier>MMS_deletePerson_20120120T191434_9913552Z</imsx_messageIdentifier>

         <imsx_statusInfo>

            <imsx_codeMajor>success</imsx_codeMajor>

            <imsx_severity>status</imsx_severity>

            <imsx_messageRefIdentifier>1234</imsx_messageRefIdentifier>

            <imsx_description/>

            <imsx_codeMinor>

               <imsx_codeMinorField>

                  <imsx_codeMinorFieldName>TargetEndSystem</imsx_codeMinorFieldName>

                  <imsx_codeMinorFieldValue>fullsuccess</imsx_codeMinorFieldValue>

               </imsx_codeMinorField>

            </imsx_codeMinor>

         </imsx_statusInfo>

      </h:imsx_syncResponseHeaderInfo>

   </s:Header>

   <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

       xmlns:xsd="http://www.w3.org/2001/XMLSchema"/>

</s:Envelope>

deletePerson response header and body fields

Response header fields

For more information, refer to the topic Using LIS v2.0 Services > Request and response headers.

Response body fields

No fields are returned in the response body.

About the replacePerson operation

The replacePerson operation is used to create or update Brightspace users.

When using the default configurations, upon success, you can validate the user has been created or updated as appropriate through the Manage Users tool in Brightspace.

Process flow: replacePerson

When an LIS replacePerson request is received, Brightspace translates the request using the LIS translators configured for ITranslatePerson to transform the request into a format that the IPSIS Platform can understand.
Once the request has been translated, the IPSIS Platform handlers configured for IReplaceUserHandler process the request.
An LIS response is generated from the handler response.

Sample replacePerson request

Note: This sample request includes an optional extension field (in bold) that provides the ability to change a user’s status after its initial creation. The extension field is required for this action because the user status doesn't match directly with a field from the LIS specification.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"

  xmlns:ims="http://www.imsglobal.org/services/lis/pms2p0/wsdl11/sync/imspms_v2p0">

   <soapenv:Header>

      <ims:imsx_syncRequestHeaderInfo>

         <ims:imsx_version>V1.0</ims:imsx_version>

         <ims:imsx_messageIdentifier>12346</ims:imsx_messageIdentifier>

      </ims:imsx_syncRequestHeaderInfo>

   </soapenv:Header>

   <soapenv:Body>

      <ims:replacePersonRequest>

         <!--Not Used by D2L-->

         <ims:sourcedId>Demo_User</ims:sourcedId>

         <ims:personRecord>

            <ims:sourcedGUID>

               <ims:sourcedId>Demo_User</ims:sourcedId>

            </ims:sourcedGUID>

            <!--Optional:-->

            <ims:person>

               <!--Zero or more repetitions:-->

               <ims:name>

                  <ims:nameType>

                     <ims:instanceIdentifier>

                        <ims:language>en-US</ims:language>

                        <ims:textString>Contact</ims:textString>

                     </ims:instanceIdentifier>

                     <ims:instanceVocabulary>http://www.imsglobal.org/lis/pmsv2p0/nametypevocabularyv1p0</ims:instanceVocabulary&gt;

                     <ims:instanceValue>

                        <ims:language>en-US</ims:language>

                        <ims:textString>Contact</ims:textString>

                     </ims:instanceValue>

                  </ims:nameType>

                  <!--1 or more repetitions:-->

                  <ims:partName>

                     <ims:instanceIdentifier>

                        <ims:language>en-US</ims:language>

                        <ims:textString>Contact-First</ims:textString>

                     </ims:instanceIdentifier>

                     <ims:instanceVocabulary>http://www.imsglobal.org/lis/pmsv2p0/partnamevocabularyv1p0</ims:instanceVocabulary&gt;

                     <ims:instanceName>

                        <ims:language>en-US</ims:language>

                        <ims:textString>First</ims:textString>

                     </ims:instanceName>

                     <ims:instanceValue>

                        <ims:language>en-US</ims:language>

                        <ims:textString>Demo</ims:textString>

                     </ims:instanceValue>

                  </ims:partName>

                  <ims:partName>

                     <ims:instanceIdentifier>

                        <ims:language>en-US</ims:language>

                        <ims:textString>Contact-Last</ims:textString>

                     </ims:instanceIdentifier>

                     <ims:instanceVocabulary>http://www.imsglobal.org/lis/pmsv2p0/partnamevocabularyv1p0&lt:/ims:instanceVocabulary&gt;

                     <ims:instanceName>

                        <ims:language>en-US</ims:language>

                        <ims:textString>Last</ims:textString>

                     </ims:instanceName>

                     <ims:instanceValue>

                        <ims:language>en-US</ims:language>

                        <ims:textString>User</ims:textString>

                     </ims:instanceValue>

                  </ims:partName>

               </ims:name>

               <!--Zero or more repetitions:-->

               <ims:contactinfo>

                  <ims:contactinfoType>

                     <ims:instanceIdentifier>

                        <ims:language>en-US</ims:language>

                        <ims:textString>EmailPrimary</ims:textString>

                     </ims:instanceIdentifier>

                     <ims:instanceVocabulary>http://www.imsglobal.org/lis/pmsv2p0/contactinfotypevocabularyv1p0</ims:instanceVocabulary&gt;

                     <ims:instanceValue>

                        <ims:language>en-US</ims:language>

                        <ims:textString>EmailPrimary</ims:textString>

                     </ims:instanceValue>

                  </ims:contactinfoType>

                  <ims:contactinfoValue>

                     <ims:language>en-US</ims:language>

                     <ims:textString>duser@demo.com</ims:textString>

                  </ims:contactinfoValue>

               </ims:contactinfo>

               <!--Zero or more repetitions:-->

               <ims:roles>

                  <ims:enterpriserolesType>

                     <ims:instanceIdentifier>

                        <ims:language>en-US</ims:language>

                        <ims:textString>StudentInformationSystem</ims:textString>

                     </ims:instanceIdentifier>

                     <ims:instanceVocabulary>http://www.imsglobal.org/lis/pmsv2p0/epriserolestypevocabularyv1p0</ims:instanceVocabulary&gt;

                     <ims:instanceValue>

                        <ims:language>en-US</ims:language>

                        <ims:textString>StudentInformationSystem</ims:textString>

                     </ims:instanceValue>

                  </ims:enterpriserolesType>

                  <!--Zero or more repetitions:-->

                  <ims:institutionRole>

                     <ims:institutionroletype>

                        <ims:instanceIdentifier>

                           <ims:language>en-US</ims:language>

                           <ims:textString>StudentInformationSystem-Student</ims:textString>

                        </ims:instanceIdentifier>

                        <ims:instanceVocabulary>http://www.imsglobal.org/lis/pmsv2p0/institutionroletypevocabularyv1p0</ims:instanceVocabulary&gt;

                        <ims:instanceValue>

                           <ims:language>en-US</ims:language>

                           <ims:textString>Student</ims:textString>

                        </ims:instanceValue>

                     </ims:institutionroletype>

                     <ims:primaryroletype>1</ims:primaryroletype>

                  </ims:institutionRole>

                  <!--Optional:-->

                  <ims:userId>

                     <ims:userIdValue>

                        <ims:language>en-US</ims:language>

                        <ims:textString>duser</ims:textString>

                     </ims:userIdValue>

                     <!--Optional:-->

                     <ims:password>

                        <ims:language>en-US</ims:language>

                        <ims:textString>d2l</ims:textString>

                     </ims:password>

                  </ims:userId>

               </ims:roles>


		 <ims:extension>


		    <ims:extensionField>


			<ims:fieldName>IsActive</ims:fieldName>


			<ims:fieldType>Boolean</ims:fieldType>


			<ims:fieldValue>True</ims:fieldValue>


		    </ims:extensionField>


		 </ims:extension>

            </ims:person>

         </ims:personRecord>

      </ims:replacePersonRequest>

   </soapenv:Body>

</soapenv:Envelope>

<ims:agent>

<ims:agentId>

<ims:language>en-US</ims:language>

<ims:textString>{Parent user Id}</ims:textString>

</ims:agentId>

<ims:agentDomain>

<ims:language>en-US</ims:language>

<ims:textString>{Parent role}</ims:textString>

</ims:agentDomain>

</ims:agent>

<ims:extension>

<ims:extensionField>

<ims:fieldName>SynchronizeRelationships</ims:fieldName>

<ims:fieldType>Boolean</ims:fieldType>

<ims:fieldValue>true</ims:fieldValue>

</ims:extensionField>

</ims:extension>

replacePerson request header and body fields

Request header fields

For more information, refer to the topic Using LIS v2.0 Services > Request and response headers.

Request body fields

The template translator configuration accepts the following fields in the request:

Property	LIS Request Mapping	Required
OrgDefinedId	sourcedGUID.sourcedId	Yes
Full Name	person.name.formname	No
First Name	person.name.partName.instanceValue.textString where person.name.partName.instanceName.textString = "First" or "Given"	Yes
Last Name	person.name.partName.instanceValue.textString where person.name.partName.instanceName.textString = "Last", "Family" or "Surname"	Yes
Email Address	person.contactinfo.contactinfoValue.textString where person.contactinfo.contactinfoType.instanceValue = "EmailPrimary"	No
Role	person.roles.institutionRole(*).institutionroletype.instanceValue.textString	No
Primary Role	person.roles.institutionRole().institutionroletype.instanceValue.textString when person.roles.institutionRole().primaryroletype = true	No
Username	person.roles.userId.userIdValue.textString	No
Username Type	person.roles.userId.userIdType.textString	No
Password	person.roles.userId.password.textString	No
Encryption Type	person.roles.userId.pwEncryptionType.textString	No
Authentication Type	person.roles.userId.authenticationType.textString	No
IsActive	person.extension.extensionField.fieldValue	No

Sample replacePerson response

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">

   <s:Header>

      <h:imsx_syncResponseHeaderInfo

          xmlns:h="http://www.imsglobal.org/services/lis/pms2p0/wsdl11/sync/imspms_v2p0"

          xmlns="http://www.imsglobal.org/services/lis/pms2p0/wsdl11/sync/imspms_v2p0"

          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

          xmlns:xsd="http://www.w3.org/2001/XMLSchema">

         <imsx_version>V1.0</imsx_version>

         <imsx_messageIdentifier>PMS_replacePerson_20120418T234324_4244880Z</imsx_messageIdentifier>

         <imsx_statusInfo>

            <imsx_codeMajor>success</imsx_codeMajor>

            <imsx_severity>warning</imsx_severity>

            <imsx_messageRefIdentifier>12346</imsx_messageRefIdentifier>

            <imsx_description/>

            <imsx_codeMinor>

               <imsx_codeMinorField>

                  <imsx_codeMinorFieldName>TargetEndSystem</imsx_codeMinorFieldName>

                  <imsx_codeMinorFieldValue>partialdatastorage</imsx_codeMinorFieldValue>

               </imsx_codeMinorField>

            </imsx_codeMinor>

         </imsx_statusInfo>

      </h:imsx_syncResponseHeaderInfo>

   </s:Header>

   <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

       xmlns:xsd="http://www.w3.org/2001/XMLSchema"/>

</s:Envelope>

replacePerson response header and body fields

Response header fields

For more information, refer to the topic Using LIS v2.0 Services > Request and response headers.

Response body fields

No fields are returned in the response body.

Sample readPerson request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"

   xmlns:ims="http://www.imsglobal.org/services/lis/pms2p0/wsdl11/sync/imspms_v2p0">

   <soapenv:Header>

      <ims:imsx_syncRequestHeaderInfo>

         <ims:imsx_version>1.0</ims:imsx_version>

         <ims:imsx_messageIdentifier>1234567</ims:imsx_messageIdentifier>

         <!--Optional:-->

         <ims:imsx_sendingAgentIdentifier/>

      </ims:imsx_syncRequestHeaderInfo>

   </soapenv:Header>

   <soapenv:Body>

      <ims:readPersonRequest>

         <ims:sourcedId>Demo_User</ims:sourcedId>

      </ims:readPersonRequest>

   </soapenv:Body>

</soapenv:Envelope>

Sample readPerson response

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">

   <s:Header>

      <h:imsx_syncResponseHeaderInfo xmlns:h="http://www.imsglobal.org/services/lis/pms2p0/wsdl11/sync/imspms_v2p0"

         xmlns="http://www.imsglobal.org/services/lis/pms2p0/wsdl11/sync/imspms_v2p0"

         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

         xmlns:xsd="http://www.w3.org/2001/XMLSchema">

         <imsx_version>V1.0</imsx_version>

         <imsx_messageIdentifier>PMS_readPerson_20120720T192847_4131414Z</imsx_messageIdentifier>

         <imsx_statusInfo>

           <imsx_codeMajor>success</imsx_codeMajor>

            <imsx_severity>warning</imsx_severity>

            <imsx_messageRefIdentifier>12354</imsx_messageRefIdentifier>

            <imsx_description>PMS.readPerson</imsx_description>

            <imsx_codeMinor>

               <imsx_codeMinorField>

                  <imsx_codeMinorFieldName>TargetEndSystem</imsx_codeMinorFieldName>

                  <imsx_codeMinorFieldValue>partialdatastorage</imsx_codeMinorFieldValue>

               </imsx_codeMinorField>

            </imsx_codeMinor>

         </imsx_statusInfo>

      </h:imsx_syncResponseHeaderInfo>

   </s:Header>

   <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

      <readPersonResponse xmlns="http://www.imsglobal.org/services/lis/pms2p0/wsdl11/sync/imspms_v2p0">

         <personRecord>

           <sourcedGUID>

              <sourcedId>Demo_User</sourcedId>

           </sourcedGUID>

           <person>

               <formname>

                 <formnameType>

                     <instanceIdentifier>

                       <language>en-US</language>

                    </instanceIdentifier>

                     <instanceVocabulary>http://www.imsglobal.org/lis/pmsv2p0/formatnmetypevocabularyv1p0</instanceVocabulary&gt;

                     <instanceValue>

                       <language>en-US</language>

                        <textString>Full</textString>

                     </instanceValue>

                 </formnameType>

                  <formattedName>

                    <language>en-US</language>

                     <textString>Demo User</textString>

                 </formattedName>

               </formname>

              <name>

                  <nameType>

                    <instanceIdentifier>

                        <language>en-US</language>

                     </instanceIdentifier>

                    <instanceVocabulary>http://www.imsglobal.org/lis/pmsv2p0/nametypevocabularyv1p0</instanceVocabulary&gt;

                    <instanceValue>

                        <language>en-US</language>

                        <textString>Full</textString>

                     </instanceValue>

                  </nameType>

                 <partName>

                    <instanceIdentifier>

                       <language>en-US</language>

                    </instanceIdentifier>

                    <instanceVocabulary>http://www.imsglobal.org/lis/pmsv2p0/partnamevocabularyv1p0</instanceVocabulary&gt;

                    <instanceName>

                        <language>en-US</language>

                       <textString>First</textString>

                    </instanceName>

                     <instanceValue>

                        <language>en-US</language>

                       <textString>Demo</textString>

                     </instanceValue>

                  </partName>

                  <partName>

                     <instanceIdentifier>

                       <language>en-US</language>

                     </instanceIdentifier>

                    <instanceVocabulary>http://www.imsglobal.org/lis/pmsv2p0/partnamevocabularyv1p0</instanceVocabulary&gt;

                     <instanceName>

                        <language>en-US</language>

                        <textString>Last</textString>

                     </instanceName>

                     <instanceValue>

                        <language>en-US</language>

                        <textString>User</textString>

                    </instanceValue>

                  </partName>

               </name>

           </person>

         </personRecord>

      </readPersonResponse>

   </s:Body>

</s:Envelope>