2318897 - LMS ODATA Webservices Knowledge Support and Tips

Click to go back to the main page

 

LMS ODATA WEBSERVICES KNOWLEDGE SESSION FOR CUSTOMERS, PARTNERS AND SAP PRODUCT SUPPORT

1.  What are Web Services?

1.1.  Description Web Service

1.2. LMS WEB Services : ODATA

1.3 ODATA for SAP SuccessFactors Learning Application

1.4. But What it is ODATA?

1.5. Why ODATA?

1.6. LMS Modularization and URL Pattern

2.  LMS Web Services

2.1. ODATA LMS API Web Services

3. Common Errors        

3.1. Known Issues: KBA created for webservices LMS

4. General Notes

5. Webservices new features (b1505 - b1602)

SAP SuccessFactors Learning (LMS)

1. What are Web Service?

• Web services are open standard (XML, SOAP, HTTP etc.) based Web applications that interact with other web applications for the purpose of exchanging data.
• Web Services can convert your existing applications into Web-applications.
• A web service is any piece of software that makes itself available over the internet and uses a standardized XML messaging system. XML is used to encode all communications to a web service. For example, a client invokes a web service by sending an XML message, then waits for a corresponding XML response. As all communication is in XML, web services are not tied to any one operating system or programming language--Java can talk with Perl; Windows applications can talk with Unix applications.
• Web services are self-contained, modular, distributed, dynamic applications that can be described, published, located, or invoked over the network to create products, processes, and supply chains. These applications can be local, distributed, or web-based. Web services are built on top of open standards such as TCP/IP, HTTP, Java, HTML, and XML.
• Web services are XML-based information exchange systems that use the Internet for direct application-to-application interaction. These systems can include programs, objects, messages, or documents.
• Simplified, non-technical explanation: A web service allows a PROGRAM to talk to a web page, instead of using your browser to open a web page.
• Example: I can go to maps.google.com, and type in my home address, and see a map of where I live in my browser.
• But what if you were writing a computer program where you wanted to take an address and show a pretty map, just like Google maps?  Well, you could write a whole new mapping program from scratch, OR you could call a web service that Google maps provides, send it the address, and it will return a graphical map of the location, which you can display in your program.  There is a lot more to it, as some of the other posts go into, but the upshot is that it allows your application to either retrieve information FROM, or submit information to some resource. Some other examples:
• Use a web service to retrieve information about books at Amazon.com
• Use a similar web service to submit an order to Amazon.com
• CREATE a web service to allow outside applications to find out about product information within your company
• Create a web service to allow outside applications to submit orders to your company.

1.1.  Description Web Service

To summarize, a complete web service is, therefore, any service that:
-  Is available over the Internet or private (intranet) networks
-  Uses a standardized XML messaging system
-  Is not tied to any one operating system or programming language
-  Is self-describing via a common XML grammar
-  Is discoverable via a simple find mechanism

1.2. LMS WEB Services : ODATA

Web Services are used to access application data outside of the application UI and there are two types of LMS Web Services:

1. SOAP/WSDL (AXIS): These were the old LMS Web Services used in old implementations and deprecated in 1808.
   •Engineering is no longer adding or correcting defects unless it is a big problem with them.
   •From Customer Support we advice customers to move to LMS OData Web Services.
   •Calls are made by an Admin id.
2. ODATA (RESTful API): OData is used to define best practices that are required to build and consume RESTful APIs.
   Have every Entity covered within Learning OData API Reference Help Guide: https://help.sap.com/viewer/5aab9bef78fc4c4fa199c1f7aa142720/latest/en-US/1da023d82c524aae853bca590b2f9ed0.html

 In this case we will choose the Learning: Learning OData API Reference

1.3 ODATA for SAP SuccessFactors Learning Application

• This is the newer Web Services available on the SAP SuccessFactors Learning application
• Calls are made with a user id and has the user’s context, or the admin id and the admin’s context
• As we can use a user’s context, customers can more easily create their own custom portals in Customer side.
• Each Service is all documented on the SuccessFactors Learning Web Services - OData API Reference as a powerful feature, ODATA Provides $metadata, which is a service guide itself. Customer who uses ODATA MUST get used to read the $metadata which comes automatically with the service instead of using the old fashioned API Reference.
• Instead of a password you need to get a secret key from System Admin -> Configuration -> OAuth Token Server. The key will only show once after you request a new one. Previous keys will be invalidated. We use this key to get a token that we use to validation our session while making REST Api calls.

1.4. But What it is ODATA?

OData (Open Data Protocol) is an OASIStandard that defines the best practice for building and consuming OData RESTful APIs. An application-level open protocol allow the creation and consumption of queryable and interoperable RESTful APIs in a simple and standard way.

Benefits of using ODATA Web Services

Key Terms:

• REST: is an architecture of how to send messages over HTTP.
• OData V4: is a specific implementation of REST, really defines the content of the messages in different formats. ODataV4 follows rest principles.
• API: Application Programming Interface

