API: getLearnerCertificationPivotReport
  • 7 Minutes to read
  • Dark
    Light

API: getLearnerCertificationPivotReport

  • 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 getLearnerCertificationPivotReport returns the following for the specified certification:

  • The users who are assigned the certification 
  • The user's status for each course and action associated with the certification

The getLearnerCertificationPivotReport returns a maximum of 2000 users, 200 courses, and 200 actions. These limits are independent of one another.

Who Has Access

The following users have access to the getLearnerCredentialReport method:

API Call XML Package

<SmarterU>
   <AccountAPI><![CDATA[]]></AccountAPI>
   <UserAPI><![CDATA[]]></UserAPI>
   <Method>getLearnerCertificationPivotReport</Method>
   <Parameters>
      <Certification>
         <Page></Page>
         <PageSize></PageSize>
         <SortField></SortField>
         <SortOrder></SortOrder>

         <Filters>
            <Certifications>
               <Certification>
                  <ID></ID>
               </Certification>
            </Certifications>

            <Users>
               <User>
                  <ID></ID>
                     - OR -
                  <Email></Email>
                     - OR - 
                  <EmployeeID></EmployeeID>
               </User>
            </Users>

            <UserCustomFields>
               <UserCustomField>
                  <CustomFieldName></CustomFieldName>
                  <CustomFieldValue></CustomFieldValue>
               </UserCustomField>
            </UserCustomFields>

            <UserHomeGroups>
               <UserHomeGroup>
                  <ID></ID>
               </UserHomeGroup>
            </UserHomeGroups>

            <Supervisors>
               <Supervisor>
                  <ID></ID>
                     - OR -
                  <Email></Email>
                     - OR - 
                  <EmployeeID></EmployeeID>
               </Supervisor>
            </Supervisors>

            <Credentials>
               <Credential>
                  <ID></ID>
               </Credential>
            </Credentials>

            <LearningModules>
               <LearningModule>
                  <ID></ID>
               </LearningModule>
            </LearningModules>

            <EnrollmentStates>
               <EnrollmentState></EnrollmentState>
            </EnrollmentStates>

            <CredentialStates>
               <CredentialState></CredentialState>
            </CredentialStates>
         </Filters>
      </Certification>
   </Parameters>
</SmarterU>

Certification Tag Group

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

<Certification>
   <Page></Page>
   <PageSize></PageSize>
   <SortField></SortField>
   <SortOrder></SortOrder>

   <Filters>
      <Certifications>
         <Certification>
            <ID></ID>
         </Certification>
      </Certifications>

      <Users>
         <User>
            <ID></ID>
               - OR -
            <Email></Email>
               - OR - 
            <EmployeeID></EmployeeID>
         </User>
      </Users>

      <UserCustomFields>
         <UserCustomField>
            <CustomFieldName></CustomFieldName>
            <CustomFieldValue></CustomFieldValue>
         </UserCustomField>
      </UserCustomFields>

      <UserHomeGroups>
         <UserHomeGroup>
            <ID></ID>
         </UserHomeGroup>
      </UserHomeGroups>

      <Supervisors>
         <Supervisor>
            <ID></ID>
               - OR -
            <Email></Email>
               - OR - 
            <EmployeeID></EmployeeID>
         </Supervisor>
      </Supervisors>

      <Credentials>
         <Credential>
            <ID></ID>
         </Credential>
      </Credentials>

      <LearningModules>
         <LearningModule>
            <ID></ID>
         </LearningModule>
      </LearningModules>

      <EnrollmentStates>
         <EnrollmentState></EnrollmentState>
      </EnrollmentStates>

      <CredentialStates>
         <CredentialState></CredentialState>
      </CredentialStates>
      
   </Filters>
</Certification>

The Certification tag may contain the following.

Page (optional)

The page number to return. The default is 1.

PageSize (optional)

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

SortField (optional)

The field used to sort the results:

  • Name - The results will be sorted by user names.
  • Employee_ID - The results will be sorted by employee IDs.

SortOrder (optional)

