Web Services en

PUBLIC
SAP Cloud Integration for data services 1.0.11

2022-10-11
Web Services Guide

© 2022 SAP SE or an SAP affiliate company. All rights reserved.
THE BEST RUN

Content
1 Web Services Guide for SAP Cloud Integration for data services . . . . . . . . . . . . . . . . . . . . . . . . 3
2 Web Services Technologies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1 SOAP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.2 WSDL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Accessing the WSDL File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.3 XML Schema. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.4 UDDI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3 Creating a Client to Use Web Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
4 Supported Web Service Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4.1 Connection Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
ping. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
logon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
logout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.2 Project Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
runTask. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
getTaskStatusByRunId. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
getTaskStatusByRunId2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
getTaskLogs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
getAllExecutedTasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
getAllExecutedTasks2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
searchTasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
getAgents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
getSystemConfigurations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30
getProjects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
getProjectTasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
getTaskInfo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
cancelTask. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
5 Error Reporting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Web Services Guide

2 PUBLIC Content
1 Web Services Guide for SAP Cloud
Integration for data services
When an external application calls into SAP Cloud Integration for data services 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.
Web Services Guide

Web Services Guide for SAP Cloud Integration for data services PUBLIC 3
2 Web Services Technologies
SAP Cloud Integration for data services 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
Related Information
SOAP [page 4]
WSDL [page 4]
XML Schema [page 6]
UDDI [page 6]
2.1 SOAP
SAP Cloud Integration for data services 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 Cloud Integration for data services
supports SOAP over HTTP and HTTPS protocols.
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 Cloud
Integration for data services WSDL file.
Web Services Guide

4 PUBLIC Web Services Technologies
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 sin
gle 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.
Related Information
Accessing the WSDL File [page 5]
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 Cloud Integration for data services 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
Web Services Guide

Web Services Technologies PUBLIC 5
 Example
http://hcids.us1.hana.ondemand.com/DSoD/webservices?wsdl=SoapGateway.wsdl
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.
2.4 UDDI
UDDI is a method of publishing comments and other reference information about jobs to an external web site.
SAP Cloud Integration for data services does not publish information to a UDDI web site because most web
service users work behind enterprise firewalls.
Web Services Guide

6 PUBLIC Web Services Technologies
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. These basic steps apply as a simple overview to all development projects for web services clients.
To use a published web service, you must first know the URL of the target WSDL.
The primary SAP Cloud Integration for data services WSDL file is located at:
http://<hci_host>:<port>/DSoD/webservices?wsdl
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 Cloud Integration
for data services web services host.
Related Information
Web Services Guide

Creating a Client to Use Web Services PUBLIC 7
4 Supported Web Service Operations
SAP Cloud Integration for data services 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.
Related Information
Connection Operations [page 8]

Project Operations [page 13]
4.1 Connection Operations
The Web Services Guide for SAP Cloud Integration for data services WSDL defines connection operations that
belong to web services.
The software supports the following Connection operations:
Operation Description
ping Verifies the connection to SAP Cloud Integration for data services web services.
logon Verifies secure access and establishes a web services session.
logoff Terminates an existing web services session.
Related Information
ping [page 9]
logon [page 9]
logout [page 12]
Web Services Guide

8 PUBLIC Supported Web Service Operations
4.1.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.
Response message
Table 2: pingResponse elements

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 Cloud
Integration for data services WSDL.
Related Information
4.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 Cloud Integration for data services security log.
Web Services Guide

Supported Web Service Operations PUBLIC 9
Request message
Table 3: logonRequest elements

orgName xs:string The name of the SAP Cloud Integration for data services or
ganization.
userName xs:string The user name. The user name must not contain the colon
character (:).
password xs:string The password. The password must not contain the colon
character (:).
isProduction xs:boolean Specifies whether to log in to the production or sandbox re

pository.
Default value: false
 Note