1.5. Why ODATA?

1.6. LMS Modularization and URL Pattern

OData version 4 - http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part1-protocol.html

• To maximize performance and flexibility, there are multiple OData service end points, or multiple $metadata instead of just one:
• /learning/odatav4/public/user/catalogSearch/v1/$metadata
• /learning/odatav4/public/user/learningPlan/v1/$metadata
• /learning/odatav4/public/user/learningPlan/v1/$metadata
• Leverage Odata’s <edm:reference> feature to share entities across different services:
• URL pattern – {servlet_context}/odatav4/{visibility}/{user_type}/{odata_service}/{odat_service_version}/{entity/function/action}

2.  LMS Web Services

SuccessFactors Learning Web Services - OData API Reference Guide is the guide for implementing Webservices in LMS.

2.1. ODATA LMS API Web Services

ODATA LMS API:

This is the newer Web Services it is offer on the LMS instanceCalls are made with a user id and has the user’s context, or the admin id and the admin’s contextAs we can use a user’s context customers can more easily create a custom portals in Customer side.Each Service is all documented on the SuccessFactors Learning Web Services - OData API Reference.

Instead of a password you need to get a secret key from System Admin -> Configuration -> OAuth Token Server.  The key will only show once after you request a new one.  Previous keys will be invalidated.

We use this key to get a token that we use to validation our session while making REST API calls.

24 Q3 2016 (B1608) API Calls Available:

• Add and Update LMS User
• Curricula Status Web Services
• Learning Catalog Search
• Financial Transactions
• Learning History Web Service
• Learning Item Assignment Web Service v1
• Learning Item Assignment Web Service v2
• Learning Program Assignment Web Service
• Learning Curriculum Assignment Web Service
• Get Enrollment List
• Enroll into Scheduled Offerings
• Mark Segment Attendance Web Service
• Modify Enrollment Status Web Service
• Learning Item Detail Web Service
• Learning Item Prerequisite Web Service
• Learning Item Related Documents Web Service
• Learning Plan Search
• Search Curricula Web Service
• Student/User Search Web Service
• Learning Item Search Web Service
• Record Learning Event to Learning History Web service
• Get Scheduled Offering Web Service
• Get Available Scheduled Offering Web Service
• SAP SuccessFactors Learning Approval Web Service

Root:
The root URL is the URL you type into a browser to open the log in page, like https://{root}.successfactors.com. In this document, you see URLs as follows, where you substitute {root} with your root URL:

Calls to the actual web services are prefaced by: https://{root}/learning/public-api/odatav4. The path is reiterated in each of the web service calls descriptions.

Calls to get tokens are prefaced by: https://{root}/learning/oauth-api/rest/v1/token. The path is reiterated in the documentation for getting tokens.

If customer do not know the learning server URL, they will contact SAP SuccessFactors for help.

Note 1: As of May 5, 2015, all new customer / new webservices implementations are required to use OData APIs for integrations. The old RESTful web services, which were not based on OData, will continue to be supported (but not enhanced). They will be supported for customers who already implemented a solution based on the old RESTful APIs before May 5, 2015. We recommend them that they begin using the OData web services described in this document.

Note 2: As of 2017 Q1 - Although we are not ready to deprecate OData services, we prefer that you use our micro-services because we plan to shift resources in the future to the preferred micro-services. When you see a service that has the syntax *-service, you know it is part of the forward-looking microservices strategy that we are building. When possible, use these services because they are the most actively maintained.

Overview of OAuth for SuccessFactors Learning
This topic provides an overview of the OAuth authentication for SAP SuccessFactors Learning web services, which use a RESTful interface, and pass JSON objects.Audience for

OAuth and Web Service Documentation
To be successful with SAP SuccessFactors Learning web services, you need experience building clients with HTTP 1.1 specifications, RESTful conventions, JSON formatting, and OAuth tokens.

About OAuth
OAuth is a widely accepted framework for limited machine-to-machine data sharing. Full log in credentials are not stored or shared on the client machine. Instead, the client and server share a token that allows the client access to only a limited set of data and methods on the data. The process of gaining a token and its policy creates trust between the two servers. You can learn more about OAuth on its web site.

1. Log in to the SAP SuccessFactors Learning administration environment for your tenant and go to System Admin->Configuration->OAuth Token Server.
   
2. Click Generate a new Client Secret.  SAP SuccessFactors Learning generates a client secret, a client secret has value, and a public key.
3. Copy the values on the page.
4. Encode the client id with the secret key to base64.
• You can use this free online tool to do this –> http://www.base64encode.org/
• The format is clientId:secretKey
5. User your base64 encoded secret key to create a token request:
1. Request url resource path is /learning/oauth-api/rest/v1/token
2. Method is POST
3. Add a parameter to the request:
1. Name: Authorization
2. Value: Basic base64 encoded key
                      
