You are on page 1of 100

SAP Sourcing Release 10.

Web Service Cookbook and


Troubleshooting Guide

November 2015

© 2015 SAP AG. All rights reserved.


Table of Contents
Introduction................................................................................................................................................ 4
Intended Audience and Assumptions ........................................................................................................... 4
Cookbook 1: Executing Scripts via the Web Service Framework ........................................................... 5
Sample Reference Scripts for Script-based Web Services ............................................................................ 5
Configuring the Sample Project Web Service ............................................................................................... 6
Executing the Sample Project Web Service using Chrome Postman ...........................................................17
Getting Started............................................................................................................................................18
Services Discovery .....................................................................................................................................21
Using POST to create a Project ..................................................................................................................23
Using PUT to update a Project ....................................................................................................................29
Understanding the XML payload format for POST and PUT ........................................................................32
Using GET to read a Project .......................................................................................................................32
Viewing the Web Service Request Log........................................................................................................34
Troubleshooting Guide for Executing Scripts via the Web Service Framework ....................................38
The desired Web Service is stopped ...........................................................................................................38
Connection Error: The Sourcing/CLM application server is not running ........................................................39
Connection Error: Misssing https certificate for Chrome...............................................................................39
Connection Error: Space character at beginning of URL ..............................................................................41
Resource Not Found Error - Bad URL - Missing URL resource ....................................................................41
Schema File attachment errors ...................................................................................................................42
Cookbook 2: Submitting Queries via the Web Service Framework ........................................................45
Configuring the Query Web Service Report and Queries .............................................................................45
How to Submit Queries via the Web Service Framework (WSF), using Chrome Postman ............................50
Submitting a query (/executeGet method) ...................................................................................................53
Parameters (/params method).....................................................................................................................53
Submitting a query (/execute method) .........................................................................................................54
Notes on Using Filter Parameters................................................................................................................58
Working with Filters – Examples by DataType .............................................................................................59
Troubleshooting Guide for Submitting Queries via the Web Service Framework .................................67
Queries Inappropriate for Submitting via Web Service Framework (WSF)....................................................67
Error Messages & Possible Reasons ..........................................................................................................68
HTTP Response Statuses & Possible Reasons ...........................................................................................69
Other Symptoms and Possible Reasons .....................................................................................................70
FAQ ............................................................................................................................................................71
Cookbook 3: OAuth Authentication and Authorization...........................................................................74
Configuring Sourcing/CLM for OAuth ..........................................................................................................74
Change the Web Service Definition to use OAuth........................................................................................74
Configure a new External Consumer Application OAuth Registration...........................................................77
Executing the OAuth Handshake Token Exchange .....................................................................................82
Getting Chrome Postman Ready for OAuth Handshake ..............................................................................82

© 2014 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 3

OAuth Handshake Step 1: Get the OAuth Temporary Token .......................................................................85


OAuth Handshake Step 2: Get the Verifier Code .........................................................................................87
OAuth Handshake Step 3: Get the Final OAuth Token ................................................................................93
Accessing Protected Resources With Your OAuth Token ............................................................................95
Copyrights, Trademarks, and Disclaimers ..............................................................................................99

© 2012 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 4

Introduction
SAP Sourcing supports custom scripting and custom queries as key features in extending its default
functionality. The new Web Service Framework script-based web service feature is built on top of the
existing scripting framework and the existing Explicitly Called Scripts objects. The new Web Service
Framework query-based web service feature is built on top of the existing Reports and Query Definition
query framework.
This Guide will walk through executing examples of script-based web services and query-based web
services. It also contains sections on troubleshooting when using the script-based and query-based web
services.

Recommendation
The troubleshooting guides should be reviewed before attempting to develop custom script-
based or query-based web services.

In addition, there is a separate cookbook section that will walk through an example of the Sourcing/CLM
configuration required and the actual execution of the OAuth handshake and token exchange.

Intended Audience and Assumptions


The intended audience for this document is technical users who are Java programmers with experience
in creating and parsing XML documents. SAP also recommends familiarity with BeanShell and the
RESTful architectural style of web services. Additionally, some of the query-based web service
techniques described in this document requires some knowledge of SQL and Sourcing Query Definitions.
An in-depth knowledge of SAP Sourcing customization features, such as using the Setup Import and the
use of extensions and extension collections is recommended. In addition, a conceptual understanding of
SAP Sourcing business documents is required. Configuration experience is also required, including script
testing and system log review.

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 5

Cookbook 1: Executing Scripts via the


Web Service Framework
In order to get acquainted with the new Web Service Framework script-based web service feature, we will
walk through the use of one of the provided script-based web service samples.

Sample Reference Scripts for Script-based Web


Services
Note
For all master data objects used in the reference scripts, the object’s “External ID” should be
passed as the ID parameter in Web service calls.

Sample web service reference scripts are available for download directly from the Sourcing application’s
Reference Guide:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 6

Note
The reference scripts provided contain script code “samples” and are not intended for use in
production. For example, a script may need to be enhanced to perform appropriate data
validations and error handling if the web service request URLs or payloads may contain
invalid data – e.g., non-numeric alpha data when an integer is required in the script.

Configuring the Sample Project Web Service


The following examples use the Sample Project Web Service. This is the simplest script-based web
service sample provided. However, the same basic process described below can also be used when
working with the Sample Contract Web Service and the Sample RFx Web Service. In addition, it’s
important to note that any script-based web service can be developed and configured manually. The
content provided in the Reference Guide is intended to help jump-start the use and understanding of the
script-based web service feature.

Download the Sample Project Web Service zip file from the Reference Guide link and extract all of the
files:

Recommendation
Read the included README.txt file. It contains a number of important points that should be
understood when using the samples provided. Also, read section 'Authoring New Inbound
Script-Based Web Services' in the "Web Services Guide for SAP Sourcing 10.0" which is
available on Service Marketplace and is the official documentation of the new Web Service
Framework.

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 7
Use the following default Configuration tab Enabled column settings for Yes/No and import the
ProjectServiceWorkbook to load in the Localized Resources for Errors content and to create a Web
Service Definition object.

After the Import, access the newly created Web Service Definition object from the System Setup tab of
the Setup Page:

Note
Web Service Definition objects can also be created manually using the New button:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 8

Open the just created (via the Workbook Import) Project Service Web Service Definition object:

Press Edit. Then attach the Sample Project Service zip file’s Schema (.xsd) File:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 9

Note
The sample script-based web services use the Authentication Type of Directory Config
Setting and HTTP Basic Authentication (username and password). The Sourcing
application’s Active Internal Directory Config Setting must be Local, LDAP, or Netweaver
UME in order to use the samples asis.

Save the Web Service Definition and note that the Java stub classes and associated Javadocs have
been generated:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 10

Save the Web Service Definition.

Note
All of the sample Schema Files provided in the zip file have an http internet reference to the
swaref.xsd file. If you do not have internet access when you perform this step you will
receive an IOException unless you perform the steps described in SAP Note 1903471 -
Adapters XSD for Scripts in the Web Service Framework.

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 11

Note
The Web Service Definition must be saved before the Javadocs can be accessed:

View the Javadocs and Java classes automatically created from the attached Schema File:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 12

