API - Program Members List

Get Program Enrollments Report

This API can be used to get program enrollments report (Program members listing). The API is a restrictive one and can be called by an admin of the site only. Any other user trying to invoke this API would result in an error being returned by the API.

API Details

Signature of API call

connection.invokeApi(String uri, String realUserName, Map<String, String> requestParameters);

See details about invoking API in general

 

Parameter 1 - URI

reportService.do

 

Parameter 2 - UserName

Username of any site administrator

 

Parameter 3 - Request Parameters

Name Value
dispatch listProgramMembers
No other parameters are required
userId return data for a specific user corresponding to specified userId
openId return data for a specific user corresponding to specified openId
programId for a specific program id, or comma separated multiple program ids
programSessionId for a specific program (via program session id)
extId for a specific program session using its external id
child0Id Group Id of the group for which to fetch the learners data
status COMPLETED or ENROLLED indicates user's completion status in program
userNameSearch matching username, first/last name, email
fromDate min enrolled/start date of learner in program
toDate max enrolled/start date of learner in program
compFromDate min award date (completion date) of learner in program
compToDate max award date (completion date) of learner in program
expFromDate min award validity expiration date
expToDate max award validity expiration date
Paging parameters
currPage page number to fetch, must be specified for 2nd page onwards. Value of currPage starts with 0. So for page 2 specify currPage = 1
numItems total records in the list, must be specified for 2nd page onwards. You can get the count of records from response of first page. then pass it as-is in subsequent pages.
pageSize Number of items in a page

All date parameters are numbers, represented as epoch time in milliseconds - number of milliseconds that have elapsed since January 1, 1970 (midnight UTC/GMT),

Date filtering note - by default, date filters are converted to BOD and EOD (e.g. from date is converted to beginning of the day and to date is converted to end of day while applying the filtering criteria (similar to report screens in application). If you like to perform exact filtering on the passed date time, then set API_REPORT_USE_EXACT_TIME=true in Site Admin->Site Details->Customization. 

Response

1. Response on successfully getting results

HTTP Response Code = HttpServletResponse.SC_OK

Response XML

<response code="0">
    <msgs>
         <msg>
             <code>0</code>
             <value><![CDATA[Success]></value>
         </msg>
    </msgs>

 

<data>
    <programMembers numItems="198" currPage="0" pageSize="10">
    <!-- incomplete record -->
    <programMember id="88619e6e-8de8-11e6-a9c3-7b8f5d23978d" noCertificate="false" award="false" programId="fc183f24-8de4-11e6-a9c3-7b8f5d23978d" programType="TRAINING" incompleteReqdCoursesCount="2">
        <userId>2fce8ff2-8de6-11e6-a9c3-7b8f5d23978d</userId>

        <openId>xxxx:1234</openId>
        <firstName><![CDATA[John]]></firstName>
        <lastName><![CDATA[Doe]]></lastName>
        <userName><![CDATA[y4il*jdoe]]></userName>
        <status>ENROLLED</status>
        <startDate>1475994054000</startDate>
        <programName><![CDATA[Onboarding Program]]></programName>
    </programMember>
    <!-- completed record -->
    <programMember id="89019e6e-8de8-11e6-a9c3-7b8f5d23978d" noCertificate="false" award="false" programId="fc183f24-8de4-11e6-a9c3-7b8f5d23978d" programType="TRAINING" points="90" passed="true" credits="5" grade="A" awardExpired="true">
        <userId>2fce8ff2-8de6-11e6-a9c3-7b8f5d23978d</userId>
        <firstName><![CDATA[Jack]]></firstName>
        <lastName><![CDATA[Joe]]></lastName>
        <userName><![CDATA[y4il*jackdoe]]></userName>
        <status>COMPLETED</status>
        <startDate>1475994054000</startDate>
        <completionDate>1444460400000</completionDate>        

        <validityExpDate>1444460400000</validityExpDate>
        <certificateUrl><![CDATA[...]]></certificateUrl>
        <programName><![CDATA[Onboarding Program]]></programName>
        <badgeId>xxxxx</badgeId>
        <badgeName><![CDATA[Expert]]></badgeName>
        <badgeDescription><![Expert Badge]]></badgeDescription>
        <badgeExt><![CDATA[png]]></badgeExt>
    </programMember>
</programMembers>   
</data>

</response>

2. Response for unauthorized access

HTTP Response Code = HttpServletResponse.SC_UNAUTHORIZED

Response XML

<response code="-1">

    <msgs>

         <msg>

             <code>0005</code>

             <value><![CDATA[You are not allowed to perform this action.]]></value>

         </msg>

    </msgs>

</response>

3. Response on invalid filter (e.g. courseSessionId, extId, userId, openId) 

By default, when an invalid filter is passed in input, API igonres the filter and returns the results without applying it. E.g. if you are searching for a specific program session, and did not pass a valid program session id, api will return results without filtering on program session. If you want the API to not return any results and return an error code for invalid filter, you should set the property

API_NO_RESULTS_ON_INVALID_FILTER = true 

in the Site Admin->Site Details->Customization 

<response code="0">

    <msgs>

        <msg>

            <code>0004</code>

            <value>

                <![CDATA[ Unable to find User with matching ProgramSessionId=111. ]]>

            </value>

        </msg>

    </msgs>

    <data>

        <programMembers numItems="0" currPage="-1" pageSize="10"></programMembers>

    </data>

</response>

Code Snippet

       /*  Check API Call for detail generic code */
    Map<String, String> parameters = new HashMap<String, String>();
    parameters.put("dispatch", "listProgramMembers");    
   
    String retStr = connection.invokeApi("reportService.do", "chenry", parameters);
    System.out.println(retStr);

 

 


Rating: