API: createRequirement
  • 5 Minutes to read
  • Dark
    Light

API: createRequirement

  • 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 createRequirement method adds a requirement

Who Has Access

The following users have access to the createRequirement method:

API Call XML Package

<SmarterU>
   <AccountAPI><![CDATA[]]></AccountAPI>
   <UserAPI><![CDATA[]]></UserAPI>
   <Method>createRequirement</Method>
   <Parameters>
      <Requirement>
         <Name></Name>
         <Status></Status>
         <Description></Description>
         <ReqExpires></ReqExpires>
         <DaysGood></DaysGood>
         <ExpirationDate></ExpirationDate>
         <RecallDays></RecallDays>
         <MetByDefault></MetByDefault>
         <DaysMet></DaysMet>
         <DaysMetWarning></DaysMetWarning>
         <Blocks>
            <Block>
               <BlockSortOrder></BlockSortOrder>
               <Items>
                  <Item>
                     <LearningModuleID></LearningModuleID>
                     <CredentialName></CredentialName>
                     <Type></Type>
                     <SelfEnroll></SelfEnroll>
                     <AutoEnroll></AutoEnroll>
                     <SendAutoEnrollNotification></SendAutoEnrollNotification>
                     <SendAutoEnrollSessionConfirmation></SendAutoEnrollSessionConfirmation>
                     <AutoEnrollIlt></AutoEnrollIlt>
                     <AutoEnrollOnFailure></AutoEnrollOnFailure>
                     <SortOrder></SortOrder>
                  </Item>
               </Items>
            </Block>
         </Blocks>
      </Requirement>
   </Parameters>
</SmarterU>

Requirement Tag Group

The Requirement tag group is a container for the requirement's details. 

<Requirement>
   <Name></Name>
   <Status></Status>
   <Description></Description>
   <ReqExpires></ReqExpires>
   <DaysGood></DaysGood>
   <ExpirationDate></ExpirationDate>
   <RecallDays></RecallDays>
   <MetByDefault></MetByDefault>
   <DaysMet></DaysMet>
   <DaysMetWarning></DaysMetWarning>
   <Blocks>
      <Block>
         <BlockSortOrder></BlockSortOrder>
         <Items>
            <Item>
               <LearningModuleID></LearningModuleID>
               <CredentialName></CredentialName>
               <Type></Type>
               <SelfEnroll></SelfEnroll>
               <AutoEnroll></AutoEnroll>
               <SendAutoEnrollNotification></SendAutoEnrollNotification>
               <SendAutoEnrollSessionConfirmation></SendAutoEnrollSessionConfirmation>
               <AutoEnrollIlt></AutoEnrollIlt>
               <AutoEnrollOnFailure></AutoEnrollOnFailure>
               <SortOrder></SortOrder>
            </Item>
         </Items>
      </Block>
   </Blocks>
</Requirement>

The Requirement tag may contain the following. 

Name

The requirement's name.

Status

The requirement's status. Acceptable values are Active or Inactive.

Description

The requirement's description.

ReqExpires (optional)

Indicates whether the requirement expires. Acceptable values are: 

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

If this tag is not provided, the tag's value will default to 1.

DaysGood (optional)

This is only used when ReqExpires is set to and you want the requirement to expire after the specified number of days. 

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 (optional)

This tag is only used when the ReqExpires tag is set to 1 and you want the requirement to expire on a specific date. 

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

RecallDays (optional)

This is only used when ReqExpires is set to 1

MetByDefault (optional)

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 (optional)

This tag is only used when MetByDefault is set to 1

DaysMetWarning (optional)

This setting is only used when MetByDefault is set to 1

Blocks (optional)

A container for the requirement's blocks. Refer to Blocks Tag Group.

Blocks Tag Group

The Blocks tag group is a container for the requirement's blocks.

<Blocks>
   <Block>
      <BlockSortOrder></BlockSortOrder>
      <Items>
         <Item>
            <LearningModuleID></LearningModuleID>
            <CredentialName></CredentialName>
            <Type></Type>
            <SelfEnroll></SelfEnroll>
            <AutoEnroll></AutoEnroll>
            <SendAutoEnrollNotification></SendAutoEnrollNotification>
            <SendAutoEnrollSessionConfirmation></SendAutoEnrollSessionConfirmation>
            <AutoEnrollIlt></AutoEnrollIlt>
            <AutoEnrollOnFailure></AutoEnrollOnFailure>
            <SortOrder></SortOrder>
         </Item>
      </Items>
   </Block>
</Blocks>