Note
These java classes are immediately available for the Scripting environment. During normal
custom development of script-based web services, the developer may iterate between
adding java classes and setter/getter methods via the Schema File, adding scripting code in
an Explicitly Called Script that access these classes and methods, testing the existing web
service functionality, then adding more content to the Schema File, saving/generating the
java classes, adding more script code, …, etc. All of this can be done at run time – there is
no need to stop the application.

In the following example we manually create the Explicitly Called Script from the zip file’s Bean Shell
ProjectHeaderService_script.bsh file.

Even though the workbook allows the Explicitly Called Script to be created via an Import, we would
need to stage the .bsh file on the application server in order to import it via the workbook.

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 13
Instead, we will simply create it via the Explicitly Called Script User Interface available on the System
Setup tab of the Setup Page:

Open ProjectHeaderService_script.bsh file file in Notepad with Word Wrap off, select all of the text, copy
it to a new Explicitly Called Script object Script field:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 14

Set the Explicitly Called Script External ID, Display Name, and Description using the same values
from the Workbook’s callable_scripts sheet:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 15

Save the new Explicitly Called Script:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 16

We will now create the Project Service’s Web Service Definition object’s Operations data via the import
workbook.

Note
Web Service Definition objects Operations data can also be created manually using the Add
button:

Change the workbook’s Configuration tab Enabled settings to Yes for the Operation Configurations and
to No for the rest of the contents:

Import the Workbook and check the previously created Web Service Definition object’s updated Web
Service Definition Operations content:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 17

Now we can start the Project Service directly from the Web Service Definition Actions menu:

Executing the Sample Project Web Service using


Chrome Postman
The following examples are shown using Chrome Postman and assume the prior section on configuring
the sample Project Web Service has been successfully completed. You can download Postman from the
Chrome Web Store.

Note
Other REST Client programs can be used to execute script-based Web Services.

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 18

Getting Started

Open Postman in the Chrome browser. The first screen you see looks something like:

Notice there is a tab called “Basic Auth”. We will be using Basic Authorization (username and password)
for our example web service calls to the sample Project Service. Click on this first so that you can
indicate what user is submitting the web service request:

Here you can enter a username and password. This should be a valid internal Sourcing user with
appropriate security to use the WSF (see section Setting Up User Account Permissions, in the Web
Services Guide for SAP Sourcing 10.0). For this Cookbook, the user also needs permission to Create,
Edit, and View Projects.

After entering the username and password, click the Refresh Headers button:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 19

Note the Base64 encoded HTTP Authorization Header is automatically generated:

Since we will be sending our example web service request payloads in XML, we should set the HTTP
Content-Type Header to application/xml:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 20
Next click the Normal tab and the Headers button to hide the Headers and have more space for our web
service responses.

The Headers information is cached for each web service request so it doesn’t need to be specified again
to execute multiple HTTP calls.

Key areas of this screen are:


1. “Normal” tab: this is the tab where you enter the URL you want to submit.
2. Entry field for the URL.
3. This dropdown is for the http verb (Get, Post, Put, Delete, etc.) you are using
4. The Headers button allows you to see header information for your URL submission.

Note that at the left: the Postman tool collects a history of URLs you have submitted. You can click on
any of these to bring it back to the main entry area, when you want to resubmit a URL.

Note
For the following Project Service web service calls, you can construct the web service URLs
by copying the Sourcing application's URL and removing all text from the end to the left
through
the 'fsbuyer' servlet and append:
/ngservices/rest/<ENDPOINT_URL>/<RESOURCE_URL>
For example, this Sourcing buy-side logon url:
https://xxx.corp:50001/eso10/fsbuyer/portal/index
becomes:
https://xxx.corp:50001/eso10/ngservices/rest/<ENDPOINT_URL>/<RESOURCE_URL>

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 21
You can find the <ENDPOINT_URL> value in the import workbook's web_services sheet
and you can find the <RESOURCE_URL> in the import workbook's operation_configs
sheet.

Services Discovery

When we started the Project Service web service earlier by clicking Start in the Web Service
Definition’s Actions menu, the web service framework published the service to the Sourcing
application’s Service Discovery page. (Reference section ‘Service Discovery’ in the Web Services
Guide for SAP Sourcing 10.0). We can use Postman to access Service Discovery page, by constructing
the URL as follows:
 https://xxx.corp:50001/eso10/ngservices (Ref. The Note above regarding how to construct the
first part of the URL.)

and then setting the HTTP verb to GET and pressing the Send button:

When the results are returned, press the Preview button to see all of the running web services. Also note
our Project Service that we just started:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 22

We can then copy the WADL http URL to the Chrome URL field, leave the HTTP verb as GET, and press
Send again to see the Project Service WADL details:

Press the Pretty button to see the WADL contents:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 23

The WADL has been built from the Project Service Schema File and the Project Service Web Service
Definition Operations data. The WADL is the REST version of a SOAP WSDL. It contains the interface
information needed by the consumer application developer.

Note
Authentication is required in order to access both the Services Discovery page and a
running web service WADL.

Using POST to create a Project


In Chrome, change the HTTP verb to POST, remove the last WADL part of the prior URL
(?_wadl=&type=xml), and press the raw button to open an area on the UI for the POST Request XML
payload:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 24

Add /project to the end of the URL:

So that it now matches the POST Operation Resource URL Part in the Web Service Definition:

From the directory where you extracted the Sample Project Web Service zip file, open the
projHeaderPost.xml file in Notepad:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 25

This sample XML payload contains a subset of XML Elements that are defined in the Project Service
Schema File’s HeaderPost complexType:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 26

Note
All of the Sample script-based web service POST operation scripts assume a Document
Template will be provided in the XML request payload so that a “Create from Template” will
be performed in the Explicitly Called Script.

Change the XML POST payload in Notepad to replace the TemplateName element with a valid Project
Template name:

Note
An alternative would be to create a Project Template with the sample payload name:
PROJ_SERVICE_TEST_TEMPLATE.

Copy the modified projHeaderPut.xml request payload from Notepad and paste it into the raw XML text
area in Chrome and press Send:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 27

Note the successful Status 200 returned and the ID of the just created Project is returned in the XML
response payload:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 28

Sign in to the Sourcing application and verify that the Project was created and what its name is:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 29

Using PUT to update a Project


Now let’s change the Name of the Project we just created using the sample PUT XML payload provided
in the Sample Project Web Service zip file. From the directory where you extracted the Sample Project
Web Service zip file, open the projHeaderPut.xml file in Notepad:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 30

Note that in this next example we will be changing the Project’s Name from PROJECT HEADER POST to
PROJECT HEADER PUT.

Also note that the sample PUT payload just contains one field (DisplayName) while the Schema File’s
HeaderPut complexType allows for additional fields to be changed via a PUT:

Copy the projHeaderPut.xml request payload from Notepad and paste it into the Chrome Request raw
XML text area replacing the previous POST XML request payload:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 31

Note in the Project Service Web Service Definition Operations area that to perform a PUT/Update, we
need to provide a URL variable parameter containing the ID of the Project we want to update:

So, in Postman, add the Project ID returned from the prior POST/Create response payload to the end of
the URL and set the HTTP verb to PUT:

Press Send to execute the PUT/Update web service and note the status and response:

Sign in to the Sourcing application and verify that the Project Name was changed:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 32

Understanding the XML payload format for POST and PUT