3. Style: Header
4. Add the following to the body of the request:
    { "grant_type":"client_credentials",
       "scope":{
         "userId":"yourId",
         "companyId":"yourCompany",
         "userType":"user",
         "resourceType":"learning_public_api"
       }
   }
   
   The userId in the above code is the context for all further requests; Please use your user/admin id depending on the micor-service call.
5. Most requests (maybe all) that require user authentication have ‘current-user’ in the URL
6. The session will last 1800 seconds or 30 minutes; then you will need to request a new token. 

 Steps to test one of the services (LMS ODATA SEARCH STUDENT)

1. You will need the token from the previous steps in all of your requests.  
2. The request url is https://{root}.plateau.com/learning/odatav4/searchStudent/v1/Students?$filter=criteria/learnerID eq %TEST%27
3. Method is GET
4. Add the following parameters:
1.  Auth token:
     i.  Name: Authorization
    ii.  Value: Bearer token from token request
   iii.  Style: Header 

Steps to test LMS ODATA LEARNING HISTORY

1. The request url is {root} /learning/odatav4/public/user/learningHistory/v1/learninghistorys?$filter=criteria/targetUserID eq %27USERID%27
2. Method is GET
3. Add the following parameters in the Header
1. Auth token
1. Name: Authorization
2. Value: Bearer token from token request
      Example: Bearer eyJzaWduYXR1cmUiOiJQazR……
3. Style: Header

 You should get SUCCESS 200

3. Common Errors

1. There is something missing from your request or your request does not have the required information:  The action you requested could not be processed
2. The request URL is not correct: The page you requested does not exist   Please try to compare with a working service call and search jira to find the right url. 
3. If your token is wrong or you did not follow the right steps:
   java.lang.NullPointerException: while trying to invoke the method com.plateausystems.elms.framework.oauth2.api.TokenSignedEnvelope.getSignature() of an object loaded from local variable 'tokenSignedEnvelope'
4. If you forgot to add you Authorization parameter or forgot to make it HEADER based:
   Invalid OAuth Request to the protected resource.
   javax.servlet.ServletException: Invalid OAuth Request to the protected resource.
5. SoapUI may throw an UnknownHostException when trying any calls.  This is likely and issue with your computer only.  Typically you were on VPN or corporate proxy and are now off of it.  Try saving your project and reloading SoapUI.  You could also try to by-pass any proxy in the preferences of SoapUI.

3.1.  Known Issues: KBA created for webservices LMS    

• 2279128 - Enable API Webservices LMS data in LMS instance
• 2271099 - Error returned when adding user via webservice api

4. General Notes

1. Web Services are used to access application data outside of the application UI.  
2. Our job is to make sure these work as designed; Typically this means asking the customer for the specific call or calls that are not working and trying them on a test instance.  
3. Most of the time customers are missing key or required fields or have ill-formatted fields.
4. May require logs; SF Support can match to our logs and get any other associated information.
5. Customers who have Akamai may not have taken that into account and need special firewall rules for their custom applications.  Suggest adding origin- to the LMS domain to bypass Akamai.  Example:  https://origin-{root}.plateau.com
6. Like Connectors and the Data Import Tool, data entered by Web Services can be subject to problems because the normal checks done by the UI are not in play.  Many defects are rooted in this issue.
7. SF Support doesn’t help fix a customer’s custom application - Professional Services
8. SF Support doesn’t help fix a customer’s custom portal - Professional Services
9. SF doesn’t help a customer in generating calls programmatically - Professional Services

5. Webservices new features (b1505 - b1602)

B1505 release new features:

• LRN-7904
• LRN-7958 - RESTful Webservices Enhancements
  Update User Item Rating (new – used so that user can rate item)
  Get Learning History (enhanced to return item rating)

B1508 release new features:

• LRN-9464
  ODataAPIs enhancements:
  Get Item Details (new)
  Get Item Prerequisites (new)
  Get Item Related Documents (new)
  Add/Update User:added support for the "User can Use Org Accounts" field in the OData API (corresponds to PA_STUDENT: ACCESS_TO_ORG_FIN_ACT field in DB). 

B1511 release new features:

• LRN-8922
  OdataAPIs:
  -Item Assignment (self/supervisor/admin)
  -Get Learning History
  Universal 

• LRN-8059:
  New ODATA APIs and Financial Transactions Admin UI enhancements were added to support integration with Financial Accounting Systems. The APIs are available to use to build a custom integration with an external financial system.
  The planned Hana Cloud Interface Integration with SAP FICO will also be built using these APIs.

New ODATA APIs created:
•Financial Transactions Query API
•Financial Transactions Posting Status Update API

B1602 release new features:

• LRN-11201
  ODATA API: Add Learning Event (as a user / supervisor / admin)
  Universal 

SAP Sf success factors learning LMS Odata Web services service RESTful API rest call , KBA , LOD-SF-LMS , Learning Management System , LOD-SF-LMS-CON , Connectors , How To