An administrator can enable the WebServicesUser, a pre-defined system user only for SAP Cloud
Integration for data services web services. The web services user is not a regular user where the password
policy is enforced by the system. The web services user password does not automatically expire.
Response message
Table 4: logonResponse elements

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.
Web Services Guide

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 The authentication type and the base64-encoded value of

<authorization> the username and password pair:
<username>:<password>
orgName Alphanumeric characters The name of the SAP Cloud Integration for data services or
ganization.
dsodEnv PRODUCTION The type of repository that the web services session should
access.
SANDBOX
SOAPAction function=logon The SOAP action to perform.
 Note
The organization name and environment can be included in the authorization header. For example:
username|orgName|dsodEnv:password. DsodEnv is optional and defaults to PRODUCTION. The pipe
character (“|”) is a reserved character only used for log on information.
 Note
When using HTTP-based authentication to log on to the SAP Cloud Integration for data services 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.
Certificate-Based Authentication
As an alternative to providing the logon details via username and password, the logon operation also supports
client certificate authentication for the WebServicesUser.
Client certificates are sent using HTTPS and the TLS protocol. The client cerificate is passed during the TLS
handshake, and the orgName and isProduction parameters must be provided in the logonRequest.
 Note
Ensure that the certificate is in the list of supported root CA certificates which can be found here:https://
launchpad.support.sap.com/#/notes/2801396 .
Web Services Guide

Table 6: logonRequest elements
Header Possible values Description
orgName Alphanumeric characters The name of the SAP Cloud Integration for data services or
ganization.
isProduction xs:boolean Specifies whether to log in to the production or sandbox re

pository.
Default value: false
For more information about the structure of the logon request and response messages, refer to the SAP Cloud
Integration for data services WSDL.
Related Information

Activate the Pre-defined User WebServicesUser
4.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 Cloud Integration for data services security log.
Request message
Table 7: logout elements

SessionID xs:string The unique ID of the session that should be logged out and
destroyed.
Response message
Table 8: logoutResponse elements

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
Cloud Integration for data services WSDL.
Web Services Guide

Related Information
4.2 Project Operations
The SAP Cloud Integration for data services 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.
getTaskStatusByRunId2 Returns the status of the task execution with the specified run ID. Includes the
option to return status codes TASK:SUCCESS_WITH_ERRORS_D and
TASK:SUCCESS_WITH_ERRORS_E which are not available in the
getTaskStatusByRunId operation.
getTaskLogs Retrieves the trace, monitor, or error log for the task execution with the specified
run ID.
getAllExecutedTasks Returns a list of tasks that are currently running or already executed from Run
Now, a task schedule, or web services.
getAllExecutedTasks2 Returns a list of tasks that are currently running or already executed from Run
Now, a task schedule, or web services. Includes the option to return status codes
TASK:SUCCESS_WITH_ERRORS_D and
TASK:SUCCESS_WITH_ERRORS_E which are not available in the
getAllExecutedTasks operation.
searchTasks Returns all tasks whose name matches the pattern.
getAgents List all the agents and agent groups in the defined hierarchy.
getSystemConfigurations Returns a list of profiles and system configurations.
getProjects Provides ability to browse all projects. Returns list of all projects.
getProjectTasks Given the project's unique ID (GUID), returns all tasks or processes in the project.
getTaskInfo Given the task's unique ID (GUID), returns task execution information, include
global variables, execution properties, and so on.
cancelTask Stops the execution of a task or process, if execution is not finished yet
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.
Web Services Guide

Table 9: 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.
 Note
An administrator can enable the WebServicesUser, a pre-defined system user only for SAP Cloud
Integration for data services web services. The WebServicesUser has access to all repositories in an
organization.
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 10: SOAP header elements

SessionId xs:string The unique ID of the session that should be used for the web
service operation.
Related Information
runTask [page 15]

getTaskStatusByRunId [page 16]
getTaskStatusByRunId2 [page 18]
getTaskLogs [page 20]
getAllExecutedTasks [page 22]
getAllExecutedTasks2 [page 24]
searchTasks [page 28]
getAgents [page 29]
getSystemConfigurations [page 30]
getProjects [page 30]
getProjectTasks [page 31]
Web Services Guide