Each block is contained in a Block tag and may contain the following.

BlockSortOrder (optional)

The order that the block will be displayed.

Items

A container for the block's courses and actions. Each course or action is contained in an Item tag and may contain the following. 

TagDescription
LearningModuleID (optional)

This tag is only used when Type is set to 1.

The course's system-generated identifier. This is the LearningModuleID returned by the listLearningModules method. 

CredentialName (optional)The course or action's name.
Type (optional)

Indicates whether the item is a course or an action. Acceptable values are: 

  • 1 - The item is a course.
  • 2 - The item is an action.
SelfEnroll (optional)

This tag is only used when Type is set to 1.

Indicates whether the course's Self-Enroll setting is enabled. Acceptable values are: 

  • 0 - Self-enrollment is disabled.
  • 1 - Self-enrollment is enabled.
AutoEnroll (optional)

Indicates whether the course's Auto-Enroll setting is enabled (i.e., 0 = disabled; 1 = enabled). Refer to API: Requirement's Course Auto-Enroll Settings for details.

SendAutoEnrollNotification (optional)

This tag is only used when AutoEnroll is set to 1.

Indicates whether the account's selected Course Enrollment email template is sent to learners when they're automatically enrolled in the course. Acceptable values are:

  • 0 - The email is not sent.
  • 1 - The email is sent.
SendAutoEnrollConfirmationNotification (optional)

This tag is only used when AutoEnrollILT is set to 1.

Indicates whether the account's selected Confirm Attendance email template is sent to learners when they're automatically enrolled in the instructor-led course course. Acceptable values are:

  • 0 - The email is not sent.
  • 1 - The email is sent.
AutoEnrollILT (optional)

Indicates the Auto-Enroll setting for an instructor-led course. Refer to API: Requirement's Course Auto-Enroll Settings for details.

AutoEnrollOnFailure (optional)

Indicates whether learners are re-enrolled if they fail the course. Refer to API: Requirement's Course Auto-Enroll Settings for details.

SortOrder (optional)

The course or action's position in the block.

API Response XML Package

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

<SmarterU>
   <Result></Result>
   <Info>
      <Requirement><![CDATA[]]></Requirement>
      <RequirementID/>
   </Info>

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

The response may also contain the following.

Requirement

The requirement's name.

RequirementID

The requirement's system-generated identifier.

Example API Response XML Package

Below is an example of an API response XML package.

<SmarterU>
   <Result></Result>
   <Info>
      <Requirement><![CDATA[Conflict Resolution]]></Requirement>
      <RequirementID/>
   </Info>

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

Error Codes

Error CodeMessage
CR:01
The name provided is invalid.
CR:02
The status provided is invalid.
CR:03 
The description provided is invalid.
CR:04
The requirement expires is invalid.
CR:05
The days good provided is invalid.
CR:06
The recall days provided is invalid.
CR:07
The met by default provided is invalid.
CR:08
The days met count provided is invalid.
CR:09
The days met warning provided is invalid.
CR:10
The credential name provided is invalid.
CR:11
The type provided is invalid.
CR:12
The self enroll provided is invalid.
CR:13
The auto enroll provided is invalid.
CR:14
The auto enroll ILT provided is invalid.
CR:15
The auto enroll on failure provided is invalid.
CR:16
The sort order provided is invalid.
CR:17
The blocks provided is invalid.
CR:18
The block provided is invalid.
CR:19
The block id provided is invalid.
CR:20
The block sort order provided is invalid.
CR:21
The item is invalid.
CR:22
The items provided is invalid.
CR:23
The item action provided is invalid.
CR:24
The learning module id provided is invalid.
CR:25
The status provided is not valid. Only ACTIVE or INACTIVE are allowed values.
CR:26
Credential name is required for actions.
CR:27
One or more of the items provided are not valid. Actions and Courses cannot be added more than once.
CR:28
One or more of the action names provided are not valid.
CR:29
Incorrect/Missing Structure/Parameters. LearningModuleID is required for courses.
CR:30
One or more of the items provided are not valid. Actions and Courses cannot be added more than once.
CR:31
One or more of the courses provided are not valid.
CR:32
Requirement name cannot be used.
CR:33
The required permissions are not met to call the createRequirement method.
CR:34
Type provided is invalid. Type must be 1 or 2.
CR:35
Days good should be greater than recall days.
CR:36
Days met should be greater than days met warning.
CR:37
Days good should be greater than days met.
CR:38
Either DaysGood or ExpirationDate can be provided.

Was this article helpful?