API: getLearnerCertificationReport
  • 8 Minutes to read
  • Dark
    Light

API: getLearnerCertificationReport

  • 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

The getLearnerCertificationReport is used to run a Learning Plan Report for certifications.

Who Has Access

The following users have access to the getLearnerCertificationReport method:

API Call XML Package

<SmarterU>
   <AccountAPI><![CDATA[]]></AccountAPI>
   <UserAPI><![CDATA[]]></UserAPI>
   <Method>getLearnerCertificationReport</Method>

   <Parameters>
      <Report>
         <Type></Type>
         <Page>
            <Num></Num>
            <Size></Size>
         </Page>

         <Filters>
            <Status></Status>

            <MetDates>
               <MetDate>
                  <MetDateFrom><![CDATA[]]></MetDateFrom>
                  <MetDateTo><![CDATA[]]></MetDateTo>
               </MetDate>
            </MetDates>

            <WarningDates>
               <WarningDate>
                  <WarningDateFrom><![CDATA[]]></WarningDateFrom>
                  <WarningDateTo><![CDATA[]]></WarningDateTo>
               </WarningDate>
            </WarningDates>

            <ExpirationDates>
               <ExpirationDate>
                  <ExpirationDateFrom><![CDATA[]]></ExpirationDateFrom>
                  <ExpirationDateTo><![CDATA[]]></ExpirationDateTo>
               </ExpirationDate>
            </ExpirationDates>

            <Certifications>
               <Certification>
                  <ID><![CDATA[]]></ID>
               </Certification>
            </Certifications>

            <Users>
               <UserStatus><![CDATA[]]></UserStatus>
                  - OR -
               <Identifier>
                  <EmailAddresses>
                     <EmailAddress><![CDATA[]]></EmailAddress>
                  </EmailAddresses>
                     - AND/OR -
                  <EmployeeIDs>
                     <EmployeeID><![CDATA[]]></EmployeeID>
                  </EmployeeIDs>
               </Identifier>
            </Users>

            <HomeGroups>
               <HomeGroup>
                  <ID><![CDATA[]]></ID>
               </HomeGroup>
            </HomeGroups>

            <Supervisors>
               <SupervisorStatus><![CDATA[]]></SupervisorStatus>
                  - OR -
               <Identifier>
                  <EmailAddresses>
                     <EmailAddress><![CDATA[]]></EmailAddress>
                  </EmailAddresses>
                     - AND/OR - 
                  <EmployeeIDs>
                     <EmployeeID><![CDATA[]]></EmployeeID>
                  </EmployeeIDs>
               </Identifier>
            </Supervisors>
         </Filters>

         <SortBy>
            <Column></Column>
            <Order></Order>
         </SortBy>

      </Report>
   </Parameters>
</SmarterU>

Report Tag Group

Type

The type of report to run. Acceptable values are:

  • DetailedList - Returns the users who are assigned the certification. 
  • Summary - Returns a count of users who are assigned the certification. This is the default if the Type is not specified.

Page

The Page tag group is a container for the page number returned by the response and the size of the response. Refer to Page Tag Group.

Filters

The Filters tag group is a container for the filters you want to apply. Refer to Filters Tag Group.

SortBy

The SortBy tag group is a container for the columns to use to order the response. Refer to SortBy Tag Group.

Page Tag Group

The Page tag group is a container for the page number returned by the response and the size of the response.

Num

The page number to return. The default is 1.

Size

The maximum number of records to return. If the Size tag is not provided, up to 50 results are returned by default. The maximum allowed value is 1000.

Filters Tag Group

The Filters tag group is a container for the filters you want to apply. 

