API: getRequirement
  • 4 Minutes to read
  • Dark
    Light

API: getRequirement

  • 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

The getRequirement method retrieves a requirement's details.

Who Has Access

The following users have access to the getRequirement method:

API Call XML Package

<SmarterU>
   <AccountAPI><![CDATA[]]></AccountAPI>
   <UserAPI><![CDATA[]]></UserAPI>
   <Method>getRequirement</Method>
   <Parameters>
      <Requirement>
         <Name><![CDATA[]]></Name>
         <ID></ID>
      </Requirement>
   </Parameters>
</SmarterU>

Requirement Tag Group

The Requirement tag group is a container for the requirement filters.

<Requirement>
   <Name><![CDATA[]]></Name>
   <ID></ID>
</Requirement>

The Requirement tag contains one of the following.

Name

The requirement's name. This tag is mutually exclusive with the ID tag.

ID

The requirement's system-generated identifier. This tag is mutually exclusive with the Name tag. 

This is not yet an ID that you can access through the SmarterU system. Please contact our Success Desk to request your IDs.

API Response XML Package

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

<SmarterU>
   <Result></Result>
   <Info>      
      <Requirement>
         <Name><![CDATA[]]></Name>
         <RequirementID><![CDATA[]]></RequirementID>
         <CreatedDate></CreatedDate>
         <ModifiedDate></ModifiedDate>
         <Description></Description>
         <ReqExpires></ReqExpires>
         <ExpirationType></ExpirationType>
         <DaysGood></DaysGood>
         <ExpirationDate></ExpirationDate>
         <RecallDays></RecallDays>
         <MetByDefault></MetByDefault>
         <DaysMet></DaysMet>
         <DaysMetWarning></DaysMetWarning>

         <Certifications>
            <Certification>
               <ID></ID>
               <Name></Name>
            </Certification>
         </Certifications>

         <Blocks>
            <Block>
               <BlockID></BlockID>
               <BlockSortOrder></BlockSortOrder>
               <Items>
                  <Item>
                     <ID></ID>
                     <Name><![CDATA[]]></Name>
                     <Type></Type>
                     <AutoEnroll></AutoEnroll>
                     <AutoEnrollILT></AutoEnrollILT>
                     <AutoEnrollOnFailure></AutoEnrollOnFailure>
                     <SelfEnroll></SelfEnroll>
                     <SortOrder></SortOrder>
                  </Item>
               </Items>
            </Block>
         </Blocks>
         <Status></Status>
      </Requirement>
   </Info>

   <Errors>
      <Error>
         <ErrorID></ErrorID>
         <ErrorMessage></ErrorMessage>
      </Error>
   </Errors>
</SmarterU>

The requirement is contained in a Requirement tag and may contain the following.

Name

The requirement's name.

RequirementID

The requirement's system-generated identifier. 

CreatedDate

The date the requirement was added.

ModifiedDate

The date the requirement was last edited.

Description

The requirement's description.

ReqExpires

Indicates whether the requirement expires. Possible values are: 

  • 0  - The requirement doesn't expire.
  • 1  - The requirement expires.

ExpirationType

This is only returned when the ReqExpires tag is set to 1

Indicates how the requirement expires. Possible values are:

  • ByDays - The requirement expires after the days specified in the DaysGood tag.
  • ByDate - The requirement expires on the date specified in the ExpirationDate tag.

DaysGood

This tag is only returned if the ReqExpires tag returns 1 and the ExpirationType tag returns ByDays

The number of days that the requirement is valid from the date that a user meets the requirement. If this tag is not provided, the tag's value defaults to 365.

ExpirationDate

This tag is only returned when the ReqExpires tag returns 1 and the ExpirationType tag returns ByDate

The date the requirement will expire in D-MMM format.

RecallDays

This tag is only returned if the ReqExpires tag returns 1. 

The number of days prior to the requirement's expiration that will cause the status to change to Warning.

MetByDefault

Indicates whether the requirement is met by default. Acceptable values are: 

  • 0 - The requirement isn't met by default
  • 1 - The requirement is met by default.

DaysMet

This tag is only returned if the MetByDefault tag returns 1

DaysMetWarning

This setting is only returned if the MetByDefault tag returns 1. 

Certifications

A container for the certifications that include the requirement. Each certification is contained in a Certification tag and contains the following.

TagDescription
IDThe certification's system-generated identifier. 
NameThe certification's name.

Blocks

A container for the requirement's blocks. Each block is contained in a Block tag and contains the following.

TagDescription
BlockIDThe block's system-generated identifier. 
BlockSortOrderThe order that the block will be displayed.
ItemA container for the block's courses and actions. Each course or action is contained in an Item tag and contains the following:

Example API Response XML Package

Below is an example of an API response XML package.

<SmarterU>
   <Result></Result>
   <Info>
      <Requirement>
         <Name><![CDATA[Fina Customer Service]]></Name>
         <RequirementID><![CDATA[17872]]></RequirementID>
         <CreatedDate>2018-09-11 16:27:17.28</CreatedDate>
         <ModifiedDate>2018-09-11 16:27:17.28</ModifiedDate>
         <Description><![CDATA[Customer service requirements]]></Description>
         <ReqExpires>1</ReqExpires>
         <ExpirationType>ByDays</ExpirationType>
         <DaysGood>365</DaysGood>
         <RecallDays>90</RecallDays>
         <MetByDefault>0</MetByDefault>
         <DaysMet>60</DaysMet>
         <DaysMetWarning>15</DaysMetWarning>

         <Certifications>
            <Certification>
               <ID>12402</ID>
               <Name>Fina Customer Service</Name>
            </Certification>
         </Certifications>

         <Blocks>
            <Block>
               <BlockID>92825</BlockID>
               <BlockSortOrder>1</BlockSortOrder>
               <Items>
                  <Item>
                     <ID>94261</ID>
                     <Name><![CDATA[Customer Service: Phone Support]]></Name>
                     <Type>1</Type>
                     <AutoEnroll>1</AutoEnroll>
                     <AutoEnrollILT>0</AutoEnrollILT>
                     <AutoEnrollOnFailure>1</AutoEnrollOnFailure>
                     <SelfEnroll>0</SelfEnroll>
                     <SortOrder>1</SortOrder>
                  </Item>
               </Items>
            </Block>
            <Block>
               <BlockID>92826</BlockID>
               <BlockSortOrder>2</BlockSortOrder>
               <Items>
                  <Item>
                     <ID>94259</ID>
                     <Name><![CDATA[Customer Service: Retail]]></Name>
                     <Type>1</Type>
                     <AutoEnroll>1</AutoEnroll>
                     <AutoEnrollILT>0</AutoEnrollILT>
                     <AutoEnrollOnFailure>1</AutoEnrollOnFailure>
                     <SelfEnroll>0</SelfEnroll>
                     <SortOrder>1</SortOrder>
                  </Item>
               </Items>
            </Block>
         </Blocks>
         <Status>Active</Status>
      </Requirement>
   </Info>

   <Errors>
   </Errors>
</SmarterU>

Error Codes

Error CodeMessage
GR:01
The name provided is invalid.
GR:02
The ID provided is invalid.
GR:03
The required permissions are not met to call the getRequirement method.
GR:04
The requested Requirement does not exist.
GR:05
Requirement Name and ID not provided. You must provide a Name or ID.

Was this article helpful?