API: listRoles
  • 1 Minute to read
  • Dark
    Light

API: listRoles

  • Dark
    Light

Article Summary

  • 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 listRoles method retrieves learning plans that meet the specified filter. 

Who Has Access

The following users have access to the listRoles method:

API Call XML Package

<SmarterU>
   <AccountAPI><![CDATA[]]></AccountAPI>
   <UserAPI><![CDATA[]]></UserAPI>
   <Method>listRoles</Method>    
   <Parameters>
      <Role>
         <Page><![CDATA[]]></Page>
         <Filters>
            <RoleStatus><![CDATA[]]></RoleStatus>
         </Filters>
      </Role>
   </Parameters>
</SmarterU>

Role Tag Group

The Role tag group is a container for how the response is returned and the learning plan filter.

<Role>
   <Page><![CDATA[]]></Page>
   <Filters>
      <RoleStatus><![CDATA[]]></RoleStatus>
   </Filters>
</Role>

The Role tag may contain the following. 

Page (optional)

The page to get. Default is 1. If the Page tag is not provided, up to 50 results are returned by default.

Filters (optional)

A container for the learning plan status filter. This tag contains the following.

TagDescription

RoleStatus

The learning plan status filter. Acceptable values are Active, Inactive, or All. The default is All

API Response XML Package

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

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

The Roles tag is a container for the learning plans returned by the listRoles method. Each learning plan is contained in a Role tag and may contain the following.

Name

The learning plan's name.

RoleID

The learning plan's user-specified identifier.

Status

The learning plan's status (i.e., Active, Inactive).

Example API Response XML Package

Below is an example of an API response XML package.

<SmarterU>
    <Result>Success</Result>
    <Info>
        <Roles>
            <Role>
                <Name><!--[CDATA[Forklift Operator]]--></Name>
                <RoleID><!--[CDATA[LP-2093]]--></RoleID>
                <Status>Active</Status>
            </Role>

            <Role>
                <Name><!--[CDATA[Store Manager]]--></Name>
                <RoleID><!--[CDATA[LP-1020]]--></RoleID>
                <Status>Active</Status>
            </Role>
        </Roles>
    </Info>
</SmarterU>

Error Codes

Error CodeMessage
LR:01
The page number provided is not valid.
LR:02
The learning plan status provided is not valid.
LR:03
The required permissions are not met to call the listRoles method.
LR:04
The value for a role status must be Active, Inactive, or All.

Was this article helpful?