The directions the results will be sorted:

  • Asc - The results will be sorted in ascending order.
  • Desc - The results will be sorted in descending order.

Filters

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

Filters Tag Group

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

<Filters>
   <Certifications>
      <Certification>
         <ID></ID>
      </Certification>
   </Certifications>

   <Users>
      <User>
         <ID></ID>
            - OR -
         <Email></Email>
            - OR -
         <EmployeeID></EmployeeID>
      </User>
   </Users>

   <UserCustomFields>
      <UserCustomField>
         <CustomFieldName></CustomFieldName>
         <CustomFieldValue></CustomFieldValue>
      </UserCustomField>
   </UserCustomFields>

   <UserHomeGroups>
      <UserHomeGroup>
         <ID></ID>
      </UserHomeGroup>
   </UserHomeGroups>

   <Supervisors>
      <Supervisor>
         <ID></ID>
            - OR -
         <Email></Email>
            - OR -
         <EmployeeID></EmployeeID>
      </Supervisor>
   </Supervisors>

   <Credentials>
      <Credential>
         <ID></ID>
      </Credential>
   </Credentials>

   <LearningModules>
      <LearningModule>
         <ID></ID>
      </LearningModule>
   </LearningModules>

   <EnrollmentStates>
      <EnrollmentState></EnrollmentState>
   </EnrollmentStates>

   <CredentialStates>
      <CredentialState></CredentialState>
   </CredentialStates>
      
</Filters>

The Filters tag may contain the following.

Certifications

You must specify at least one certification; you can specify up to 50 certifications.

The Certifications tag is a container for the certifications to include in the response. 

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

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

TagDescription
IDThe certification's system-generated identifier. 

Users (optional)

The Users tag is a container for the users to include in the response. 

<Users>
   <User>
      <ID></ID>
         - OR -
      <Email></Email>
         - OR -
      <EmployeeID></EmployeeID>
   </User>
</Users>
You can specify up to 200 users.

Each user is contained in a User tag and may contain the following.

TagDescription
IDThe user's system-generated identifier. This is the ID returned by the getUser and listUsers methods. 
EmailThe user's email address. This is the Email returned by the getUser and listUsers methods. 
EmployeeIDThe user's employee ID. This is the EmployeeID returned by the getUser and listUsers methods. 

UserCustomFields (optional)

The UserCustomFields tag is a container for the custom user field values to include in the response. 

<UserCustomFields>
   <UserCustomField>
      <CustomFieldName></CustomFieldName>
      <CustomFieldValue></CustomFieldValue>
   </UserCustomField>
</UserCustomFields>
You can specify up to 10 custom user fields.

Each custom user field filter is contained in a UserCustomField tag and contains the following.

TagDescription
CustomFieldNameThe custom user field's name. To specify the field name of a hierarchical custom user field, separate each level with a greater than symbol (>).
CustomFieldValueThe value of the custom user field. To specify the value for a hierarchical custom user field, separate each level with a greater than symbol (>). 

UserHomeGroups (optional)

The UserHomeGroups tag group is a container for the home groups to include in the response.

<UserHomeGroups>
   <UserHomeGroup>
      <ID></ID>
   </UserHomeGroup>
</UserHomeGroups>
You can specify up to 50 home groups.

Each home group is contained in a UserHomeGroup tag and contains the following.

TagDescription
IDThe group's user-specified identifier

Supervisors (optional)

The Supervisors tag group is a container for the supervisors to include in the response.

<Supervisors>
   <Supervisor>
      <ID></ID>
         - OR -
      <Email></Email>
         - OR -
      <EmployeeID></EmployeeID>
   </Supervisor>
</Supervisors>
You can specify up to 200 supervisors.

Each supervisor is contained in a Supervisor tag and contains the following.

TagDescription
IDThe supervisor's system-generated identifier. This is the ID returned by the getUser and listUsers methods. 
EmailThe supervisor's email address.
EmployeeIDThe supervisor's employee ID.

Credentials (optional)

The Credentials tag group is a container for the actions to include in the response.

<Credentials>
   <Credential>
      <ID></ID>
   </Credential>
</Credentials>
You can specify up to 50 actions.

