API: updateRole
  • 3 Minutes to read
  • Dark
    Light

API: updateRole

  • Dark
    Light

  • Starting June 1, 2022, SmarterU will require all API calls to POST to HTTPS. Any POST to HTTP will result in the SU:01 error (i.e., No POST data detected.).
  • If you are viewing the help in a language other than English, please change your language to English before copying and pasting any code. All API attributes and functions are in English.
  • Tags are required unless specified.

Description

Learning Plans were previously referred to as roles

The updateRole method edits a learning plan.

Who Has Access

The following users have access to the updateRole method:

API Call XML Package

<SmarterU>
   <AccountAPI><![CDATA[]]></AccountAPI>
   <UserAPI><![CDATA[]]></UserAPI>
   <Method>updateRole</Method>
   <Parameters>
      <Role>
         <Identifier>
            <Name><![CDATA[]]></Name>
               - OR -
            <RoleID><![CDATA[]]></RoleID>
         </Identifier>

         <Name><![CDATA[]]></Name>
         <RoleID><![CDATA[]]></RoleID>
         <Status><![CDATA[]]></Status>
         <Description><![CDATA[]]></Description>
         <Certifications>
            <Certification>
               <CertificationName><![CDATA[]]></CertificationName>
               <MandateLevel><![CDATA[]]></MandateLevel>
               <CertificationAction><![CDATA[]]></CertificationAction>
            </Certification>
         </Certifications>
      </Role>
   </Parameters>
</SmarterU>

Role Tag Group

The Role tag group is a container for the learning plan's details. 

<Role>
   <Identifier>
      <Name><![CDATA[]]></Name>
         - OR -
      <RoleID><![CDATA[]]></RoleID>
   </Identifier>

   <Name><![CDATA[]]></Name>
   <RoleID><![CDATA[]]></RoleID>
   <Status><![CDATA[]]></Status>
   <Description><![CDATA[]]></Description>

   <Certifications>
      <Certification>
         <CertificationName><![CDATA[]]></CertificationName>
         <MandateLevel><![CDATA[]]></MandateLevel>
         <CertificationAction><![CDATA[]]></CertificationAction>
      </Certification>
   </Certifications>
</Role>

The Role tag may contain the following. 

The Identifier tag contains the information for the learning plan you want to update. The remaining tags in the Role tag group specify the updates to the learning plan. 

Identifier

The identifier of the learning plan you want to update. This tag contains the following.

TagDescription

Name

The learning plan's name. This tag is mutually exclusive with the RoleID tag.

RoleID

The learning plan's user-specified identifier. This tag is mutually exclusive with the Name tag. This is the RoleID returned by the listRoles method.

Name (optional)

The learning plan's name

RoleID (optional)

The learning plan's user-specified identifier

Status (optional)

The learning plan's status. Acceptable values are Active or Inactive

Description (optional)

The learning plan's description.

Certifications (optional)

A container for assigning certifications to or removing certifications from the learning plan. Refer to Certifications Tag Group.

Certifications Tag Group (Optional)

The Certifications tag group is a container for assigning certifications to or removing certifications from the learning plan. 

<Certifications>
   <Certification>
      <CertificationName><![CDATA[]]></CertificationName>
      <MandateLevel><![CDATA[]]></MandateLevel>
      <CertificationAction><![CDATA[]]></CertificationAction>
   </Certification>
</Certifications>

Each certification is contained in a Certification tag and contains the following.

CertificationName

The certification's name.

MandateLevel

The certification's mandate level. Acceptable values are:

  • Mandatory - The certification is required for the learning plan.
  • Recommended - The certification is not required, but recommended for the learning plan.
  • Optional - The certification is optional for the learning plan. 

CertificationAction

Indicates the action you are taking on the learning plan's certification. Acceptable values are:

  • Add - You're adding the certification to the learning plan, or updating a certification that was previously added to the learning plan.
  • Remove - You're removing the certification from the learning plan.

API Response XML Package

The API response XML package will always include a Result, Info, and Errors tag.

<SmarterU>
   <Result></Result>
   <Info>
      <Role><![CDATA[]]></Role>
      <RoleID><![CDATA[]]></RoleID>
   </Info>
   <Errors>
      <Error>
         <ErrorID></ErrorID>
         <ErrorMessage></ErrorMessage>
      </Error>
   </Errors>
</SmarterU>

The response may also contain the following.

Role

The learning plan's name.

RoleID

The learning plan's user-specified identifier.

Example API Response XML Package

Below is an example of an API response XML package.

<SmarterU>
   <Result>Success</Result>
   <Info>
      <Role><![CDATA[Store Manager]]></Role>
      <RoleID><![CDATA[LP-1020]]></RoleID>
   </Info>

   <Errors>
   </Errors>
</SmarterU> 

Error Codes

Error CodeMessage
UR:01
The name provided is not valid.
UR:02
The learning plan ID provided is not valid.
UR:03
The status provided is not valid.
UR:04
The description provided is not valid.
UR:05
The certification name provided is not valid.
UR:06
The certification action provided is not valid.
UR:07
The mandate level provided is not valid.
UR:08
The required permissions are not met to call the updateRole method.
UR:09
The requested learning plan does not exist.
UR:10
The status provided is not valid. Acceptable values are Active or Inactive.  
UR:11
One or more of the certification names provided are not valid.
UR:12
A certification mandate level must be provided when adding a certification to a role.
UR:13
One or more mandate levels provided are not valid. Acceptable values are Mandatory, Optional, or Recommended.
UR:15
The certification action provided is not valid. Acceptable values are Add or Remove
UR:16
Learning plan name cannot be used.
UR:17
Learning plan ID cannot be used.
UR:18
The required permissions are not met to call the updateRole method.

Was this article helpful?