<Filters>
   <Status></Status>

   <MetDates>
      <MetDate>
         <MetDateFrom><![CDATA[]]></MetDateFrom>
         <MetDateTo><![CDATA[]]></MetDateTo>
      </MetDate>
   </MetDates>

   <WarningDates>
      <WarningDate>
         <WarningDateFrom><![CDATA[]]></WarningDateFrom>
         <WarningDateTo><![CDATA[]]></WarningDateTo>
      </WarningDate>
   </WarningDates>

   <ExpirationDates>
      <ExpirationDate>
         <ExpirationDateFrom><![CDATA[]]></ExpirationDateFrom>
      <ExpirationDateTo><![CDATA[]]></ExpirationDateTo>
   </ExpirationDate>
   </ExpirationDates>

   <Certifications>
      <Certification>
         <ID><![CDATA[]]></ID>
      </Certification>
   </Certifications>

   <Users>
      <UserStatus><![CDATA[]]></UserStatus>
         - OR -
      <Identifier>
         <EmailAddresses>
            <EmailAddress><![CDATA[]]></EmailAddress>
         </EmailAddresses>
            - AND/OR -
         <EmployeeIDs>
            <EmployeeID><![CDATA[]]></EmployeeID>
         </EmployeeIDs>
      </Identifier>
   </Users>

   <HomeGroups>
      <HomeGroup>
         <ID><![CDATA[]]></ID>
      </HomeGroup>
   </HomeGroups>

   <Supervisors>
      <SupervisorStatus><![CDATA[]]></SupervisorStatus>
         - OR -
      <Identifier>
         <EmailAddresses>
            <EmailAddress><![CDATA[]]></EmailAddress>
         </EmailAddresses>
            - AND/OR - 
         <EmployeeIDs>
            <EmployeeID><![CDATA[]]></EmployeeID>
         </EmployeeIDs>
      </Identifier>
   </Supervisors>
</Filters>

The Filters tag group may contain the following.

Status (optional)

The certification status to include in the response. Acceptable values are Met, Warning, and NotMet.

MetDates (optional)

A container for the met date range to include in the response.

<MetDates>
   <MetDate>
      <MetDateFrom><![CDATA[]]></MetDateFrom>
      <MetDateTo><![CDATA[]]></MetDateTo>
   </MetDate>
</MetDates>

 A MetDate tag must be added with the following.

TagDescription
MetDateFromThe first date to include in the certification's met date range filter.
MetDateToThe last date to include in the certification's met date range filter. 
  • Dates should be in dd-MMM-yyyy date format.
  • Only one date range may be specified for the MetDate tag.

WarningDates (optional)

A container for the warning date range to include in the response. 

<WarningDates>
   <WarningDate>
      <WarningDateFrom><![CDATA[]]></WarningDateFrom>
      <WarningDateTo><![CDATA[]]></WarningDateTo>
   </WarningDate>
</WarningDates>

A WarningDate tag must be included with the following.

TagDescription
WarningDateFromThe first date to include in the certification's warning date range filter.
WarningDateToThe last date to include in the certification's warning date range filter. 
  • Dates should be in dd-MMM-yyyy date format.
  • Only one date range may be specified for the WarningDate tag.

ExpirationDates (optional)

A container for the expiration date range to include in the response. 

<ExpirationDates>
   <ExpirationDate>
      <ExpirationDateFrom><![CDATA[]]></ExpirationDateFrom>
      <ExpirationDateTo><![CDATA[]]></ExpirationDateTo>
   </ExpirationDate>
</ExpirationDates>

An ExpirationDate tag must be included with the following.

TagDescription
ExpirationDateFromThe first date to include in the certification's expiration date range filter.
ExpirationDateToThe last date to include in the certification's expiration date range filter. 
  • Dates should be in dd-MMM-yyyy date format.
  • Only one date range may be specified for the ExpirationDate tag.

Certifications (optional)

A container for the certifications to include in the response.

<Certifications>
   <Certification>
      <ID><![CDATA[]]></ID>
   </Certification>
</Certifications>

For each certification filter, a Certification tag must be added with the following.

TagDescription
IDThe certification's system-generated identifier.

For example, the following filters for certification IDs 4321 and 6789.

<Certifications>
   <Certification>
      <ID><![CDATA[4321]]></ID>
   </Certification>

   <Certification>
      <ID><![CDATA[6789]]></ID>
   </Certification>
</Certifications>

Users (optional)

A container for the users to include in the response.

<Users>
   <UserStatus><![CDATA[]]></UserStatus>
      - OR -
   <Identifier>
      <EmailAddresses>
         <EmailAddress><![CDATA[]]></EmailAddress>
      </EmailAddresses>
         - AND/OR -
      <EmployeeIDs>
         <EmployeeID><![CDATA[]]></EmployeeID>
      </EmployeeIDs>
   </Identifier>
</Users>

The Users tag may contain the following.

TagDescription
UserStatusThe user's status. Acceptable values are Active, Inactive, or All. This tag is mutually exclusive with the Identifier tag.
IdentifierA container for the user email addresses and/or employee IDs to include in the response. This is mutually exclusive with the UserStatus tag. The Identifier tag may contain the following.
  • EmailAddresses - A container for the user email addresses. Each email address should be enclosed within an EmailAddress tag.
  • EmployeeIDs - A container for the employee IDs. Each employee ID should be enclosed within an EmployeeID tag.

