API: getPointTrackerData
  • 3 Minutes to read
  • Dark
    Light

API: getPointTrackerData

  • 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 getPointTrackerData method retrieves a point tracker's details.

Who Has Access

Administrators and owners have access to the getPointTrackerData method.

API Call XML Package

<SmarterU>
   <AccountAPI><![CDATA[]]></AccountAPI>
   <UserAPI><![CDATA[]]></UserAPI>
   <Method>getPointTrackerData</Method>
   <Parameters>
      <PointTracker>
         <Mode><![CDATA[]]></Mode>
         <Filters>
            <PointTrackerName><![CDATA[]]></PointTrackerName>
            <Status><![CDATA[]]></Status>
            <Group>
               <Name><![CDATA[]]></Name>
               <GroupID><![CDATA[]]></GroupID>
            </Group>
            <StartDate><![CDATA[]]></StartDate>
            <EndDate><![CDATA[]]></EndDate>
         </Filters>
      </PointTracker>
   </Parameters>
</SmarterU>

PointTracker Tag Group

The PointTracker tag group is a container for how the response is returned and the point tracker filters.

<PointTracker>
   <Mode><![CDATA[]]></Mode>
   <Filters>
      <PointTrackerName><![CDATA[]]></PointTrackerName>
      <Status><![CDATA[]]></Status>
      <Group>
         <Name><![CDATA[]]></Name>
         <GroupID><![CDATA[]]></GroupID>
      </Group>
      <StartDate><![CDATA[]]></StartDate>
      <EndDate><![CDATA[]]></EndDate>
   </Filters>
</PointTracker>

The PointTracker tag may contain the following.

Mode

The type of point tracker data to return. Acceptable values are: 

  • Detailed - Returns the point tracker's details and the users who have earned points toward the point tracker.
  • Summary - Returns the point tracker's details. 

Filters

A container for the point tracker filters. Refer to Filters Tag Group.

Filters Tag Group

The Filters tag group is a container for the point tracker filters. 

<Filters>
   <PointTrackerName><![CDATA[]]></PointTrackerName>
   <Status><![CDATA[]]></Status>
   <Group>
      <Name><![CDATA[]]></Name>
      <GroupID><![CDATA[]]></GroupID>
   </Group>
   <StartDate><![CDATA[]]></StartDate>
   <EndDate><![CDATA[]]></EndDate>
</Filters>

The Filters tag group may contain the following.

PointTrackerName

The point tracker's name.

Status

The point tracker's status. Acceptable values are Active and Inactive.

Group

A container for the group filters. The Group tag contains one of the following.

TagDescription

Name

The group's name. This tag is mutually exclusive with the GroupID tag. This is the Name returned by the getGroup method.

GroupID

The group's user-specified identifier. This tag is mutually exclusive with the Name tag. This is the GroupID returned by the getGroup method.

StartDate

The first date that points for the point tracker were earned. If no StartDate filter is provided, the method returns all entries from the date the point tracker was created. Refer to Acceptable Date Formats for additional details.

EndDate

The last date that points for the point tracker were earned. If no EndDate filter is provided, the method returns all entries up to and including the current date. Refer to Acceptable Date Formats for additional details.

Acceptable Date Formats

The following are acceptable date formats for the StartDate and EndDate tags.

Format

Example

YYYY-MM-DD

2018-05-24

YYYY MM DD

2018 05 24

YYYY/MM/DD

2018/05/24

DD MMM YYYY

24 May 2018

DD MMM YY

24 May 18

MMM DD YYYY

May 24 2018

API Response XML Package

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

