PUBLIC
SAP HANA Cloud Integration for data services
Document Version: 1.0.10 December 4, 2015
Web Services Guide
Content
Technologies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1
Web service support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2
Web services technologies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
SOAP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
WSDL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
XML Schema. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
UDDI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.3
Creating a client to use web services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
2.1
Supported web service operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.2
Connection operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
ping. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
logon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8
logout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.3
Project operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
runTask. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
getTaskStatusByRunID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
getTaskLogs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14
getAllExecutedTasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Error Reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
3.1
Error reporting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18
PUBLIC
2015 SAP SE or an SAP affiliate company. All rights reserved.
Web Services Guide
Content
Technologies
1.1
Web service support
When an external application calls into SAP HANA Cloud Integration through web services, the application acts as
a web service client accessing a web services server.
Web service clients call the published web services, pass in the appropriate parameters, and receive the results.
1.2
Web services technologies
SAP HANA Cloud Integration web services are compliant with JAX-WS and Web Services Interoperability (WS-I)
Basic Profile 1.0, and support several Java web services technologies.
Technology
Description
SOAP
Connection protocol (envelope for XML messages)
WSDL
XML-based language used describe published web services
XML Schema
Format used for the WSDL file
1.2.1 SOAP
SAP HANA Cloud Integration supports the Simple Object Access Protocol (SOAP).
SOAP is an industry standard from the World Wide Web Consortium (WC3.org) used to invoke network resources
using XML over HTTP, HTTPS, and other standard protocols. SAP HANA Cloud Integration supports SOAP over
HTTP and HTTPS protocols.
1.2.2 WSDL
Web Services Description Language (WSDL) is a subset of XML used as a transport mechanism for XML
messages.
The WSDL file generated by the software includes elements (such as services, bindings, ports, and operations)
that support the use of the SOAP protocol. Each element uses a name that the software provides.
This table shows the elements in a WSDL file, and describes how those elements are used in the SAP HANA Cloud
Integration WSDL file.
Web Services Guide
Technologies
PUBLIC
2015 SAP SE or an SAP affiliate company. All rights reserved.
Element Name
Description
definition
Root element.
service
Used to group a set of related ports or endpoints to which a client application will
connect. The software publishes a single service in the WSDL file.
port
Defines a specific web service endpoint that a client can access. Each port has a
unique name and a specific address used for binding. The software defines a single
port that contains the operations.
portType
Defines a set of operations that a web service publishes.
A portType is bound to a particular port. The binding specifies the protocol and data
formation for the operations defined by a portType.
operation
Defines a specific function call. The software publishes connection and project op
erations.
message
Defines the data to transmit. There is an input (request) message, which the web
service receives from the client, and there is an output (response) message, which
the web service sends back to the client.
type
Defines the data types used in messages sent to and from a web service.
1.2.2.1
Accessing the WSDL file
Access the WSDL file by making web service client calls to it using your HCI URL.
Use the information in the WSDL file provided by SAP HANA Cloud Integration to create an application that can
access tasks.
To view the WSDL file so that you can create your application, open a browser window and navigate to:
http://<hci_url>/DSoD/webservices?wsdl
Example
http://integration.ondemand.com/DSoD/webservices?wsdl
Note that the primary WSDL contains only a readable listing of the available web service operations. A secondary,
imported WSDL defines the XML schema of the services:
http://<hci_url>/DSoD/webservices?wsdl=SoapGateway.wsdl
Example
http://hcids.us1.hana.ondemand.com/DSoD/webservices?wsdl=SoapGateway.wsdl
PUBLIC
2015 SAP SE or an SAP affiliate company. All rights reserved.
Web Services Guide
Technologies
1.2.3 XML Schema
WSDL uses XML Schemas to define input and output message formats.
XML Schema formats are defined in the types element of the WSDL file.
1.2.4 UDDI
UDDI is a method of publishing comments and other reference information about jobs to an external web site.
SAP HANA Cloud Integration does not publish information to a UDDI web site because most web service users
work behind enterprise firewalls.
1.3
Creating a client to use web services
The tools you use to develop your web services client are your choice and the exact steps in using those tools
vary, but these basic steps apply as a simple overview to all development projects for web services clients.
Context
To use a published web service, you must first know the URL of the target WSDL.
The primary SAP HANA Cloud Integration WSDL file is located at:
http://<hci_host>:<port>/DSoD/webservices?wsdl
Procedure
1. Import the software's WSDL into your development environment to create a web services client application.
The incorporated web services appear in the hierarchy of your development.
2. Open the web service.
Each available port for the web service is made visible in the IDE.
3. Write the code to call any of the jobs or services provided by the ports.
4. Run the project to execute the code.
Executing the code initiates the web services job, and a connection is made to the SAP HANA Cloud
Integration web services host.
Web Services Guide
Technologies
PUBLIC
2015 SAP SE or an SAP affiliate company. All rights reserved.
Related Information
Accessing the WSDL file [page 4]
PUBLIC
2015 SAP SE or an SAP affiliate company. All rights reserved.
Web Services Guide
Technologies
Operations
2.1
Supported web service operations
SAP HANA Cloud Integration provides a WSDL file with a single service definition.
It is possible to create multiple service definitions in a WSDL, but many web service implementations do not
support more than one service definition. To avoid that limitation, the software creates only one service.
2.2
Connection operations
The SAP HANA Cloud Integration WSDL defines connection operations that belong to web services.
The software supports the following Connection operations:
Operation
Description
ping
Verifies the connection to SAP HANA Cloud Integration web services.
logon
Verifies secure access and establishes a web services session.
logoff
Terminates an existing web services session.
2.2.1 ping
The ping operation can be used to maintain a user session.
Request message
Table 1: ping elements
Element
Type
Description
SessionID
xs:string
The unique ID of the session that should be used for the web
service operation.
If a session ID is not specified in the request message, the ping operation returns an error message that the
server is available but no ID was specified.
Web Services Guide
Operations
PUBLIC
2015 SAP SE or an SAP affiliate company. All rights reserved.
Response message
Table 2: pingResponse elements
Element
Type
Description
Message
xs:string
A message that indicates that a connection has been estab
lished.
For more information about the structure of the ping request and response messages, refer to the SAP HANA
Cloud Integration WSDL.
Related Information
Accessing the WSDL file [page 4]
2.2.2 logon
The logon operation provides basic user authentication and returns a valid web services session ID.
Web service logon operations are logged in the SAP HANA Cloud Integration security log.
Request message
Table 3: logonRequest elements
Element
Type
Description
orgName
xs:string
The name of the SAP HANA Cloud Integration organization.
userName
xs:string
The user name.
password
xs:string
The password.
isProduction
xs:boolean
Specifies whether to log in to the production or sandbox repo
sitory.
Default value: false
PUBLIC
2015 SAP SE or an SAP affiliate company. All rights reserved.
Web Services Guide
Operations
Response message
Table 4: logonResponse elements
Element
Type
Description
SessionID
xs:string
A unique session ID that can be used for subsequent web
services operations.
The session ID is valid only for the specified repository type.
For example, a session ID generated by specifying
<isProduction>true</isProduction> cannot be
used to execute tasks in the sandbox repository, even if the
user would otherwise have permissions to do so. You must
first log out and then log in again, requesting a new session ID.
By default, the session will expire and become invalid after an
idle timeout of 30 minutes. The expiration timer is reset each
time a web service operation is called using the session ID. All
session IDs expire after 24 hours.
Additionally, if the user or organization associated with the
session is disabled or deleted, the session will be expired.
HTTP Basic Authentication
As an alternative to providing the logon details in the SOAP body, the logon operation also supports HTTP Basic
Authentication.
To use HTTP Basic Authentication, do not use the logonRequest element, and instead provide the access details
in the HTTP header.
Table 5: HTTP headers
Header
Possible values
Description
Authorization
Basic
<authorization>
The authentication type and the base64-encoded value of the
username and password pair:
<username>:<password>
orgName
dsodEnv
Alphanumeric characters
The name of the SAP HANA Cloud Integration organization.
PRODUCTION
The type of repository that the web services session should
access.
SANDBOX
SOAPAction
function=logon
The SOAP action to perform.
Note
When using HTTP-based authentication to log on to the SAP HANA Cloud Integration web services from a SAP
Data Services job, you must still include the logonRequest element in the message body because SAP Data
Services does not support an empty mapping. Instead, specify a null value for each element of the
logonRequest message.
Web Services Guide
Operations
PUBLIC
2015 SAP SE or an SAP affiliate company. All rights reserved.
For more information about the structure of the logon request and response messages, refer to the SAP HANA
Cloud Integration WSDL.
Related Information
Accessing the WSDL file [page 4]
2.2.3 logout
The logout operation logs the user out of the system and destroys the specified session.
Web service logout operations are logged in the SAP HANA Cloud Integration security log.
Request message
Table 6: logout elements
Element
Type
Description
SessionID
xs:string
The unique ID of the session that should be logged out and de
stroyed.
Response message
Table 7: logoutResponse elements
Element
Type
Description
LogoutMessage
xs:string
A message that indicates that the web services session has
been terminated.
For more information about the structure of the logout request and response messages, refer to the SAP HANA
Cloud Integration WSDL.
Related Information
Accessing the WSDL file [page 4]
10
PUBLIC
2015 SAP SE or an SAP affiliate company. All rights reserved.
Web Services Guide
Operations
2.3
Project operations
The SAP HANA Cloud Integration WSDL defines project operations that allow you to execute tasks and retrieve
execution status information.
The software supports the following Project operations:
Operation
Description
runTask
Executes a task and returns a run ID.
getTaskStatusByRunID
Returns the status of the task execution with the specified run ID.
getTaskLogs
Retrieves the trace, monitor, or error log for the task execution with the specified
run ID.
getAllExecuted
Returns a list of tasks that are currently running or already executed from Run Now,
a task schedule, or web services.
Access restrictions
The roles of the user that created the web services session determines whether the project services have access
to the sandbox or production repository.
Table 8: Repository access for project services
User role
Sandbox
Production
Integration developer
Yes
No
Production operator
No
Yes
Administrator
Yes
Yes
All other roles
No
No
Note
The role-based repository access is additive. That is, if the user is assigned both the Integration developer
and Production operator roles, the project services will be able to access both repositories.
SOAP header
All project services may be accessed only by specifying a valid web services session ID obtained from the logon
operation. The session ID must be specified in the SOAP header of the web service request.
Web Services Guide
Operations
PUBLIC
2015 SAP SE or an SAP affiliate company. All rights reserved.
11
Table 9: SOAP header elements
Element
Type
Description
SessionID
xs:string
The unique ID of the session that should be used for the web
service operation.
2.3.1 runTask
The runTask operation executes a task in either the sandbox or production repository.
Request message
Table 10: runTaskRequest elements
Element
Type
Description
taskName
xs:string
The name of the task that should be executed.
agentName
xs:string
The name of the SAP Data Services Agent that should be used
to execute the task.
globalVariables
xs:sequence
Optional. A list of the global variables to pass to the task, de
fined as a sequence of xs:string elements.
For example:
<variable name="myVar">Value</variable>
Response message
Table 11: runTaskResponse elements
Element
Type
Description
RunID
xs:string
A unique ID that identifies the specific execution instance for
the task and can be used to retrieve the execution status or
logs.
For more information about the structure of the runTask request and response messages, refer to the SAP
HANA Cloud Integration WSDL.
Related Information
Accessing the WSDL file [page 4]
12
PUBLIC
2015 SAP SE or an SAP affiliate company. All rights reserved.
Web Services Guide
Operations
2.3.2 getTaskStatusByRunID
The getTaskStatusByRunID operation retreives the status of a task execution with a specified run ID.
To prevent server overload, the getTaskStatusByRunID operation should be called only using a fixed time
overload.
Request message
Table 12: taskStatusRequest elements
Element
Type
Description
runID
xs:int
The unique run ID of the task execution instance.
Response message
Table 13: taskStatusResponse elements
Element
Type
Description
taskStatusRequest
tns:taskStatusReques A copy of the request used to retrieve the task status.
t
JobID
xs:string
The unique JobID of the task.
Even if a task is deleted and a new one with the same name is
then created, the JobID for each remains unique.
statusCode
xs:string
The status of the task execution.
Possible values:
TASK:IMPORTED
TASK:RUNNING
TASK:SUCCESS
TASK:ERROR
TASK:QUEUEING
TASK:TERMINATED
TASK:TERMINATED_FAILED
TASK:UNKNOWN
statusMsg
xs:string
Additional information about the task execution status.
startTime
xs:string
The time the task execution started.
endTime
xs:string
The time the task execution ended.
executionTime
xs:double
The duration of the task execution.
For more information about the structure of the getTaskStatusByRunID request and response messages, refer
to the SAP HANA Cloud Integration WSDL.
Web Services Guide
Operations
PUBLIC
2015 SAP SE or an SAP affiliate company. All rights reserved.
13
Related Information
Accessing the WSDL file [page 4]
2.3.3 getTaskLogs
The getTaskLogs operation retrieves the trace, monitor, or error logs for a task execution with a specified run ID.
Request message
Table 14: taskLogsRequest elements
Element
Type
Description
runID
xs:int
The unique run ID of the task execution instance.
base64Encode
xs:boolean
Specifies whether any log data returned should be encoded in
base64 format.
Default value: true
traceLog
tns:LogType
Optional. Specifies which page of the trace log to retrieve, if
any.
monitorLog
tns:LogType
Optional. Specifies which page of the monitor log to retrieve, if
any.
errorLog
tns:LogType
Optional. Specifies which page of the error log to retrieve, if
any.
Element
Type
Description
getLog
xs:boolean
Specifies whether to retrieve log data for this log type.
pageNum
xs:int
Specifies the page of the log to return.
Table 15: tns:LogType elements
Default value: 1
If the page number is not specified or is larger than the maxi
mum number of pages in the log, the first page is returned.
Response message
Table 16: taskLogsResponse elements
Element
Type
Description
traceLog
tns:LogContent
The content for the requested page of the trace log.
14
PUBLIC
2015 SAP SE or an SAP affiliate company. All rights reserved.
Web Services Guide
Operations
Element
Type
Description
monitorLog
tns:LogContent
The content for the requested page of the monitor log.
errorLog
tns:LogContent
The content for the requested page of the error log.
Table 17: tns:LogContent elements
Element
Type
Description
maxPage
xs:int
The total number of pages in the log.
pageNum
xs:int
The page number of the requested log page.
isJobRunning
xs:boolean
Specifies whether the task is still running.
messageLines
xs:string
A line of content from the requested page of the log.
For more information about the structure of the getTaskLogs request and response messages, refer to the SAP
HANA Cloud Integration WSDL.
Related Information
Accessing the WSDL file [page 4]
2.3.4 getAllExecutedTasks
The getAllExecutedTasks operation returns a list of tasks that are currently running or already executed from
Run Now, a task schedule, or web services.
Request message
Table 18: executedTaskFilterRequest elements
Element
Type
Description
taskName
xs:string
Optional. The name of the task that should be executed.
startDate
xs:dateTime
Optional. The start date of the range for which task executions
should be returned, specified using the XML Schema date
Time format.
For example: 2015-03-20T18:30:00Z
Web Services Guide
Operations
PUBLIC
2015 SAP SE or an SAP affiliate company. All rights reserved.
15
Element
Type
Description
endDate
xs:dateTime
Optional. The end date of the range for which task executions
should be returned, specified using the XML Schema date
Time format.
For example: 2015-03-27T18:30:00Z
If no end date is specified, the range of task executions re
turned is 7 days after the start date. If the range specified is
more than 90 days, an error is returned.
statusCode
tns:JobRunStatus
Optional. The status of the task executions to return.
Possible values:
TASK:IMPORTED
TASK:RUNNING
TASK:SUCCESS
TASK:ERROR
TASK:QUEUEING
TASK:TERMINATED
TASK:TERMINATED_FAILED
TASK:UNKNOWN
Note
When you do not specify any input filter options, all task executions from the past seven days are returned.
16
PUBLIC
2015 SAP SE or an SAP affiliate company. All rights reserved.
Web Services Guide
Operations
Response message
Table 19: executedTaskResponse elements
Element
Type
Description
runID
xs:int
A unique ID that identifies the specific execution instance for
the task and can be used to retrieve the execution status or
logs.
Note
The runID elements are ordered by the time when each
task was started.
Attributes:
jobID: The ID of the task executed.
startDate: The number of milliseconds since the Unix
epoch.
statusCode: The status code associated with the
taskName: The name of the task executed.
unique task execution.
For more information about the structure of the getAllExecutedTasks request and response messages, refer
to the SAP HANA Cloud Integration WSDL.
Related Information
Accessing the WSDL file [page 4]
Web Services Guide
Operations
PUBLIC
2015 SAP SE or an SAP affiliate company. All rights reserved.
17
Error Reports
3.1
Error reporting
In addition to the output message for each web services operation, the SAP HANA Cloud Integration returns a
fault message when an error occurs.
Fault message
Table 20: WebFaultException elements
Element
Type
Description
faultCode
xs:string
The type of fault that occurred.
Possible values:
faultString
18
xs:string
PUBLIC
2015 SAP SE or an SAP affiliate company. All rights reserved.
Connection:Authentication
Services:Authorization
Services:Server
A description of the fault that has occurred.
Web Services Guide
Error Reports
Important Disclaimers and Legal Information
Coding Samples
Any software coding and/or code lines / strings ("Code") included in this documentation are only examples and are not intended to be used in a productive system
environment. The Code is only intended to better explain and visualize the syntax and phrasing rules of certain coding. SAP does not warrant the correctness and
completeness of the Code given herein, and SAP shall not be liable for errors or damages caused by the usage of the Code, unless damages were caused by SAP
intentionally or by SAP's gross negligence.
Accessibility
The information contained in the SAP documentation represents SAP's current view of accessibility criteria as of the date of publication; it is in no way intended to be a
binding guideline on how to ensure accessibility of software products. SAP in particular disclaims any liability in relation to this document. This disclaimer, however, does
not apply in cases of wilful misconduct or gross negligence of SAP. Furthermore, this document does not result in any direct or indirect contractual obligations of SAP.
Gender-Neutral Language
As far as possible, SAP documentation is gender neutral. Depending on the context, the reader is addressed directly with "you", or a gender-neutral noun (such as "sales
person" or "working days") is used. If when referring to members of both sexes, however, the third-person singular cannot be avoided or a gender-neutral noun does not
exist, SAP reserves the right to use the masculine form of the noun and pronoun. This is to ensure that the documentation remains comprehensible.
Internet Hyperlinks
The SAP documentation may contain hyperlinks to the Internet. These hyperlinks are intended to serve as a hint about where to find related information. SAP does not
warrant the availability and correctness of this related information or the ability of this information to serve a particular purpose. SAP shall not be liable for any damages
caused by the use of related information unless damages have been caused by SAP's gross negligence or willful misconduct. All links are categorized for transparency
(see: http://help.sap.com/disclaimer).
Web Services Guide
Important Disclaimers and Legal Information
PUBLIC
2015 SAP SE or an SAP affiliate company. All rights reserved.
19
www.sap.com/contactsap
2015 SAP SE or an SAP affiliate company. 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 SE
or an SAP affiliate company. The information contained herein may
be changed without prior notice.
Some software products marketed by SAP SE and its distributors
contain proprietary software components of other software
vendors. National product specifications may vary.
These materials are provided by SAP SE or an SAP affiliate company
for informational purposes only, without representation or warranty
of any kind, and SAP or its affiliated companies shall not be liable for
errors or omissions with respect to the materials. The only
warranties for SAP or SAP affiliate company 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.
SAP and other SAP products and services mentioned herein as well
as their respective logos are trademarks or registered trademarks
of SAP SE (or an SAP affiliate company) in Germany and other
countries. All other product and service names mentioned are the
trademarks of their respective companies.
Please see http://www.sap.com/corporate-en/legal/copyright/
index.epx for additional trademark information and notices.