Each action is contained in a Credential tag and contains the following. 

TagDescription
IDThe action's system-generated identifier. This is the CredentialID returned by the getCredential and listCredentials methods.

LearningModules (optional)

The LearningModules tag group is a container for the courses to include in the response. 

<LearningModules>
   <LearningModule>
      <ID></ID>
   </LearningModule>
</LearningModules>
You can specify up to 50 courses.

Each course is contained in a LearningModule tag and contains the following.

TagDescription
IDThe course's user-specified identifier.

EnrollmentStates (optional)

The EnrollmentStates tag group is a container for the enrollment statuses to include in the response.

<EnrollmentStates>
   <EnrollmentState></EnrollmentState>
</EnrollmentStates>
You can specify up to 20 enrollment statuses.

Each enrollment status is contained in an EnrollmentState tag. Acceptable values are:

  • Enrolled
  • In Progress
  • Complete
  • Warning
  • Overdue
  • Not Enrolled

CredentialStates (optional)

The CredentialStates tag is a container for the action statuses to include in the response.

<CredentialStates>
   <CredentialState></CredentialState>
</CredentialStates>
You can specify up to 20 action statuses.

Each action status is contained in a CredentialState tag. Acceptable values are:

  • Accepted
  • Pending
  • Review
  • Not Assigned

API Response XML Package

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

<SmarterU>
   <Result></Result>
   <Info>
      <Columns>
         <Column>
            <ReportName></ReportName>
            <DisplayName></DisplayName>
            <Type></Type>
         </Column>
      </Columns>

      <LearnerCertificationPivotReport rows=”” rowlimitreached=”” courselimitreached=”” credentiallimitreached=””>
         <Learner>
            <ID></ID>
            <LastName></LastName>
            <FirstName></FirstName>
            <EmployeeID></EmployeeID>
            <LearningModule_nnn></LearningModule_nnn>
            <Credential_nnn></Credential_nnn>
         </Learner>
      </LearnerCertificationPivotReport>
   </Info>
</SmarterU>

The response may also contain the following.

Columns

The Columns tag is a container for the response's column headers. 

<Columns>
   <Column>
      <ReportName></ReportName>
      <DisplayName></DisplayName>
      <Type></Type>
   </Column>
</Columns>

Each column is contained in a Column tag and may contain the following. 

TagDescription
ReportNameThe system-generated name for the report. The ReportName will be prefixed with Credential_ or Learningmodule_.
DisplayNameThe name of the course or action.
TypeIndicates what's displayed in the column. Possible values are:
  • Credential - The column displays an action.
  • LearningModule - The column displays a course.

LearnerCertificationPivotReport

The LearnerCertificationPivotReport is a container for the learners, and their status for the course or action. 

<LearnerCertificationPivotReport rows=”” rowlimitreached=”” courselimitreached=”” credentiallimitreached=””>
   <Learner>
      <ID></ID>
      <LastName></LastName>
      <FirstName></FirstName>
      <EmployeeID></EmployeeID>
      <LearningModule_200></LearningModule_200>
      <Credential_100></Credential_100>
   </Learner>
</LearnerCertificationPivotReport>

The following attributes are contained in the LearnerCertificationPivotReport tag and provide notification when a limit was reached.

  • rows - The number of records that meet the specified filters. 
  • rowlimitreached - Indicates whether the maximum number of learners that can be returned (i.e., 2000) for the certification was reached.
  • courselimitreached - Indicates whether the maximum number of courses that can be returned (i.e., 200) for the certification was reached.
  • credentiallimitreached - Indicates whether the maximum number of actions that can be returned (i.e., 200) for the certification was reached. 

Each learner is contained in a Learner tag and may contain the following.

TagDescription
IDThe user's system-generated identifier. 
LastNameThe user's surname.
FirstNameThe user's given name.
EmployeeIDThe user's employee ID.
LearningModule_nnnThe user's status for the course.
Credential_nnnThe user's status for the action.

Example API Response XML Package