Note
Please note that the SAP Sourcing/CLM framework's automatic use of Meta data for
processing the various Sourcing/CLM data types is being leveraged by the Web Service
Framework. The resulting data structure needed for each field in the XML payload for a
POST or PUT web service call may not be obvious. One of the quickest ways to
understand this XML structure and format of each Sourcing/CLM datatype is to review the
data element's XML structure using a GET web service request (ref. next section).

For example, you can fill out the values for these fields of interest – e.g., Dates, Object
References, Value List Values, Enums, etc. - in the Sourcing/CLM application's User
Interface and save a specific Business Document. Then execute a web service GET on
that instance of the Business Document. The Response XML payload will have the format
of that field's data type for reference.

Using GET to read a Project


Now let’s execute an HTTP GET web service call to read the Project.

Note that there is no request payload sent with a GET web service call. In addition, per the Web Service
Definition Operations data, the Project Service expects the Project ID of the Project to be read to be
passed as a URL variable parameter:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 33

In Chrome Postman, we just need to change the HTTP verb to GET (assuming the prior URL was from
the PUT request above which still has the Project ID set as the URL variable parameter) and press Send:

Note the GET call status and response:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 34

Viewing the Web Service Request Log


Now let’s view the logging of the Web Service Requests we made earlier.

Note
In order to view the Web Service Requests log you need to have the appropriate Security
permission. The new delivered Web Service Administrator has this permission set as the
default:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 35

You can access the Web Service Requests log from the System Administration tab of the Setup page:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 36

Note
The Web Service Requests log is a new log that is entirely separate from the standard
SAP Sourcing/CLM logs. The log is cleaned up by daemons that run at configurable times.
(see Section ‘Expiration of Web Service Request Data’, in the Web Services Guide for SAP
Sourcing 10.0).

Here are the logged web service calls we made earlier for the Project Service PUT and GET:

When the Status column value is clicked, the full log entry is displayed:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 37

Note that the web service URL, the Web Service Definition that was executed, the User Account for the
web service execution session, the HTTP operation that was performed, as well as the Request and
Response payloads are all captured in the Web Service Request log.

You can open the Request or Response payload by clicking their links.

If an error had been encountered when executing the Explicitly Called Script, an error message and a
partial error stack trace would also be captured (the full stack trace could be found in the standard SAP
Sourcing/CLM logs.

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 38

Troubleshooting Guide for Executing


Scripts via the Web Service Framework
Examples here are shown using Chrome Postman.

The desired Web Service is stopped

To use this web service it needs to be started:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 39

Connection Error: The Sourcing/CLM application


server is not running

The Sourcing/CLM application is down and needs to be restarted.

Connection Error: Misssing https certificate for


Chrome
The Sourcing/CLM application server has an https certificate and Chrome does not.

If an https certificate has been installed on the Sourcing/CLM application service, then the certificate also
needs to be installed in the Chrome browser. An idication that this is the problem is getting the following
message when trying to log in to the Sourcing/CLM application when using Chrome:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 40

Here’s the browser certificate missing message you get when using the Internet Explorer browser:

Note
Chrome and Internet Explorer share the same certificate store.

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 41

Connection Error: Space character at beginning


of URL
There’s a problematic space before “http” on URL line:

This can sometimes occur when the URL text is copied and then pasted into Postman. If there is a
beginning space on the Postman URL, Postman pre-pends an ‘http://’.

Resource Not Found Error - Bad URL - Missing


URL resource
In the following, the Project Service is missing “/project” after …/projectservice”:

The URL should be:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 42
http://xml2394.wdf.sap.corp:8080/eso10/ngservices/rest/projectservice/project/PROCAT-013-BGNXM-
2014

Schema File attachment errors


Symptom: You get the following error when attaching a Schema File (.xsd) to a Web Service Definition:

[error] At line – 1, column-1: IOException thrown when processing "http://ws-


i.org/profiles/basic/1.1/swaref.xsd. Exception: java.net.<............>

All of the sample Schema Files provided in the zip file have an http internet reference to the swaref.xsd
file. If you do not have internet access when you perform this step you will receive an IOException
unless you perform the steps described in SAP Note 1903471 - Adapters XSD for Scripts in the Web
Service Framework.

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 43
Symptom: You get the following error when attaching a Schema File (.xsd) to a Web Service Definition
and you notice a jar conflict issue in the logs:

This error could be due to a missing Netweaver configuration. You may need to set:
“-Djava.endorsed.dirs” by pointing it to the endorsed folder under “lib” in Sourcing (ex:
\exlib\java\ODP\lib\endorsed).

Here is a screenshot that shows where to set this property:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 44

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 45

Cookbook 2: Submitting Queries via the


Web Service Framework
Configuring the Query Web Service Report and
Queries
Recommendation
Read the ‘Using the RESTful Query Service’ section in the "Web Services Guide for SAP
Sourcing 10.0" which is available on Service Marketplace and is the official documentation
of the new Web Service Framework.

First, we need to create a new standard Sourcing/CLM Report with an Internal Name of Custom-
WebService-Queries-Report.

Note
If you want to use a different Internal Name for this Report, you need to set System Property
odp.integration.webservice_queries with the alternate name. (See section ‘Using the
RESTFul Query Service’, in the Web Services Guide for SAP Sourcing 10.0).

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 46

A localized resoruce has been provided for the Report Display Name: Web Service Queries:

Now we need to add the Query Definitions that we want to execute as web services to this Report.

Note
Only 1 Report is used to contain the Query Definitions that can be run as a web service.
Only Query Definitions added to this 1 Report can be run as a web service.

For the Chrome Postman examples below, we will use 2 standard SAP delivered Query Definitions: FCI-
MaterialsByPlant and FCI-MyRFPsActive.

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 47
Next click on the Report Elements tab and press the Add Query Definition button:

Select FCI-MaterialsByPlant:

Then press the Add Query Definition button again to select FCI-MyRFPsActive:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 48

Then Save the Report:

In order to run the Query Service we need to start the SAP delivered Web Service Definition: REST
Query Service.

Access the REST Query Service Web Service Definition object from the System Setup tab of the
Setup page:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 49

Select the REST Query Service Web Service Definition to open it:

The click Actions Start:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 50

How to Submit Queries via the Web Service


Framework (WSF), using Chrome Postman
The following examples are shown using Chrome Postman and assume the prior section on configuring
the sample Report has been successfully completed.

Note
Other REST Client programs can be used to execute query-based Web Services.

Open Postman in Chrome. The first screen you see looks something like:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 51

Notice (in box) there is a tab called “Basic Auth.” Click on this first so that you can indicate what user is
submitting a query. Next you see:

Here (box) you can enter a username and password. This should be a valid internal Sourcing user with
appropriate security to use WSF (see section Setting Up User Account Permissions, in the Web Services
Guide for SAP Sourcing 10.0). After entering the username and password, click on the Normal tab to
return there.

Key areas of this screen are in boxes.


5. “Normal” tab: this is the tab where you enter the URL you want to submit.
6. Entry field for the URL.
7. This dropdown is for the http verb (Get, Post, Put, Delete, etc.) you are using. For our purposes
you will use either Get or Post.
8. The Headers button allows you to see header information for your URL submission.

At left: the tool collects a history of URLs you have submitted. You can click on any of these to bring it
back to the main entry area, when you want to resubmit a URL.

Note
For the examples that follow, we will configure the HTTP Headers in Postman to pass any
Query Request payloads in XML and for the query web service to return any Query

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 52

Response payloads in JSON. We do this by setting the Content-Type Header to


application/XML and the Accept Header to Application/JSON.

Note
At this time, only the REST Query Service can return Response payloads optionally in
JSON or XML. The Script-based Web Service currently only returns Response payloads in
XML.

Click Headers button and you see:

Authorization: “Basic” indicates you are using Basic, not OAuth, authentication. This is followed by the
(encrypted) username and password entered on the Basic Auth tab earlier.
Content-Type: indicates the format of your parameters. Can be Application/XML or Application/JSON.
You must have a header like this whenever you are submitting parameters with your query.
Accept: indicates the format in which you would like to see query results. Same possible values.

You will do two things on this screen:


a) Find out the names/entry types of the parameters for a query you want to submit via WSF.
b) Submit that query, with values for its filters as necessary.