getTaskInfo [page 32]
cancelTask [page 34]
4.2.1 runTask
The runTask operation executes a task in either the sandbox or production repository.
Request message
Table 11: runTaskRequest elements

taskName xs:string The name of the task that should be executed.
description xs:string Description of the task.
agentName xs:string The name of the SAP Data Services Agent that should be
used to execute the task.
agentGroup xs:string The name of the agent group (collection of SAP Data
Services Agents that should be used to execute the task.
profileName xs:string The system configuration that should be used when the task
is executed.
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 12: runTaskResponse elements

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
Web Services Guide

Related Information
4.2.2 getTaskStatusByRunId
The getTaskStatusByRunId operation retrieves 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 13: taskStatusRequest elements

runId xs:int The unique run ID of the task execution instance.
Response message
Table 14: taskStatusResponse elements

taskStatusRequest tns:taskStatusReque A copy of the request used to retrieve the task status.
st
projectName xs:string The name of the project that contains the task.
jobId xs:string The unique Job ID 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.
Web Services Guide

statusCode xs:string The status of the task execution. Possible values:
• TASK:IMPORTED: Agent has successfully imported

the ATL to agent repository. Execution not started yet.
• TASK:RUNNING: Job is currently running.
• TASK:SUCCESS: Job completed with no errors.
• TASK:ERROR: The job completed with an error.
• TASK:QUEUEING: Server placed task execution in a
queue, waiting for agent to start task.
• TASK:TERMINATED: The task or process was termi
nated successfully.
• TASK:TERMINATION_FAILED: The task or process
was not terminated successfully.
• TASK:UNKNOWN: Intermediate state.
• TASK:FETCHED: Agent picked the task or process ex
ecution requests.
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.
uploadBatchInfos tns:UploadBatchInfo List of batch IDs associated with the task or process execu
s tion. When the task or process is set to execute postprocess
ing after running the task or process, there will be one entry
of UploadBatchInfo. When it is set to execute postprocessing
after the dataflow, the number of entries equals the number
of dataflows inside the task or process that is uploaded to
the IBP target.
Table 15: UploadBatchInfo elements

id xs:string IBP batch ID to identify the postprocessing execution (for ex

ample, bd62fc06974311e8a55d3e2437805af4).
name xs:string IBP Batch Name used to identify the postprocessing execu
tion (for example,
PD6_10_APO2IBP_MD_DF_IBP_UnitsOfMeasure_
Conversion.
startTime xs:string Postprocessing start time for this batch.
For more information about the structure of the getTaskStatusByRunId request and response messages,
refer to the SAP Cloud Integration for data services WSDL.
Web Services Guide

Related Information
4.2.3 getTaskStatusByRunId2
The getTaskStatusByRunId2 operation retrieves the status of a task execution with a specified run ID. The
GetTaskStatusByRunId2 operation includes the option to return status codes
TASK:SUCCESS_WITH_ERRORS_D and TASK:SUCCESS_WITH_ERRORS_E which are not available in the
getTaskStatusByRunId operation.
 Note
In the SAP Cloud Integration for data services user interface, in the task execution properties you can
define when you want the post-processing to occur and how SAP Cloud Integration for data services
reports post-processing errors.
Task that successfully loads data,

State of “Treat ‘Processed with Er but has post-processing errors com
ror’ as success” checkbox pletes as: Web services status
Selected TASK:SUCCESS_WITH_ERRORS_
Success
D
Deselected (cleared) TASK:SUCCESS_WITH_ERRORS_

Failure
E
To prevent server overload, the getTaskStatusByRunId2 operation should be called only using a fixed time
overload.
Request message
Table 16: taskStatusRequest elements

runId xs:int The unique run ID of the task execution instance.
version xs:string Available values: 1.0, 2.0.
Use 2.0 to return TASK:SUCCESS_WITH_ERRORS_D

and TASK:SUCCESS_WITH_ERRORS_E status codes.
Web Services Guide

Response message
Table 17: taskStatusResponse elements

taskStatusRequest tns:taskStatusReque A copy of the request used to retrieve the task status.
st
projectName xs:string The name of the project that contains the task.
jobId xs:string The unique Job ID of the task.
Even if a task is deleted and a new one with the same name
is then created, the Job ID for each remains unique.
statusCode xs:string Status of the task execution. Possible values:

• TASK:SUCCESS_WITH_ERRORS_D: Task was suc
cessful despite IBP post-processing errors.
• TASK:SUCCESS_WITH_ERRORS_E: Task completed
with errors if the run contains IBP post-processing er
rors.
nated successfully.
ecution requests.
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.
uploadBatchInfos tns:UploadBatchInfo List of batch IDs associated with the task or process execu
s tion. When the task or process is set to execute postprocess
ing after running the task or process, there will be one entry
of UploadBatchInfo. When it is set to execute postprocessing
after the dataflow, the number of entries equals the number
of dataflows inside the task or process that is uploaded to
the IBP target.
Web Services Guide

Table 18: UploadBatchInfos elements
id xs:string IBP batch ID to identify the postprocessing execution (for ex

ample, bd62fc06974311e8a55d3e2437805af4).
name xs:string IBP Batch Name used to identify the postprocessing execu
tion (for example,
PD6_10_APO2IBP_MD_DF_IBP_UnitsOfMeasure_
Conversion.
startTime xs:string Postprocessing start time for this batch.
For more information about the structure of the getTaskStatusByRunId request and response messages,
Related Information
Post-Processing for SAP Integrated Business Planning

4.2.4 getTaskLogs
The getTaskLogs operation retrieves the trace, monitor, or error logs for a task execution with a specified run
ID.
Request message
Table 19: taskLogsRequest elements

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.
Web Services Guide

Table 20: tns:LogType elements
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 maxi

mum number of pages in the log, the first page is returned.
Response message
Table 21: taskLogsResponse elements

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 22: tns:LogContent elements

maxPage xs:int The total number of pages in the log.
pageNum xs:int The page number of the requested log page.
JobRunStatus 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 Cloud Integration for data services WSDL.
Related Information
Web Services Guide

4.2.5 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 23: executedTaskFilterRequest elements

taskName xs:string Optional. The name of the task that should be executed.
startDate Optional. The start date of the range for which task execu
tions should be returned, specified using the XML Schema
dateTime format.
For example: 2015-03-20T18:30:00Z
Use "from" and "to" to filter for a range of start dates. For ex
ample, to filter for tasks that have started over a 7-day pe
riod without regard to if they have completed (UTC time
zone):
<startDate>
<from>2016-04-22T18:30:00Z</from>
<to>2016-04-29T18:30:00Z</to>
</startDate>
endDate Optional. The end date of the range for which task execu
dateTime 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.
Use "from" and "to" to filter for a range of end dates. For ex
ample, to filter for tasks that have completed over a 7-day
period without regard to when they started (UTC time zone):
<endDate>
<from>2016-04-22T18:30:00Z</from>
<to>2016-04-29T18:30:00Z</to>
</endDate>
Web Services Guide

statusCode tns:JobRunStatus Optional. The status of the task executions to return. Possi
ble values:

nated successfully.
ecution requests.
Considerations for filtering on startDate and endDate:
• When you do not specify any input filter options, all task executions from the past seven days are returned
• Filtering can be based on startDate, endDate, or both
• When the range is specified as “from” and “to”, the maximum range is 90 days
• startDate and endDate are independent of each other and act as an “AND” operator
• The “from” field is required if a startDate or endDate is specified
• Time is based on the Gregorian calendar format and, by default, uses the time zone where the server is
running. To query the time based on UTC timezone, specify “Z” at the end of the time. For example:
<startDate>
<from>2015-11-26T18:30:00Z</from>

<to>2015-11-29T18:30:00Z</to>
</startDate>
Web Services Guide

Response message
Table 24: executedTaskResponse elements

runId xs:int A unique ID that identifies the specific execution instance for
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
unique task execution.
• taskName: The name of the task executed.
For more information about the structure of the getAllExecutedTasks request and response messages,
* Any software coding and/or code snippets are examples. They are not for
productive use. The example code is only intended to better explain and visualize
the syntax and phrasing rules. SAP does not warrant the correctness and
completeness of the example code. SAP shall not be liable for errors or damages
caused by the use of example code unless damages have been caused by SAP's gross
negligence or willful misconduct.
Related Information
4.2.6 getAllExecutedTasks2
The getAllExecutedTasks2 operation returns a list of tasks that are currently running or already executed
from Run Now, a task schedule, or web services. The GetAllExecutedTasks2 operation includes the option
to return status codes TASK:SUCCESS_WITH_ERRORS_D and TASK:SUCCESS_WITH_ERRORS_E, which are not
available in the getAllExecutedTasks operation.
Web Services Guide

 Note
In the SAP Cloud Integration for data services user interface, in the task execution properties you can
define when you want the post-processing to occur and how SAP Cloud Integration for data services
reports post-processing errors.
Task that successfully loads data,

State of “Treat ‘Processed with Er but has post-processing errors com
ror’ as success” checkbox pletes as: Web services status
Selected TASK:SUCCESS_WITH_ERRORS_
Success
D
Deselected (cleared) TASK:SUCCESS_WITH_ERRORS_

Failure
E
Request message
Table 25: executedTaskFilterRequest elements

taskName xs:string Optional. The name of the task that should be executed.
version xs:string Available values: 1.0, 2.0.
Use 2.0 to return TASK:SUCCESS_WITH_ERRORS_D

and TASK:SUCCESS_WITH_ERRORS_E status codes.
startDate Optional. The start date of the range for which task execu
dateTime format.
For example: 2015-03-20T18:30:00Z
Use "from" and "to" to filter for a range of start dates. For ex
ample, to filter for tasks that have started over a 7-day pe
riod without regard to if they have completed (UTC time
zone):
<startDate>
<from>2016-04-22T18:30:00Z</
from>
<to>2016-04-29T18:30:00Z</to>
</startDate>
Web Services Guide

endDate Optional. The end date of the range for which task execu
dateTime 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.
Use "from" and "to" to filter for a range of end dates. For ex
ample, to filter for tasks that have completed over a 7-day
period without regard to when they started (UTC time zone):
<endDate>
<from>2016-04-22T18:30:00Z</
from>
<to>2016-04-29T18:30:00Z</to>
</endDate>
statusCode tns:JobRunStatus Optional. The status of the task executions to return. Possi
ble values:

• TASK:SUCCESS_WITH_ERRORS_D: Task was suc
cessful despite IBP post-processing errors.
• TASK:SUCCESS_WITH_ERRORS_E: Task completed
with errors if the run contains IBP post-processing er
rors.
nated successfully.
ecution requests.
Considerations for filtering on startDate and endDate:
• When you do not specify any input filter options, all task executions from the past seven days are returned
• Filtering can be based on startDate, endDate, or both
• When the range is specified as “from” and “to”, the maximum range is 90 days
Web Services Guide

• startDate and endDate are independent of each other and act as an “AND” operator
• The “from” field is required if a startDate or endDate is specified
• Time is based on the Gregorian calendar format and, by default, uses the time zone where the server is
running. To query the time based on UTC timezone, specify “Z” at the end of the time. For example:
<startDate>
<from>2015-11-26T18:30:00Z</from>

<to>2015-11-29T18:30:00Z</to>
</startDate>
Response message
Table 26: executedTaskResponse elements

runId xs:int A unique ID that identifies the specific execution instance for
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
unique task execution.
• taskName: The name of the task executed.
For more information about the structure of the getAllExecutedTasks request and response messages,
* Any software coding and/or code snippets are examples. They are not for
productive use. The example code is only intended to better explain and visualize
the syntax and phrasing rules. SAP does not warrant the correctness and
completeness of the example code. SAP shall not be liable for errors or damages
caused by the use of example code unless damages have been caused by SAP's gross
negligence or willful misconduct.
Related Information
Post-Processing for SAP Integrated Business Planning

Web Services Guide

4.2.7 searchTasks
The searchTasks operation returns all tasks and/or processes whose name matches the pattern.
Request message
Table 27: searchTasksRequest elements

nameFilter xs:string Name filter used for the search, in this example, look for all
tasks or processes that contains the specified text in the
name.
Response message
Returns a list of tasks. Each task of the list entry has the following details.
Table 28: searchTasksResponse elements

taskName xs:string Name of the task or process.
description xs:string Description of the task or process.
taskGuid xs:string Unique ID of the task or process, which is used in follow-up

calls.
type tns:ObjectType Possible values:
• TASK
• PROCESS
For more information about the structure of the searchTasks request and response messages, refer to the
SAP Cloud Integration for data services WSDL.
Related Information
Web Services Guide

4.2.8 getAgents
The getAgents operation lists all the agents and agent groups in the defined hierarchy.
Request message
Table 29: getAgentsRequest elements

activeOnly xs:string When true, lists only the connected agents.
Response message
Response lists all the agent groups and agents belonging to each AgentGroup.
Table 30: getAgentResponse AgentGroup elements

name xs:string Agent name.
guid xs:string Agent unique ID.
description xs:string Description of the agent group.
agents tns:agents List of agents belonging to this group.
Table 31: <agent> elements

name xs:string Agent name.
guid xs:string Agent unique ID.
description xs:string Description of the agent.
lastConnected xs:string Last connected time stamp.
version xs:string Agent version.
agentStatus tns:agentStatus Status of the agent. The status of the last execution. Possi
ble values:
• AGENT:NOT_CONNECTED
• AGENT:CONNECTED
• AGENT:MAINTENANCE
For more information about the structure of the getAgent request and response messages, refer to the SAP
Web Services Guide

4.2.9 getSystemConfigurations
Returns a list of system configuration objects.
Request message
No input elements needed.
Response message
Table 33: SystemConfigurationsResponse

name xs:string Name of the system configuration.
guid xs:string Unique ID of the system configuration.
description tns: List of data store configurations (see table below).

dsConfigurations
Table 34: dsConfigurations: DataStore Configuration details

dataStoreName xs:string Name of the datastore
dataStoreConfiguration- xs:string Unique ID of the datastore configuration.

Name
For more information, refer to the SAP Cloud Integration for data services WSDL.
4.2.10 getProjects
Provides the ability to browse all projects. Returns a list of all projects.
Request message
No input elements needed.
Web Services Guide

Response message
Table 36: getProjectsResponse elements

name xs:string Project name.
guid xs:string Project unique ID.
description xs:string Project description.
4.2.11 getProjectTasks
Given the project's unique ID, returns all tasks or processes in the project.
Request message
Table 37: ProjectTasksRequest elements

projectGuid xs:string Unique ID of the project, returned by getProjects call.
Response message
Table 38: ProjectTasksResponse elements

taskName xs:string Name of the task or process.
description xs:string Description of the task or process.
taskGuid xs:string Unique ID of the task or process, which is used in follow-up

calls.
type xs:string Type of the task: TASK or PROCESS.
Web Services Guide

4.2.12 getTaskInfo
Given the task's unique ID, returns task execution information, include global variables, execution properties,
and so on.
Request message
Table 39: TaskInfoRequest elements

taskGuid xs:string Unique ID of the task or process, returned with searchTask

or getProjectTasks call.
Response message
The response contains information required to run the task, including global variables and key execution
properties.
Table 40: TaskInfoResponse elements

taskName xs:string Name of task or process.
taskGuid xs:string Unique ID of the task or process.
description xs:string Description of global variable.
type tns:ObjectType Valid values are:
• TASK
• PROCESS
globalVariables tns:globalVariables Maximum length of the variable.
properties tns:properties Precision of the variable.
Some tasks or processes involve many global variables, and at run time, some of those global variables need an
overwritten value. Providing the list of global variables with their details can greatly simplify the web service
client work.
Table 41: Global Variables

Collection of global variables needed to run the task
name xs:string Name of global variable.
description xs:string Description of global variable.
Web Services Guide

dataType tns:DataType Data type of the global variable. Valid values are:
• REAL
• FLOAT
• DOUBLE
• BYTE
• SMALL
• INTEGER
• DECIMAL
• NUMERIC
• FIXBSTR
• FIXCSTR
• VARBSTR
• VARCSTR
• VARLONG
• DATE
• TIME
• INTERVAL
• TIMESTAMP
• VOID
• FUNCSTRUCTIN
• FUNCSTRUCTOUT
• FUNCTABLE
• LONG
• MS_REAL
• TIMESTAMP2
• VARBINARY
• FUNCNUM_TYPE
• FUNCCHAR_TYPE
• NFIXCSTR
• NVARCSTR
• FUNCCOL_TYPE
• FUNCDS_TYPE
• NUMMTERM_VARCSTR
• DECIMAL_STR
• NRDM_TYPE
• PTR
• NLONG
• BLONG
• FUNCANY_TYPE
• UNKNOWN
length xs:string Maximum length of the variable.
precision xs:string Precision of the variable.
Web Services Guide

scale xs:string Scale of the variable.
defaultValue xs:string Default value of the variable.
Table 42: Properties

Collection of execution properties.
Four properties related to IBP postprocessing are exposed:
• Status check duration (hours).

• "Processed with error" status indicates a success data flow completion.
• Begin postprocessing after task or process is completed.
• Begin postprocessing after each data flow is completed.
name xs:string Unique name of the execution property.
value xs:string Current value of the execution property.
caption xs:string Caption of the property.
4.2.13 cancelTask
The cancelTask operation cancels the execution of a task or process, if execution is not finished yet.
Request message
Table 43: cancelTaskRequest elements

runId xs:string A unique ID that identifies the specific execution instance for
the task or process.
Web Services Guide

Response message
Table 44: cancelTaskResponse elements

status tns:CancelTaskStatu Possible values:

s
• TASK_NOT_STARTED
• TASK_FINISHED
• TASK_CANCEL_ISSUED
message xs:string Detailed description of the return status.
For more information about the structure of the cancelTask request and response messages, refer to the SAP
Related Information
Web Services Guide

5 Error Reporting
In addition to the output message for each web services operation, SAP Cloud Integration for data services
returns a fault message when an error occurs.
Fault message
Table 45: WebFaultException elements

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 Guide

36 PUBLIC Error Reporting
Important Disclaimers and Legal Information
Hyperlinks
Some links are classified by an icon and/or a mouseover text. These links provide additional information.
About the icons:
• Links with the icon : You are entering a Web site that is not hosted by SAP. By using such links, you agree (unless expressly stated otherwise in your
agreements with SAP) to this:
• The content of the linked-to site is not SAP documentation. You may not infer any product claims against SAP based on this information.
• SAP does not agree or disagree with the content on the linked-to site, nor does SAP warrant the availability and correctness. SAP shall not be liable for any
damages caused by the use of such content unless damages have been caused by SAP's gross negligence or willful misconduct.
• Links with the icon : You are leaving the documentation for that particular SAP product or service and are entering a SAP-hosted Web site. By using such
links, you agree that (unless expressly stated otherwise in your agreements with SAP) you may not infer any product claims against SAP based on this
information.
Videos Hosted on External Platforms

Some videos may point to third-party video hosting platforms. SAP cannot guarantee the future availability of videos stored on these platforms. Furthermore, any
advertisements or other content hosted on these platforms (for example, suggested videos or by navigating to other videos hosted on the same site), are not within
the control or responsibility of SAP.
Beta and Other Experimental Features

Experimental features are not part of the officially delivered scope that SAP guarantees for future releases. This means that experimental features may be changed by
SAP at any time for any reason without notice. Experimental features are not for productive use. You may not demonstrate, test, examine, evaluate or otherwise use
the experimental features in a live operating environment or with data that has not been sufficiently backed up.
The purpose of experimental features is to get feedback early on, allowing customers and partners to influence the future product accordingly. By providing your
feedback (e.g. in the SAP Community), you accept that intellectual property rights of the contributions or derivative works shall remain the exclusive property of SAP.
Example Code
Any software coding and/or code snippets are examples. They are not for productive use. The example code is only intended to better explain and visualize the syntax
and phrasing rules. SAP does not warrant the correctness and completeness of the example code. SAP shall not be liable for errors or damages caused by the use of
example code unless damages have been caused by SAP's gross negligence or willful misconduct.
Bias-Free Language
SAP supports a culture of diversity and inclusion. Whenever possible, we use unbiased language in our documentation to refer to people of all cultures, ethnicities,
genders, and abilities.
Web Services Guide

Important Disclaimers and Legal Information PUBLIC 37
www.sap.com/contactsap
© 2022 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 https://www.sap.com/about/legal/trademark.html for

additional trademark information and notices.
THE BEST RUN

Web Services en

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Web Services en

Uploaded by

Copyright:

Available Formats

PUBLIC

SAP Cloud Integration for data services 1.0.11

Web Services Guide

THE BEST RUN

2 Web Services Technologies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Accessing the WSDL File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2.3 XML Schema. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

3 Creating a Client to Use Web Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

4 Supported Web Service Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

4.1 Connection Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

4.2 Project Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Web Services Guide

Web Services Guide

SOAP Connection protocol (envelope for XML messages)

WSDL XML-based language used describe published web services

XML Schema Format used for the WSDL file

Web Services Guide

definition Root element.

portType Defines a set of operations that a web service publishes.

Accessing the WSDL File [page 5]

2.2.1 Accessing the WSDL File

Web Services Guide

2.3 XML Schema

Web Services Guide

Accessing the WSDL File [page 5]

Web Services Guide

Connection Operations [page 8]

4.1 Connection Operations

The software supports the following Connection operations:

logon Verifies secure access and establishes a web services session.

logoff Terminates an existing web services session.

Web Services Guide

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

Table 1: ping elements

Table 2: pingResponse elements

Accessing the WSDL File [page 5]

Web Services Guide

Table 3: logonRequest elements

isProduction xs:boolean Specifies whether to log in to the production or sandbox re­

Default value: false

Table 4: logonResponse elements

The session ID is valid only for the specified repository type.

By default, the session will expire and become invalid after

Additionally, if the user or organization associated with the

Web Services Guide

Table 5: HTTP headers

Authorization Basic The authentication type and the base64-encoded value of

SOAPAction function=logon The SOAP action to perform.

Web Services Guide

isProduction xs:boolean Specifies whether to log in to the production or sandbox re­

Default value: false

Accessing the WSDL File [page 5]

Table 7: logout elements

Table 8: logoutResponse elements

Web Services Guide

Accessing the WSDL File [page 5]

4.2 Project Operations

The software supports the following Project operations:

runTask Executes a task and returns a run ID.

searchTasks Returns all tasks whose name matches the pattern.

getSystemConfigurations Returns a list of profiles and system configurations.

Web Services Guide

Integration developer Yes No

isProduction xs:boolean Specifies whether to log in to the production or sandbox re

isProduction xs:boolean Specifies whether to log in to the production or sandbox re

id xs:string IBP batch ID to identify the postprocessing execution (for ex

id xs:string IBP batch ID to identify the postprocessing execution (for ex

If the page number is not specified or is larger than the maxi

If no end date is specified, the range of task executions re