hci10_web_services_en.pdf

PUBLIC

SAP HANA Cloud Integration for data servicesDocument Version: 1.0.7 - 2014-11-13

Web Services Guide

Table of Contents1 Web service support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.1 Web services technologies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.1.1 SOAP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.1.2 WSDL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31.1.3 XML Schema. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.1.4 UDDI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

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

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

2.1.1 ping. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.1.2 logon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.1.3 logout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

2.2 Project operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.2.1 runTask. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122.2.2 getTaskStatusByRunID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.2.3 getTaskLogs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

3 Error reporting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

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

Web Services GuideTable of Contents

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

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.

Web Services GuideWeb service support

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

Element Name Description

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



1.1.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.1.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.2 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.



Related Information

Accessing the WSDL file [page 4]Access the WSDL file by making web service client calls to it using your HCI URL.



2 Supported web service operationsSAP 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.1 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.1.1 ping

The ping operation can be used to maintain a user session.

Request message

Table 1: ping elementsElement 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 GuideSupported web service operations


Response message

Table 2: pingResponse elementsElement Type Description

Message xs:string A message that indicates that a connection has been established.

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

Related Information


2.1.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 elementsElement 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 repository.

Default value: false



Response message

Table 4: logonResponse elementsElement 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 headersHeader Possible values Description

Authorization Basic <authorization>

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

<username>:<password>

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.1.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 Description

SessionID xs:string The unique ID of the session that should be logged out and destroyed.

Response message

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


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

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 Production

Integration developer Yes No

Production operator No Yes

Administrator Yes Yes

All 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 Description

SessionID xs:string The unique ID of the session that should be used for the web service operation.

2.2.1 runTask

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

Request message

Table 10: runTaskRequest elementsElement 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, defined as a sequence of xs:string elements.

For example:

<variable name="myVar">Value</variable>

Response message

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


2.2.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 elementsElement Type Description

runID xs:int The unique run ID of the task execution instance.

Response message

Table 13: taskStatusResponse elementsElement Type Description

taskStatusRequest tns:taskStatusRequest

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



Element Type Description

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.2.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 elementsElement Type Description

runID xs:int The unique run ID of the task execution instance.



Element Type Description

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

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 Description

traceLog tns:LogContent The content for the requested page of the trace log.

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 elementsElement 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




3 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 18: WebFaultException elementsElement Type Description

faultCode 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 reporting


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

http://help.sap.com/disclaimer/

Web Services GuideImportant Disclaimers and Legal Information


www.sap.com/contactsap

© 2014 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.

http://www.sap.com/contactsap

http://www.sap.com/corporate-en/legal/copyright/index.epx

http://www.sap.com/corporate-en/legal/copyright/index.epx

hci10_web_services_en.pdf

Documents

Transcript of hci10_web_services_en.pdf