Specification for Update User Item Rating Web Service

LMS Version 1505, Version 4, April 2nd, 2015

1.1 Introduction
The Update User Item Rating web service is intended to provide an option for external applications (Portal, External Mobile apps) to set
and update a specific User’s Item Rating. Users are able to provide an Item Rating if “User Rating” has been enabled for the Item and
the User has a corresponding Learning History record against the Item. The design is based upon the constraints and capabilities of the
User Rating Interface available via the User’s Learning History page in the Learning application.

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 update_User_Item_Rating

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.
Authorization
We will check the User has Completed an Item that has Rating Enabled.

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
Request URL http://(learning server)/learning/public-api/rest/v1/current-user/item-rating-input
Request Method POST
Description Update / Insert User Item Rating
Request Header Accept: application/json (Optional)
Parameters See details below
Request Body None
RESPONSE HEADER 200: OK. or ERROR see HTTP error codes.
RESPONSE Body RestOperationStatusVOX object (This response object will have “status” put in its "status" field.
SuccessFactors Confidential Page 1 of 5
 Update Item - Content Object Details Web Service
Also error (if any) will be stored in “errors” field )

SuccessFactors Confidential Page 2 of 5

 Update Item - Content Object Details Web Service
Inputs
Inputs are supplied to the REST API via request query-string parameter and Json Payload Objects
# DataType within Json Payload
Input Parameter Required? Description Object
1 sequenceNumber String Student Item Rating ID ( within Json Payload Object
Unique Identifier)
Data Type:
VARCHAR2(90)
2 rating Long Rating within Json Payload Object

Data Type:
Number
3 ratingDate Timestamp Date on which the Rating is within Json Payload Object
done
Data Type:
Timestamp Format in
milliseconds: 13 Bytes
4 componentTypID Y String Item Type ID within Json Payload Object

Data Type:
VARCHAR2(90)
5 componentID Y String Item ID within Json Payload Object

Data Type:
VARCHAR2(90)
6 revDte Y Timestamp Revision Date within Json Payload Object

Data Type:
Timestamp Format in
milliseconds: 13 Bytes
7 lastCompletionDate Timestamp Completion Date of the Item within Json Payload Object
used for rating
Data Type:
Timestamp Format in
milliseconds: 13 Bytes

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 3 of 5

 Update Item - Content Object Details Web Service

Validations
Error Code Error Message
500 Invalid Request - No Input Data
500 Invalid Request - Rating should be between 1 and 5
500 Invalid Authorization – Access Denied
500 Invalid Request - Component Type ID is a required field
500 Invalid Request - Component ID is a required field
500 Invalid Request - Revision Date is a required field
500 Invalid Request - Last Completion date is a required field
500 Invalid Request - Rating Date Cannot be greater than current date and time
500 Invalid Request - No matching records to update
500 Invalid Request - Item rating is not enabled for the item
500 Invalid Request - Invalid Sequence Number
500 Invalid Request - Last Completion date is incorrect

Output will be in JSON format and contains the following data elements:
No Parameter Name Data Type Description

SuccessFactors Confidential Page 4 of 5

 Update Item - Content Object Details Web Service
1.5 Data Formats/Rules

When recording any initial Item completion as Admin or User the application creates a User Item Rating record with the Rating Pending
Status of Y (true) and a Rating null.
If the User or Admin completes the same Item again then the application sets the Rating Pending flag to = Y (true) but the existing
rating will still remain.
The Pending Rating Flag allows the User to be potentially reminded if Ratings are pending. Once the User Rates an Item, updates an
Item Rating or clears a previous Item Rating the Rating Pending flag is set to N (false).
The above two scenarios where the flag is set to Y (true) are both are driven by the application functionality and when the user takes
action on rating (either rating an item or clears the rating of an item), this flag will be set to N. Therefore the User Update Item Rating
Web Service will set Rating Pending value as false by default..
The following Rules/Expectation is applicable for successful service response.

1. The client should check that the item is in learning history and User Item Rating is enabled for the Item before sending the
request.
2. All date input parameters with type long shall be passed in milliseconds since 1 Jan 1970 00:00:00
3. Input parameters specified in the input table should be passed as JSon object payload.
4. All the payload objects should carry the previous values if there is no change, otherwise it will be updated as null.

1.6 Sample Json PayLoad Input Objects

{
"sequenceNumber":"0123456789ABCDEF0123456789ABCDEF",
"rating":"4",
"ratingDate":1315679400000,
"componentTypID":"COURSE",
"componentID":"I00001",
"revDte":1315679400000,
"lastCompletionDate":1315679400000,
}

SuccessFactors Confidential Page 5 of 5