Most of the URL you submit will be the same for either of these tasks. Let’s look at the URL in the
illustration:
http://abc123.def.usa:9999/eso10/ngservices/rest/query/FCI-MaterialsByPlant/params

The first part is http://abc123.def.usa:9999/eso10. This is an example but it will match this portion of the
link you would normally use to log into Sourcing. The “abc123.def.usa” is the <host> portion of your URL,
and the “9999” is the <port> portion. The “eso10” is the <context>.

The second part is /ngservices/rest/query. This will be the same for every URL you submit.

Third is the internal name of the query you want to submit, in this case FCI-MaterialsByPlant. Make sure
the query you want to submit is named as a Report Element on the Web Service Queries Report. Go to
Setup > Reports and Queries > Reports. The name of the report you want is determined by the value of
the enterprise-level system property, odp.integration.webservice_queries.

Last: the method. This is what differs according to whether you are doing (a) or (b) above. In this
example the method says “/params”.

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 53

Submitting a query (/executeGet method)


If the query you want to submit has no required filters, or if it does but you want to use the default values
for the filters, you can submit using the /executeGet method.

Suppose you want to submit the query FCI-MyRFPsActive. You submit a URL that looks something like:
http://abc123.def.usa:9999/eso10/ngservices/rest/query/FCI-MyRFPsActive/executeGet
If you put this in the URL area and then click Send, you see results below the URL area:

Parameters (/params method)


Now let’s look at a query that does have required filters. Submit this URL:
http://abc123.def.usa:9999/eso10/ngservices/rest/query/FCI-MaterialsByPlant/params

You should see:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 54

Near the (1) you can see the status indicator. Here it says “200 OK.” If you make a mistake submitting
something, you might see a different value.

Near the (2) are two buttons “JSON” and “XML”. The JSON button is highlighted indicating the
information below is in JSON format. If you prefer XML you can click the XML button to change this.

Near the (3) is one filter parameter’s attributes. Notice this output gives you the Name and Type of the
filter, whether it is required, etc. It also provides the key values for this parameter if it is an Object
Reference. Plant has two keys, EXTERNAL_ID and BUSINESS_SYSTEM, so when using this filter via
WSF you would need to indicate both the EXTERNAL_ID and the BUSINESS_SYSTEM for the Plant you
want to use to limit the query results.

You can also see above PlantId that there is another filter, T1.IS_REPLICATED. That is a checkbox
(Boolean type filter) so either TRUE or FALSE; no key value is needed for this one.

Submitting a query (/execute method)


The /executeGet method does not allow you to enter parameter values; for that we need to use the
/execute method. Change the method at the end of the URL from /params to /execute, and use the
dropdown to change the verb from Get to Post. When you change to Post, the area where you can enter
parameter information becomes visible:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 55

Notice here:
1. “Raw” button. Click this if not already highlighted, so that you can submit your parameters as raw
html.
2. Dropdown choices are Text, JSON, XML, HTML. For submitting queries via WSF you will use
either XML or JSON format for parameters. Indicate here which you are entering.

The arrow points to the line just above the buttons, which you can use to make this parameters area
larger if you need to.

Here is an example showing the parameters entered for the FCI-MaterialsByPlant query:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 56

Click Send to submit the query and results show below the parameters area:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 57

Later in this document there are some tips for entering filters of different datatypes.

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 58

Notes on Using Filter Parameters


1. When you submit …/params to get a list of parameters for a query, if that query has no filters you will see:
{
"filterParamDefList": ""
}
2. If submitting a query with no parameter values, whether because a) the query has no required filters or b) you want the default values to
be used: if submitting via /execute, enter <param/> in the filter entry area. If you leave it blank your submission returns an error.

3. When a query filter has cardinality = List or Range, you accomplish this in the parameter entry area by using multiple parameters of the
same name. In the case of a range of values, the two parameters would represent the low and high ends of the range. Example:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 59

Working with Filters – Examples by DataType


The far left column is a list of the available filter types. In parentheses next to each one are the available cardinality settings for that filter type.

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 60

Filter type filterParamDef looks like: Filter entry example Notes