The getPointTrackerData response will depend on the Mode specified in the API call XML package. The Detail tag group is only returned when the Mode set to Detailed.
<SmarterU>
   <Result><![CDATA[]]></Result>
   <Info>
      <PointTrackers>
         <PointTracker>
            <Summary>
               <Name><![CDATA[]]></Name>
               <Status><![CDATA[]]></Status>
               <TotalPoints><![CDATA[]]></TotalPoints>
            </Summary>
            <Detail>
               <Name><![CDATA[]]></Name>
               <Status><![CDATA[]]></Status>
               <Users>
                  <User>
                     <EmployeeID><![CDATA[]]></EmployeeID>
                     <Email><![CDATA[]]></Email>
                     <GivenName><![CDATA[]]></GivenName>
                     <Surname><![CDATA[]]></Surname>
                     <TotalPoints><![CDATA[]]></TotalPoints>
                  </User>
               </Users>
               <TotalPoints><![CDATA[]]></TotalPoints>
            </Detail>
         </PointTracker>
      </PointTrackers>
   </Info>

   <Errors></Errors>
</SmarterU>

The PointTrackers tag is a container for the point trackers returned by the getPointTrackerData method. Each point tracker is contained in a PointTracker tag and may contain the following.

Summary

A container for the point tracker's summary information. The Summary tag may contain the following.

TagDescription
NameThe point tracker's name.
StatusThe point tracker's status.
TotalPointsThe total number of points users who have completed a course that earns points for the point tracker. 

Detail

A container for the point tracker's details and the users who have completed a course that earns points for the point tracker. The Detail tag may contain the following.

TagDescription
NameThe point tracker's name.
StatusThe point tracker's status.
UsersA container for the users who have completed a course that earns points for the point tracker. Each user is contained in a User tag and may contain the following:
TotalPointsThe total number of points users have earned for the point tracker.

Example API Response XML Package

Below is an example of an API response XML package.

<SmarterU>
   <Result>Success</Result>
   <Info>
      <PointTrackers>
         <PointTracker>
            <Summary>
               <Name><![CDATA[Fina Product Pro]]></Name>
               <Status>Active</Status>
               <TotalPoints>51</TotalPoints>
            </Summary>
            <Detail>
               <Name><![CDATA[Fina Product Pro]]></Name>
               <Status>Active</Status>
               <Users>
                  <User>
                     <EmployeeID><![CDATA[144]]></EmployeeID>
                     <Email><![CDATA[lou.greenberg@finashoes.com]]></Email>
                     <GivenName><![CDATA[Lou]]></GivenName>
                     <Surname><![CDATA[Greenberg]]></Surname>
                     <TotalPoints>20</TotalPoints>
                  </User>
                  <User>
                     <EmployeeID/>
                     <Email><![CDATA[cherry@neovation.com]]></Email>
                     <GivenName><![CDATA[Anna]]></GivenName>
                     <Surname><![CDATA[DeGuzman]]></Surname>
                     <TotalPoints>-4</TotalPoints>
                  </User>
                  <User>
                     <EmployeeID/>
                     <Email><![CDATA[ann.hall@finashoes.com]]></Email>
                     <GivenName><![CDATA[Ann]]></GivenName>
                     <Surname><![CDATA[Hall]]></Surname>
                     <TotalPoints>25</TotalPoints>
                  </User>
                  <User>
                     <EmployeeID/>
                     <Email><![CDATA[james.lee@finashoes.com]]></Email>
                     <GivenName><![CDATA[James]]></GivenName>
                     <Surname><![CDATA[Lee]]></Surname>
                     <TotalPoints>10</TotalPoints>
                  </User>
                  <User>
                     <EmployeeID/>
                     <Email><![CDATA[olivia.fina@finashoes.com]]></Email>
                     <GivenName><![CDATA[Olivia]]></GivenName>
                     <Surname><![CDATA[Fina]]></Surname>
                     <TotalPoints>0</TotalPoints>
                  </User>
               </Users>
               <TotalPoints>51</TotalPoints>
            </Detail>
         </PointTracker>
      </PointTrackers>
   </Info>

   <Errors>

   </Errors>
</SmarterU> 

Error Codes

Error CodeMessage
GPTD:01
The required permissions are not met to call the getPointTrackerData method.
GPTD:02
The Mode is not provided or not valid. The allowed values are Summary and Detailed.
GPTD:03
The Status provided is not valid. The allowed values are Active and Inactive.

Was this article helpful?