SAP Knowledge Base Article - Public

2318897 - LMS ODATA Webservices Knowledge Support and Tips

Symptom

SFTipsNTricks.JPGLMS.png
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)

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.

Picture1.png

1.1.  Description Web Service

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.

There is 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 a document on help.sap.com
 

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 it is offer 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

•OData helps on the business logic while building RESTful APIs without having to worry about the approaches to define request and response headers, status codes, HTTP methods, URL conventions, media types, payload formats and query options etc.
•OData also guides about tracking changes, defining functions/actions for reusable procedures and sending asynchronous/batch requests etc.
•OData provides facility for extension to fulfil any custom needs of RESTful APIs.
•OData RESTful APIs are easy to consume.
•The OData Protocol is different from other REST-based web service approaches in that it provides a uniform way to describe both the data and the data model

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?

•We want all SuccessFactors solutions to use the same API protocol. 
•It allows customers to use a single skill set and a single set of tools to integrate to all SuccessFactors Solutions.
•OData has rich features not available in any standard.
•OData is RESTFUL meaning its URL structure and usage pattern is based on rest, but it goes MUCH further.

OData exploits the relational model allowing:

-Reading related data with a "join". This means you can query a JobApplication, and its related JobRequisition and Attachment in a single query.

-OData allows a complete "hire employee" transaction to do it in one single operation. For example hiring an employee in EC requires many individual transactions to create user, person, employment, job, compensation, email, phone and other employee records in single transactions with OData this is done with the Hire Employee transaction

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}

ToTop.png

 

2.  LMS Web Services

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

 

2.1. ODATA LMS API Web Services

ODATA LMS API:

Description:

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://acme.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.

RESTful API:
Steps to set up RESTful SoapUI for testing:  (Note: this steps is using SOAP UI app)

1. Log in to the SAP SuccessFactors Learning administration environment for your tenant and go to System Admin->Configuration->OAuth Token Server.

Picture6.png
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. 
    a. You can use this free online tool to do this –> http://www.base64encode.org/ 
    b. The format is clientId: secretKey
    c. For example:
 
support02:
16513e29b008273a3c86d0bc4982e57ef2e7e3403484b4c6e4450a25d1495e6c41c5ef96f65975f6cdb29023afbc890e  
will encode to :
c3VwcG9ydDAyOjE2NTEzZTI5YjAwODI3M2EzYzg2ZDBiYzQ5ODJlNTdlZjJlN2UzNDAzNDg0YjRjNmU0NDUwYTI1ZDE0OTVlNmM0MWM1ZWY5NmY2NTk3NWY2Y2RiMjkwMjNhZmJjODkwZQ==

5.  User your base64 encoded secret key to create a token request.
     a. Request url resource path is /learning/oauth-api/rest/v1/token
     b. Method is POST
     c. Add a parameter to the request
            i. Name: Authorization
            ii. Value: Basic base64 encoded key
                    1. For example: Basic   c3VwcG9ydDAyOjE2NTEzZTI5YjAwODI3M2EzYzg2ZDBiYzQ5ODJlNTdlZjJlN2UzNDAzNDg0YjRjNmU0NDUwYTI1ZDE0OTVlNmM0MWM1ZWY5NmY2NTk3NWY2Y2RiMjkwMjNhZmJjODkwZQ==

Picture1new.png

            iii. Style: Header
     d. Add the following to the body of the request:
                       {
                       "grant_type":"client_credentials",
                       "scope":{
                       "userId":"yourUserId",
                       "companyId":"support02",
                       "userType":"user",
                       "resourceType":"learning_public_api"
                        }
                      }

Picture2new.png

    e. The userId in the above code is the context for all further requests.  Please use your user id.
      f.  If you need to use for an admin instead:
         {
         "grant_type":"client_credentials",
         "scope":{
         "userId":"YOURADMINID",
         "companyId":"support02",
         "userType":"admin",
         "resourceType":"learning_public_api"
          }
        }

Picture3new.png
     g. Most requests (maybe all) that require user authentication have ‘current-user’ in the URL
     h. 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. 
We will search for a student with criteria User ID=“AGPTEST”.
2. The request url is https://support02-stage.plateau.com/learning/odatav4/searchStudent/v1/Students?$filter=criteria/learnerID eq %27AGPTEST%27
3. Method is GET
4. Add the following parameters:
     a. Auth token
              i.  Name: Authorization
              ii.  Value: Bearer token from token request
                   1. Example: Bearer eyJzaWduYXR1cmUiOiJQazR……
                  iii.  Style: Header

On Body we will get the following results:

Picture4new.png

 

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
3. Method is GET
4. Add the following parameters in the Header
     a. Auth token
              i.  Name: Authorization
              ii.  Value: Bearer token from token request
                   1. Example: Bearer eyJzaWduYXR1cmUiOiJQazR……
                  iii.  Style: Header

 

You should get SUCCESS 200

Picture5new.png

 

 

Testing on a customer instance:
1. Because you need the secret key it’s harder to test this on a customer’s instance.  Perhaps they can give you the key securely or you could get permission to reset the key in staging.

 

ToTop.png

 

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

 

ToTop.png

 

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.
3. Typically this means asking the customer for the specific call or calls that are not working and trying them on a test instance. 
4. Most of the time customers are missing key or required fields or have ill-formatted fields.
5. Ask the customer for logs.  Besides their errors we can match to our logs and get any other associated information.
6. 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-support02-stage.plateau.com
7. 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.
8. Customer Support don’t help fix a customer’s custom application - Managed Services
9. Customer Support don’t help fix a customer’s custom portal - Managed Services
10. Customer Support don’t help a customer in generating calls programmatically - Managed Services

ToTop.png

5. Webservices new features (b1505 - b1602)

B1505 release new features:

  • LRN-7904 - Documentation will be posted on http://help.sap.com/hr_api#section3
  • 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).
    Documentation: http://help.sap.com/hr_api#section3

 

B1511 release new features:

 

  • 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:

 

ToTop.png

 

 

Keywords

  • LMS Odata
  • LMS Web services
  • RESTful
  • API
, KBA , LOD-SF-LMS , SuccessFactors Learning , LOD-SF-LMS-CON , Connectors , How To

Product

SAP SuccessFactors Learning all versions