API: getLearnerCertificationReport

8 Minutes to read

Print
Share
Dark
Light

API: getLearnerCertificationReport

8 Minutes to read

Print
Share
Dark
Light

Article Summary

Share feedback

Thanks for sharing your feedback!

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 runs a Learning Plan Report for certifications.

Who Has Access

The following users have access to the getLearnerCertificationReport method:

Users with the Group Manager, or View Learner Results group permission.
Users with the Global Reporting account permission.
Supervisors, if the account's Supervisor Access setting'sReport on Supervisees option is checked.
Administrators and owners.

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>

The Report tag group is a container for how the response is returned and the report filters.

<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>

The Report tag may contain the following.

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 by status. This is the default if the Type is not specified.

Page

A container for the page number to return and the size of the response. The Page tag may contain the following.

Tag	Description
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

The Filters tag group is a container for the report filters. Refer to Filters Tag Group.

SortBy

The SortBy tag group is a container for how the response should be ordered. Refer to SortBy Tag Group.

The Filters tag group is a container for the report filters.

<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 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>

The date range is contained in a MetDate tag and contains the following.

Tag	Description
MetDateFrom	The first date to include in the certification's met date range filter.
MetDateTo	The 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>

The date range is contained in a WarningDate tag and contains the following.

Tag	Description
WarningDateFrom	The first date to include in the certification's warning date range filter.
WarningDateTo	The 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>

The date range is contained in an ExpirationDate tag and contains the following.

Tag	Description
ExpirationDateFrom	The first date to include in the certification's expiration date range filter.
ExpirationDateTo	The 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>

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

Tag	Description
ID	The 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.

Tag	Description
UserStatus	The user's status. Acceptable values are Active, Inactive, or All. This tag is mutually exclusive with the Identifier tag.
Identifier	A container for the user email addresses and/or employee IDs to include in the response. This tag 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 is contained in an EmailAddress tag. EmployeeIDs - A container for the employee IDs. Each employee ID is contained in an EmployeeID tag.

Tag

Description

UserStatus

The user's status. Acceptable values are Active, Inactive, or All. This tag is mutually exclusive with the Identifier tag.

Identifier

A container for the user email addresses and/or employee IDs to include in the response. This tag 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 is contained in an EmailAddress tag.
EmployeeIDs - A container for the employee IDs. Each employee ID is contained in 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.

Tag	Description
HomeGroup	A container for the home group's identifier. 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.

Tag	Description
SupervisorStatus	The supervisor's status. Acceptable values are Active, Inactive, or All. This tag is mutually exclusive with the Identifier tag.
Identifier	A container for the supervisors' email addresses and/or employee IDs. This tag is mutually exclusive with the SupervisorStatus tag. The Identifier tag may contain the following: EmailAddresses - A container for the supervisors' email addresses. Each email address is contained in an EmailAddress tag. EmployeeIDs - A container for the supervisors' employee IDs. Each employee ID is contained in an EmployeeID tag.

Tag

Description

SupervisorStatus

The supervisor's status. Acceptable values are Active, Inactive, or All. This tag is mutually exclusive with the Identifier tag.

Identifier

A container for the supervisors' email addresses and/or employee IDs. This tag is mutually exclusive with the SupervisorStatus tag. The Identifier tag may contain the following:

EmailAddresses - A container for the supervisors' email addresses. Each email address is contained in an EmailAddress tag.
EmployeeIDs - A container for the supervisors' employee IDs. Each employee ID is contained in an EmployeeID tag.

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

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

The SortBy tag may contain the following.

Column

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

Type	Acceptable SortBy Values
DetailedList	MetDate WarningDate ExpirationDate LearnerName Status
Summary	MetCount WarningCount NotMetCount CertificationName

Each sort by column is contained 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. Acceptable values are:

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 API response XML package will always include a Result, Info, and Errors tag. 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 certifications returned by the getLearnerCertificationReport method. The CertificatonReport tag may contain the following.

Tag	Description
LearnerCertification	A container for the user who is assigned a certification. The LearnerCertification tag that may contain the following: ID - The system-generated identifier for the relationship between the certification and the user the certification is assigned to. FirstName - The user's given name. LastName - The user's surname. EmployeeID - The user's employee ID. CertificationName - The certification's name. CertificationID - The certification's system-generated identifier. Status - The user's status for the certification. MetDate - The date, in UTC, the user satisfied the certification's requirements. WarningDate - The date, in UTC, the user's certification changed to Warning. ExpirationDate - The date, in UTC, the user's certification expires. MetDateConverted - The date, converted to the API user's timezone, the user satisfied the certification's requirements. WarningDateConverted - The date, converted to the API user's timezone, the user's certification changed to Warning. ExpirationDateConverted - The date, converted to the API user's timezone, the user's certification expires.

Tag

Description

LearnerCertification

A container for the user who is assigned a certification. The LearnerCertification tag that may contain the following:

ID - The system-generated identifier for the relationship between the certification and the user the certification is assigned to.
FirstName - The user's given name.
LastName - The user's surname.
EmployeeID - The user's employee ID.
CertificationName - The certification's name.
CertificationID - The certification's system-generated identifier.
Status - The user's status for the certification.
MetDate - The date, in UTC, the user satisfied the certification's requirements.
WarningDate - The date, in UTC, the user's certification changed to Warning.
ExpirationDate - The date, in UTC, the user's certification expires.
MetDateConverted - The date, converted to the API user's timezone, the user satisfied the certification's requirements.
WarningDateConverted - The date, converted to the API user's timezone, the user's certification changed to Warning.
ExpirationDateConverted - The date, converted to the API user's timezone, the user's certification expires.

The response will also include a TotalRows tag that is a count of the records in the response.

Example DetailedList API Response XML Package

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. The CertificationReport tag may contain the following.

Tag	Description
Certification	A container for the certification. This tag may contain the following: ID - The certification's system-generated identifier. CertificationName - The certification's name. Met - The number of users who have met the certification. Warning - The number of users who have certification requirements that are within the warning period. NotMet - The number of users who have not met their certification's requirements. Total - The total number of users who are assigned the certification.

Tag

Description

Certification

A container for the certification. This tag may contain the following:

ID - The certification's system-generated identifier.
CertificationName - The certification's name.
Met - The number of users who have met the certification.
Warning - The number of users who have certification requirements that are within the warning period.
NotMet - The number of users who have not met their certification's requirements.
Total - The total number of users who are assigned the certification.

Example Summary API Response XML Package

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

Was this article helpful?

What's Next

API: getLearnerCredentialReport

Table of contents

Description
Who Has Access
API Call XML Package
Report Tag Group
Filters Tag Group
SortBy Tag Group (optional)
API Response XML Package
Error Codes

SmarterU LMS is proudly located in the heart of North America, helping our clients around the globe unleash their human potential and increase their organizational intelligence.

SmarterU LMS

Company

Top Features

API: getLearnerCertificationReport

Description

Who Has Access

API Call XML Package

Report Tag Group

Type

Page

Filters

SortBy

Filters Tag Group

Status (optional)

MetDates (optional)

WarningDates (optional)

ExpirationDates (optional)

Certifications (optional)

Users (optional)

HomeGroups (optional)

Supervisors (optional)

SortBy Tag Group (optional)

Column

Order

API Response XML Package

Response for DetailedList

Example DetailedList API Response XML Package

Response for Summary

Example Summary API Response XML Package

Error Codes

Related articles

What's Next