Web Services Guide - SAP HCI

PUBLICSAP HANA Cloud Integration for data servicesDocument Version: 1.0.10 December 4, 2015

Web Services Guide

Content

1 Technologies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31.1 Web service support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Web services technologies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

SOAP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3WSDL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3XML Schema. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5UDDI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1.3 Creating a client to use web services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2 Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72.1 Supported web service operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.2 Connection operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7

ping. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7logon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8logout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

2.3 Project operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11runTask. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12getTaskStatusByRunID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13getTaskLogs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14getAllExecutedTasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

3 Error Reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183.1 Error reporting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18

2P U B L I C 2015 SAP SE or an SAP affiliate company. All rights reserved.

Web Services GuideContent

1 Technologies

1.1 Web service supportWhen 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 technologiesSAP 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 DescriptionSOAP Connection protocol (envelope for XML messages)WSDL XML-based language used describe published web servicesXML Schema Format used for the WSDL file

1.2.1 SOAPSAP 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 WSDLWeb 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 GuideTechnologies

P U B L I C 2015 SAP SE or an SAP affiliate company. All rights reserved. 3

Element Name Descriptiondefinition 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 operations.

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 fileAccess 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:///DSoD/webservices?wsdl

Examplehttp://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:///DSoD/webservices?wsdl=SoapGateway.wsdl

Examplehttp://hcids.us1.hana.ondemand.com/DSoD/webservices?wsdl=SoapGateway.wsdl



1.2.3 XML SchemaWSDL 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 UDDIUDDI 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 servicesThe 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://:/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.



Related Information

Accessing the WSDL file [page 4]



2 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 Descriptionping 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 elementsElement Type DescriptionSessionID 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 GuideOperations


Response message

Table 2: pingResponse elementsElement Type DescriptionMessage 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


2.2.2 logonThe 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 elementsElement Type DescriptionorgName 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



Response messageTable 4: logonResponse elementsElement Type DescriptionSessionID 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 true 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 AuthenticationAs 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 headersHeader Possible values DescriptionAuthorization Basic

The authentication type and the base64-encoded value of the username and password pair::

orgName Alphanumeric characters The name of the SAP HANA Cloud Integration organization.dsodEnv PRODUCTION

SANDBOX

The type of repository that the web services session should access.

SOAPAction function=logon The SOAP action to perform.

NoteWhen 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.



For more information about the structure of the logon request and response messages, refer to the SAP HANA Cloud Integration WSDL.

Related Information


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 elementsElement Type DescriptionSessionID xs:string The unique ID of the session that should be logged out and de

stroyed.

Response message

Table 7: logoutResponse elementsElement Type DescriptionLogoutMessage 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




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 DescriptionrunTask 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 servicesUser role Sandbox ProductionIntegration developer Yes NoProduction operator No YesAdministrator Yes YesAll other roles No No

NoteThe 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.



Table 9: SOAP header elementsElement Type DescriptionSessionID xs:string The unique ID of the session that should be used for the web

service operation.

2.3.1 runTaskThe runTask operation executes a task in either the sandbox or production repository.

Request message

Table 10: runTaskRequest elementsElement Type DescriptiontaskName 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:

Value

Response message

Table 11: runTaskResponse elementsElement Type DescriptionRunID 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




2.3.2 getTaskStatusByRunIDThe 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 elementsElement Type DescriptionrunID xs:int The unique run ID of the task execution instance.

Response message

Table 13: taskStatusResponse elementsElement Type DescriptiontaskStatusRequest tns:taskStatusReques

tA copy of the request used to retrieve the task status.

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.



Related Information


2.3.3 getTaskLogsThe getTaskLogs operation retrieves the trace, monitor, or error logs for a task execution with a specified run ID.

Request message

Table 14: taskLogsRequest elementsElement Type DescriptionrunID 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.

Table 15: tns:LogType elementsElement Type DescriptiongetLog xs:boolean Specifies whether to retrieve log data for this log type.pageNum xs:int Specifies the page of the log to return.

Default value: 1

If the page number is not specified or is larger than the maximum number of pages in the log, the first page is returned.

Response message

Table 16: taskLogsResponse elementsElement Type DescriptiontraceLog tns:LogContent The content for the requested page of the trace log.



Element Type DescriptionmonitorLog 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 elementsElement Type DescriptionmaxPage 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


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 elementsElement Type DescriptiontaskName 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 dateTime format.For example: 2015-03-20T18:30:00Z



Element Type DescriptionendDate xs:dateTime Optional. The end date of the range for which task executions

should be returned, specified using the XML Schema dateTime format.For example: 2015-03-27T18:30:00Z

If no end date is specified, the range of task executions returned 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

NoteWhen you do not specify any input filter options, all task executions from the past seven days are returned.



Response message

Table 19: executedTaskResponse elementsElement Type DescriptionrunID 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.

NoteThe 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

unique task execution. taskName: The name of the task executed.

For more information about the structure of the getAllExecutedTasks request and response messages, refer to the SAP HANA Cloud Integration WSDL.

Related Information




3 Error Reports

3.1 Error reportingIn 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 elementsElement Type DescriptionfaultCode xs:string The type of fault that occurred.

Possible values: Connection:Authentication Services:Authorization Services:Server

faultString xs:string A description of the fault that has occurred.


Web Services GuideError Reports

Important Disclaimers and Legal Information

Coding SamplesAny 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.

AccessibilityThe 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 LanguageAs 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 HyperlinksThe 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 GuideImportant Disclaimers and Legal Information


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.

Web Services GuideContent1 Technologies1.1 Web service support1.2 Web services technologies1.2.1 SOAP1.2.2 WSDL1.2.2.1 Accessing the WSDL file

1.2.3 XML Schema1.2.4 UDDI

1.3 Creating a client to use web services

2 Operations2.1 Supported web service operations2.2 Connection operations2.2.1 ping2.2.2 logon2.2.3 logout

2.3 Project operations2.3.1 runTask2.3.2 getTaskStatusByRunID2.3.3 getTaskLogs2.3.4 getAllExecutedTasks

3 Error Reports3.1 Error reporting

Important Disclaimers and Legal InformationCopyright / Legal Notice

Documents

Web Services Guide - SAP HCI