Big Decimal { <param>


(single/ "filterParamDefList": { …
range/ list)
"filterParamDef": [ <filterParam>
or
…. <name>greaterThanDays</name>
Integer
(single/ { <value>
range/list) "name": "lessThanDays", <data>14</data>
"prompt": "Agreement Length Less Than </value>
(days)", </filterParam>
"type": "Integer", <filterParam>
"cardinality": "Single", <name>lessThanDays</name>
"required": false, <value>
"values": "" <data>20</data>
}, </value>
{ </filterParam>
"name": "greaterThanDays", </param>
"prompt": "Agreement Length Greater
Than (days)",
"type": "Integer",
"cardinality": "Single",
"required": false,
"values": ""

}

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 61

Filter type filterParamDef looks like: Filter entry example Notes

Boolean <filterParamDef> <param>


(single) <name>MyOwnership</name> <filterParam>
<prompt>My Ownership</prompt>
<name>MyOwnership</name>
<type>Enumeration</type>
<cardinality>Single</cardinality> <value>
<required>true</required> <data>1</data>
<defaultValue>1</defaultValue> </value>
<values>
</filterParam>
<value>
<key>1</key> </param>
<data>Owner</data>
</value>
<value>
<key>2</key>
<data>Owner or Collaborator</data>
</value>
</values>
</filterParamDef>

Date (single/ <filterParamDef> <param> Dates & times for WSF are in
range/list) <name>TimePeriodBeginning</name> the format for the
<filterParam>
<prompt>Time Period Beginning at</prompt> authenticated user.
<name>TimePeriodBeginning</name>
<type>Date</type> <value>
<cardinality>Single</cardinality> <data>1/1/13</data> <FilterParamDef> shows the
<required>true</required> </value> expected format for the date.
<format>M/d/yy</format> </filterParam>
<values/>
</filterParamDef> </param>

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 62

Filter type filterParamDef looks like: Filter entry example Notes

DateTime .... <param> <FilterParamDef> shows the


(single/ <filterParamDef> <filterParam> expected format for the datetime
range/list) <name>T1.DUE_DATE_DATETIME</nam
<name>T1.DUE_DATE_DATETIME</name>
<prompt>RFx Response Due</prompt> e>
<type>DateTime</type> <value>
<cardinality>Single</cardinality> <data>2/28/2013 06:00:00</data>
<required>false</required> </value>
<format>MM/dd/yyyy hh:mm:ss</format> </filterParam>
<values/> </param>
...

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 63

Filter type filterParamDef looks like: Filter entry example Notes

Enumeration <filterParamDef> <param> Notice that in the <data>


(single/list) <name>T1.STATUS</name> <filterParam> portion of your parameters,
you use the value found in the
<prompt>Status</prompt> <name>OnlyShowMy</name> <key> portion of the
<type>Enumeration</type> <value> <filterParamDef>.
<cardinality>Single</cardinality> <data>1</data>
<required>false</required> </value>
<values> <name>T1.STATUS</name>
<value> <value>
<key>1</key> <data>4</data>
<data>Not started yet</data> </value>
</value> </filterParam>
<value> </param>
<key>2</key>
<data>Open for bidding</data>
</value>
<value>
<key>4</key>
<data>Closed</data>
</value>
....
</values>
</filterParamDef>

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 64

Filter type filterParamDef looks like: Filter entry example Notes

Object <filterParamDef> <param>


Reference <name>Category</name> <filterParam>
(single/list)
<prompt>Category</prompt> <name>Category</name>
<type>ObjectReference</type> <value>
<cardinality>Single</cardinality>
<required>true</required> <key>BUSINESS_SYSTEM</key>
<values> <data>SOURCING</data>
<value> </value>
<key>CATEGORY_ID</key> <value>
</value> <key>CATEGORY_ID</key>
<value> <data>A411</data>
<key>BUSINESS_SYSTEM</key> </value>
</value> </filterParam>
</values> </param>
</filterParamDef>

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 65

Filter type filterParamDef looks like: Filter entry example Notes

String <filterParamDef> ... This is also an example of


(single/list) <name>MaterialDesc</name> <filterParam> selecting "None" for the
Business System by leaving a
<prompt>Show Materials with Description <name>T1.BUSINESS_SYSTEM_OB blank value for the
containing</prompt> JECT_ID</name> EXTERNAL_ID.
<type>String</type> <value>
<cardinality>Single</cardinality> <key>EXTERNAL_ID</key>
<required>false</required> <data></data>
<defaultValue>*</defaultValue> </value>
<values/> </filterParam>
</filterParamDef> ...
<filterParam>
<name>MaterialDesc</name>
<value>
<data>circuit</data>
</value>
...

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 66

Filter type filterParamDef looks like: Filter entry example Notes

Value List { <param> Notice that in the <data>


(single/ "filterParamDefList": { <filterParam> portion of your parameters,
range/list) you use the value found in the
"filterParamDef": [ <name>T1.COUNTRY_OBJECT_ID< <key> portion of the
{ /name> <filterParamDef>.
… <value>
{ <data>AF</data>
"name": "T1.COUNTRY_OBJECT_ID", </value>
"prompt": "Country", </filterParam>
"type": "ValueList", </param>
"cardinality": "Single",
"required": false,
"values": {
"value": [
{
"key": "AF",
"data": "Afghanistan"
},
{
"key": "AL",
"data": "Albania"
},

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 67

Troubleshooting Guide for Submitting


Queries via the Web Service Framework
Examples here are shown using Chrome Postman.

Queries Inappropriate for Submitting via Web


Service Framework (WSF)
Because of the nature of the web service framework, certain types of queries do not lend
themselves to use with this tool.
Spend Analysis queries If the database used is not Oracle, or if the Spend Analysis feature is not
enabled, then previewing a spend analysis query or submitting via WSF will
give you the message “The spend analysis environment is not ready to provide
spend data.”

If using the Oracle DBMS and the spend analysis feature is enabled and data
has been imported: a preview of a spend analysis query will work but any
drilldown links will not work correctly via WSF. Queries for data that is part of
the spend analysis structure (e.g. queries with Dim or Dimension in their
names) will have results.

© 2014 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 68

Queries including the These UI tokens normally result in data being returned as a link. For example
tokens in FCI-VendorsByBuyer, there is a column for the internal contact for each
REQUEST_PAGE_PA supplier, which in the Sourcing UI is shown as a link to that user’s settings
TH, page. If this query is submitted to WSF, what should be a link comes back
REQUEST_PATH_OBJ only as the data. Note that in the picture below, the link information is not
, underlined, i.e. not a link.
BASE_SERVLET_PAT
H

Queries whose internal A query with this name has information in the Chart tab of its definition
names end in the word indicating how to build a chart of the results of the query. If you submit such a
Chart query via WSF, WSF can’t build the chart. You could get results looking like:

Not very useful!

Error Messages & Possible Reasons


Error message Possible Reason

No service was found. Web service is not running. Open the Web Service
Definition and choose Actions > Start.

Unauthorized. Please contact web service 1) Your user is not authorized to use web service; the
administrator. user account is not assigned a security profile that
allows the use of web service.
2) The query you tried to execute is not on the list of
queries that can be executed via WSF. If the query

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 69

should be enabled to run as a web service, open the


Report that lists these (defined at enterprise level in
the system property
odp.integration.webservice_queries) and add this
query to the list of Query Definitions. For more
information, see Specify What Queries the Query
Service Can Execute in the Web Services Guide for
SAP Sourcing 10.0.
User sjoan is not authorized to execute query Same as above, or, the Access tab of the query or
Joan-FCI-AllProjects. report being submitted has entries in it, and sjoan is not
included in the list of users/groups/companies
authorized to run this query.

Unexpected error on SAP Sourcing side. If First, check for an error in your request. For example, a
problem continues, notify the server’s System typo in the query name could result in this error. URLs
Administrator. Troubleshooting details have and method fields are case-sensitive.
been logged on the Server.
Go to Setup > System Administration > Administrative
Reports > Web Service Requests. There you will see a
list of web service requests, most recent first. If you got
this “unexpected error” message in Postman, the first
item on the list here probably has status = Error. You
should be able to click on the word Error to see more
detail about the problem.

HTTP Response Statuses & Possible Reasons


400 Bad Request Something wrong with the format of your request. For a
query with no filters, for example, if submitting using
/execute with Verb = Post, you can’t submit an empty body.
In the Raw area you would submit <param/> indicating there
are no parameters. If you leave it blank instead, you would
get this status. The same applies if you are submitting a
query that has filters but you are not using them (even if
none are required).

404 Not Found Check for an error in your request. For example if you
accidentally submitted
http://abc123.def.usa:9999/eso10/ngservices/rest/query/FCI-
ProjectByEstimatedValue/execuute instead of .../execute,
you would get this status with a “1” in the results area.

415 Unsupported Media Type Check the header for your request. Does it specify Content-
Type either Application/XML or Application/JSON? If not,
that could be the reason for this status.

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 70

Other Symptoms and Possible Reasons


Symptom Possible Cause(s)

I got results but not all the Consider the Maxfields and MaxRows settings. If the results returned are
results I expected. limited because of one of these limits, you will see that information at the
top of your results:

{
"resultList": {
"message": {
"@type": "WARNING",
"$": "Max rows limit reached: 5."
….

See the FAQ’s relating to maxRows and maxFields later in this


document.

For more information about the system properties, see Section


“Appendix: System Properties Relevant to the Web Services
Framework” in the Web Services Guide for SAP Sourcing 10.0.

I submitted a request for the Are you looking for a Hidden parameter? Filter parameters defined with
parameters for a query via Hidden = checked are not shown in response to a /params request. If
WSF, but not all the you see them in the query definition, though, you can use them – if
parameters I expected are submitted via WSF they will be applied.
shown.

I submitted a URL to the web This occurs because the User B information is still in the tool’s
service using User A, but I’m (Postman’s or whatever tool you are using) cache. When one request
seeing results that seem to ends, the cookie is still there and the next request picks it up rather than
apply to User B. Not long using the new authenticated user. To clear the cache so that your new
ago I did submit a URL as authenticated user is recognized:
User B.
1) Ctrl-H to bring up Browsing History.
2) Click “Clear browsing data…”
3) Choose to obliterate from “the beginning of time” and check all
the boxes underneath EXCEPT “Deauthorize content licenses.”
Click the button “Clear browsing data.”
4) Exit Chrome (X at upper right).
5) Restart Chrome and get back into Postman.
6) Go to the Basic Auth page and enter the new user/password you
want to work with.
7) Click Refresh Headers.

Submit your URL again and you should get the results appropriate to the
new user you just entered.

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 71

I submitted a URL to the web This is also caused by caching. Do the 7 steps described above and try
service for User A, but I’m again.
getting a “user not
authorized” message. User
B, which I was using recently,
is in fact not authorized to this
query. Or, I got the
unauthorized message
because the query wasn’t on
the list of WSF queries, but I
added it recently.

FAQ
1. What determines the limit on the number of rows returned in my query results? Can I adjust that?
a. MaxRows has a default value of 300; this can be increased or decreased using system property
odp.integration.ngservices.rest.query.max_rows_limit.

Note: When you consider the value for the system property, be aware that increasing the value will
have a negative impact on performance: see Query Service Performance Recommendations and
Benchmarks in the Web Services Guide for Sourcing 10.0. You will want to consider all throttling
attributes together: see chapter Appendix: System Properties Relevant to the Web Services
Framework in the same guide.

You can override the system property to a lower number using the attribute Max. Rows Returned on
the query definition.

You can adjust the setting further using a parameter submitted with the WSF query request.

 append it to the URL if not specifying other parameters:


http://vmw2924.wdf.sap.corp:50000/eso10/ngservices/rest/query/FCI-
MyRFPsActive/executeGet?maxrows=5
 add it as a parameter in the body of the request:
<param>
<filterParam>
<name>MyOwnership</name>
<value>
<data>2</data>
</value>
</filterParam>
<maxRows>5</maxRows>
</param>
This number can be greater or less than the query definition attribute, but it can’t be greater than the
system property value.
Here are some examples putting all these values together:
Default System Query Definition Parameter Result (# Notes
maxRows Property attribute = Max. submitted with rows actually
value value Rows Returned WSF request returned)
300 200 150 80 80

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 72

Default System Query Definition Parameter Result (# Notes


maxRows Property attribute = Max. submitted with rows actually
value value Rows Returned WSF request returned)
160 160 Submitted parameter
can be greater or less
than query defn
attribute as long as it’s
not greater than the
system property
210 200 If parameter submitted
with request is greater
than system property,
it’s ignored
300 200 220 [none] 200 If query definition
attribute is greater
than system property,
it’s ignored

2. When determining the number of records to return in results, are Hidden result fields included?
a. No, result fields that are defined as Hidden are not counted toward the Max Fields number.
3. What determines the limit on the number of fields returned in my query results? Can I adjust that?
a. The default maximum number of fields returned is 3500. This can be increased or decreased
using the enterprise-level system property odp.integration.ngservices.rest.query.fields_limit; but
that property cannot be greater than 10000.

4. When using the MaxFields property, how is it determined which is the last row of results to show?
a. The results can show fewer but not more fields than the max fields value. Suppose the
MaxFields property is set to 1000. You submit a query whose result rows have 12 fields each.
You would see up to 83 rows of results because 83 * 12 = 996 so this is the greatest number of
rows that can be shown without going over the Max Fields limit of 1000. If, however, the Max
Rows parameter in this case were 60, you would only see 60 rows of results even though the
MaxFields property would allow for more.
5. I’m working with a query that has a filter on Business System that in the UI defaults to the value for the
user’s context. In the UI I can use a Business System picker that lets me choose None (rather than the
default) so that I’m seeing results for all business systems. How can I get the same result when
submitting a query via WSF?
a. To get these results, include the parameter for business system in your request, but with a null
value (nothing – not the word “null”) in the data portion of your parameter. This would look like:
<filterParam>
<name>T1.BUSINESS_SYSTEM_OBJECT_ID</name>
<value>
<key>EXTERNAL_ID</key>
<data></data>
</value>
</filterParam>

6. Is it possible to control the time zone to be used for any results returned that include times?
a. No, not as of Release 10.0. The time zone used is the time zone for the authenticated user.

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 73

7. What about generic list pages? Is there a way I can submit one of these via WSF and add extra filters
dynamically as I can in the Sourcing UI?
a. No, not as of Release 10.0. You have access to all filters specifically defined for a query,
whether hidden or not; but you can’t dynamically add filters.
8. What about saved searches? Using the Sourcing UI, I can save a query with certain settings with a
specific name. Can I submit one of these saved searches via WSF?
a. No, not as of Release 10.0.
9. Are filters with Cardinality = list or range supported with WSF?
a. Yes they are. You should be able to define a query with a filter of cardinality = list or range and if
this is allowed (not all datatypes allow all cardinality settings), it should work in WSF as well as in
the Sourcing UI.
10. Are URLs submitted via WSF case-sensitive?
a. Yes, they are. So for example if the query definition has an internal name of FCI-
ActiveProposals, then a URL including the query name FCI-ACTIVEPROPOSALS would result
in an error.

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 74

Cookbook 3: OAuth Authentication and


Authorization
OAuth allows a user to grant access to Sourcing/CLM from an external application’s web service calls
without having to provide the user’s username and password to the external application.

In order to get acquainted with how OAuth authentication and authorization works with the new Web Service
Framework, we will walk through an example of the Sourcing/CLM configuration required and the actual
execution of the OAuth handshake and token exchange. Then we will execute a web service call using
OAuth Authentication instead of Basic Authentication (username and password).

Recommendation
In addition to using this cookbook, also read OAuth related sections ‘Managing External
Consumer App OAuth Registrations', ‘Using OAuth to Allow or Deny Client Applications Access
to SAP Sourcing’, and ‘Using OAuth 1.0 to Authenticate Web Service Requests’ in the "Web
Services Guide for SAP Sourcing 10.0" which is available on Service Marketplace and is the
official documentation of the new Web Service Framework.

Configuring Sourcing/CLM for OAuth


Note
The following assumes that the Sample Project Web Service has already been configured in
Sourcing/CLM as described earlier in Cookbook 1, section ‘Configuring the Sample Project
Web Service’.

Change the Web Service Definition to use OAuth


First, in order to make a change to the Project Service Web Service Definition configuration, we need to
stop it via the Actions menu:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 75

Then, we can press the Edit button:

And change the Authentication Type to OAuth:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 76

Then, we can save the changed Web Service Definition:

Note
You can no longer call the Project Service with Basic Authorization (username and password).
If you try to you will get am OAuth parameter absent error:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 77

Note how OAuth tries to give you a hint of what caused the problem by returning information in
the response Headers:

Start the Project Service again:

Configure a new External Consumer Application OAuth Registration


Next we need to register an external application so that it can consume our Project Service and authenticate
users (or possibly a single “technical user”) without the external application knowing the user’s username or
password.

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 78

Note
For this example, we will just use Chrome Postman as the external consumer application.

To perform this registration, first go to Setup, System Setup tab:

In the Integration section, click on External Consumer App OAuth Registration:

Since we are creating a new registration, press the New button:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 79

Now fill in the fields External ID, Name, Application Name, Application URI, and Access Token Expires
After as follows in the screen shot below.

Note
Since we will just use Chrome Postman as the external consumer application, the Application
Name is just made up. Also, the Application URI is used as the consumer application’s URL
that Sourcing/CLM needs to redirect to after the web service call’s user is authenticated in
Sourcing/CLM. Since the redirected URL contains needed information for the OAuth token
exchange, we are just using the SAP.com site for this example redirect.

Then press the Add button:

Now we need to select the “scope” of what this external application can perform – via web service calls - on
behalf of the OAuth authenticated user. In this example, we want the scope to be just the Project Service
web services, so, after pressing the Add button highlighted above, we need to select the Project Service
Web Service Definition:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 80

Note
Only Web Service Definitions with an Authentication Type of OAuth are available to select.

Click OK and we see:

Now we need to Save the External Consumer App OAuth Registration to generate the OAuth Client ID
and Oauth Client Secret for the external application to use when performing the OAuth handshake and
token exchange:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 81

We will need the Application URI field value plus the following highlighted fields in order to perfrom the
OAuth handshake and token exchange from our external consumer application:

Recommendation
You may want to copy these felds into Notepad so that it will be easier to paste them into
Chrome Postman and to make sure they do not contain any additional characters.

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 82

Executing the OAuth Handshake Token Exchange


Note
The following example uses Chrome Postman to manually demonstrate the mechanics of the
OAuth handshake and token exchange. In a real world example, a client consumer application
will need to manage the following steps.

Getting Chrome Postman Ready for OAuth Handshake


First, we want to make sure that the Chrome Postman browser cache does not have any authentication
credentials in its cache. So, via Chrome’s menus/buttons, let’s clear the cache:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 83

Now let’s verify that there are no cached creadentials.

Cick the Basic Auth tab in Chrome Postman, clear any Username and Password data, and press the
Refresh Headers button:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 84

Now set the URL to the value used in the Cookbook 1 section “Services Discovery” and set the HTTP verb to
GET:

Press Send and verify that the attempt to read the Services Discovery page (which we successfully read
earlier in Cookbook 1 in section “Services Discovery”) from Postman is not allowed without authentication:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 85

OAuth Handshake Step 1: Get the OAuth Temporary Token

Press the OAuth 1.0 tab at the top of Chrome Postman:

Copy/Paste the Clent ID from Notepad (or the External Consumer App OAuth Registration) into the
Postman Consumer Key field and. Copy/Paste the Clent Secret from Notepad (or the External Consumer
App OAuth Registration) into the Postman Consumer Secret fields.

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 86

Note
Be very careful not to include any leading or trailing spaces when copying fields from Notepad
(or the External Consumer App OAuth Registration) to Postman. An extra space can cause the
handshake to fail (e.g., signature_invalid error).

Then check the Add params to header and Auto add params checkboxes and set Postman’s URL with the
“initiate” handshake URL from the ‘Request Token URL’ value you had previously copied into Notepad (or
copy it from the External Consumer App OAuth Registration):

Then set the HTTP verb to POST and note the Header Key Value pairs that are made available:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 87

We need to provide 2 Key Value pairs of information for the OAuth callback URL and the scope as follows:

Key oauth_callback Value http://www.sap.com


Key scope Value ProjectService

Press Send and note the response:

We have begun the OAuth handshake!

OAuth Handshake Step 2: Get the Verifier Code

Now copy the above response character string after ‘&oauth_token=’ and before the next & and paste it into
Postman’s Token field and copy the response character string after ‘&oauth_token_secret=’ and paste it into
Postman’s Token Secret field:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 88

Change the HTTP verb to GET and set Postman’s URL with the “authorize” URL from the ‘Authorize URL’
value you had previously copied into Notepad (or copy it from the External Consumer App OAuth
Registration). Then Press Send.

In order to verify we are now in the step where a user has to sign on to SAP Sourcing/CLM (to
“authenticate”) and then to authorize the access to SAP Sourcing/CLM resources by the external consumer
application on behalf of this user, press the Preview button:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 89

Note that the “authorize” web service call just made was understood by Sourcing/CLM to require a user to
log on (“authenticate”). So Sourcing/CLM provided its Log On page.

Since we are simulating the entire OAuth handshake flow using a REST Client tool (Postman), we now need
to sign on to Sourcing/CLM by using the URL provided by Sourcing/CLM. We can do this by finding the URL
we need in the XML response payload and then, on a separate/different tab on the Chrome browser, paste
the URL.

To get the URL in the reponse payload, press the Pretty button that is to the left of the Preview button:

And then scroll down in the payload until you find the function login:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 90

Now we need to copy just the http URL portion from the response into the clipboard. Please note the
following regarding a suggested way to copy it:

Note
If you try to just copy the http string only, when you click on it in the response window, Postman
clears the response and places it in the Postman URL field and replaces the ‘&’ character with
the ‘&amp;’ string:

This will cause the subsequent Sourcing/CLM authorization UI to not appear. The symptom will
be: after pasting the string in a new browser window and logging on to Sourcing/CLM, you will
be presented with the main Workbench UI instead of the OAuth authorization UI. So, to avoid
this problem, you can copy the entire function from the response:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 91

Then paste it into Notepad and remove the non-HTTP URL string characters:

Now select the HTTP URL from Notepad and paste it into a new different Chrome browser tab and hit your
keyboard Enter key to execute the URL in the browser to get the Sourcing/CLM log on page:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 92

Now sign in with valid SAP Sourcing/CLM user credentials and note the next screen displayed:

You were redirected to the Sourcing/CLM OAuth Authorize Access UI. You are being asked to “authorize”
an external application’s use of the Project Service web service on your behalf. Press the Allow button and
note that Sourcing/CLM redirected you to www.sap.com:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 93

If this were an actual external client consumer program, the redirect would actually be back to the external
client consumer program.

Also note the OAuth Verifier token in the redirect URL:

Seeing the verifier token means the request token has been authenticated. Now we just need to get the
access token to complete the handshake!

OAuth Handshake Step 3: Get the Final OAuth Token

Now copy the above response character string after ‘&oauth_verifier=’. Then, go back to Postman and
change the HTTP verb to POST and paste it into the next Header Key Value pair Value field and set the Key
field to oauth_verifier. Also set the Postman URL to the value from the Access Token URL field you had

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 94

previously copied into Notepad (or copy it from the External Consumer App OAuth Registration). Then
Press Send:

Note the response results:

We have completed the OAuth handshake and token exchange!

You can verify that the Authorization has been successful by going to the Authroizations tab of the User
Account of the user that signed on to Sourcing/CLM and allowed the “Project Service Client” external
program access:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 95

Note
The user or a System Administrtor can also revoke this access at any time by going in to Edit,
selecting the Project Service Client row and pressing the Revoke Access button.

Accessing Protected Resources With Your OAuth Token

We now have our OAuth Access Token and Token Secret. Since we set the Access Token Expires After
field on the External Consumer App OAuth Registration to 30 days, we can run the Project Service web
service for 30 days without a user having to provide a username and password.

Note
In this example we set the Access Token Expires After to 30 days. However, if we left it
blank, the access credentials for the external application would never expire. This blank setting
may be more appropriate when an integration technical user is used.

Now copy the above response character string after ‘&oauth_token=’ and before the next & and paste it into
Postman’s Token field and copy the response character string after ‘&oauth_token_secret=’ and paste it into
Postman’s Token Secret field:

Note
The actual external client consumer program would need to persist these values so that the
OAuth handshake and token exchange would not need to be done again until the access token
expires.

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 96

Also delete the Key Value pair values left over from the POST and change the HTTP verb to GET

To verify we can now access the Project Service using OAuth, set the URL to the value used in the
Cookbook 1 section “Using GET to read a Project”:

Press Send and view the response:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 97

You have read a project using OAuth authentication and authorization!

Also note how Postman, using the UI fields, produced an HTTP Authorization Header containing not only
some of the Postman UI fields’ data but also the oauth_signature:

OAuth realm="http://xml2394.wdf.sap.corp:8080/eso10/ngservices/rest/projectservice/project/PROCAT-013-
BGNXM-
2014",oauth_consumer_key="12bb95a78afdbb273dec836a8c7d1e5",oauth_token="b9223fe570f57a735330
6c35271c75d",oauth_signature_method="HMAC-
SHA1",oauth_timestamp="1402595094",oauth_nonce="uMQ9J6",oauth_version="1.0",oauth_signature="yE
VWZfyIaw7015xbnOWfEzo96SQ%3D"

The actual external client consumer program would need to build an HTTP Authorization header the same
way.

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 98

Recommendation
Read section ‘Using OAuth 1.0 to Authenticate Web Service Requests’ in the "Web Services
Guide for SAP Sourcing 10.0" which is available on Service Marketplace and is the official
documentation of the new Web Service Framework.

If you save the provided Access Token and Access Secret, you can clear the Chrome browser cache, close
and re-open Chrome Postman, then fill in the following Postman OAuth 1.0 tab fields: Consumer Key
(Sourcing/CLM Client ID), Consumer Secret (Sourcing/CLM Client Secret), Token and Token Secret as
well as a valid Project Service URL, press Send – and execute a Project Service web service call without
providing a username and password!

Note
After you have successfully completed the OAuth handshake and token exchange and saved
the Token and Token Secret, it is still very easy to get the following error due to a copy/paste
of the keys and secrets into Postman; For example, by having a trailing space on the Token
string, you will get this error:

Also, note that OAuth does try to give you a hint of the problem in the response headers:

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 99

Copyrights, Trademarks, and Disclaimers


© 2014 SAP AG. All rights reserved.
No part of this publication may be reproduced or transmitted in any form or for any purpose without the
express permission of SAP AG. The information contained herein may be changed without prior notice.
Some software products marketed by SAP AG and its distributors contain proprietary software components
of other software vendors.
Microsoft, Windows, Excel, Outlook, PowerPoint, Silverlight, and Visual Studio are registered trademarks of
Microsoft Corporation.
IBM, DB2, DB2 Universal Database, System i, System i5, System p, System p5, System x, System z,
System z10, z10, z/VM, z/OS, OS/390, zEnterprise, PowerVM, Power Architecture, Power Systems,
POWER7, POWER6+, POWER6, POWER, PowerHA, pureScale, PowerPC, BladeCenter, System Storage,
Storwize, XIV, GPFS, HACMP, RETAIN, DB2 Connect, RACF, Redbooks, OS/2, AIX, Intelligent Miner,
WebSphere, Tivoli, Informix, and Smarter Planet are trademarks or registered trademarks of IBM
Corporation.
Linux is the registered trademark of Linus Torvalds in the United States and other countries.
Adobe, the Adobe logo, Acrobat, PostScript, and Reader are trademarks or registered trademarks of Adobe
Systems Incorporated in the United States and other countries.
Oracle and Java are registered trademarks of Oracle and its affiliates.
UNIX, X/Open, OSF/1, and Motif are registered trademarks of the Open Group.
Citrix, ICA, Program Neighborhood, MetaFrame, WinFrame, VideoFrame, and MultiWin are trademarks or
registered trademarks of Citrix Systems Inc.
HTML, XML, XHTML, and W3C are trademarks or registered trademarks of W3C®, World Wide Web
Consortium, Massachusetts Institute of Technology.
Apple, App Store, iBooks, iPad, iPhone, iPhoto, iPod, iTunes, Multi-Touch, Objective-C, Retina, Safari, Siri,
and Xcode are trademarks or registered trademarks of Apple Inc.
IOS is a registered trademark of Cisco Systems Inc.
RIM, BlackBerry, BBM, BlackBerry Curve, BlackBerry Bold, BlackBerry Pearl, BlackBerry Torch, BlackBerry
Storm, BlackBerry Storm2, BlackBerry PlayBook, and BlackBerry App World are trademarks or registered
trademarks of Research in Motion Limited.
Google App Engine, Google Apps, Google Checkout, Google Data API, Google Maps, Google Mobile Ads,
Google Mobile Updater, Google Mobile, Google Store, Google Sync, Google Updater, Google Voice, Google
Mail, Gmail, YouTube, Dalvik and Android are trademarks or registered trademarks of Google Inc.
INTERMEC is a registered trademark of Intermec Technologies Corporation.
Wi-Fi is a registered trademark of Wi-Fi Alliance.
Bluetooth is a registered trademark of Bluetooth SIG Inc.
Motorola is a registered trademark of Motorola Trademark Holdings LLC.
Computop is a registered trademark of Computop Wirtschaftsinformatik GmbH.
SAP, R/3, SAP NetWeaver, Duet, PartnerEdge, ByDesign, SAP BusinessObjects Explorer, StreamWork,
SAP HANA, and other SAP products and services mentioned herein as well as their respective logos are
trademarks or registered trademarks of SAP AG in Germany and other countries.
Business Objects and the Business Objects logo, BusinessObjects, Crystal Reports, Crystal Decisions, Web
Intelligence, Xcelsius, and other Business Objects products and services mentioned herein as well as their
respective logos are trademarks or registered trademarks of Business Objects Software Ltd. Business
Objects is an SAP company.
Sybase and Adaptive Server, iAnywhere, Sybase 365, SQL Anywhere, and other Sybase products and
services mentioned herein as well as their respective logos are trademarks or registered trademarks of
Sybase Inc. Sybase is an SAP company.

© 2015 SAP AG. All rights reserved.


Sourcing 10.0 Web Service Cookbook and Troubleshooting Guide 100

Crossgate, m@gic EDDY, B2B 360°, and B2B 360° Services are registered trademarks of Crossgate AG in
Germany and other countries. Crossgate is an SAP company.
All other product and service names mentioned are the trademarks of their respective companies. Data
contained in this document serves informational purposes only. National product specifications may vary.
These materials are subject to change without notice. These materials are provided by SAP AG and its
affiliated companies ("SAP Group") for informational purposes only, without representation or warranty of any
kind, and SAP Group shall not be liable for errors or omissions with respect to the materials. The only
warranties for SAP Group products and services are those that are set forth in the express warranty
statements accompanying such products and services, if any. Nothing herein should be construed as
constituting an additional warranty.

© 2015 SAP AG. All rights reserved.