Specification for Learning History Web Service

1.1 Introduction

The Learning History web service is intended to externalize user Learning History interactions for a customer portal. This web service
returns a user's Learning History details. The design is based upon the capabilities and constraints of the Learning History in the
SuccessFactors Learning user interface. For 1505 this web service has been extended to return the individual User’s Item Rating. Users
are able to provide an Item Rating providing “User Rating” has been enabled for the Item and the User has a corresponding Learning
History record against the Item. The Rating Sequence number can be used in conjunction with the 1505 “Update User Item Rating” Web
Service which allows the User’s Item Rating to be set or updated.

1.2 General Technical Design

The web service is designed to adhere to the principles of REST.
A RESTful web service (also called a RESTful web API) is a web service implemented using HTTP. It is a collection of resources, with
four defined aspects:
• The base URI for the web service, such as http://example.com/resources/. Please refer the service invocation section below to
find out the URI for this web service API.
• The Internet media type of the data supported by the web service. This web service will return JSON type of response object.
• The set operations supported by the web service using HTTP methods (e.g., GET, PUT, POST, or DELETE).
• The API must be hypertext driven.

1.3 Deprecation
As of May 5, 2015, all new customer / new webservices implementations are required to use OData
APIs for integrations (http://help.sap.com/hr_api/). This guide will remain available and RESTful web
services will continue to be supported (but no longer enhanced) for customers that had already
implemented a solution based on the RESTful APIs prior to May 5, 2015.

1.4 Functional Specifications

Service Name
This web service is Get Learning History Service

Authentication Mechanism
Webservice client will access the token provider tool in the LMS to get the user based token which later on will be passed with rest
API call. A Secret Key will be shared between LMS token provider and webservice client and will be used for authentication when web
service client is requesting for the token.

i18n Requirements (Localization)

Locale of the user passed to generate the token will be the locale for the Web service API call.

Service Invocation
RESOURCE DESCRIPTION
https://(learning server)/learning/rest/public-api/v1/current-user/learning-
history?targetUserID={targetUserID}&maxNumberToRetrieve={maxNumberToR
Request URL
etrieve}&itemID={itemID}&itemRevisionDate={itemRevisionDate}&itemType={ite
mType}&fromDate={completion from date}&toDate={completion to date}
Request Method GET
Description Learning History
Request Header Accept: application/json (Optional)
Parameters None

SuccessFactors Confidential Page 1 of 3

 Learning History Web Service
Request Body None.
RESPONSE HEADER 200: OK. or ERROR see HTTP error codes.
RestOperationStatusVOX object (This response object will have LearningHistoryDTO put in its
RESPONSE Body "data" field. LearningHistoryDTO will contain all the output parameters given below as
Key/value pair)

Inputs
Inputs are supplied to the REST API via request query-string parameters.
# Input Parameter Required? DataType Description Details/Business
Rules
1 targerUserID Yes String This is the target user id LMS user id whose learning
history is being requested
2 maxNumberToRetrieve No Number Maximum number of records Maximum number of records
to be returned to be returned
3 itemID No String This is the ID for the course Must align to the Item Type ID
(Item) defined within the LMS’
Reference Values
4 itemType No String Item Type for the Item Must be a valid Item ID in the
LMS
5 itemRevisionDate No Timestamp Revision date of the Item Must align to the revision date
of the item being queried.
Format: MMDDYYY
24HHMMSS
6 fromDate No Date From Date If specified, only those
learning history records are
returned where completion
date is on or after the from
date
7 toDate No Date To Date If specified, only those
learning history records are
returned where completion
date is on or before the to
date

Outputs
RestOperationStatusVOX
Field Description
operation Operation name
status Success/Fail
data Data returned (as described in Response body above in service invocation section)
errors Json errors (if any)
warnings Json warnings (if any)

The HTTP Response Code is used as a primary indicator of the success or failure of the API call:
HTTP Error Code Description
400 Bad request – invalid or missing inputs
401 Unauthorized – authentication credential is missing or incorrect
403 Forbidden – you are not allowed to perform this operation
404 Not found – the API itself does not exist
500 Internal server error

SuccessFactors Confidential Page 2 of 3

 Learning History Web Service

Validations
Error Code Error Message
500 User does not exist
500 User does not have access to Learning History workflow
500 User does not have Learning History
500 Item does not exist

Output is in JSON format and contains the following data elements:

# Parameter Name Data Type Description
1. componentTypeID String Item Type ID (For External Events, it will be null)
2. componentID String Item ID (For External Events, it will be null)
3. revisionDate Timestamp Revision Date
4. revisionNumber String Item Revision # (For External Events, it will be null)
5. title String Item Title
6. completionStatusID String Item Completion Status ID (For External Events, it will be null)
7. provideCredit Boolean Flag to indicate whether to provide credit to the user against the
item
8. studentComponentID Long This is the primary key for the Student Item association (For
External Events, it will be null)
9. instructorName String Instructor Name
10. grade String User’s grade for the Item (For External Events, it will be null)
11. totalHours Double Total Hours
12. creditHours Double Total Credit Hours
13. contactHours Double Total Contact Hours
14. cpeHours Double Total CPE Hours
15. comments String Additional comments entered for the employee history
16. esigUsername String Esignature Username
17. lastUpdateTimestamp Timestamp Timestamp for last time the Item was updated
18. esigMeaningCode String Esignature meaning code
19. scheduleID Long Schedule Offering ID
20. componentKey String Item Key
21. reviewContentAllowed Boolean Flag to indicate whether content can be reviewed from the User’s
Completed Work (For External Events, it will be null)
22. rating Double User’s rating of the course (For External Events, it will be null)
23. seqNum String Sequence Number (For External Events, it will be null)
24. enableRating Boolean Flag to indicate whether the user can rate the course upon
completion (For External Events, it will be null)
25. formatedRevisionDate String Revision Date
26. completionDate Timestamp Completion Date
27. status String Completion status description (For External Events, it will be null)
28. ratingDate Timestamp Date on which the rating has been done
29. ratingPending Boolean Flag to indicate whether the User has rated already or not.
30. lastCompletionDate Timestamp Completion Date of the item being used for rating, if the user has
completed the item more than once.

SuccessFactors Confidential Page 3 of 3