<SmarterU>
	<Result></Result>
	<Info>
		<Columns>
			<Column>
				<ReportName>credential_100</ReportName>
				<DisplayName>Photo ID</DisplayName>
				<Type>Credential</Type>
			</Column>
			<Column>
				<ReportName>credential_200</ReportName>
				<DisplayName>Emergency Contact Form</DisplayName>
				<Type>Credential</Type>
			</Column>

			<Column>
				<ReportName>learningmodule_100</ReportName>
				<DisplayName>Customer Service: Retail</DisplayName>
				<Type>LearningModule</Type>
			</Column>
			<Column>
				<ReportName>learningmodule_200</ReportName>
				<DisplayName>Using the Point-of-Sales System</DisplayName>
				<Type>LearningModule</Type>
			</Column>

			<Column>
				<ReportName>learningmodule_300</ReportName>
				<DisplayName>Fitting Customers for Footwear</DisplayName>
				<Type>LearningModule</Type>
			</Column>
		</Columns>
		<LearnerCertificationPivotReport rows=”4” rowlimitreached=”false” courselimitreached=”false” credentiallimitreached=”false”>
			<Learner>
				<ID>1</ID>
				<LastName>Atkins</LastName>
				<FirstName>Robin</FirstName>
				<EmployeeID>1234</EmployeeID>
				<learningmodule_100>Overdue</learningmodule_100>
				<learningmodule_200>Warning</learningmodule_200>
				<learningmodule_300>Complete</learningmodule_200>
				<credential_100>Review</credential_100>
				<credential_200>Accepted</credential_200>
			</Learner>

			<Learner>
				<ID>2</ID>
				<LastName>Black</LastName>
				<FirstName>Kevin</FirstName>
				<EmployeeID>5678</EmployeeID>
				<learningmodule_100>Complete</learningmodule_100>
				<learningmodule_200>Warning</learningmodule_200>
				<learningmodule_300>Overdue</learningmodule_200>
				<credential_100>Pending</credential_100>
				<credential_200>Not Assigned</credential_200>
			</Learner>

			<Learner>
				<ID>3</ID>
				<LastName>Kravitz</LastName>
				<FirstName>Amber</FirstName>
				<EmployeeID>9876</EmployeeID>
				<learningmodule_100>Complete</learningmodule_100>
				<learningmodule_200>Complete</learningmodule_200>
				<learningmodule_300>Warning</learningmodule_200>
				<credential_100>Accepted</credential_100>
				<credential_200>Accepted</credential_200>
			</Learner>
		</LearnerCertificationPivotReport>
	</Info>
</SmarterU>

Error Codes

Error CodeMessage
CLGPR:01The page number provided is not valid.
CLGPR:02The page size provided is not valid.
CLGPR:03The sort field provided is not valid.
CLGPR:04The sort order provided is not valid.
GLCPR:05The required permissions are not met to call the getLearnerCertificationPivotReport method.
GLCPR:06The value for the sort order must be ASC or DESC.
GLCPR:07The value for the sort field must be NAME or EMPLOYEE_ID.
GLCPR:08One or more of the user email and/or employee ids provided are invalid.
GLCPR:09One or more of the custom field names provided are invalid.
GLCPR:10Encrypted custom fields cannot be used for filtering.
GLCPR:11One or more of the custom hierarchical custom field values is invalid.
GLCPR:12One or more of the home groups provided are invalid.
GLCPR:13One or more of the supervisor email and/or employee ids provided are invalid.
>GLCPR:14One or more certifications provided are invalid.
GLCPR:15One or more credentials provided are invalid.
GLCPR:16One or more learning modules provided are invalid.
GLCPR:17Invalid enrollment status filter, allowed values are Enrolled, In Progress, Completed, and Not Enrolled.
GLCPR:18Invalid credential status filter, allowed values are Pending, Review, Accepted, and Not Assigned.
GLCPR:19No certifications were found using the filters provided.
GLCPR:20One or more learning module filters provided are not assigned to the certifications provided.
GLCPR:21One or more credential filters provided are not assigned to the certifications provided.
GLCPR:22No learning modules or credentials are assigned to the certifications provided.

Was this article helpful?