HomeGroups (optional)

A container for the user home groups to include in the response.

<HomeGroups>
   <HomeGroup>
      <ID></ID>
   </HomeGroup>
</HomeGroups>

The HomeGroups tag may include the following.

TagDescription
HomeGroupA container for the home group. Each home group that you want to include in the response must be enclosed within a HomeGroup tag. The tag must contain the following.
  • ID - The home group's system-generated identifier. 

Supervisors (optional)

A container for the supervisors to include in the response. 

<Supervisor>
   <SupervisorStatus></SupervisorStatus>
      - OR - 
   <Identifier>
      <EmailAddresses>
         <EmailAddress><![CDATA[]]></EmailAddress>
      </EmailAddresses>
            - AND/OR -
      <EmployeeIDs>
         <EmployeeID><![CDATA[]]></EmployeeID>   
      </EmployeeIDs>
   </Identifier>
<Supervisor/>

The Supervisor tag may contain the following.

TagDescription
SupervisorStatusThe supervisor's status. Acceptable values are Active, Inactive, or All. This tag is mutually exclusive with the Identifier tag.
IdentifierA container for the supervisors' email addresses and/or employee IDs. The Identifier tag may contain the following.

SortBy Tag Group (optional)

The SortBy tag group is a container how the response should be ordered. 

<SortBy>
   <Column></Column>
   <Order></Order>
</SortBy>

The tag may contain the following. 

Column

A container for the columns to use to order the response. The acceptable values will depend on the Type specified.

TypeAcceptable SortBy Values
DetailedList
  • MetDate 
  • WarningDate
  • ExpirationDate
  • LearnerName
  • Status
Summary
  • MetCount 
  • WarningCount
  • NotMetCount
  • CertificationName

Each sort by column should be enclosed within less than and greater than ("<" and ">") characters. In the following example, the response will be sorted by the certification's status and learner's name.

<SortBy>
   <Column>
      <Status>
      <LearnerName>
   </Column>
</SortBy>

Order

The direction that the response will be sorted:

  • asc - The response will be sorted in ascending order. This is the default.
  • desc - The response will be sorted in descending order. 

API Response XML Package

The getLearnerCertificationReport response will depend on the Type specified in the API call XML package.

Response for DetailedList

The following is the response for the getLearnerCertificationReport API method when the Type is set to DetailedList.

<SmarterU>
   <Result></Result>

   <Info>
      <CertificationReport>
         <LearnerCertification>
            <ID><![CDATA[]]></ID>
            <FirstName><![CDATA[]]></FirstName>
            <LastName><![CDATA[]]></LastName>
            <EmployeeID><![CDATA[]]></EmployeeID>
            <CertificationName><![CDATA[]]></CertificationName>
            <CertificationID><![CDATA[]]></CertificationID>
            <Status><![CDATA[]]></Status>
            <MetDate><![CDATA[]]></MetDate>
            <WarningDate><![CDATA[]]></WarningDate>
            <ExpirationDate><![CDATA[]]></ExpirationDate>
            <MetDateConverted><![CDATA[]]></MetDateConverted>
            <WarningDateConverted><![CDATA[]]></WarningDateConverted>
            <ExpirationDateConverted><![CDATA[]]></ExpirationDateConverted>
         </LearnerCertification>
      </CertificationReport>

      <TotalRows><![CDATA[]]></TotalRows>
   </Info>

   <Errors>
      <ErrorID></ErrorID>
      <ErrorMessage></ErrorMessage>
   </Errors>

</SmarterU> 

The CertificationReport tag is a container for the actions returned by the getLearnerCertificationReport method. Each user who is assigned a certification is contained in a LearnerCertification tag that may contain the following.

TagDescription
IDThe system-generated identifier for the relationship between the certification and the user the certification is assigned to.
FirstNameThe user's given name.
LastNameThe user's surname.
EmployeeIDThe user's employee ID.
CertificationNameThe certification's name.
CertificationIDThe certification's system-generated identifier.
StatusThe user's status for the certification.
MetDateThe date, in UTC, the user satisfied the certification's requirements. 
WarningDateThe date, in UTC, the user's certification changed to Warning.
ExpirationDateThe date, in UTC, the user's certification expires.
MetDateConvertedThe date, converted to the API user's timezone, the user satisfied the certification's requirements. 
WarningDateConvertedThe date, converted to the API user's timezone, the user's certification changed to Warning.
ExpirationDateConvertedThe date, converted to the API user's timezone, the user's certification expires. 

The response also includes a TotalRows tag which includes a count of the records in the response.

The Errors tag contains any error codes returned by the getLearnerCertificationReport method. 

Below is an example of an API response XML package when the Type is set to DetailedList.

<SmarterU>
   <Result>Success</Result>

   <Info>
      <CertificationReport>
         <LearnerCertification>
            <ID><![CDATA[1185291]]></ID>
            <FirstName><![CDATA[Lou]]></FirstName>
            <LastName><![CDATA[Greenberg]]></LastName>
            <EmployeeID/>
            <CertificationName><![CDATA[Conveyor Belt Operation]]></CertificationName>
            <CertificationID><![CDATA[11262]]></CertificationID>
            <Status><![CDATA[Met]]></Status>
            <MetDate><![CDATA[14-Aug-2019]]></MetDate>
            <WarningDate/>
            <ExpirationDate/>
            <MetDateConverted><![CDATA[13-Aug-2019]]></MetDateConverted>
            <WarningDateConverted><![CDATA[]]></WarningDateConverted>
            <ExpirationDateConverted><![CDATA[]]></ExpirationDateConverted>
         </LearnerCertification>
      </CertificationReport>

      <TotalRows><![CDATA[1]]></TotalRows>
   </Info>

   <Errors>
   </Errors>

</SmarterU> 

Response for Summary

The following is the response for the getLearnerCertificationReport API method when the Type is set to Summary.

<SmarterU>
   <Result></Result>

   <Info>
      <CertificationReport>
         <Certification>
            <ID><![CDATA[]]></ID>
            <CertificationName><![CDATA[]]></CertificationName>
            <Met><![CDATA[]]></Met>
            <Warning><![CDATA[]]></Warning>
            <NotMet><![CDATA[]]></NotMet>
            <Total><![CDATA[]]></Total>
         </Certification>
      </CertificationReport>
   </Info>

   <Errors>
      <ErrorID></ErrorID>
      <ErrorMessage></ErrorMessage>
   </Errors>

</SmarterU> 

The CertificationReport tag is a container for the certifications returned by the getLearnerCertificationReport method. Each certification is contained in a Certification tag that contains the following.

TagDescription
IDThe certification's system-generated identifier.
CertificationNameThe certification's name.
MetThe number of users who have met the certification.
WarningThe number of users who have certification requirements that are within the warning period.
NotMetThe number of users who have not met their certification's requirements.
TotalThe total number of users who are assigned the certification.

The Errors tag contains any error codes returned by the getLearnerCertificationReport method. 

Below is an example of an API response XML package when the Type is set to Summary.

<SmarterU>
   <Result>Success</Result>

   <Info>
      <CertificationReport>
         <Certification>
            <ID><![CDATA[10222]]></ID>
            <CertificationName><![CDATA[Forklift Operation]]></CertificationName>
            <Met><![CDATA[3]]></Met>
            <Warning><![CDATA[2]]></Warning>
            <NotMet><![CDATA[6]]></NotMet>
            <Total><![CDATA[11]]></Total>
         </Certification>
      </CertificationReport>
   </Info>

   <Errors>
   </Errors>

</SmarterU> 

Error Codes

Error CodeMessage
GLCR:01The report type provided is not valid.
GLCR:02Page number provided is not valid.
GLCR:03Page size provided is not valid.
GLCR:04The page size provided exceeds limit.
GLCR:05The sort by column provided is not valid.
GLCR:06The sort by order provided is not valid.
GLCR:07The status provided is not valid.
GLCR:08The met date provided is not valid.
GLCR:09The warning date provided is not valid.
GLCR:10The expiration date provided is not valid.
GLCR:11The certification ID provided should not be blank.
GLCR:12The user status provided is not valid.
GLCR:13The home group ID provided should not be blank.
GLCR:14The supervisor status provided is not valid.
GLCR:15The certification ID provided is not valid.
GLCR:16The home group ID provided is not valid.
GLCR:17User filtering is not supported in summary report.
GLCR:18Home group filtering is not supported in summary report.
GLCR:19Supervisor filtering is not supported in summary report.
GLCR:20The learner email provided should not be blank.
GLCR:21The learner employee ID provided should not be blank.
GLCR:22The supervisor email provided should not be blank.
GLCR:23The supervisor employee ID provided should not be blank.
GLCR:24The users provided should not be blank.
GLCR:25The supervisors provided should not be blank.
GLCR:26The user identifier provided should not be blank.
GLCR:27The supervisor identifier provided should not be blank.

Was this article helpful?