ds 42 integrate en

PUBLIC
SAP Data Services
Document Version: 4.2 Support Package 6 (14.2.6.0) – 2015-11-19
Integrator Guide
Content
1
Welcome to SAP Data Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1
Welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.2
Documentation set for SAP Data Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.3
Accessing documentation from the Web. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.4
SAP information resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
2
Web service support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.1
Web services technologies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
SOAP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
REST web service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3
Using SAP Data Services as a web service provider. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.1
WSDL basics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Building a WSDL file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Tips for using the WSDL file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
WSDL versions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
3.2
Creating a client to use web services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Design choices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
3.3
Supported web service operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Connection port. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Realtime_Service_Admin port. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Batch_Job_Admin port. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Real-time_Services port. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Batch_Jobs port. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Repo_Operations port. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58
3.4
Enabling SSL support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Configuring SSL on the web application server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
3.5
Error reporting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Administrator log. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Web service log. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Error messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Failed Request log. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
4
Consuming external web services in SAP Data Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
4.1
Accessing a web service using the Designer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
4.2
Adding web service calls to a job. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
4.3
Configuring HTTP header fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74
Configuring standard HTTP header fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
2
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Content
Configuring dynamic HTTP header fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
4.4
Enabling SSL support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
Configuring SSL on the native web service datastore. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Configuring SSL in the runtime execution file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
4.5
Enabling WS-Security support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Configuring WS-Security on the native web service datastore. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
5
Using the operational statistics API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78
5.1
Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78
6
Using the Message Client API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
6.1
Interface components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
6.2
Creating the connection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
6.3
Sending messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
6.4
Closing the connection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
6.5
Pseudo code example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
6.6
C++ API reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Class RTServiceClient. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82
Class RTServiceClientError. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
6.7
Java API reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
Class RTServiceClient. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
7
Object creation XML toolkit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
7.1
Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
7.2
Using the toolkit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Templating objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Exporting objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Adapting objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Using web services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Encrypting passwords. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Best practices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Limitations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
7.3
XML schema reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91
Batch job. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
work flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
data flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Script. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
File format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Database datastore. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103
Database table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Data Quality transforms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Query transform. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Integrator Guide
Content
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
3
Parameters and variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Basic example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
8
Job launcher execution commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
9
Legacy adapter information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
9.1
Legacy adapter for external web services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Legacy adapter installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Legacy adapter configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Configuring SSL with the legacy adapter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Legacy adapter error messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
4
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Content
1
Welcome to SAP Data Services
1.1
Welcome
SAP Data Services delivers a single enterprise-class solution for data integration, data quality, data profiling, and
text data processing that allows you to integrate, transform, improve, and deliver trusted data to critical business
processes. It provides one development UI, metadata repository, data connectivity layer, run-time environment,
and management console—enabling IT organizations to lower total cost of ownership and accelerate time to
value. With SAP Data Services, IT organizations can maximize operational efficiency with a single solution to
improve data quality and gain access to heterogeneous sources and applications.
1.2
Documentation set for SAP Data Services
Become familiar with all the pieces of documentation that relate to your SAP Data Services product.
The latest Data Services documentation can be found on the SAP Help Portal.
Table 1:
Document
What this document provides
Adapter SDK Guide
Information about installing, configuring, and running the Data Services Adapter SDK .
Administrator Guide
Information about administrative tasks such as monitoring, lifecycle management, security,
and so on.
Customer Issues Fixed
Information about customer issues fixed in this release.
Note
In some releases, this information is displayed in the Release Notes.
Designer Guide
Information about how to use Data Services Designer.
Documentation Map
Information about available Data Services books, languages, and locations.
Installation Guide for UNIX
Information about and procedures for installing Data Services in a UNIX environment.
Installation Guide for Win­
dows
Information about and procedures for installing Data Services in a Windows environment.
Integrator Guide
Information for third-party developers to access Data Services functionality using web services
and APIs.
Management Console Guide
Information about how to use Data Services Administrator and Data Services Metadata
Reports.
Integrator Guide
Welcome to SAP Data Services
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
5
Document
What this document provides
Master Guide
Information about the application, its components and scenarios for planning and designing
your system landscape. Information about SAP Information Steward is also provided in this
guide.
Performance Optimization
Guide
Information about how to improve the performance of Data Services.
Reference Guide
Detailed reference material for Data Services Designer.
Release Notes
Important information you need before installing and deploying this version of Data Services.
Technical Manuals
A compiled, searchable, “master” PDF of core Data Services books:
●
Administrator Guide
●
Designer Guide
●
Reference Guide
●
Management Console Guide
●
Performance Optimization Guide
●
Integrator Guide
●
Supplement for Adapters
●
Supplement for Google BigQuery
●
Supplement for J.D. Edwards
●
Supplement for Oracle Applications
●
Supplement for PeopleSoft
●
Supplement for SAP
●
Supplement for Siebel
●
Workbench Guide
Text Data Processing Extrac­ Information about building dictionaries and extraction rules to create your own extraction pat­
tion Customization Guide
terns to use with Text Data Processing transforms.
Text Data Processing Lan­
guage Reference Guide
Information about the linguistic analysis and extraction processing features that the Text Data
Processing component provides, as well as a reference section for each language supported.
Tutorial
A step-by-step introduction to using Data Services.
Upgrade Guide
Information to help you upgrade from previous releases of Data Services and release-specific
product behavior changes from earlier versions of Data Services to the latest release.
What's New
Highlights of new key features in this SAP Data Services release. This document is not updated
for support package or patch releases.
Workbench Guide
Provides users with information about how to use the Workbench to migrate data and database
schema information between different database systems.
In addition, you may need to refer to several Supplemental Guides.
Table 2:
Document
What this document provides
Supplement for Adapters
Information about how to install, configure, and use Data Services adapters.
Supplement for Google BigQuery
Information about interfaces between Data Services and Google BigQuery.
Supplement for J.D. Edwards
Information about interfaces between Data Services and J.D. Edwards World and J.D.
Edwards OneWorld.
Supplement for Oracle Applications
Information about the interface between Data Services and Oracle Applications.
6
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Welcome to SAP Data Services
Document
What this document provides
Supplement for PeopleSoft
Information about interfaces between Data Services and PeopleSoft.
Supplement for SAP
Information about interfaces between Data Services, SAP Applications, and SAP Net­
Weaver BW.
Supplement for Siebel
Information about the interface between Data Services and Siebel.
We also include these manuals for information about SAP BusinessObjects Information platform services.
Table 3:
Document
What this document provides
Information platform services Administrator Guide
Information for administrators who are responsible for config­
uring, managing, and maintaining an Information platform
services installation.
Information platform services Installation Guide for UNIX
Installation procedures for SAP BusinessObjects Information
platform services on a UNIX environment.
Information platform services Installation Guide for Windows
Installation procedures for SAP BusinessObjects Information
platform services on a Windows environment.
1.3
Accessing documentation from the Web
You can access the complete documentation set for SAP Data Services from the SAP Business Users Support
site.
To do this, go to http://help.sap.com/bods.
You can view the PDFs online or save them to your computer.
1.4
SAP information resources
A list of information resource links.
A global network of SAP technology experts provides customer support, education, and consulting to ensure
maximum information management benefit to your business.
Useful addresses at a glance:
Table 4:
Address
Content
Customer Support, Consulting, and Education services
Information about SAP Business User Support programs, as
well as links to technical articles, downloads, and online dis­
cussions.
http://service.sap.com/
Integrator Guide
Welcome to SAP Data Services
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
7
Address
Content
Product documentation
SAP product documentation.
http://help.sap.com/bods/
SAP Data Services tutorial
http://help.sap.com/businessobject/product_guides/
sbods42/en/ds_42_tutorial_en.pdf
SAP Data Services Community Network
http://scn.sap.com/community/data-services
EIM Wiki page on SCN
http://wiki.sdn.sap.com/wiki/display/EIM/EIM+Home
Supported Platforms (Product Availability Matrix)
https://service.sap.com/PAM
Blueprints
http://scn.sap.com/docs/DOC-8820
8
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Introduces core features, concepts and techniques to extract,
transform, and load batch data from flat-file and relational da­
tabase sources for use in a data warehouse.
Get online and timely information about SAP Data Services,
including forums, tips and tricks, additional downloads, sam­
ples, and much more. All content is to and from the commun­
ity, so feel free to join in and contact us if you have a submis­
sion.
The means with which to contribute content, post comments,
and organize information in a hierarchical manner to so that
information is easy to find.
Information about supported platforms for SAP Data Services
with a search function to quickly find information related to
your platform.
Blueprints for you to download and modify to fit your needs.
Each blueprint contains the necessary SAP Data Services
project, jobs, data flows, file formats, sample data, template
tables, and custom functions to run the data flows in your en­
vironment with only a few modifications.
Integrator Guide
Welcome to SAP Data Services
2
Web service support
Web services are modular business applications based on open standards (WSDL, REST, SOAP, and XML Schema
primarily) that allow integration among different applications and environments through the Internet. Web
services allow parts of existing applications to be used by other applications.
Administrators can configure SAP Data Services through the Administrator to publish jobs as callable web
services and then application developers can access those web services.
The software publishes web services from the Management Console Administrator. To use SAP Data Services as
a web service, select the Web Services node in the Administrator's navigation tree.
For general information on using the Administrator, see the Management Console Guide.
For business intelligence (BI), you can use web services to accomplish the following:
● Access legacy systems
● Conduct computer-to-computer interaction over an internal or external web
● Allow applications constructed in different languages on different platforms to communicate with each other
in an enterprise environment
SAP Data Services can:
● Publish any job as a callable web service (server functionality)
● Call published web services from within its jobs using the built-in web services datastore (client functionality)
If you have an application that also supports web services, you can use that application to run batch and real-time
jobs or to publish your application's functionality to be called by data flows.
After you install the software, you can immediately start working with its client functionality because the built-in
web services datastore is a web services client that provides access to a web services server from a data flow.
Related Information
Using SAP Data Services as a web service provider [page 15]
Consuming external web services in SAP Data Services [page 70]
2.1
Web services technologies
SAP Data Services web services are fully compliant with Web Services Interoperability (WS-I) Basic Profile 1.0,
and support three Java Web Services technologies.
Integrator Guide
Web service support
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
9
Table 5:
Web service technology
Description
SOAP
Connection protocol (envelope for XML messages).
WSDL
Language used to request a service and return replies (subset of XML).
XML Schema
Format used for the WSDL file.
The software supports SOAP 1.1, WSDL version 1.1, 2.0 and 2.1, and Apache Axis 1.1 (an industry-standard SOAP
message handler and WSDL parser).
SAP Data Services is also compliant with the Microsoft .NET environment for web services. You can import the
WSDL that the software generates into Visual Studio .NET and the web services datastore can call the WSDL that
Visual Studio .Net generates.
SAP Data Services also supports the following for REST web services:
Table 6:
Web service technology
Description
REST
Design pattern based on HTTP connection protocol.
WADL
Language used to describe the request and response for a web provider.
XML Schema
Schema used to describe the input and output for a web service operation.
JSON/XML
Message format used by web services to communicate with a client.
Note
Currently, SAP Data Services only supports consuming external REST web service providers (for example,
outbound web calls allowing you to call a provider). The software does not expose REST web service operations
(for example, inbound web calls allowing you to access SAP Data Services).
Related Information
SOAP [page 10]
REST web service [page 12]
2.1.1 SOAP
SOAP is a connection protocol (envelope for XML messages).
SAP Data Services allows you to invoke real-time services using the following:
● Message Client API (which supports C++ and Java connections)
● TCP/IP
● proprietary XML using HTTP
10
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Web service support
In addition, the software supports the Simple Object Access Protocol (SOAP). SOAP is the industry standard from
the World Wide Web Consortium (WC3.org) used to invoke network resources using XML over HTTP, HTTPS, and
other standard protocols.
A SOAP gateway is built in to the Administrator. The software supports SOAP over HTTP and HTTPS protocols.
2.1.1.1
WSDL
Web Services Description Language (WSDL) is a subset of XML. It is used as a transport mechanism for XML
messages.
SAP Data Services publishes its jobs in WSDL based on configuration settings applied in the Administrator, and
then developers can create a web services client based on the software's WSDL.
The software also publishes all comments entered into the Designer's Job Descriptions box with each job that is
added to the WSDL file.
The WSDL file generated by the software includes tags (such as services, bindings, ports, and operations) that
support the use of the SOAP protocol. Each tag uses a name that the software provides. For example:
● You select which jobs to publish in the web service named DataServices_server. In WSDL, a service is a
set of business operations with connection endpoints.
● Binding names include Connection_Operations, Batch_Jobs, Real-time_Services, and
Batch_Job_Admin. WSDL uses bindings to associate operations with ports.
● Operation names have a one-to-one relationship with the names of batch jobs or real-time services.
2.1.1.2
XML Schema
WSDL uses XML Schemas to define input and output message formats.
● For server functionality, if a real-time service was defined with DTDs, you will need to translate the DTD
format into the XML Schema format.
● For client functionality, the web services datastore imports metadata into SAP Data Services using the XML
Schema format only.
XML Schema formats are defined in the types element of the WSDL file.
Note
When you import an XML schema for a real-time web service job, you should use a unique target namespace
for the schema. When Data Services generates the WSDL file for a real-time job with a source or target schema
that has no target namespace, it adds an automatically generated target namespace to the types section of the
XML schema. This can reduce performance because Data Services must suppress the namespace information
from the web service request during processing, and then reattach the proper namespace information before
returning the response to the client.
Integrator Guide
Web service support
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
11
2.1.1.3
UDDI
UDDI is a method of publishing comments and other reference information about jobs to an external web site.
SAP Data Services does not publish information to a UDDI web site because most web service users work behind
enterprise firewalls.
2.1.2 REST web service
Representational State Transfer (REST or RESTful) web service is a design pattern for the World Wide Web. Data
Services allows you to call a REST server and then browse through and use the data the server returns.
Unlike SOAP, which exposes functions, REST exposes resources (data). The REST web services supports JSON
and XML data types.
Each function in REST web service uses a unique endpoint uniform resource identifier (URI). Data Services strictly
requires each function to have a fixed schema defined by XSD (XML Schema Definition). Based on HTTP verbs,
Data Services is then able to get or modify resources. Some of the more common HTTP verbs include GET
(retrieves data), PUT (updates data), POST (creates new data), and DELETE (deletes data).
Note
Data Services does not support the HEAD HTTP verb. It does not expose header outputs in the Query
transform.
In order to call the REST web service through Data Services, you need to provide a Web Application Description
Language (WADL) file. This XML file describes methods and input and output schemas and provides Data
Services with all the required parameters it needs to call REST functions.
Data Services allows you to do the following:
● Create a Web Services REST datastore. The datastore exposes functions that Data Services uses to call the
server through HTTP communication.
● Parse the WADL file to expose REST functions.
● Browse a Web Services REST datastore to find and import functions.
● Use REST functions in a Query transform.
● Use JSON or XML as input and output for REST functions.
● Consume REST web services (outbound only) from the engine.
For more information, see "Web service datastores" in the Designer Guide.
Related Information
Authorization schemas for REST [page 13]
WADL [page 13]
HTTP Status Codes [page 14]
Consuming external web services in SAP Data Services [page 70]
12
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Web service support
2.1.2.1
Authorization schemas for REST
Data Services supports several REST authorization schemas. You must have knowledge of the provider to which
you are connecting in order to obtain some configuration information, such as the consumer key.
● Basic
● Basic + CSRF (Cross-Site Request Forgery protection)
● Authorization Header (Custom Token, API key, and so on)
● OAuth 1.0 (2-legged)
● OAuth 2.0 (2-legged)
Note
For OAuth 2.0 based authentication, Data Services only supports client_credentials and password-based grant
types. Data Services does not support the 3-legged model.
2.1.2.2
WADL
A WADL file contains language used to describe the request and response for a web provider. You must provide
Data Services with a well-organized WADL file.
This file should follow the schema provided by the World Wide Web Consortium (WC3.org) at http://
www.w3.org/Submission/wadl/wadl.xsd . There are various third party tools that you can use to create and
edit this file.
The file should contain a Grammars element, which provides the location for input and output schemas. Data
Services can then parse elements and store them in an internal repository for browsing and exposing operations.
A WADL file contains many components. The following table explains some of the more common elements of the
schema:
Table 7:
Element
Description
Application
Forms the root of the WADL file and contains all the resources.
Doc
Describes an element. If provided in the param element, this information will be displayed as the func­
tion description in the Designer user interface.
Grammars
Provides the external location for input and output schemas.
Resources
Contains a list of resources.
Resource
Defines a unique URI.
Method
Defines the HTTP verb for selected resource.
Representation
Indicates the content type and respective element defined in grammar.
Param
Contains parameters that form a part of the URI or header.
Integrator Guide
Web service support
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
13
2.1.2.3
HTTP Status Codes
HTTP Status Codes are standard response codes that a server returns to help you identify the cause of a problem.
An HTTP Status Code of 200 OK is the correct response (for example, the XML/JSON document matches the
schema output schema) and is considered a success. An HTTP Status Code greater than or equal to 400 is
considered an error and Data Services populates the AL_ERROR_MSG column with a server error message.
● AL_ERROR_NUM — returns error codes: 0 for success and a non-zero integer for failures
● AL_ERROR_MSG — returns an error message if AL_ERROR_NUM is not 0. Returns NULL if AL_ERROR_NUM
is 0
Table 8: Error codes for AL_ERROR_NUM column
Error code
Description
0
The call was successful and the server returned a 200 OK status.
1
NRDM to XML/JSON conversion failed. The engine was unable to successfully create the message pay­
load. This can be caused by an invalid character in the input, and so on.
2
XML/JSON to NRDM conversion failed. Engine was unable to successfully convert the response pay­
load. Possible causes include:
3
4
14
●
invalid XML/JSON
●
server did not return a document that matches the schema (the engine requires the XML/JSON
document to exactly match the schema)
●
invalid characters (for example, control characters)
The call to the server failed. Possible causes include:
●
invalid URL
●
malformed URL
●
server does not exist
●
SSL certificate is missing
●
proxy or firewall does not allow Data Services to communicate with the URL
●
no internet communication
●
resource can't be found
●
lack of privileges to access the resource
An OAuth communication error. This error can be caused by all the items listed for error code 3, but are
related to only OAuth and OAuth errors.
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Web service support
3
Using SAP Data Services as a web service
provider
After the Administrator publishes batch or real-time jobs as web services, the web application hosts those web
services. When an external application calls into SAP Data Services through web services, the application acts as
a web services client accessing a web services server.
Web service clients call the published web services, pass in the appropriate parameters, and receive the results.
The software routes calls to the appropriate Job Server and job for processing.
Web services might be used in the following example scenarios:
● Dynamically update an internal web site
Suppose you have an internal web site that manages foreign exchange rate status worldwide for the Finance
department. When foreign exchange rates change more than a certain percentage, a batch job updates
exchange rates in your financial data mart. The rate change initiates a call to a web service that starts the
appropriate batch ETL job.
● Solve a processing issue
Suppose you have an existing Enterprise Application Integration (EAI) bus infrastructure and want to manage
batch processes and EAI transactional processes from within the same infrastructure. The transactional
processes are complex. Their staging is laid out in the order process. However, EAI work flows do not have the
ability to run batch processes.
The software can publish Web services that allow you to leverage EAI process management category tools
(for example, webMethods Business Process Manager) to control and stage batch processes alongside its
transactional processes.
The work flows might call the software to:
○ Perform an initial load of a data mart for real-time reporting
Integrator Guide
Using SAP Data Services as a web service provider
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
15
○ Refresh the data cache depending on specified business criteria
○ Perform complex transforms on hierarchical objects for mapping data between ERP systems
3.1
WSDL basics
WSDL is a subset of XML that you can use to describe network services as a collection of endpoints capable of
exchanging messages.
This table shows the elements in a WSDL file, and describes how those elements are used in the SAP Data
Services-generated WSDL file.
Table 9:
Element Name
Description
definition
Root element
service
Used to group a set of related ports or endpoints to which a client application will con­
nect. The software publishes a single service in the WSDL file it generates.
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 ports for
web services as:
●
Connection_Operations: used for authentication and ping
●
Real-time_Services: used for real-time jobs exposed as web services
●
Batch_Jobs: used for batch jobs exposed as web services (each batch jobs
has its own operation)
●
portType
Batch_Job_Admin: used for administrative operations for batch jobs
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 each batch job and real-time
service as an operation. It also publishes connection 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/from a web service.
Related Information
SoapAction element [page 57]
16
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Using SAP Data Services as a web service provider
3.1.1 Building a WSDL file
Use the information in the WSDL file produced by SAP Data Services to create an application that can access
batch jobs and real-time services. Access the WSDL file by making web service client calls to it using a reference
URL.
To view the WSDL file so that you can create your application, use the Web Services node of the Management
Console Administrator, or open a browser window and search for:
http://<hostname:port>/DataServices/servlet/webservices?ver=<version_number>&wsdlxml
If you are using WSDL labels, you can see a filtered view of the API by adding a label parameter to the end of the
URL:
http://<hostname:port>/DataServices/servlet/webservices?
ver=<version_number>&label=<label_name>&wsdlxml
Related Information
Using custom WSDL labels [page 21]
3.1.1.1
Configuring web service information using the
Administrator
SAP Data Services publishes its jobs in WSDL based on configuration settings applied in the Administrator, and
then developers can create a web services client based on the software's WSDL.
To configure web service information, do the following:
1. Open the Administrator.
2. Log in with Administrator-level privileges. Users with Monitor-level privileges cannot configure web services.
Note
If you enable security for the WSDL file, SAP Data Services requires that web services clients use the user
name and password of any user with Administrator-level privileges to access all published web services.
3. Add connections from Access Servers and repositories to view jobs in the Administrator.
4. If you plan to publish real-time jobs as web services, configure real-time jobs as real-time services.
The software publishes the following as web services:
○ Real-time services enabled as web service operations in the Administrator
○ Batch jobs enabled as web service operations in the Administrator
○ Connection Operations
○ Ping - Used to ping Web services
○ Logon and Logout - Security operations that provide controlled access to Web service operations (if
enabled).
Integrator Guide
Using SAP Data Services as a web service provider
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
17
5. In the Administrator's navigation tree, select Web Services.
The Web Services Status page opens. This page lists Web service operations that are published in the WSDL.
By default, only the Ping operation is automatically published.
6. Click the Web Services Configuration tab.
Use the Configuration tab to open the Web Services Configuration page. Use this page to select jobs and realtime services to be published, enable/disable security for the WSDL file, enable/disable access to full batch
job attributes, and enable/disable failed request logging.
7. From the pull-down menu, use Add Real-time Service or Add Batch Job to add jobs or services to the WSDL,
and click Apply.
On the Add Real-time Service page, real-time services are grouped by the Access Server for which the service
is configured. To add a real-time service to the WSDL, select an Access Server or select All, select the check
box in front of a real-time service name, and click Add.
On the Add Batch Job page, jobs are grouped by the repository on which the job is stored. To add a job to the
WSDL, select a repository or select All, select the check box in front of a job name, and click Add.
8. (Optional) On the Web Services Configuration page, select Enable Session Security and click Apply to enable
security for the WSDL.
Security for published operations is disabled by default.
With security enabled, instead of making a single call to the Administrator to start a batch job or trigger a realtime service from an external application, clients must make at least three calls:
○ The first call logs in to the Administrator and gets a session ID.
○ The second call accesses a job or service using the session ID as an input parameter. Create a call for
each job or service you want to access.
○ The final call logs out of the session.
9. (Optional) On the Web Services Configuration page, from the drop-down menu, select Enable Job Attributes to
allow the input message for all the batch jobs you publish to include all options supported for submitting
batch jobs from the Administrator. The following table lists elements added to the message:
Table 10:
18
Element
Description
job_system_profile
System profile used to run the job.
sampling_rate
Monitor sample rate (# of seconds).
auditing
Enable auditing (true or false).
recovery
Enable recovery (true or false).
job_server
Job Server or Server Group.
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Using SAP Data Services as a web service provider
Element
Description
trace
Trace option to be enabled. You must specify an option to enable tracing.
This element can be repeated for as many trace options as you require.
The WSDL defines values for the trace option and includes the following (all
options on the batch job submit page of the administrator):
distribution_level
○
job_trace_all
○
job_trace_row
○
job_trace_session
○
job_trace_workflow
○
job_trace_dataflow
○
job_trace_transform
○
job_trace_usertransform
○
job_trace_userfunction
○
job_trace_abapquery
○
job_trace_sqlfunctions
○
job_trace_sqlreaders
○
job_trace_sqlloaders
○
job_trace_optimized_dataflow
○
job_trace_table
○
job_trace_script
○
job_trace_ascomm
○
job_trace_rfc_function
○
job_trace_table_reader
○
job_trace_idoc_file
○
job_trace_adapter
○
job_trace_communication
○
job_trace_parallel_execution
○
job_trace_audit
You can distribute the execution of a job or a part of a job across multiple
Job Servers within a Server Group to better balance resource-intensive oper­
ations.
You can specify the following values on the distribution level option when you
execute a job:
○
Job: A job can execute on an available Job Server.
○
Data flow: Each data flow within a job can execute on an available Job
Server.
○
Sub data flow: A resource-intensive operation (such as a sort, table
comparison, or table lookup) within a data flow can execute on an avail­
able Job Server.
Note
Casing and spacing are important for these values.
Integrator Guide
Using SAP Data Services as a web service provider
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
19
10. Navigate back to the Web Services Status page, choose the WSDL version and the label name, and click View
WSDL. You can add a label in the Custom WSDL Labels tab.
A new browser window opens with the WSDL displayed. Use the information in this file to perform the
following:
○ Confirm that the software updated the WSDL file with all jobs and services without error.
○ Create calls to the software.
Use the information in the WSDL file to configure your application to access batch jobs and real-time
services.
To ensure that your application calls the latest version of the job, update the WSDL when the metadata
imported into the software changes for a job or real-time service by removing then re-adding a job or
service from the Web Services Configuration page.
11. After your web service clients are accessing jobs, you can monitor the status of web service operations on the
server by viewing the data on the Web Services Status page.
Table 11:
Column name
Description
Operation Name
Same as job or real-time service name.
Web Services Port
For jobs, the port name is Batch_jobs.
For services, the port name is Real-Time_Service.
For built-in operations, the port name is Connection_Operations.
For administrative operations for batch jobs, the port name is
Batch_Job_Admin.
Repository/ Access Server
For jobs, the repository name.
For services, the Access Server name.
Job Information
For jobs, a link to the Batch Job History page.
For services, a link to the Real-time Services History page.
Requests Processed
Number of client requests successfully processed.
Requests Failed
Number of client requests that failed somewhere between the time
that the Web Server receives the request and the Job Server receives
it.
Requests Pending
Number of requests in a queue for Job Server.
Jobs Failed
Number of requests that failed due to a problem with the Job Server.
Related Information
Using custom WSDL labels [page 21]
Failed Request log [page 68]
20
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Using SAP Data Services as a web service provider
3.1.1.2
Using custom WSDL labels
Labels allow you to create WSDL files with only a subset of the API exposed. This makes it easier for you to
manage your SOAP based applications.
You must have Administrator-level privileges to create, delete, and edit custom WSDL labels.
To work with WSDL labels, do the following:
1. Open the Administrator and click Web Services.
2. After configuring web service information, navigate to the Custom WSDL Labels tab.
3. In the Custom WSDL Labels tab, you can do the following:
○ Click on an existing label hyperlink to edit the list of operations you want exposed for that WSDL label.
○ Click Add to create a new label. In the Add Custom WSDL Label page, enter a label name and click Add.
Label names can be up to 16 characters in length, should be lowercase (the software forces uppercase to
lowercase), and cannot contain special characters other than periods (.), dashes (-), and underscores (_).
Spaces between words are not allowed and spaces around the name will be trimmed.
Choosing - default - from the Label Name drop-down in the Web Services Status page allows you to view a
WSDL file with the full API exposed.
○ Click Remove to delete one or more labels.
4. In the Web Services Configuration - Custom WSDL Label - <Label_Name> tab you can choose a subset of jobs
and services for a custom WSDL label.
This tab displays all the optional operations, including batch jobs and real-time service jobs.
5. Click Apply.
WSDL labels will display on the Add Custom WSDL Label page and in the Label drop-down on the Web Services
Status tab.
3.1.2 Tips for using the WSDL file
Web Services Description Language (WSDL) is a subset of XML. To make working with WSDL files a little easier,
we have provided you with some helpful tips.
The WSDL file:
● Appears in the View WSDL window or any browser window by searching for the following URL:
http://<hostname:port>/DataServices/servlet/webservices?
ver=<version_number>&wsdlxml
If you are using WSDL labels, you can see a filtered view of the API by adding a label parameter to the end of
the URL:
http://<hostname:port>/DataServices/servlet/webservices?
ver=<version_number>&label=<label_name>&wsdlxml
● Displays all real-time services and jobs enabled for web services in the Administrator.
● Only displays log on, log off, and session ID information when security is enabled.
● Displays XML Schema formats in the types element.
Integrator Guide
Using SAP Data Services as a web service provider
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
21
Related Information
Using custom WSDL labels [page 21]
3.1.3 WSDL versions
From time to time, the WSDL versions supported by SAP Data Services may change.
A change in versioning usually means improvements. For example, syntax may change in order to operate more
efficiently, or to add support for new technologies.
Although we typically maintain backward compatibility between WSDL versions, we recommend that you move to
the newest WSDL version available in your Data Services installation. The latest version often includes
improvements in web service execution, and older versions may be deprecated and no longer supported over
time.
For more information about the changes between specific WSDL versions, see the Upgrade Guide.
Version history
In general, a WSDL version is deprecated when the version of Data Services in which it was introduced is no longer
supported.
Table 12:
WSDL Version
Introduced
Deprecated
1.0
Original WSDL release
n/a
1.1
Data Integrator 11.5.0.0
n/a
2.0
Data Integrator 11.7.0.0
n/a
2.1
Data Services 12.2.1
n/a
3.2
Creating a client to use web services
To use a published web service, you must know the URL of the target WSDL. The Administrator produces a WSDL
file with this URL: http://<hostname:port>/DataServices/servlet/webservices?
ver=<version_number>&wsdlxml
If you are using WSDL labels, you can see a filtered view of the API by adding a label parameter to the end of the
URL:
http://<hostname:port>/DataServices/servlet/webservices?
ver=<version_number>&label=<label_name>&wsdlxml
The batch or real-time jobs must have previously been exposed as web services.
22
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Using SAP Data Services as a web service provider
This section discusses general steps for using a published SAP Data Services web service. 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.
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 environment.
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. A connection is made to the web services tier of the Access
Server.
The Access Server then sends information to various job servers, which then executes the al_engine process to
run the job, and results are sent back to the Web services client application.
Related Information
Using custom WSDL labels [page 21]
3.2.1 Design choices
SAP Data Services provides different ways that you can call jobs using web services, each with benefits and
drawbacks:
● Individually published job-specific web services (Batch_Jobs and Real-time_Services ports)
These web services have their schema published directly in the WSDL, and web service development tools
can automatically create classes that serialize and deserialize the input and output XML messages. However,
you need to create a separate operation for each published job.
● Generalized web services (Batch_Jobs_Admin and Realtime_Service_Admin ports)
These web services take a job name as input, but do not directly expose the input schema of the job. This
allows an application to dynamically call different jobs with one web service, but the schema must be known in
advance or generated dynamically with another web service call.
3.3
Supported web service operations
SAP Data Services creates 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.
Within the service definition, the software defines ports for:
● Connection_Operations
Integrator Guide
Using SAP Data Services as a web service provider
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
23
● Batch_Job_Admin
● Real-time_Services
● Batch_Jobs
● Repo_Operations
3.3.1 Connection port
SAP Data Services generates WSDL that defines connection operations that belong to web services. The software
supports the following Connection operations.
Table 13:
Operation
Description
Ping
Verifies the connection to web services
Logon
Verifies secure access before establishing a session
Logout
Terminates a session
Note
The software generates Logon and Logout operations only if you enable security for published jobs.
3.3.1.1
Ping
The Ping operation is an empty input message with a ping operation request. The output message is a text string
that returns the current SAP Data Services version, which indicates that a connection has been established.
3.3.1.2
Logon
The Logon operation is required when you enable SAP Data Services to provide secure communication. To access
web services, provide an Administrator login name and password (with Administrator-level privileges). When the
software validates them, the logon operation returns an Administrator session ID that you must include in all
subsequent calls to the web services.
24
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Using SAP Data Services as a web service provider
Input message
Table 14:
Element
Type
cms_authentica­ String
tion
Description
Specifies the type of authentication to use for logging on to a Data Services web service.
Values include:
●
secEnterprise: Use for Enterprise authentication
●
secLDAP: Use for LDAP authentication
●
secWinAD: Use for Windows Active Directory authentication
●
secSAPR3: Use for SAP authentication
cms_system
String
The CMS server name. If the CMS server is listening on the default 6400 port, then pass
only the CMS server name. If the server is listening on any other port, then also pass the
port number.
password
String
Password for the CMS user.
username
String
CMS user name.
Output message
Table 15:
Element
Type
Description
SessionId
String
A unique session ID is returned. Use this session ID in subsequent Data Services opera­
tions for which session security is enabled.
3.3.1.3
Logout
The Logout operation is required when you enable SAP Data Services to provide secure communication. When
web service communication is complete, call the Logout operation to terminate the session.
3.3.1.4
Validate_SessionID
Use Validate_SessionID to retrieve the status status code of the session ID.
Input message
Validate_SessionID takes no input message.
Integrator Guide
Using SAP Data Services as a web service provider
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
25
Output message
Table 16:
Element
Type
Description
Status
int
The SessionID status type.
●
0: SessionID is valid
●
1: SessionID is invalid
Example
SOAP request XML
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ser="http://www.businessobjects.com/DataServices/ServerX.xsd">
<soapenv:Header>
<ser:session>
<SessionID>69B89E79-34E3BBEF-18A4-979A8C73A0E5A84A6DA144C9B0DF5ED6D559E991E69D</SessionID>
</ser:session>
</soapenv:Header>
<soapenv:Body>
<ser:ValidateSessionIDRequest/>
</soapenv:Body>
</soapenv:Envelope>
Example
SOAP response XML
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<localtypes:ValidateSessionIDResponse xmlns:localtypes="http://
www.businessobjects.com/DataServices/ServerX.xsd">
<Status>0</Status>
</localtypes:ValidateSessionIDResponse>
</soapenv:Body>
</soapenv:Envelope>
3.3.2 Realtime_Service_Admin port
3.3.2.1
Get_AS_Info
Use Get_AS_Info to retrieve Access Server information.
Note
You must provide a valid repository and Job Server name. Data Services returns an error message if the
repository cannot be reached or if it does not exist.
26
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Using SAP Data Services as a web service provider
Input message
Get_AS_Info takes no input message.
Output message
Table 17:
Element
Type
Description
ASName
string
The name of the Access Server. For example,
<MachineName>: <port>.
MachineName
string
The name of the Access Server machine.
Port
string
The Access Server port.
UseSSLProtocol
string
Indicates if the Access Server uses SSL Protocol (Yes or No).
Status
string
The status of the Access Server (Valid or Invalid).
Example
SOAP request XML
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ser="http://www.businessobjects.com/DataServices/ServerX.xsd">
<soapenv:Header>
<ser:session>
<SessionID>69B89E79-34E3BBEF-18A4-979A8C73A0E5A84A6DA144C9B0DF5ED6D559E991E69D</SessionID>
</ser:session>
</soapenv:Header>
<soapenv:Body>
<ser:GetAccessServerInfoRequest/>
</soapenv:Body>
</soapenv:Envelope>
Example
SOAP response XML
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<localtypes:GetAccessServerInfoResponse xmlns:localtypes="http://
www.businessobjects.com/DataServices/ServerX.xsd">
<AccessServerInfo>
<AsName>10.193.245.97:4000</AsName>
<MachineName>10.193.245.97</MachineName>
<Port>4000</Port>
<UseSSLProtocol>No</UseSSLProtocol>
<Status>Valid</Status>
</AccessServerInfo>
</localtypes:GetAccessServerInfoResponse>
</soapenv:Body>
Integrator Guide
Using SAP Data Services as a web service provider
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
27
</soapenv:Envelope>
3.3.2.2
Get_RTMsg_Format
Use Get_RTMsg_Format to retrieve the input/output format for a real-time service as an XML Schema. The realtime service does not need to be published as a web service.
Input message
Table 18:
Element
Type
Description
serviceName
string
The name of the real-time service as displayed in the Adminis­
trator.
selector
string
A selector that determines whether the input or output
schema for the service is returned. Valid strings include:
●
in - Returns the input schema.
●
out - Returns the output schema.
Output message
Table 19:
Element
Type
Description
schema
string
The input or output XML Schema for the real-time service.
rootElement
string
The root element of the returned XML Schema.
rootElementNS
string
The root element namespace of the returned XML Schema.
schemaName
string
The name of a dependent schema used in the returned XML
Schema, if applicable. This element may be returned multiple
times.
schema
string
A dependent schema used in the returned XML Schema, if ap­
plicable. This element may be returned multiple times.
errorMessage
string
Any error message that resulted while retrieving the XML
Schema for the real-time service.
3.3.2.3
Get_RTService_Info
Use Get_RTService_Info to retrieve all the real-time services information.
28
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Using SAP Data Services as a web service provider
Note
You must provide a valid Access Server name. Data Services returns an error message if the Access Server
cannot be reached or if it does not exist.
Input message
Table 20:
Element
Type
Description
AccessServer
string
The name of the Access Server machine. For example,
<MachineName>: <port>.
Output message
Table 21:
Element
Type
Description
RTServiceName
string
The name of the real-time service associated with the Access
Server.
RTJobName
string
The name of real-time job in the real-time service.
StatusCode
int
Real-time service status type.
Valid value include:
StatusDescription
int
●
0 : Real-time service is initialized
●
1 : Real-time service is starting
●
2 : Real-time service is started
●
3 : Real-time service is shutting down
●
4 : Real-time service is warning
●
5 : Real-time service is error
●
6 : Real-time service is unavailable
The status code description.
Example
SOAP request XML
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ser="http://www.businessobjects.com/DataServices/ServerX.xsd">
<soapenv:Header>
<ser:session>
<SessionID>755D02EF-6984-131C-5316-AB1413B98CF2</SessionID>
</ser:session>
Integrator Guide
Using SAP Data Services as a web service provider
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
29
</soapenv:Header>
<soapenv:Body>
<ser: GetRTServiceInfoRequest >
< AccessServer >10.193.245.75:4000</ AccessServer >
</ser:GetRTServiceInfoRequest >
</soapenv:Body>
</soapenv:Envelope>
Example
SOAP response XML
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<localtypes: GetRTServiceInfoResponse
xmlns:localtypes="http://www.businessobjects.com/DataServices/ServerX.xsd">
< RealTimeServiceInfo >
< RTServiceName >NewService1</ RTServiceName >
< RTJobName >RJ_SPX_CHOICE</ RTJobName >
< StatusCode >2</ StatusCode >
< StatusDescription >Service Started</StatusDescription >
</ RealTimeServiceInfo >
< RealTimeServiceInfo >
< RTServiceName >NewService1</ RTServiceName >
< RTJobName >RJ_SPX_CHOICE</ RTJobName >
< StatusCode >2</ StatusCode >
< StatusDescription >Service Started</StatusDescription >
</ RealTimeServiceInfo >
</localtypes: GetRTServiceInfoResponse >
</soapenv:Body>
</soapenv:Envelope>
3.3.2.4
Get_RTService_List
Use the Get_RTService_List operation to retrieve a list of the names of published real-time services.
Input message
Get_RTService_List takes no input message.
Output message
Table 22:
Element
Type
Description
serviceName
string
The list of published real-time services.
30
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Using SAP Data Services as a web service provider
Element
Type
Description
errorMessage
string
Any error message that occurredwhile retrieving the list of
real-time services.
3.3.2.5
Get_RTService_Statistic
Use Get_RTServices_Statistic to retrieve all the real-time service statistics.
Note
You must provide a valid Access Server name and real-time service name. Data Services returns an error
message if the Access Server cannot be reached or if it does not exist.
Input message
Table 23:
Element
Type
Description
ASName
string
The name of the Access Server. For example,
<MachineName>: <port>.
RTServiceName
string
The name of the real-time service associated with the Access
Server.
Output message
Table 24:
Element
Type
Description
ProcessedRequestsNumber
string
The number of processed requests to call real-time web serv­
ices.
RequestsInQueueNumber
string
The number of requests to call real-time web services in the
queue.
MaxQueuingTime
int
The maximum queuing time, in milliseconds.
AvgQueuingTime
int
The average queuing time, in milliseconds.
QueuingTimeout
int
The maximum processing time, in milliseconds.
Integrator Guide
Using SAP Data Services as a web service provider
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
31
Element
Type
Description
MaxProcessingTime
int
The average processing time, in milliseconds.
ProcessingTimeouts
int
The number of processing timeouts.
Example
SOAP request XML
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ser="http://www.businessobjects.com/DataServices/ServerX.xsd">
<soapenv:Header>
<ser:session>
<SessionID>69B89E79-34E3BBEF-18A4-979A8C73A0E5A84A6DA144C9B0DF5ED6D559E991E69D</SessionID>
</ser:session>
</soapenv:Header>
<soapenv:Body>
<ser:GetRTServiceStatisticRequest>
<ASName>10.193.245.97:4000</ASName>
<RTServiceName>NewService1</RTServiceName>
</ser:GetRTServiceStatisticRequest>
</soapenv:Body>
</soapenv:Envelope>
Example
SOAP response XML
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<localtypes: GetRTServiceStatisticResponse xmlns:localtypes="http://
www.businessobjects.com/DataServices/ServerX.xsd">
< ProcessedRequestsNumber> 8</ ProcessedRequestsNumber>
< RequestsInQueueNumber> 0</ RequestsInQueueNumber>
< MaxQueuingTime> 7552</ MaxQueuingTime >
< AvgQueuingTime > 944</ AvgQueuingTime >
< QueuingTimeout > 0</ QueuingTimeout >
< MaxProcessingTime > 76</ MaxProcessingTime >
< AvgProcessingTime > 10</ AvgProcessingTime >
< ProcessingTimeouts > 6</ ProcessingTimeouts >
</localtypes: GetRTServiceStatisticResponse>
</soapenv:Body>
</soapenv:Envelope>
3.3.2.6
Run_Realtime_Service
Use Run_Realtime_Service to call a published real-time service. The real-time service must be running and
published as a web service in the Administrator, and the XML input content must match the input format defined
for the real-time service.
32
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Using SAP Data Services as a web service provider
Input message
Table 25:
Element
Type
Description
serviceName
string
The name of the real-time service as displayed in the Adminis­
trator.
xmlInput
string
The XML input content used to start the real-time service.
This content must match the input format required by the
real-time service.
Element
Type
Description
xmlOutput
string
The XML output content returned by the real-time service.
This content is formatted according to the output schema of
the real-time service called.
errorMessage
string
Any error message that resulted while attempting to call the
real-time service.
Output message
Table 26:
3.3.3 Batch_Job_Admin port
3.3.3.1
Get_BatchJob_ExeDetail
Use Get_BatchJob_ExeDetail to retrieve a list of all job executions for the selected repository and job. You can also
filter the list by time range.
Note
When the StartTime and EndTime elements are empty, this operation returns all the batch job details. When
one field is empty, this operation returns the current date as the default value.
Input message
Table 27:
Element
Type
Description
jobName
String
The name of the batch job.
repoName
String
The name of the repository.
Integrator Guide
Using SAP Data Services as a web service provider
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
33
Element
Type
Description
startTime
String
The date the job started (<YYYY-MM-DD HH:mm:ss>). For ex­
ample, 2013-06-08 10:10:10.
This element is optional. When it is empty, the software re­
turns the current date as default value.
endTime
String
The date the job stopped (<YYYY-MM-DD HH:mm:ss>). For
example, 2013-06-08 10:10:10.
This element is optional. When it is empty, the software re­
turns the current date as default value.
Output message
Table 28:
Element
Type
Description
ObjID
String
The job's unique identifier.
RunID
String
The unique ID for the batch job run.
JobName
String
The name of the batch job.
StartTime
String
The date and time the job started (<yyyy-MM-dd HH:mm:ss
am>).
EndTime
String
The time the job stopped (<yyyy-MM-dd HH:mm:ss am>).
ExecutionTime
String
The length of time (in seconds) the job ran.
Status
String
The status code for the batch job run. Valid strings include:
JobServerUsed
String
●
Succeed
●
Recovered
●
Failed
The name of the job server, the port number, and the host
name. The format is <jobserver name:jobserver port@
jobserver hostname>.
Example
SOAP request XML
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ser="http://www.businessobjects.com/DataServices/ServerX.xsd">
<soapenv:Header>
<ser:session>
<SessionID>D19C201F-074C-B5FE-70A4-2F3436AC04E8</SessionID>
</ser:session>
</soapenv:Header>
<soapenv:Body>
<ser:jobExcutionDetailsRequest>
<jobName>Job1_Query</jobName>
<repoName>echo_oracle</repoName>
<!--Optional:-->
34
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Using SAP Data Services as a web service provider
<startTime>2013-06-18</startTime>
<!--Optional:-->
<endTime>2013-06-19</endTime>
</ser:jobExcutionDetailsRequest>
</soapenv:Body>
</soapenv:Envelope>
Example
SOAP response XML
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<localtypes:jobExcutionDetailsResponse xmlns:localtypes="http://
www.businessobjects.com/DataServices/ServerX.xsd">
<jobDetail>
<ObjID>146</ObjID>
<RunID>37</RunID>
<JobName>Job1_Query</JobName>
<StartTime>2013-06-18 12:22:41 PM</StartTime>
<EndTime>2013-06-18 12:22:55 PM</EndTime>
<ExecutionTime>14</ExecutionTime>
<Status>error</Status>
<JobServerUsed>echo_orc:3500@vanpgc33b12</JobServerUsed>
</jobDetail>
<jobDetail>
<ObjID>146</ObjID>
<RunID>38</RunID>
<JobName>Job1_Query</JobName>
<StartTime>2013-06-18 12:23:18 PM</StartTime>
<EndTime>2013-06-18 12:23:32 PM</EndTime>
<ExecutionTime>14</ExecutionTime>
<Status>succeeded</Status>
<JobServerUsed>echo_orc:3500@vanpgc33b12</JobServerUsed>
</jobDetail>
<StatusCode>0</StatusCode>
</localtypes:jobExcutionDetailsResponse>
</soapenv:Body>
</soapenv:Envelope>
3.3.3.2
Get_BatchJob_FlowDetails
Use Get_BatchJob_FlowDetails to get details about the tasks included in a job.
Input message
Table 29:
Element
Type
Description
repoName
String
The name of the repository to access.
runID
String
The unique ID for the batch job.
Integrator Guide
Using SAP Data Services as a web service provider
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
35
Output message
Table 30:
Element
Type
Description
ObjectName
String
The name of the object used in the job.
ObjectType
String
The type of object. For example, workflow, dataflow, and so
on.
ParentObject
String
The name of the main or base object.
ParentType
String
The type of parent object. For example, workflow, dataflow,
and so on.
StartTime
String
The date and time that the job execution instance started
(<yyyy-MM-dd HH:mm:ss am/pm>). For example,
2013-06-18 10:05:38 AM.
EndTime
String
The date and time that this job execution instance stopped
(<yyyy-MM-dd HH:mm:ss am/pm>). For example,
2013-06-18 12:05:38 PM.
Duration
String
The time (in seconds) that the job took to complete.
RowsRead
String
The number of rows read.
JobserverUsed
String
The name of the job server used to run the job. The format is
<jobserver name:jobserver port>.
hasAuditData
String
Specifies if there is audit data. Valid strings include:
●
Yes
●
No
Example
SOAP request XML
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ser="http://www.businessobjects.com/DataServices/ServerX.xsd">
<soapenv:Header>
<ser:session>
<SessionID>D19C201F-074C-B5FE-70A4-2F3436AC04E8</SessionID>
</ser:session>
</soapenv:Header>
<soapenv:Body>
<ser:jobFlowDetailsRequest>
<repoName>echo_oracle</repoName>
<runID>29</runID>
</ser:jobFlowDetailsRequest>
</soapenv:Body>
</soapenv:Envelope>
Example
SOAP response XML
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<localtypes:jobExcutionDetailsResponse xmlns:localtypes="http://
www.businessobjects.com/DataServices/ServerX.xsd">
36
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Using SAP Data Services as a web service provider
<flowDetail>
<ObjectName>New_DataFlow10</ObjectName>
<ObjectType>Dataflow</ObjectType>
<ParentObject>audit008</ParentObject>
<ParentType>Job</ParentType>
<StartTime>2013-06-18 12:05:38 PM</StartTime>
<EndTime>2013-06-18 12:05:38 PM</EndTime>
<Duration>0</Duration>
<RowsRead>2</RowsRead>
<JobserverUsed>echo_orc:3500</JobserverUsed>
<hasAuditData>yes</hasAuditData>
</flowDetail>
<StatusCode>0</StatusCode>
</localtypes:jobExcutionDetailsResponse>
</soapenv:Body>
</soapenv:Envelope>
3.3.3.3
Get_BatchJob_List
Use Get_BatchJob_List to retrieve a list of the names of published batch jobs.
Input message
Table 31:
Element
Type
Description
repoName
String
The name of the repository to access. This element is op­
tional.
allBatchJobs
Boolean
Includes all batch jobs in the repository, not only those pub­
lished as web services. This parameter is optional.
Element
Type
Description
jobName
String
The list of published batch jobs. This element has an addi­
tional attribute, repo, which specifies the name of the reposi­
tory that contains the job.
errorMessage
String
Any error message that occurred while retrieving the list of
batch jobs.
Output message
Table 32:
Integrator Guide
Using SAP Data Services as a web service provider
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
37
3.3.3.4
Get_BatchJob_RunIDs
Each individual run of an SAP Data Services batch job is assigned a unique run ID.
Use Get_BatchJob_RunIDs to retrieve a list of run IDs associated with a particular batch job.
Input message
Table 33:
Element
Type
Description
jobName
String
The name of the batch job.
status
String
The status code for the type of run IDs requested. Valid codes
include: running, succeeded, error, warning, and all.
repoName
String
The name of the repository to access. When specified, the op­
eration returns only run IDs from this repository. This element
is optional.
Output message
The response of the Get_BatchJobs_RunIDs operation contains one or more run element. Each run element
contains the following sub-elements:
Table 34:
Element
Type
Description
runID
Integer
The unique ID for the batch job run.
status
String
The status code for the batch job run. Valid codes include:
running, succeeded, error, warning, and all.
repoName
String
The repository name associated with the batch job.
errorMessage
String
Any error message that occurred while retrieving the list of
batch jobs.
3.3.3.5
Get_BatchJob_Status
Use Get_BatchJob_Status to retrieve the status of a particular batch job run.
38
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Using SAP Data Services as a web service provider
Input message
Table 35:
Element
Type
Description
runID
Integer
The run ID for the particular batch job status desired.
repoName
String
The name of the repository to access.
Element
Type
Description
returnCode
Integer
The status for the operation. Valid values include:
Output message
Table 36:
status
String
●
0 - The operation completed successfully.
●
1 - The operation encountered an error. For example, the
repoName specified is invalid.
The status of the batch job run. Valid values include:
●
3.3.3.6
Running - The job is currently running.
●
Succeeded - The job completed with no errors.
●
Warning - The job completed, but warnings occurred.
●
Error - The job completed with an error.
Get_DF_Auditdata
Use Get_DF_Auditdata to show audit information for a data flow. To retrieve audit information, you need to enable
the audit point in your data flow object.
Input message
Table 37:
Element
Type
Description
runID
String
The unique ID for the batch job.
repoName
String
The name of the repository to access.
dataflow
String
The name of the data flow for which you want audit informa­
tion.
Integrator Guide
Using SAP Data Services as a web service provider
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
39
Output message
Table 38:
Element
Type
Description
auditPoint
String
The name of the object in a data flow from which you are col­
lecting audit statistics.
auditValue
String
The value of the audit function in the audit point.
Example
SOAP request XML
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ser="http://www.businessobjects.com/DataServices/ServerX.xsd">
<soapenv:Header>
<ser:session>
<SessionID>D19C201F-074C-B5FE-70A4-2F3436AC04E8</SessionID>
</ser:session>
</soapenv:Header>
<soapenv:Body>
<ser:dataflowAuditRequest>
<runID>34</runID>
<repoName>echo_oracle</repoName>
<dataflow>New_DataFlow10</dataflow>
</ser:dataflowAuditRequest>
</soapenv:Body>
</soapenv:Envelope>
Example
SOAP response XML
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<localtypes:dataflowAuditResponse xmlns:localtypes="http://
www.businessobjects.com/DataServices/ServerX.xsd">
<audit>
<auditPoint>$Count_Query_1</auditPoint>
<auditValue>6</auditValue>
</audit>
<audit>
<auditPoint>$CountError_Query</auditPoint>
<auditValue>0</auditValue>
</audit>
<audit>
<auditPoint>$Count_Query</auditPoint>
<auditValue>6</auditValue>
</audit>
<audit>
<auditPoint>$CountError_Row_Generation</auditPoint>
<auditValue>0</auditValue>
</audit>
<StatusCode>0</StatusCode>
</localtypes:dataflowAuditResponse>
</soapenv:Body>
</soapenv:Envelope>
40
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Using SAP Data Services as a web service provider
3.3.3.7
Get_DF_Monitor_Log
Use Get_DF_Monitor_Log to show the runtime statistics for a single data flow execution.
Note
The Job Server must be running in order to use this operation.
Input message
Table 39:
Element
Type
Description
repoName
String
The name of the repository to access.
runID
Integer
The unique ID for the batch job.
dataflow
String
The name of the dataflow which contains the batch job.
stoponly
String
Indicates if the process ended without error. You can use a
Yes or No string for this element. If it is set to Yes, the output
will have only Stop rows, meaning the transform object status
is in a Stop state.
Element
Type
Description
threadName
String
The name of the thread.
state
String
The status of each process in the execution of the data flow.
Valid strings include:
Output message
Table 40:
●
Initializing - Indicates that the job is initializing.
●
Optimizing - Indicates that the job is optimizing.
●
Proceed - Indicates that the process is executing.
●
Stop - Indicates that the process ended without error.
absoluteTime
Integer
The amount of time (in seconds) since the execution of the
data flow began.
counter
Integer
The number given to each monitor log file to which the soft­
ware writes information.
rowProcessed
Long
The number of rows processed through the object.
bufferSize
Long
The output buffer size (in kilobytes). This is the amount of
time allotted for processing.
bufferUsed
String
The output buffer size used.
Integrator Guide
Using SAP Data Services as a web service provider
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
41
Element
Type
Description
CPUUtilization
String
The percent of CPU uses per thread.
jobServerUsed
String
The name of the job server used to execute the data flow.
Example
SOAP request XML
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ser="http://www.businessobjects.com/DataServices/ServerX.xsd">
<soapenv:Header>
<ser:session>
<SessionID>D19C201F-074C-B5FE-70A4-2F3436AC04E8</SessionID>
</ser:session>
</soapenv:Header>
<soapenv:Body>
<ser:DataFlowMonitorLogRequest>
<runID>29</runID>
<repoName>echo_oracle</repoName>
<dataflow>New_DataFlow10</dataflow>
<stoponly>yes</stoponly>
</ser:DataFlowMonitorLogRequest>
</soapenv:Body>
</soapenv:Envelope>
Example
SOAP response XML
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<localtypes:DataFlowMonitorLogResponse xmlns:localtypes="http://
www.businessobjects.com/DataServices/ServerX.xsd">
<Row>
<threadName>/New_DataFlow10/Row_Generation</threadName>
<state>STOP</state>
<absoluteTime>2.906</absoluteTime>
<counter>1</counter>
<rowProcessed>6</rowProcessed>
<bufferSize>0</bufferSize>
<bufferUsed>0</bufferUsed>
<CPUUtilization>0.0</CPUUtilization>
<jobServerUsed>echo_orc:3500</jobServerUsed>
</Row>
<Row>
<threadName>/New_DataFlow10/Query-Mapping1</threadName>
<state>STOP</state>
<absoluteTime>2.906</absoluteTime>
<counter>1</counter>
<rowProcessed>0</rowProcessed>
<bufferSize>0</bufferSize>
<bufferUsed>0</bufferUsed>
<CPUUtilization>0.0</CPUUtilization>
<jobServerUsed>echo_orc:3500</jobServerUsed>
</Row>
<Row>
<threadName>/New_DataFlow10/Audit[3]</threadName>
<state>STOP</state>
<absoluteTime>2.906</absoluteTime>
<counter>1</counter>
<rowProcessed>0</rowProcessed>
42
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Using SAP Data Services as a web service provider
<bufferSize>0</bufferSize>
<bufferUsed>0</bufferUsed>
<CPUUtilization>0.0</CPUUtilization>
<jobServerUsed>echo_orc:3500</jobServerUsed>
</Row>
<Row>
<threadName>/New_DataFlow10/Merge: 0</threadName>
<state>STOP</state>
<absoluteTime>2.906</absoluteTime>
<counter>1</counter>
<rowProcessed>6</rowProcessed>
<bufferSize>0</bufferSize>
<bufferUsed>0</bufferUsed>
<CPUUtilization>0.0</CPUUtilization>
<jobServerUsed>echo_orc:3500</jobServerUsed>
</Row>
<Row>
<threadName>-New_DataFlow10/output8.txt</threadName>
<state>STOP</state>
<absoluteTime>2.906</absoluteTime>
<counter>1</counter>
<rowProcessed>6</rowProcessed>
<bufferSize>0</bufferSize>
<bufferUsed>0</bufferUsed>
<CPUUtilization>0.0</CPUUtilization>
<jobServerUsed>echo_orc:3500</jobServerUsed>
</Row>
<returnCode>0</returnCode>
</localtypes:DataFlowMonitorLogResponse>
</soapenv:Body>
</soapenv:Envelope>
3.3.3.8
Get_DF_Monitor_Log_Pivot
Use Get_DF_Monitor_Log_Pivot to show the runtime statistics as pivoted for a single data flow execution.
Note
The Job Server must be running in order to use this operation.
Input message
Table 41:
Element
Type
Description
repoName
String
The name of the repository to access.
runID
Integer
The unique ID for the batch job.
dataflow
String
The name of the data flow for which you want audit informa­
tion.
threadName
String
Filters the output based on the thread name. This element is
optional.
Integrator Guide
Using SAP Data Services as a web service provider
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
43
Element
Type
Description
measure
String
Filters the output based on the measure type. This element is
optional. Valid strings include:
●
rows processed
●
buffer used
●
thread CPU %
Output message
Table 42:
Element
Type
Description
threadName
String
The name of the thread.
measure
String
The measure type. Valid strings include:
sample<x>
Integer
●
rows processed
●
buffer used
●
thread CPU %
The software writes information to log files at assigned inter­
vals. The sample number corresponds to the monitor sample
counter, which is a number that is assigned to each monitor
log file. The sample output consists of measure type statistics
for a thread. Output is limited to 500 sample columns (sam­
ple1 through sample500).
Example
SOAP request XML
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ser="http://www.businessobjects.com/DataServices/ServerX.xsd">
<soapenv:Header>
<ser:session>
<SessionID>D19C201F-074C-B5FE-70A4-2F3436AC04E8</SessionID>
</ser:session>
</soapenv:Header>
<soapenv:Body>
<ser:DataFlowMonitorLogPivotRequest>
<runID>29</runID>
<repoName>echo_oracle</repoName>
<dataflow>New_DataFlow10</dataflow>
<!--Optional:-->
<threadName></threadName>
<!--Optional:-->
<measure>thread CPU %</measure>
</ser:DataFlowMonitorLogPivotRequest>
</soapenv:Body>
</soapenv:Envelope>
44
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Using SAP Data Services as a web service provider
Example
SOAP response XML
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<localtypes:DataFlowMonitorLogPivotResponse xmlns:localtypes="http://
www.businessobjects.com/DataServices/ServerX.xsd">
<Row>
<threadName>/New_DataFlow10/Row_Generation</threadName>
<measure>thread CPU %</measure>
<Sample1>0.0</Sample1>
<Sample2>0.0</Sample2>
<Sample3>0.0</Sample3>
<Sample4/>
<Sample5/>
<Sample6/>
<Sample7/>
<Sample8/>
<Sample9/>
<Sample10/>
<Sample11/>
...
<Sample496/>
<Sample497/>
<Sample498/>
<Sample499/>
<Sample500/>
</Row>
<returnCode>0</returnCode>
</localtypes:DataFlowMonitorLogPivotResponse>
</soapenv:Body>
</soapenv:Envelope>
3.3.3.9
Get_Error_Log
SAP Data Services produces several types of log information for a batch job published as a web service.
Use the Get_Error_Log operation to retrieve the error log for a batch job.
Input message
Table 43:
Element
Type
Description
runID
integer
The batch job run ID for the particular log desired.
repoName
string
The name of the repository to access.
page
integer
The page number of the error log to return. This element is
optional.
Integrator Guide
Using SAP Data Services as a web service provider
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
45
Output message
Table 44:
Element
Type
Description
returnCode
integer
The status for the operation. Valid values include:
error
string
●
0 - The operation completed successfully.
●
1 - The operation failed to retrieve the error log.
The error log associated with the input batch job run ID.
3.3.3.10 Get_Job_Input_Format
Use Get_Job_Input_Format to retrieve the input format for a batch job as an XML Schema.
Input message
Table 45:
Element
Type
Description
jobName
string
The name of the batch job as displayed in the Administrator.
repoName
string
The name of the repository to access.
Element
Type
Description
format
string
The input format for the batch job, as an XML Schema.
errorMessage
string
Any error message that resulted while retrieving the input for­
mat for the batch job.
Output message
Table 46:
3.3.3.11 Get_Jobserver_List
Use Get_Jobserver_List to retrieve a list of Job Servers that are registered to a repository.
Note
You must provide a valid repository name. Data Services returns an error message if the repository cannot be
reached or if it does not exist.
46
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Using SAP Data Services as a web service provider
Input message
Table 47:
Element
Type
Description
repoName
string
The name of the repository to access.
Note
Data Services lists all Job Servers from all repositories if
the string input value is empty. The timeout for an inactive
repository is within 60 seconds.
Output message
Table 48:
Element
Type
Description
jobServerName
string
The name of the Job Server that is configured in the Server
Manager.
jobServer
string
Job Server machine information. For example, <jobserver
hostname>:<jobserver port>.
Example
SOAP request XML
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ser="http://www.businessobjects.com/DataServices/ServerX.xsd">
<soapenv:Header>
<ser:session>
<SessionID>69B89E79-34E3BBEF-18A4-979A8C73A0E5A84A6DA144C9B0DF5ED6D559E991E69D</SessionID>
</ser:session>
</soapenv:Header>
<soapenv:Body>
<ser:GetJobServerListRequest>
<repoName>HANA</repoName>
</ser:GetJobServerListRequest>
</soapenv:Body>
</soapenv:Envelope>
Example
SOAP response XML
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<localtypes:GetJobServerListResponse xmlns:localtypes="http://
www.businessobjects.com/DataServices/ServerX.xsd">
<JobServerInfo>
<jobServerName>JS</jobServerName>
<jobServer>SHG-CHF:3500</jobServer>
Integrator Guide
Using SAP Data Services as a web service provider
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
47
</JobServerInfo>
</localtypes:GetJobServerListResponse>
</soapenv:Body>
</soapenv:Envelope>
3.3.3.12 Get_Jobserver_Status
Use Get_Jobserver_Status to retrieve the status of Job Servers that are registered to a repository.
Note
You must provide a valid repository and Job Server name. Data Services returns an error message if the
repository cannot be reached or if it does not exist.
Input message
Table 49:
Element
Type
Description
repoName
string
The name of the repository to access.
Note
Data Services lists all Job Servers from all repositories if
the string input value is empty. The timeout for an inactive
repository is within 60 seconds.
string
Job Server machine information. For example, <jobserver
hostname>:<jobserver port>.
Element
Type
Description
Status
int
The Job Server status type. Valid value include:
jobServer
Output message
Table 50:
48
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
●
0: Job Server is running
●
1: Job Server cannot connect to the repository
●
501: Job Server is not running
Integrator Guide
Using SAP Data Services as a web service provider
Example
SOAP request XML
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ser="http://www.businessobjects.com/DataServices/ServerX.xsd">
<soapenv:Header>
<ser:session>
<SessionID>69B89E79-34E3BBEF-18A4-979A8C73A0E5A84A6DA144C9B0DF5ED6D559E991E69D</SessionID>
</ser:session>
</soapenv:Header>
<soapenv:Body>
<ser:GetJobServerStatusRequest>
<repoName>HANA</repoName>
<jobServer>SHG-CHF:3500</jobServer>
</ser:GetJobServerStatusRequest>
</soapenv:Body>
</soapenv:Envelope>
Example
SOAP response XML
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<localtypes:GetJobServerStatusResponse xmlns:localtypes="http://
www.businessobjects.com/DataServices/ServerX.xsd">
<Status>0</Status>
</localtypes:GetJobServerStatusResponse>
</soapenv:Body>
</soapenv:Envelope>
3.3.3.13 Get_MC_Machine_Timezone
Use Get_MC_Machine_Timezone to retrieve the time zone of the Management Console machine.
Note
Get_MC_Machine_Timezone returns only time zone information for the Management Console machine. It does
not return Central Management Server (CMS) or job server time zone information. Be aware that the
Management Console, the CMS, and the job server you use may be deplayed across different time zones.
Input message
No input parameter is needed. You only need to log into the system.
Integrator Guide
Using SAP Data Services as a web service provider
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
49
Output message
Table 51:
Element
Type
Description
TimeZone
String
The human-readable name of the time zone. For example, Pa­
cific Standard Time.
TimeZoneShortName
String
The short name of the time zone. For example, PST.
Offset
Int
The offset of the time zone from the Coordinated Universal
Time (UTC) time zone (in minutes).
Example
SOAP request XML
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ser="http://www.businessobjects.com/DataServices/ServerX.xsd">
<soapenv:Header>
<ser:session>
<SessionID>755D02EF-6984-131C-5316-AB1413B98CF2</SessionID>
</ser:session>
</soapenv:Header>
<soapenv:Body>
<ser:GetMCMachineTimezoneRequest/>
</soapenv:Body>
</soapenv:Envelope>
Example
SOAP response XML
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<localtypes:GetMachineTimezoneResponse xmlns:localtypes="http://
www.businessobjects.com/DataServices/ServerX.xsd">
<MachineInfo>
<TimeZone>Pacific Standard Time</TimeZone>
<TimeZoneShortName>PST</TimeZoneShortName>
<Offset>-480</Offset>
</MachineInfo>
</localtypes:GetMachineTimezoneResponse>
</soapenv:Body>
</soapenv:Envelope>
3.3.3.14 Get_Monitor_Log
SAP Data Services produces several types of log information for a batch job published as a web service.
Use the Get_Monitor_Log operation to retrieve the monitor log for a batch job.
50
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Using SAP Data Services as a web service provider
Input message
Table 52:
Element
Type
Description
runID
integer
The batch job run ID for the particular log desired.
repoName
string
The name of the repository to access.
page
integer
The page number of the monitor log to return. This element is
optional.
Element
Type
Description
returnCode
integer
The status for the operation. Valid values include:
Output message
Table 53:
monitor
string
●
0 - The operation completed successfully.
●
1 - The operation failed to retrieve the monitor log.
The monitor log associated with the input batch job run ID.
3.3.3.15 Get_Scheduled_Tasks
Use Get_Scheduled_Tasks to retrieve the list of all scheduled tasks for the selected repository, and get the
detailed schedule information from the repository which is stored in table “AL_SCHED_INFO”.
Note
When repoName elements are empty, this operation returns scheduled jobs of all repositories. Currently,
“NextRunTime” will base on centre services time zone, not on the Jobserver.
Input message
Table 54:
Element
Type
Description
repoName
String
The name of the repository.
allBatchJobs
String
The default is to return active scheduled task. When set to “true’, the software will return all
scheduled task.
Integrator Guide
Using SAP Data Services as a web service provider
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
51
Output message
Table 55:
Element
Type
Description
ScheduledTaskName String
The name of the scheduled task.
JobName
String
The name of the batch job.
RepoName
String
The name of the repository.
NextRunTime
String
The next scheduled start time for a job. The format is dow mon dd hh:mm:ss zzz yyyy. For ex­
ample, Mon Jun 30 11:46:12 CEST 2013.
IsActive
String
The active status of a scheduled task.
●
0 for inactive
●
1 for active
RecurrenceType
String
The recurrence type (daily/weekly/monthly).
RecurrenceDays
String
Lists the recurrence days, separated by ".".
StartTime
String
The start time in one day.
DurationTime
String
The duration time in one day. It will be 0 if set to trigger once a day.
RepeatInterval
String
The repeat interval in one day. It will be 0 if set to trigger once a day.
Example
SOAP request XML
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ser="http://www.businessobjects.com/DataServices/ServerX.xsd">
<soapenv:Header>
<ser:session>
<SessionID>755D02EF-6984-131C-5316-AB1413B98CF2</SessionID>
</ser:session>
</soapenv:Header>
<soapenv:Body>
<ser:GetScheduledTasksRequest>
<!--Optional:-->
<RepoName>HANAREPO</RepoName>
<!--Optional:-->
<allBatchJobs>True</allBatchJobs>
</ser:GetScheduledTasksRequest>
</soapenv:Body>
</soapenv:Envelope>
Example
SOAP response XML
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<localtypes:GetScheduledTasksResponse xmlns:localtypes="http://
www.businessobjects.com/DataServices/ServerX.xsd">
<SchduledTask>
<ScheduledTaskName>NewSchedule734</ScheduledTaskName>
<JobName>hana_ansi_createtables</JobName>
<RepoName>HANAREPO</RepoName>
<RecurrenceType>Monthly</RecurrenceType>
52
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Using SAP Data Services as a web service provider
<RecurrenceDays>2.</RecurrenceDays>
<StartTime>11:47 AM</StartTime>
<DurationTime>0</DurationTime>
<RepeatInterval>0</RepeatInterval>
<NextRunTime/>
<IsActive>false</IsActive>
</SchduledTask>
</localtypes:GetScheduledTasksResponse>
</soapenv:Body>
</soapenv:Envelope>
3.3.3.16 Get_Trace_Log
SAP Data Services produces several types of log information for a batch job published as a web service.
Use the Get_Trace_Log operation to retrieve the trace log for a batch job.
Input message
Table 56:
Element
Type
Description
runID
integer
The batch job run ID for the particular log desired.
repoName
string
The name of the repository to access.
page
integer
The page number of the trace log to return. This element is
optional.
Element
Type
Description
returnCode
integer
The status for the operation. Valid values include:
Output message
Table 57:
trace
string
●
0 - The operation completed successfully.
●
1 - The operation failed to retrieve the trace log.
The trace log associated with the input batch job run ID.
3.3.3.17 Run_Batch_Job
Use Run_Batch_Job to call a batch job with the ability to specify job parameters and global variables.
Integrator Guide
Using SAP Data Services as a web service provider
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
53
Input message
Table 58:
Element
Type
Description
jobName
string
The name of the batch job as displayed in the Administrator.
repoName
string
The name of the repository to access.
jobServer
string
The name of the job server to use to execute the job. This ele­
ment is optional, but cannot be specified if serverGroup is also
specified.
serverGroup
string
The name of the server group to use to execute the job. This
element is optional, but cannot be specified if jobServer is also
specified.
jobParameters
complex
A complex XML element that sets specific job execution pa­
rameters.
globalVariables
complex
A complex XML element that defines global job execution vari­
ables.
Note
If you do not specify a serverGroup or jobServer, the operation attempts to find an available job server that is
attached to the repository by first checking the server group list, and then the job server list.
Note
For detailed information about the jobParameters and globalVariables elements, view the WSDL from the
Administrator. For more information about available job parameters and global variables, see the Reference
Guide.
Output message
Table 59:
Element
Type
Description
pid
int
The process ID number for the batch job execution. Process
IDs can be reused.
cid
int
The counter ID number for the batch job excecution. You can
use a counter ID together with a process ID to uniquely iden­
tify a specific instance of the job execution.
rid
int
The run ID associated with the specific execution of the batch
job.
repoName
string
The repository name associated with the batch job execution.
errorMessage
string
Any error message that resulted while attempting to call the
batch job.
54
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Using SAP Data Services as a web service provider
3.3.3.18 Stop_Batch_Job
Use the Stop_Batch_Job operation to stop a particular batch job run.
Input message
Table 60:
Element
Type
Description
runID
integer
The run ID for the particular batch job run to stop.
repoName
string
The name of the repository to access.
Element
Type
Description
returnCode
integer
The success code for the batch job stop attempt. Valid codes
include:
Output message
Table 61:
errorMessage
string
●
0 - The operation successfully stopped the specified
batch job.
●
1 - The operation failed to stop the specified batch job in
the specified repository.
The error message associated with a failure to stop a batch
job run.
3.3.4 Real-time_Services port
SAP Data Services generates WSDL that defines how to invoke real-time services enabled as web service
operations. Each real-time service name is represented as an operation name in the WSDL file.
Each real-time service operation has a set of messages that it uses to communicate with the real-time service.
Real-time services use a defined XML message as input and a defined XML message as output. Real-time services
obtain the format of these messages from the repository and provide the format in the WSDL.
The software supports XML Schemas as its message format for real-time services. A web service provides only
XML Schemas in the WSDL. You will need to convert any DTDs to XML schemas as necessary.
The repository stores XML Schemas that define the input and output messages as independent definitions. The
WSDL file includes these definitions in the types element.
The messages that an XML Schema defines for each real-time service operation are:
● Header message
If security is enabled for the message, the software defines a secure session identifier in the message header.
Integrator Guide
Using SAP Data Services as a web service provider
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
55
● Input message
When an external web services client invokes it, the input message passes information to a real-time service.
The name of the input message is the name of the operation that the software publishes followed by the suffix
_Input. The input message contains the message source defined by the real-time service.
● Output message
The software returns the output message when the real-time service completes. The output message
contains the output generated by the real-time service. The name of the output message is the name of the
operation followed by the suffix _Output. The output message contains the message target defined by the
real-time service.
● Fault message
The software returns a fault message when it cannot invoke the real-time service.
3.3.4.1
Message formats
The following segment shows the syntax that Data Services generates in a WSDL file to define an operation's
messages. In this example:
● RTService represents the name of the real-time service as defined in the Administrator.
● XMLSchemaName represents the name of the XML Schema that was used to create an XML message source
or XML message target in the Designer.
● RootElement represents the root element of the XML Schema.
The software publishes a WSDL that includes input and output XML Schema message formats in the types
element.
Note
Server support for real-time services requires that you use a valid URL for locating XML Schema (.xsd) files in
an import statement. A local file name cannot be used. For example, the .xsd must be either self-contained
when imported into the software or it must use a network reference (URL), not a file or relative path reference,
as an identifier.
The WSDL file displays the operations for real-time services within a portType tag.
3.3.5 Batch_Jobs port
SAP Data Services generates WSDL that defines how to start batch jobs. The WSDL file represents each batch job
name as an operation.
In addition, the WSDL file defines an input and output message for each operation. An input message
communicates the input needed by the job at startup (such as the global variables needed to start the job). An
output message either confirms that the job started or presents the errors that prevent the job from starting.
WSDL defines the following messages for each operation:
56
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Using SAP Data Services as a web service provider
Table 62:
Message
Description
Header message
When security is enabled for the message, the software defines a secure session identifier in
the message header.
Input message
The input message passes information needed by the batch job at startup. The name assigned
to the input message is the name of the operation followed by the suffix _Input. The input
message contains global variables.
When security is enabled for the message, the software defines a secure session identifier in
the message header.
Output message
The software returns the output message when the batch job starts. The output message con­
tains the job identification. The name of the output message is the name of the operation fol­
lowed by the suffix _Output. The output message contains the following IDs:
Fault message
●
OS process ID of the started job
●
Job Server Counter ID of the started job
The software returns a fault message if the batch job fails to start. It returns a text description
of the error that prevents the job from starting.
3.3.5.1
SoapAction element
The definition of each batch job operation uses the soapAction element to define the batch job name needed to
launch the job.
The WSDL file displays the soapAction element in the service and port section.
3.3.5.2
Security
When publishing a job as a web service, the Administrator can enable secure access, requiring that web services
clients provide authentication and authorization (an Administrator username and password) for access to the
web service operations. Administrator-level (not Monitor-level) privileges must be used. That is, you cannot limit
access to users based on role. This authentication is SSL-compliant.
If you do not enable secure access and you are using HTTP, web services clients have open access to all published
batch jobs and real-time services.
Related Information
Configuring web service information using the Administrator [page 17]
Integrator Guide
Using SAP Data Services as a web service provider
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
57
3.3.6 Repo_Operations port
SAP Data Services generates WSDL that defines operations that belong to web services. The software supports
the following operations on the Repo_Operations port.
Table 63:
Operation
Description
Delete_Repo_Objects
Deletes objects from the repository.
Import_Repo_Object
Imports an object to the repository.
Validate_Repo_Object
Validates an object contained in the repository.
Export_DQReport
Exports reports to a specified location at runtime.
Get_Repository_List
Retrieves the entire repository list based on the user's permissions. This operation
also returns a list of the repositories that the user is currently logged into.
3.3.6.1
Delete_Repo_Objects
Use the Delete_Repo_Objects operation to delete objects from the SAP Data Services repository.
58
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Using SAP Data Services as a web service provider
Input message
Table 64:
Element
Type
Description
objName
string
The name of the object to delete from the repository. This ele­
ment requires the attribute objType and can occur multiple
times.
The objType attribute specifies the type of the object:
●
BATCH_JOB
●
REALTIME_JOB
●
WORKFLOW
●
DATAFLOW
●
ABAP_DATAFLOW
●
DATA_QUALITY_TRANSFORM_CONFIGURATION
●
DATASTORE
●
FILE_FORMAT
●
XML_SCHEMA
●
DTD
●
CUSTOM_FUNCTION
●
EXCEL_WORKBOOK
●
COBOL_COPYBOOK
●
SYSTEM_PROFILE
●
SUBSITUTION_CONFIGURATION
●
PROJECT
●
TABLE
●
TEMPLATE_TABLE
●
DOMAIN
●
HIERARCHY
●
STORED_PROCEDURE
●
IDOC
●
BW_MASTER_TRANSFER_STRUCTURES
●
BW_MASTER_TEXT_TRANSFER_STRUCTURES
●
BW_TRANSACTION_TRANSFER_STRUCTURES
●
BW_HIERARCHY_TRANSFER
repoName
string
The name of the repository that contains the objects to delete.
jobServer
string
The name of the job server associated with the repository.
This element is optional, but cannot be specified if server­
Group is also specified.
serverGroup
string
The name of the server group associated with the repository.
This element is optional, but cannot be specified if jobServer
is also specified.
traceOn
string
Enables tracing for the operation. This element is optional.
Integrator Guide
Using SAP Data Services as a web service provider
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
59
Note
If you do not specify a serverGroup or jobServer, the operation attempts to find an available job server that is
attached to the repository by first checking the server group list, and then the job server list.
Output message
Table 65:
Element
Type
Description
returnCode
int
The status of the operation:
●
0 - The operation completed successfully.
●
1 - The operation failed to complete successfully.
errorMessage
string
The error message associated with the operation. This ele­
ment is output only if the operation fails to complete success­
fully.
traceMessage
string
The trace message associated with the operation. This ele­
ment is output only if the traceOn element is specified on in­
put.
3.3.6.2
Import_Repo_Object
Use the Import_Repo_Object operation to save an XML object definition to the SAP Data Services repository.
Input message
Table 66:
Element
Type
Description
definition
string
The object to import to the repository. The object must be de­
fined in XML format.
repoName
string
The name of the repository in which to import the object.
jobServer
string
The name of the job server associated with the repository.
This element is optional, but cannot be specified if server­
Group is also specified.
serverGroup
string
The name of the server group associated with the repository.
This element is optional, but cannot be specified if jobServer
is also specified.
traceOn
string
Enables tracing for the operation. This element is optional.
60
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Using SAP Data Services as a web service provider
Element
Type
Description
passphrase
string
The passphrase that was used to encode any passwords in
the XML object definition.
Note
If the passphrase you specify is incorrect, the operation will
still save the XML objects to the repository, but any pass­
words in the definition will be removed.
Note
If you do not specify a serverGroup or jobServer, the operation attempts to find an available job server that is
attached to the repository by first checking the server group list, and then the job server list.
Output message
Table 67:
Element
Type
Description
returnCode
int
The status of the operation:
●
0 - The operation completed successfully.
●
1 - The operation failed to complete successfully.
errorMessage
string
The error message associated with the operation. This ele­
ment is output only if the operation fails to complete success­
fully.
traceMessage
string
The trace message associated with the operation. This ele­
ment is output only if the traceOn element is specified on in­
put.
3.3.6.3
Validate_Repo_Object
Use the Validate_Repo_Object operation to validate an object stored in the SAP Data Services repository.
Input message
Table 68:
Element
Type
Description
objName
string
The name of the object to validate.
Integrator Guide
Using SAP Data Services as a web service provider
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
61
Element
Type
Description
objType
string
The type of the object to validate:
●
BATCH_JOB
●
REALTIME_JOB
●
WORKFLOW
●
DATAFLOW
●
ABAP_DATAFLOW
●
DATA_QUALITY_TRANSFORM_CONFIGURATION
●
CUSTOM_FUNCTION
repoName
string
The name of the repository that contains the object to vali­
date.
systemProfile
string
The name of the job system profile to use while validating the
object. This element is optional.
jobServer
string
The name of the job server associated with the repository.
This element is optional, but cannot be specified if server­
Group is also specified.
serverGroup
string
The name of the server group associated with the repository.
This element is optional, but cannot be specified if jobServer
is also specified.
substitutionParameters
complex
Substitution parameters to override while validating the ob­
ject. This element is optional and contains one or more pa­
rameter child elements.
parameter
string
An individual substitution parameter.
traceOn
string
Enables tracing for the operation. This element is optional.
Note
If you do not specify a serverGroup or jobServer, the operation attempts to find an available job server that is
attached to the repository by first checking the server group list, and then the job server list.
Output message
Table 69:
Element
Type
Description
returnCode
int
The status of the operation:
errorMessage
62
string
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
●
0 - The operation completed successfully.
●
1 - The operation failed to complete successfully.
The error message associated with the operation. This ele­
ment is output only if the operation fails to complete success­
fully.
Integrator Guide
Using SAP Data Services as a web service provider
Element
Type
Description
traceMessage
string
The trace message associated with the operation. This ele­
ment is output only if the traceOn element is specified on in­
put.
3.3.6.4
Export_DQReport
Use the Export_DQReport operation to export reports to a specified location at runtime.
Input message
Table 70:
Element
Type
Description
runID
integer
The unique ID for the batch job run.
repoName
string
The name of the repository to that contains the batch job.
Element
Type
Description
exportFileName
string
The name of the file that is exported; for example,
matchcriteriasummary_Set1.pdf.
exportPath
string
The path where the reports will be exported to. The default
path is <<DS_COMMON_DIR>>\DataQuality\reports
Output message
Table 71:
\. Upon execution, the repository name and job name folders
are appended to the path. If the Overwrite option is not se­
lected, a run ID folder is also appended to the path.
Note
If you export reports to a location other than a local drive,
such as a network drive, before you execute the job you
must start the web application server with an account that
has access rights to that location.
exportStatus
processMessage
boolean
string
Integrator Guide
Using SAP Data Services as a web service provider
The status of the overall export operation:
●
0 - The operation completed successfully.
●
Negative integer - The operation failed to complete suc­
cessfully.
Informational messages about the overall export process.
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
63
Element
Type
Description
reportName
string
The name of the report that is displayed in the Management
Console; for example, Match Criteria Summary.
reportStatus
integer
The status of the export operation for each report:
statusMessage
3.3.6.5
string
●
0 - The operation completed successfully.
●
Negative integer - The operation failed to complete suc­
cessfully.
Informational message about the export status for each re­
port.
Get_Repository_List
Use Get_Repository_List to retrieve the entire repository list based on the user's permissions. This operation also
returns a list of the repositories that the user is currently logged into.
Input message
No input parameter is needed. You only need to log into the system.
Output message
Table 72:
Element
Type
Description
repoName
String
The name of the repository that is configured in the Manage­
ment Console.
repoType
String
The repository database type. This element is optional. Valid
strings include:
●
local
●
central
●
secure central
●
profiler
dbType
String
The repository database type. For example, Oracle, DB2,
HANA, and so on.
dbHost
String
The host name of the database server.
connectionStatus
String
Indicates whether the connection is active or inactive.
username
String
The user name used to log into the database.
64
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Using SAP Data Services as a web service provider
Element
Type
Description
permissions
String
The user's permission level for the repository. If you don't
have rights to view a repository, the repository name will not
be returned. Valid strings include, READ, EDIT, and DELETE.
Example
SOAP request XML
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ser="http://www.businessobjects.com/DataServices/ServerX.xsd">
<soapenv:Header>
<ser:session>
<SessionID>D19C201F-074C-B5FE-70A4-2F3436AC04E8</SessionID>
</ser:session>
</soapenv:Header>
<soapenv:Body>
<ser:GetListOfRepositoriesRequest/>
</soapenv:Body>
</soapenv:Envelope>
Example
SOAP response XML
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<localtypes:GetListOfRepositoriesResponse xmlns:localtypes="http://
www.businessobjects.com/DataServices/ServerX.xsd">
<repository>
<repoName>echo_oracle</repoName>
<repoType>local</repoType>
<dbType>Oracle</dbType>
<dbHost>shg-v-imdb02</dbHost>
<connectionStatus>active</connectionStatus>
<username>echo</username>
<permissions>READ,EDIT,DELETE</permissions>
</repository>
<repository>
<repoName>echo_sqlany</repoName>
<repoType>local</repoType>
<dbType>SQL_Anywhere</dbType>
<dbHost>shg-v-imdb03</dbHost>
<connectionStatus>active</connectionStatus>
<username>dba</username>
<permissions>READ,EDIT,DELETE</permissions>
</repository>
</localtypes:GetListOfRepositoriesResponse>
</soapenv:Body>
</soapenv:Envelope>
Integrator Guide
Using SAP Data Services as a web service provider
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
65
3.4
Enabling SSL support
3.4.1 Configuring SSL on the web application server
For SAP Data Services web services to work with SSL, the web application server must be configured to support
SSL connections. The server.xml file can be used to configure the packaged Tomcat application server.
Note
For other web application servers, refer to the product documentation about how to configure SSL support.
1. Open server.xml in a text editor. This file is located in the Tomcat55\conf directory at the same level as
LINK_DIR.
2. Locate the commented connector element in the XML:
<!-- Define a SSL HTTP/1.1 Connector on port 8443 -->
<!-<Connector port="8443" maxHttpHeaderSize="8192"
maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" disableUploadTimeout="true"
acceptCount="100" scheme="https" secure="true"
clientAuth="false" sslProtocol="TLS" />
-->
3. Remove the comment (<!-- -->) tags around the connector element.
4. Add the keystoreFile and keystorePath attributes into the connector element.
keystoreFile="<path/to/keystore/file>"
keystorePass="<keystore_password>"
5. Restart the Tomcat application server.
3.5
Error reporting
SAP Data Services uses web services to define every operation with both an input and output message. In addition
to the output message, the software returns a fault message when an error occurs.
3.5.1 Administrator log
In addition to the fault message, SAP Data Services writes log and debug messages to the Administrator's log file
(webadmin.log). Fault messages include a short description of a failure. For detailed information about an error,
use the Administrator's log file.
All Administrator components share the Administrator's log. The software prefixes these messages with the name
of the component that issues the error message. For web services, the component name is the name of the Java
class issuing the error. All web service classes start with com.acta.adapter.webservice.
66
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Using SAP Data Services as a web service provider
The software creates the Administrator's log file in: <DS_COMMON_DIR>\log\webadmin.log.
To control the level of detail in the webadmin.log file, you must edit the log4j.properties file. The properties
file is located in:
<LINK_DIR>\ext\webserver\webapps\acta_web_admin\WEB-INF
To obtain a debug trace of events, change the log level from the default of INFO to DEBUG. For example,
log4j.rootLogger=DEBUG, A
3.5.2 Web service log
In addition to the shared Administrator log, web service messages are also written to a separate log file. The
WebService.log file is in <DS_COMMON_DIR>\log.
3.5.3 Error messages
The following are error messages that you might encounter if you are using SAP Data Services as a web service
provider to accept inbound calls:
● A web service is unable to process a request due to an unknown function in the soapAction element.
The server returns this error message if the soapAction header in the HTTP request is not recognized. Every
web service call expects a soapAction header that indicates an action. The WSDL publishes a soapAction for
each operation. When the web services server cannot determine what action to take, it is unable to call the
software.
To find extended error information, use the WebService.log file in <DS_COMMON_DIR>/log. To use
extended diagnostics, use debug tracing in the webadmin.log file.
● A web service is unable to process a request to call real-time service <ServiceName> using Access Server
<AccessServerName>.
The server returns this error message when it recognizes a request to call a real-time service but is unable to
extract the XML message from the SOAP Envelope that is supposed to be sent to the real-time service. To
find extended error information, use the WebService.log file in <DS_COMMON_DIR>/log.
To use extended diagnostics, use debug tracing in the webadmin.log file.
● A web service sent a request to invoke real-time service <ServiceName> to Access Server
<AccessServerName>. The request failed with error = <access-server generated error message>
The server returns this error message if it recognizes a request to call a real-time service, data was extracted
from the incoming SOAP Envelope, and data was passed to the Access Server, which refused to service the
request.
To locate where the error occurred use the Access Server log file (
Real-time
<AccessServerName>
Logs - Current ).
If the Access Server passed the request on to the Job Server, use the following logs to diagnose the problem:
○ Job Server log (<DS_COMMON_DIR>/log/<JobServerName>/server_eventlog.txt)
○ Real-time service provider log (
Real-time
<AccessServerName>
<Real-timeServiceName>
<ProcessID> )
● A web service operation is unable to process the request to start batch job <JobName> on server
<JobServerName>. Error = <web services generated error message>
Integrator Guide
Using SAP Data Services as a web service provider
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
67
The server returns this error message if it recognizes a request to start a batch job but is unable get the
information it needs to start the job.
To find extended error information, use the WebService.log file in <DS_COMMON_DIR>/log. To use
extended diagnostics, use debug tracing in the webadmin.log file.
● A web service sent a request to start batch job <JobName> on server <JobServerName>. The Job Server
refused the request with error: <job server generated error message>
The server returns this error message if it recognizes a request to start a batch job and has passed the
request to the Job Server to start the job. The Job Server is unable to start the job. To find extended error
information, use the Job Server log (<DS_COMMON_DIR>/log/<JobServerName>/
server_eventlog.txt).
Related Information
Administrator log [page 66]
3.5.4 Failed Request log
Data Services can write failed request information into a log file.
The Web Services Status tab displays the number of requests that failed, but a log file gives you more information
about each of the failures.
Data Services does not log failed requests by default because it can slow down performance. If you want failed
request information written to a log file, you need to enable this feature.
Note
Failed request logging is not available for the Ping, Logon, or Logoff operations.
3.5.4.1
Enabling/disabling failed request logging
You must have Administrator-level privileges to enable the failed request logging feature.
To enable logging, do the following:
1. Open the Administrator and click Web Services.
2. On the Web Services Configuration page, select one or more operations.
3. Select Enable Failed Request Logging or Disable Failed Request Logging from the drop-down at the bottom of
the page.
4. Click Apply.
Check marks appear in the Failed Request Logging column telling you which operations have the failed request
logging feature enabled.
68
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Using SAP Data Services as a web service provider
3.5.4.2
Viewing the Failed Request log file
To view a Failed Request log file, do the following:
1. Open the Administrator and click Web Services.
2. In the Web Services Status tab, click on the hyperlink text in the Requests Failed column for an operation. A
hyperlink displays only if there are failed requests.
A log viewer opens displaying a flat file that includes the date and time that the error occured, as well as the
failure error message.
Note
Counts listed in the Requests Failed column on the Web Services Status page may not match the counts in
the Failed Request log. This might occur if you turn logging on and off in the middle of an application server
session.
New log files are stored in <DS_COMMON_DIR>/wsstatus/log.
The log file name may contain the operation name, the web service port, and the repository name (if applicable).
For example, Batch_Jobs_Repo_WIN2K8R2_New_Job.txt.
Note
When you restart the application server, the following occurs:
● Log files are deleted.
● Counts listed in the Requests Failed column on the Web Services Status page are reset to zero.
Integrator Guide
Using SAP Data Services as a web service provider
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
69
4
Consuming external web services in SAP
Data Services
You can add functionality to SAP Data Services to invoke web services in external applications from data flows.
This functionality requires configuring the software's built-in web services datastore type. The web services
datastore provides support for locating and importing metadata for a web services server as well as invoking web
service operations.
The web services datastore works by sending a request and waiting until it receives a reply from a web services
server.
For example, you might create a web services server as a front-end to a legacy application. You could call the web
services server daily from a data flow to access inventory and update an inventory data mart.
The interaction between the web services datastore and an external web service has these parts:
● Creating a web services datastore that identifies the WSDL, which describes the web services server.
● Importing metadata to extract the information form the WSDL needed to access the web service server.
● Creating a data flow that uses the imported function call to call the web services server.
4.1
Accessing a web service using the Designer
To configure access to a specific web services, use the Designer to create a web service datastore. SAP Data
Services provides access to web services as stream-oriented function calls, which it configures when you import
metadata.
1. Create a web service datastore.
The following parameters are available when creating a Web Service SOAP datastore:
Parameter
Details
Datastore type
Choose Web Service SOAP.
Web Service URL Specify the URL of the web services server for a data flow to access. It must be the same URL that
accepts a web service connection and returns the WSDL. The datastore connects to the web services
server using the URL to locate the definition of published services.
70
User name
Enter the user name for HTTP basic authentication. Required only if basic authentication is needed to
connect to the web service provider.
Password
Enter the password for HTTP basic authentication. Required only if basic authentication is needed to
connect to the web service provider.
XML Recursion
Level
Enter the number of passes the software should run through the XSD to resolve names. The default is
0.
Keystore path
If the web service provider uses an SSL connection, specify the location of the keystore used to estab­
lish the connection.
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Consuming external web services in SAP Data Services
Parameter
Details
Socket timeout
Enter the maximum number of milliseconds the web service client will wait to receive the response
from the web service provider.
Axis2/c config
file path
Enter the path to your Axis2/c configuration file (axis2.xml). If a path is not specified, the default
path is <LINK_DIR>/ext/webservice-c/axis2.xml.
Proxy host
Enter the host name for the HTTP proxy server. Required only if a proxy server is needed to connect
to the web service provider.
Proxy port
Enter the port number for the HTTP proxy server. Required only if a proxy server is needed to connect
to the web service provider.
Proxy username
Enter the user name for the HTTP proxy server. Required only if a proxy server that uses authentica­
tion is needed to connect to the web service provider.
Proxy password
Enter the password for the HTTP proxy server. Required only if a proxy server that uses authentica­
tion is needed to connect to the web service provider.
The following parameters are available, depending on the Authorization Schema you select, when creating a
Web Service REST datastore:
Parameter
Details
Datastore type
Choose Web Service REST.
Web Service URL
Specify the location of the WADL. You can enter the URL or the path to a local WADL file.
Authorization
schema
Choose one of the following options:
○
○
○
○
○
Basic
Basic + CSRF
Authorization Header
OAuth 1.0 (2-legged)
OAuth 2.0 (2-legged)
Data Services does not support the 3-legged model.
User name
Enter the user name for HTTP basic authentication. Required only if basic authentication is
needed to connect to the web service provider.
Password
Enter the password for HTTP basic authentication. Required only if basic authentication is needed
to connect to the web service provider.
Password Type
Options include Plain and Digest.
CSRF Fetch URL
Enter the location (URL) to fetch the CSRF token. Tokens can be retrieved via a service call to the
server.
CSRF Fetch URL
Method
CSRF Header Key
To retrieve the token, set CSRF Fetch URL Method to GET or POST, CSRF Header Key (case sensi­
tive) to X-CSRF-Token or the server required header key, and CSRF Header Value to Fetch or the
server required value.
CSRF Header Value
Header based api
key or token
Enter the api key or token. For example, Token token=SECRET.
Proxy host
Enter the host name for the HTTP proxy server. Required only if a proxy server is needed to con­
nect to the web service provider.
Proxy port
Enter the port number for the HTTP proxy server. Required only if a proxy server is needed to con­
nect to the web service provider.
Integrator Guide
Consuming external web services in SAP Data Services
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
71
Parameter
Details
Proxy username
Enter the user name for the HTTP proxy server. Required only if a proxy server that uses authenti­
cation is needed to connect to the web service provider.
Proxy password
Enter the password for the HTTP proxy server. Required only if a proxy server that uses authenti­
cation is needed to connect to the web service provider.
Standard HTTP
Header Fields
Enter a header field. Header fields generally contain the operating parameters of an HTTP request
or response.
SSL Pem File
Enter the path and name of the .pem file (private key or certificate).
Dynamic Base URL
Enter the base URL. The base URL is comprised of the protocol, server name, port number, and
path of the service that listens to RESTful web service requests.
You can obtain ths URL from the WADL file under the element resource and attribute base. This is
useful when you have multiple servers serving the same resources and you want to dynamically
create the URL during the call.
Preferred Mediatype The following options are available:
○ Application/XML
○ Application/JSON
Consumer Key for
Oauth
Enter the Consumer Key and Consumer Key Secret for Oauth (equivalent to role account user
names and passwords). You can obtain this information through the web service provider (for ex­
ample, Google Apps or Twitter).
Consumer Key Se­
cret for Oauth
Oauth Token Key
Oauth Token Key
Secret
If the server supports 2-legged OAuth, Data Services does the authentication using the Consumer
key and secret, otherwise, enter the Token Key and Token Key Secret for the Oauth.
This information allows single user authorization. You can obtain this information through the web
service provider (for example, Google Apps or Twitter).
Signature method
Select the signature method for HTTP requests. Options include:
○ HMAC-SHA1 (default)
○ Plain text
Client ID
Enter the Client ID (represents your application) and Client Secret (security key). You can obtain
this information through the web service provider (for example, Google Apps or Twitter).
Client Secret
Access token
Enter the location (API endpoint) of the temporary token. This allows you to access protected re­
sources.
Refresh token
Enter the Refresh Token.
Request token URL
Enter the URL for requesting a temporary token and a URL for getting the final token.
Access token URL
Note
Leave these parameters empty if the server uses only consumer key and secret to access the
protected resource.
72
Grant type
Enter the type of grant access you want to use to obtain an access token. Options include:
○ Client credentials (default): Use your own credentials in order to obtain an access token.
○ Password: Use the resource owner’s password to obtain an access token.
Default configura­
tion
Indicates if you want to use the default configuration (the default is Yes).
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Consuming external web services in SAP Data Services
Parameter
Details
Preferred method
Select the method you want to use to test trusted authentication. Options include:
○ Header String (POST) (default)
○ Query String (GET)
2. Import metadata from the web service datastore
a. From the object library, open the web service datastore.
The Designer calls the web service server at the indicated WSDL or WADL URL and obtains a list of the
published services and ports.
b. Expand the ports to see published operations available for import.
c. Right-click an operation and select Import.
The software imports web service operations as function calls and lists them under the web service
datastore in the object library. Each function call includes a definition for both the input and output
messages required for communication with a web service operation. The Designer extracts the details
about the request and reply messages and generates XML Schema that describes the messages.
3. From the Designer, add a web service function call to a job.
As a web services client, the software calls a web services server twice:
○ During design time to import metadata for the functions and data types that a particular web service
supports.
○ During run time to call the web service and invoke its functionality.
For more information, see “Defining a web service datastore” in the Designer Guide.
Related Information
Configuring HTTP header fields [page 74]
4.2
Adding web service calls to a job
Once a web service datastore is created and metadata is imported, you can add web service function calls to an
SAP Data Services job.
1. Add a Query transform to the data flow.
2. Open the Query editor, right-click the target schema and select New function call.
The Function Editor opens listing the operation metadata that you imported under the datastore name.
3. Select a datastore to view the metadata that you want to add to your job.
4. Select the metadata name and click Next.
5. Map the input schema to the output schema.
Integrator Guide
Consuming external web services in SAP Data Services
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
73
Note
If you want to nest data in the target schema, use this first Query transform to place the schema in your job
and additional Query transforms to perform the nesting. The Function Editor does not allow complex
schema configuration.
6. Click OK.
The imported schema appears in the query.
7. Configure the rest of the data flow by supplying input to the function call and extracting the response
information obtained from the web service.
4.3
Configuring HTTP header fields
In the HyperText Transfer Protocol (HTTP), header fields generally contain the operating parameters of an HTTP
request or response. The header fields define various characteristics of the the data transfer that is requested or
the data that is provided in the message body.
An HTTP header field always starts with a field name, then a colon (:), and ends with the field value. A core set of
header fields is standardized by the Internet Engineering Task force. These standard headers are commonly
understood by all compliant protocol implementations. Header field names may also be any application-specific
strings, known as customary headers.
4.3.1 Configuring standard HTTP header fields
Standard HTTP header fields have specified values that are the same and fixed for all web service functions in the
web service datastore. The values for standard fields also remain the same for all web service calls in a data flow.
1. In the Designer, open the web service datastore configuration and click Advanced.
2. Select Standard HTTP header fields and click ....
The Edit HTTP Header Fields screen appears.
3. Enter each field name and its corresponding default value and click OK.
A semicolon-separated list of the header fields appears in the column for Standard HTTP header fields.
4. Click OK to accept the datastore configuration.
4.3.2 Configuring dynamic HTTP header fields
Dynamic HTTP header fields have values that may be different for each function in the web service datastore. The
values for dynamic fields can also change for each web service call in a data flow.
1. In the Designer, open the web service datastore configuration and click Advanced.
2. Select Dynamic HTTP header fields and click ....
The Edit HTTP Header Fields screen appears.
74
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Consuming external web services in SAP Data Services
3. Enter each field name and the maximum length for its value and click OK.
A semicolon-separated list of the header fields appears in the column for Dynamic HTTP header fields.
4. Click OK to accept the datastore configuration.
When you import a function into the web service datastore, the dynamic HTTP headers are available for mapping
in the HTTPHeader schema.
4.4
Enabling SSL support
4.4.1 Configuring SSL on the native web service datastore
To configure SSL support on the native web service datastore, add the path to your keystore to the datastore
configuration.
Note
The keystore path is only used while importing WSDL operations into the datastore, and is not used at runtime.
For more information about configuring web service datastores, see the Designer Guide.
4.4.2 Configuring SSL in the runtime execution file
1. Obtain a certification authority (CA) certificate for the client.
2. Open LINK_DIR\ext\webservice-c\axis2.xml in a text editor.
3. Locate the commented transportReciever and transportSender elements in the XML:
<transportReceiver name="https" class="axis2_http_receiver">
<parameter name="port" locked="false">6060</parameter>
<parameter name="exposeHeaders" locked="true">false</parameter>
</transportReceiver>
<transportSender name="https" class="axis2_http_sender">
<parameter name="PROTOCOL" locked="false">HTTP/1.1</parameter>
</transportSender>
4. Remove the comment (<!-- -->) tags around the transportReciever and transportSender elements.
5. Provide the path to the CA certificate as the SERVER_CERT parameter.
<parameter name="SERVER_CERT"></path/to/ca/certificate></parameter>
6. If you need client authentication, additionally provide the private key and keystore passphrase.
<parameter name="KEY_FILE"></path/to/client/certificate/chain/file></parameter>
<parameter name="SSL_PASSPHRASE"><passphrase></parameter>
Integrator Guide
Consuming external web services in SAP Data Services
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
75
4.5
Enabling WS-Security support
WS-Security is a communications protocol that applies security to web services at the message level. The
protocol defines how integrity and confidentiality can be enforced on web service messaging, as well as how to
attach signatures and encryption headers to SOAP messages. In addition, it defines how to attach security tokens
such as X.509 certificates or Kerberos tickets to messages.
SAP Data Services implements WS-Security support through the Apache open source project rampart/c and can
be configured through the web service datastore and an external policy file.
4.5.1 Configuring WS-Security on the native web service
datastore
1. Create a security policy file (policy.xml) based on the WS-Security policy specification that satisfies your
security requirements.
You can see sample policy files by downloading a copy of rampart/c and opening the samples/secpolicy
folder.
2. Place your security policy file in the LINK_DIR/ext/webservice-c folder or another location.
3. If your policy file is not named policy.xml or is located in a folder other than the default location, specify the
path using the WSS Policy file path parameter in the datastore configuration.
4. Enable the rampart/c module in your axis2.xml file.
Within axis2.xml, uncomment the <!-- module ref="rampart" /--> line. By default, axis2.xml is
installed to LINK_DIR/ext/webservice-c/.
You can also make more changes in the Advanced section of the native web service datastore configuration:
Table 73:
Parameter
Details
WSS Username
Enter the username to use for WS-Security.
WSS Password
Enter the password to use for WS-Security.
WSS Password type
Enter the password type to use for WS-Security. The available options are
PlainText and Digest.
WSS Time to live
Enter the time for WS-Security protected messages to live. The default is 0. Any
positive number will add a timestamp to the message.
WSS Policy file path
Enter the path to your WS-Security policy file. The default path is
LINK_DIR/ext/webservice-c/policy.xml.
For more information about configuring web service datastores, see the Designer Guide.
76
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Consuming external web services in SAP Data Services
Related Information
WS-Security policy specification
Integrator Guide
Consuming external web services in SAP Data Services
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
77
5
Using the operational statistics API
Use the operational statistics as web services API to retrieve job execution data from the Data Services repository
and local log files.
You can use the following operations to generate dashboards to further analyze and review operational statistics:
Table 74:
Operation
Description
Get_Repository_List
Use the Get_Repository_List operation to get the entire repository list based
on the user's permissions. This operation also returns a list of the reposito­
ries that the user is currently logged into. This operation is part of the
Repo_Operations port.
Get_BatchJob_ExeDetail
Retrieves a list of all job executions for the selected repository and job. You
can also filter the list by time range. This operation is part of the
Batch_Job_Admin port.
Get_BatchJob_FlowDetails
Retrieves details about the tasks included in a job. This operation is part of
the Batch_Job_Admin port.
Get_DF_Auditdata
Shows audit information for a data flow. This operation is part of the
Batch_Job_Admin port.
Get_DF_Monitor_Log
Shows the runtime statistics for single data flow execution. This operation is
part of the Batch_Job_Admin port.
Get_DF_Monitor_Log_Pivot
Shows the runtime statistics as pivoted for a single data flow execution. This
operation is part of the Batch_Job_Admin port.
Related Information
Get_Repository_List [page 64]
Get_BatchJob_ExeDetail [page 33]
Get_BatchJob_FlowDetails [page 35]
Get_DF_Auditdata [page 39]
Get_DF_Monitor_Log [page 41]
Get_DF_Monitor_Log_Pivot [page 43]
5.1
Prerequisites
The operations you use to retrieve operational statistics data are session security enabled.
Before you can call the functions, you need to log onto the system by using the Logon operation.
78
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Using the operational statistics API
To disable session security, do the following:
1. Open Data Services Management Console.
2. Open the Administrator and then click Web Services.
3. Click the Web Services Configuration tab and select the operations for which you want to disable session
security.
4. Choose the Disable Session Security option from the drop-down box at the bottom of the page and click
Apply.
Endpoints
The WSDL URL depends on your web server host and port. You can obtain the endpoint URL from the Data
Services Management Console.
Note
WSDL file version 2.1 supports the operations used to retrieve operational statistics data. Earlier versions do
not support these operations.
The basic format for the URL is as follows:
http://<serverhost>:<port>/DataServices/servlet/webservices?ver=2.1
For example:
http://localhost:8080/DataServices/servlet/webservices?ver=2.1
To get the WSDL file, you need to add "&wsdlxml" to your endpoint. For example:
http://localhost:8080/DataServices/servlet/webservices?ver=2.1&wsdlxml
Related Information
Logon [page 24]
Integrator Guide
Using the operational statistics API
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
79
6
Using the Message Client API
You can integrate SAP Data Services' real-time services by using the C++ or Java API. Either of these interfaces
allows you to connect to the real-time service with a persistent connection to the server, send and receive data
from it, and close the connection.
Note
The Message Client API supports the creation of reports, similar to any job you run with the software.
In the execution of real-time jobs with real-time services APIs, these steps take place:
1. An administrator logs into the Management Console and chooses which real-time jobs to expose as real-time
services. Those job names are stored in the local repository.
2. An administrator chooses which Access Server to run the services on and starts the real-time services.
3. A developer accesses a real-time service through Java and C++ libraries.
4. A C++ or Java application client makes a connection to the Access Server, which then sends information to
various job servers.
5. The job servers route requests to an engine to process the real-time job.
File location
The Message Client API files for each supported platform are installed to <LINK_DIR>\SDK\RTSDK. When the
software is installed on a Windows server, the Message Client API files for both C++ and Java for each UNIX
platform are provided in a .tar.gz archive.
To use the UNIX Message Client API files with a Windows installation, copy the appropriate Message Client API
package file for your UNIX platform from LINK_DIR\SDK\RTSDK\platform to your UNIX system, and then unzip
and extract the archive to the desired installation location. For example, on Solaris:
gunzip MessageClient_Solaris_64bit.tar.gz
tar -xvf MessageClient_Solaris_64bit.tar
6.1
Interface components
The interface between the Access Server and your application includes these components:
● Connection definition (Connection)
A class that defines the connection that your application uses to send and receive messages from the Access
Server. Initialize the class (using the connect method) each time you initialize your application.
● Connection initialization (Connect)
A method that creates the connection using host and port information supplied by the client.
80
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Using the Message Client API
● Request (Invoke)
A method that indicates the request message for the specified real-time service. This method is a
synchronous call that waits for a return.
● Exception handlers (Error message)
A class that returns exceptions thrown by the connection object and system exceptions, if available.
6.2
Creating the connection
The Connection object creates an active connection to the Access Server.
Creating a Connection (calling the Connect method) does the following:
● Authenticates the client as secure
● Produces an open TCP/IP socket between the client and the Access Server
● Encapsulates the connection information into a client identifier (Connection ID)
As soon as you create the Connection object, you can use it to send messages to the Access Server. Typically, you
would create a single Connection per client. If you attempt to call the Connect method for a Connection that
already exists, the Access Server ignores the call.
6.3
Sending messages
Send requests from the client application using the Invoke method and the Connection ID.
Each business operation implemented by your web application can result in a call to the Access Server with a
message. The Access Server uses the name of the business operation to determine the path for the message.
When you use SAP Data Services to process real time jobs, you pair this business operation name, called a
service, with the job and data flow names you defined in the software to process the message. There is a one-toone correlation between business operation, service, job, and XML source.
Call the Invoke method with a string return value to process a synchronous response.
6.4
Closing the connection
The library provides a method (Disconnect) with the Connection object that allows you to systematically close the
TCP/IP socket between the client and the Access Server.
Integrator Guide
Using the Message Client API
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
81
6.5
Pseudo code example
// Login and authenticate the client connection =
connect(
accessServerAddress,
// TCP/HTTP address
clientName,
// matches Access Server
clientPassword);
// IP & Client
// security settings
// Invoke Service String xmlOut =
connection.invoke(
serviceName,
//
//
//
//
has mapping to RT job
xmlIn);
according to the RT job DTD
In case of an error returns the error code
and error message
6.6
C++ API reference
6.6.1 Class RTServiceClient
RTServiceClient
Contains C++ methods for allowing a client to connect to real-time services.
Table 75:
Method summary
virtual void
connect (char* <hostname> unsigned short <port> bool <use_SSL> char*
<trusted_certs_filename>)
virtual char*
invoke (char* serviceName char* inData )
virtual void
disconnect ( )
Constructor detail
RTServiceClient
RTServiceClient(){}
82
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Using the Message Client API
Method detail
connect
virtual void
connect(char* hostname, unsigned short port)
Establishes a connection between a client and the Access Server. You must establish a connection before a
message can be exchanged.
Table 76:
Option
Description
hostname
The name or IP address of the machine that hosts the Access server.
port
The port number used for the connection.
setUseSSL
void setUseSSL(const char* certificate_dir)
Uses SSL when communicating with the Access Server.
certificate_dir - the folder that contains the certificate files. Files with .crt, .pem, and .cer extensions
are used as trusted certificates.
invoke
virtual char* invoke(char* serviceName, char* inData)
Sends the input data to the real-time service and returns the output data.
Table 77:
Option
Description
serviceName
The name of the real-time service to invoke.
inData
The input data to send to the real-time service.
disconnect
virtual void disconnect ()
Stops the connection between a client and the Access Server.
6.6.2 Class RTServiceClientError
RTServiceClientError
Represents an error object thrown by the C++ class RTServiceClient.
Integrator Guide
Using the Message Client API
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
83
Table 78:
Method summary
RTServiceClientError(const char*, int=0)
RTServiceClientError(const char*, const char*, const char*)
RTServiceClientError(const RTServiceClientError&)
Method detail
RTServiceClientError
RTServiceClientError(const char*, int=0)
RTServiceClientError(const char*, const char*, const char*)
RTServiceClientError(const RTServiceClientError&)
Represents an error object thrown by the client library.
6.7
Java API reference
6.7.1 Class RTServiceClient
com.businessobjects.rtsclient.RTServiceClient
Contains Java methods for allowing a client a connection to real-time services.
Table 79:
Method Summary
public void
connect ( char * <machineName> int <port> bool <use_SSL> char*
<trusted_certs_filename> ) throws RTServiceExceptionThrows:
public java.lang.String
invoke (java.lang.String <serviceName>
java.lang.String <inData> ) throws RTServiceExceptionThrows:
public void
disconnect ( ) throws RTServiceExceptionThrows:
Method detail
connect
public void
connect (java.lang.String machineName, int port, bool use_SSL, char*
trusted_certs_filename) throws RTServiceExceptionThrows:
84
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Using the Message Client API
Establishes a connection between a client and the Access Server. You must establish a connection before a
message can be exchanged.
Table 80:
Option
Description
machineName
The name or IP address of the machine that hosts the Access Server.
port
The port number used for the connection.
use_SSL
Indicates that SSL should be used for the connection to the Access Server.
trusted_certs_filename
The path to the file that contains the trusted SSL certificates.
invoke
public java.lang.String invoke(java.lang.String serviceName, java.lang.String
inData) throws RTServiceExceptionThrows:
Sends the input data to the real-time service and returns the output data.
Table 81:
Option
Description
serviceName
The name of the real time service to invoke.
inData
The input data to send to the real time service.
disconnect
public void disconnect ()throws RTServiceExceptionThrows:
Stops the connection between a client and SAP Data Services.
Integrator Guide
Using the Message Client API
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
85
7
Object creation XML toolkit
7.1
Overview
The object creation XML toolkit is a collection of utilities and features that enable you to programmatically create
objects such as jobs, data flows, and work flows from your own application and then import, validate, and execute
them in SAP Data Services.
The toolkit consists of several primary components:
Table 82:
Component
Purpose
XML schema
Used to defines Data Services objects
Designer import and export tools
Used to create template or example XML of objects
Web services
Used to send externally generated objects to Data Services and import, validate, or
execute them
Auxiliary utilities
Used to perform specific tasks required by some jobs, such as datastore password
encryption
7.2
Using the toolkit
In general, the object creation XML toolkit is suitable for two scenarios:
● Exporting Designer-created object definitions for use as templates that are customized with substitution
variables
● Exporting Designer-created object definitions for use as a guideline for creating new object definitions from
scratch
For both scenarios, we recommend that you use the Designer and its import and export capabilities heavily until
you have the object definition to generate from within your own application. After you have suitable object
defintions, you can use web services to import, validate, and execute jobs within Data Services.
The recommended work flow for using the toolkit is:
1. Create templates of your objects in the Designer.
2. Export your objects from the Designer to the XML format.
3. Customize the exported XML objects for generation in your external application.
4. Import, validate, and execute the XML objects generated by your application through Data Services' web
services.
86
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Object creation XML toolkit
7.2.1 Templating objects
A key feature of the object creation XML toolkit is the ability to use the Designer to template your objects. You can
use the Designer to create and debug objects, and then export them to an XML format for customization and use
in your own external application. To create a template object for use in the object creation XML toolkit, the
process is the same as creating any other normal object in the Designer.
Tip
Although it is possible to use only the XML schema to write complete repository objects from scratch, we
strongly recommend that you use the Designer to create your objects due to complex interactions between
many parts of the XML structure.
For more information about using the Designer to create and configure jobs, data flows, transforms, and other
objects, see the Designer Guide.
For more information about configuration options available for specific objects, see the Reference Guide.
7.2.2 Exporting objects
The Designer allows you to export SAP Data Services objects in a standardized, reproducible XML format. When
exporting objects, you can choose to export an entire job or individual objects. Each export option produces a
single XML file that contains all exported objects. If you want to create separate XML files for each object, use the
export editor to individually export each object.
For more information about using the export editor, see the “Export/Import” section of the Administrator Guide.
7.2.3 Adapting objects
Because the options of many XML objects, such as transforms, have complex interactions and do not always
match the way the configuration appears in the Designer, it's strongly recommended that you adapt exported
versions of these objects that have already been mostly configured how you want. By adapting existing objects,
you can be more confident that the objects generated by your application will be free of problems, and function as
you expect.
For example, you can configure several transforms using the Designer and then export them to XML files. In your
application, you can assemble the pre-configured transforms into working data flows, and use web services to
import and run them with Data Services.
Exported objects can still be customized through the use of parameters, as well as simply modifying the XML
directly.
Related Information
Parameters and variables [page 111]
Integrator Guide
Object creation XML toolkit
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
87
7.2.4 Using web services
After generating custom objects in your application, you can use web service operations provided with SAP Data
Services to import, validate, and execute them.
The general process for using the object creation XML toolkit with web service operations has several steps:
1. Log in
If web service security is enabled, use the Logon operation and get a session object.
2. Import objects
Use the Import_Repo_Object operation to import objects to the repository. You can import single or multiple
objects at a time. However, for large XML, you may need to import objects one at a time.
If an error occurs during importing, the operation returns the error message.
3. Validate objects
After the objects have been imported successfully, use the Validate_Repo_Object to perform a semantic
validation. You can also perform the validation on only the highest level object to recursively validate all
dependent objects.
If an error occurs during validation, the operation returns the error message.
4. Execute objects
After the objects have been validated successfully, use the Run_Batch_Job operation to execute the job now
stored in the repository. Use the job name as the parameter for the execution request.
If an error occurs during execution, use the returned runID code and the Get_Error_Log and Get_Trace_Log
operations to retrieve messages specific to this execution of the job.
5. Retrieve operational metadata
Use the runID code returned by Run_Batch_Job along with the Get_Error_Log, Get_Trace_Log, and
Get_Monitor_Log operations to retrieve errors, warnings, trace messages, and performance statistics for this
execution of the job.
6. Remove objects (optional)
If you don't want the objects to persist in the repository after execution, use the Delete_Repo_Objects
operation to remove them. Because the operation does not remove dependencies automatically, you need to
call it once for each object you want to remove.
7. Remove operational metadata
Error and trace logs for non-execution requests are automatically cleared at the completion of each request.
However, execution logs are not automatically cleared, and must be cleaned up manually. You can schedule
the cleanup of execution logs by setting an appropriate log retention period in the Administrator.
For more information, see the Management Console Guide.
8. Log out
If you used the Login operation to take advantage of web services security, use the Logout operation to log
out and end the session.
Related Information
Logon [page 24]
88
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Object creation XML toolkit
Import_Repo_Object [page 60]
Validate_Repo_Object [page 61]
Run_Batch_Job [page 53]
Get_Error_Log [page 45]
Get_Trace_Log [page 53]
Get_Monitor_Log [page 50]
Delete_Repo_Objects [page 58]
Logout [page 25]
7.2.5 Encrypting passwords
For security, passwords for things such as datastore connections are encrypted when stored in the repository.
However, when importing objects, SAP Data Services does not perform the encryption operation. Because of this,
in order to use passwords in externally generated objects, you must use the encrypted form of the password in
the generated XML.
To encrypt passwords outside of Data Services, use the al_encrypt utility included with the object creation XML
toolkit. You can use al_encrypt with parameters for either an existing keyfile or a plain-text passphrase.
By default, al_encrypt outputs the encrypted password to the screen. However, you can use output redirection
to store the encrypted password to a file, and then read the password from that file when generating the XML for
your object. For example:
al_encrypt -e mypassword -p thepassphrase > c:\password.txt
For complete syntax information for al_encrypt, see the Administrator Guide: Command line administration,
Password encryption.
7.2.6 Best practices
When using the object creation XML toolkit, there are a number of best practices that you can follow to simplify
your work flow and minimize any problems that you may encounter.
Importing objects
● While you are allowed to import multiple objects at once, you may need to import objects individually when
the XML syntax is large.
● Objects should be imported into the repository in order. That is, lower level objects in the dependency chain
should be imported before higher level objects. For example, if you have a job that contains a data flow that
uses a file format, you should import the file format, followed by the data flow, and then the job. By properly
maintaining the correct import order, you can avoid cross-referencing issues.
● You can avoid import problems by validating your generated XML before importing. That is, ensuring that
elements are closed correctly, and so on.
Integrator Guide
Object creation XML toolkit
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
89
Validating objects
● Validate your objects using the Designer during your design phase. The validation web service performs only a
runtime validation that is not as comprehensive as the Designer's validation. Validating in the Designer can
provide you with more detailed information that may be helpful in resolving issues.
● You can validate objects individually or recursively by validating a high level object.
Other
● All object definitions must be placed within the correct container element, DataIntegratorExport. You can
place one or more object definitions into the DataIntegratorExport element.
<?xml version="1.0" encoding="UTF-8" ?>
<DataIntegratorExport repositoryVersion="12.2.0.0000" productVersion="12.1.0.0">
<!-- One or more object definitions -->
</DataIntegratorExport>
● Some Data Services objects support expressions. For example, you can assign a query to the output field of a
query transform. In addition, scripts and custom functions are defined as expressions. The expressions used
in these objects are represented twice in exported XML:
1. As an expr attribute with the same format as shown in the Designer
2. As a complex XML hierarchy
When importing these objects, only the format contained in the expr attribute is required.
● For Data Quality transform custom configurations, it is not required to have best practice input and output
fields defined.
7.2.7 Limitations
General limitations
You should be aware of several general limitations when using the object creation XML toolkit:
● Some parts of object validation can only be performed in the Designer user interface.
To more quickly identify and fix validation problems, you can import and validate your objects in the Designer
when you are developing custom objects.
● The web service operations do not support import or bulk loading of Data Cleanse dictionaries.
Before using other web services with the Data Cleanse transform, you must configure the appropriate
dictionaries with the Designer.
90
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Object creation XML toolkit
Concurrent use issues
When multiple users access the same repository concurrently, the Data Services engine locks appropriate tables
and serializes requests so that the repository is always in a structurally valid state. However, you should be aware
of other issues that can arise due to concurrent repository access:
● Referential integrity violation due to object removal
The Delete_Repo_Objects web service operation does not enforce the rule that an object cannot be deleted if
it is being used by other objects. The exception is a datastore, which cannot be deleted if it contains any child
objects.
You should maintain referential object integrity in your application outside Data Services.
● Interference between web service operations
Some available web service operations have the potential to interfere with others if they are currently running.
For example, a job could fail if the job is deleted with the Delete_Repo_Objects operation at the same time it is
being executed with the Run_Batch_Job operation.
You should be careful to synchronize web service operations so that conflicts do not occur.
One way to avoid most concurrent use issues is by maintaining good naming conventions. For example, by using
unique names for objects created in different instances of your application, you can effectively create a
segregated domain for each application instance. As a result, the application instances will not interfere with each
other when performing operations such as creating, modifying, or reading repository objects.
7.3
XML schema reference
The object creation XML toolkit supports the creation and usage of all objects available in Data Services. This
section provides information about the structure and usage of some of the most common objects. For objects not
covered in detail, use the export function of the Designer and the “Objects” section in the Reference Guide as a
guide for creating and using your own objects.
Caution
All examples provided in this section are for reference only. Do not attempt to run them.
Enclosing objects to import
To import XML content into the Data Services repository, it must be enclosed in a DataIntegratorExport element.
Specify the repository and product versions using the repositoryVersion and productVersion attributes.
<?xml version="1.0" encoding="UTF-8" ?>
<DataIntegratorExport repositoryVersion="12.2.0.0000"
productVersion="12.2.0.0">
</DataIntegratorExport>
The DataIntegratorExport element is required only once per XML file, and should contain all objects that you want
to import.
Integrator Guide
Object creation XML toolkit
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
91
7.3.1 Batch job
Tip
It's strongly recommended that you use the Designer to create and export your objects, and then use your
application to adapt them as required. Many object options and parameters interact in complex ways, and do
not always match the way they appear in the Designer.
Creating the object definition
Open the batch job definition with the DIJob element.
<DIJob name="<JobName>" typeId="2">
Specify steps within the job using the DISteps and DICallStep elements.
<DISteps>
<DICallStep typeID="1" calledObjectType="Dataflow"
name="<DataflowName>"></DICallStep>
</DISteps>
Apply job-specific attributes with a DIAttribute block.
<DIAttributes>
<DIAttribute name="job_checkpoint_enabled" value="no" />
<DIAttribute name="job_collect_statistics" value="no" />
<DIAttribute name="job_collect_statistics_monitor"
value="no" />
<DIAttribute name="job_enable_assemblers" value="yes" />
...
</DIAttributes>
End the job definition with the closing tag of the DIJob element.
</DIJob>
Available DIAttribute names
The available DIAttribute names correspond to object parameters and properties, but do not necessarily match
the wording used in the Designer. For a complete description of each attribute, see the “Descriptions of objects”
section in the Designer Guide.
Table 83:
DIAttribute name
Designer
job_checkpoint_enabled
job_collect_statistics
92
Job properties
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Execution options
Collect statistics for optimization
Integrator Guide
Object creation XML toolkit
DIAttribute name
job_collect_statistics_monitor
Designer
Job properties
Execution options
Collect statistics for monitoring
job_monitor_sample_rate
Job properties
Execution options
Monitor sample rate
job_name
Job properties
General
job_trace_abapquery
Job properties
Trace
job_trace_all
Job properties
Execution options
job_trace_ascomm
Job properties
Trace
Access Server Communication
job_trace_assemblers
Job properties
Trace
Assemblers
job_trace_audit
Job properties
Trace
Audit Data
job_trace_dataflow
Job properties
Trace
Data Flow
job_trace_idoc_file
Job properties
Trace
IDoc file reader
job_trace_memory_loader
Job properties
Trace
Memory Target
job_trace_memory_reader
Job properties
Trace
Memory Source
job_trace_optimized_dataflow
Job properties
Trace
Optimized data flow
job_trace_parallel_execution
Job properties
Trace
Trace Parallel Execution
job_trace_rfc_function
Job properties
Trace
RFC Function
job_trace_row
Job properties
Trace
Row
job_trace_script
Job properties
Trace
Scripts and Script Functions
job_trace_session
Job properties
Trace
Session
job_trace_sql_only
Job properties
Trace
SQL Only
job_trace_sqlfunctions
Job properties
Trace
SQL Functions
job_trace_sqlloaders
Job properties
Trace
SQL Loaders
job_enable_assemblers
job_enable_audit
job_enable_dataquality
job_export_repo
job_export_reports
job_isrecoverable
job_mode
Name
job_print_version
job_testmode_enabled
Integrator Guide
Object creation XML toolkit
Trace ABAP Query
Print all trace messages
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
93
DIAttribute name
Designer
job_trace_sqlreaders
Job properties
Trace
SQL Readers
job_trace_sqltransforms
Job properties
Trace
SQL Transforms
job_trace_stored_procedure
Job properties
Trace
Stored Procedure
job_trace_table
Job properties
Trace
Tables
job_trace_table_reader
Job properties
Trace
job_trace_transform
Job properties
Trace
job_trace_userfunction
Job properties
Trace
job_trace_usertransform
Job properties
Trace
job_trace_workflow
Job properties
Trace
Job properties
Execution options
Transform
Work Flow
job_type
job_use_statistics
Use collected statistics
locale_codepage
locale_language
locale_territory
7.3.2 work flow
Tip
It's strongly recommended that you use the Designer to create and export your objects, and then use your
application to adapt them as required. Many object options and parameters interact in complex ways, and do
not always match the way they appear in the Designer.
Creating the object definition
Open the work flow definition with the DIWorkflow element.
<DIWorkflow name="<WorkflowName>" typeId="2">
Specify steps within the work flow using the DISteps, DICallStep, and DIScript elements.
<DISteps>
<DIScript>
<DIUIOptions>
<DIAttribute name="ui_display_name"
value="<ScriptName>" />
</DUIOptions>
94
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Object creation XML toolkit
...
</DIScript>
<DICallStep typeID="1" calledObjectType="Dataflow"
name="<DataflowName>"></DICallStep>
<DIScript>
<DIUIOptions>
<DIAttribute name="ui_display_name"
value="<ScriptName>" />
</DUIOptions>
...
</DIScript>
</DISteps>
Apply workflow-specific attributes with a DIAttribute block.
<DIAttributes>
<DIAttribute name="run_once" value="no" />
<DIAttribute name="unit_of_recovery" value="no" />
</DIAttributes>
End the work flow definition with the closing tag of the DIWorkflow element.
</DIWorkflow>
Available DIAttribute names
The available DIAttribute names correspond to work flow parameters and properties, but do not necessarily
match the wording used in the Designer. For a complete description of each attribute, see the “Descriptions of
objects” section in the Designer Guide.
Table 84:
DIAttribute name
Designer
run_once
Properties
General
Execute only once
unit_of_recovery
Properties
General
Recover as a unit
7.3.3 data flow
Tip
It's strongly recommended that you use the Designer to create and export your objects, and then use your
application to adapt them as required. Many object options and parameters interact in complex ways, and do
not always match the way they appear in the Designer.
Integrator Guide
Object creation XML toolkit
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
95
Creating the object definition
Open the data flow definition with the DIDataflow element.
<DIDataflow name="<DataflowName>" typeId="1">
Invoke transforms within DIDataflow by using the DITransforms element.
<DITransforms>
<DIFileSource typeId="33" formatName="<FileFormatName>"
filename="<filename.txt>"/>
<DIQuery typeId="22"/>
<DIFileTarget typeId="3"/>
...
</DITransforms>
Apply dataflow-specific attributes with a DIAttribute block.
<DIAttributes>
<DIAttribute name="Cache_type" value="pageable_cache" />
<DIAttribute name="Parallelism_degree" value="0" />
<DIAttribute name="allows_both_input_and_output"
value="yes" />
<DIAttribute name="run_once" value="no" />
<DIAttribute name="use_dataflow_links" value="no" />
<DIAttribute name="use_datastore_links" value="yes" />
<DIAttribute name="validation_xform_exists" value="no" />
<DIAttribute name="validation_xform_stats" value="no" />
</DIAttributes>
End the data flow definition with the closing tag of the DIDataflow element.
</DIDataflow>
Available DIAttribute names
The available DIAttribute names correspond to object parameters and properties, but do not necessarily match
the wording used in the Designer. For a complete description of each attribute, see the “Descriptions of objects”
section in the Designer Guide.
Table 85:
DIAttribute name
Designer
Cache_type
Properties
General
Cache type
Parallelism_degree
Properties
General
Degree of parallelism
Properties
General
Execute only once
Properties
General
Use database links
allows_both_input_and_output
run_once
use_dataflow_links
use_datastore_links
96
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Object creation XML toolkit
DIAttribute name
Designer
validation_xform_exists
validation_xform_stats
7.3.4 Script
Tip
It's strongly recommended that you use the Designer to create and export your objects, and then use your
application to adapt them as required. Many object options and parameters interact in complex ways, and do
not always match the way they appear in the Designer.
Creating the object definition
Open the script definition with the DIScript element.
<DIScript>
Specify the name of the script with a DIAttribute element in the DIOptions block.
<DIOptions>
<DIAttribute name="ui_display_name" value="<script_name>" />
</DIOptions>
Include expressions with the DIExpression element. In exported objects, additional XML syntax may be present.
However, this additional syntax is optional; only the expr attribute of DIExpression is required.
<DIExpression isString="true" expr="<script_expression>">
<<Additional optional XML syntax>/>
</DIExpression>
Include functions with the DIFunctionCallStep element. Define the function using a DIExpression element. In
exported objects, additional XML syntax may be present. However, this additional syntax is optional.
<DIFunctionCallStep typeId="23">
<DIExpression isString="true" expr="<function_call>">
<<Additional optional XML syntax>/>
</DIExpression>
</DIFunctionCallStep>
End the script definition with the closing tag of the DIScript element.
</DIScript>
Integrator Guide
Object creation XML toolkit
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
97
Available DIAttribute names
The available DIAttribute names correspond to object parameters and properties, but do not necessarily match
the wording or location used in the Designer. For a complete description of each attribute, see the “Descriptions of
objects” section in the Designer Guide.
Table 86:
DIAttribute name
ui_display_name
Designer
Properties
General
Name
For more information about scripts, see the “Objects, Script” section in the Reference Guide.
7.3.5 File format
Tip
It's strongly recommended that you use the Designer to create and export your objects, and then use your
application to adapt them as required. Many object options and parameters interact in complex ways, and do
not always match the way they appear in the Designer.
Creating the object definition
Open the file format definition with the DIFlatFileDatastore element.
<DIFlatFileDatastore name="<FileFormatName>" typeId="3">
Specify field names, types, and sizes with DIElement elements in the DISchema block.
<DISchema>
<DIElement name="<FieldName1>" datatype="VARCHAR" size="7">
</DIElement>
<DIElement name="<FieldName2>" datatype="VARCHAR" size="7">
</DIElement>
...
</DISchema>
Apply file format-specific attributes with a DIAttribute block.
<DIAttributes>
<DIAttribute name="abap_file_format" value="no" />
<DIAttribute name="blank_pad" value="leading" />
<DIAttribute name="cache" value="yes" />
<DIAttribute name="column_delimiter" value=", " />
...
</DIAttributes>
98
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Object creation XML toolkit
End the file format definition with the closing tag of the DIFlatFileDatastore element.
</DIFlatFileDatastore>
Available DIAttribute names
The available DIAttribute names correspond to object parameters and properties, but do not necessarily match
the wording used in the Designer. For a complete description of each attribute, see the “Descriptions of objects”
section in the Designer Guide.
Table 87:
DIAttribute name
Designer
abap_file_format
File Format Editor
General
Type
adaptable
File Format Editor
General
Adaptable Schema
beginning_of_file_string
File Format Editor
Input/Output
blank_pad
File Format Editor
Default format
File Format Editor
Delimiters
column_width<n>
File Format Editor
Field Size
data_alignment
File Format Editor
General
date_format
File Format Editor
Default Format
Date
datetime_format
File Format Editor
Default Format
Date-Time
end_of_file_string
File Format Editor
Input/Output
escape_character
File Format Editor
Default Format
file_location
File Format Editor
Data File(s)
Location
file_name
File Format Editor
Data File(s)
File name(s)
file_type
File Format Editor
General
ignore_row_markers
File Format Editor
Default Format
locale_codepage
File Format Editor
Locale
Code page
locale_language
File Format Editor
Locale
Language
File Format Editor
General
Name
SAP transport
BOF Marker
Blank padding
cache
column_delimiter
Column
column_width
for column <n>
Data Alignment
EOF Marker
Escape char
file_format
Type
Ignore row marker(s)
locale_territory
name
Integrator Guide
Object creation XML toolkit
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
99
DIAttribute name
Designer
null_indicator
File Format Editor
Default Format
number_of_rows_to_skip
File Format Editor
Input/Output
number_of_threads
File Format Editor
General
reader_capture_data_conversion_errors
File Format Editor
Error handling
Capture data conversion errors
reader_capture_row_format_errors
File Format Editor
Error handling
Capture row format errors
reader_error_file_name
File Format Editor
Error handling
Error file name
reader_error_file_root_dir
File Format Editor
Error handling
Error file root directory
reader_log_data_conversion_warnings
File Format Editor
Error handling
Log data conversion warnings
reader_log_row_format_warnings
File Format Editor
Error handling
Log row format warnings
reader_maximum_warnings_to_log
File Format Editor
Error handling
Maximum warnings to log
reader_write_error_rows_to_file
File Format Editor
Error handling
Write error rows to file
root_dir
File Format Editor
Data File(s)
row_delimiter
File Format Editor
Delimiters
skip_row_header
File Format Editor
Input/Output
time_format
File Format Editor
Default Format
transfer_argument
File Format Editor
Custom Transfer
transfer_custom
File Format Editor
General
transfer_name
File Format Editor
Custom Transfer
Program executable
transfer_password
File Format Editor
Custom Transfer
Password
transfer_user
File Format Editor
Custom Transfer
User name
write_bom
File Format Editor
Input/Output
Write BOM
write_row_header
File Format Editor
Input/Output
Write row header
NULL inicator
Skipped rows
Parallel process threads
Root directory
Row
Skip row header
table_weight
Time
Arguments
Custom transfer program
use_root_dir
7.3.5.1
Using as a source
To use a file format as a source within a data flow, invoke the format with the DIFileSource element. The
DIFileSource element must be placed within the DITransforms section of a data flow.
<DIFileSource typeId="33" formatName="<FormatName>"
filename="<FileName>">
100
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Object creation XML toolkit
Define the name of the source with a DIAttribute element.
<DIUIOptions>
<DIAttribute name="ui_display_name" value="<SourceName>" />
</DIUIOptions>
Specify a name for the output schema with the DIOutputView element. By default, it is set to the format name.
However, you can change it to any unique string, and use it in all downstream transforms.
<DIOutputView name="<SchemaName>" />
Apply source-specific attributes with a DIAttribute block.
<DIAttributes>
<DIAttribute name="adaptable" value="no" />
<DIAttribute name="cache" value="yes" />
<DIAttribute name="connection_port" value="no" />
<DIAttribute name="file_location" value="local" />
...
</DIAttributes>
End the source definition, with the closing tag of the DIFileSource element.
</DIFileSource>
Available DIAttribute names
The available DIAttribute names correspond to object parameters and properties, but do not necessarily match
the wording or location used in the Designer. For a complete description of each attribute, see the “Descriptions of
objects” section in the Designer Guide.
Table 88:
DIAttribute name
Designer
adaptable
Source File Editor
General
Adaptable Schema
cache
Source File Editor
General
Cache
file_location
Source File Editor
Data File(s)
name
Source File Editor
General
reader_capture_data_conver­
sion_errors
Source File Editor
Error handling
Capture data conversion errors
reader_capture_row_for­
mat_errors
Source File Editor
Error handling
Capture row format errors
reader_filename_col
Source File Editor
Source information
Column name
reader_filename_col_size
Source File Editor
Source information
Column size
reader_filename_only
Source File Editor
Source information
Include path
connection_port
Integrator Guide
Object creation XML toolkit
Location
Name
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
101
DIAttribute name
Designer
reader_include_filename
Source File Editor
Source information
reader_log_data_conver­
sion_warnings
Source File Editor
Error handling
Log data conversion warnings
reader_log_row_for­
mat_warnings
Source File Editor
Error handling
Log row format warnings
reader_maximum_warn­
ings_to_log
Source File Editor
Error handling
Maximum warnings to log
reader_write_er­
ror_rows_to_file
Source File Editor
Error handling
Write error rows to file
root_dir
Source File Editor
Data File(s)
Source File Editor
General
Include file name column
Root directory
table_weight
transfer_custom
7.3.5.2
Custom transfer program
Using as a target
To use a file format as a target within a data flow, invoke the format with the DIFileTarget element. The
DIFileTarget element must be placed within the DITransforms section of a data flow.
<DIFileTarget typeId="3" formatName="<FormatName>"
filename="<FileName>">
Define the name of the target with a DIAttribute element.
<DIUIOptions>
<DIAttribute name="ui_display_name" value="<TargetName>" />
</DIUIOptions>
Specify a name for the input schema with the DIInputView element. By default, it is set to the format name.
However, you can change it to any unique string, and use it in all downstream transforms.
<DIInputView name="<SchemaName>" />
Apply target-specific attributes with a DIAttribute block.
<DIAttributes>
<DIAttribute name="connection_port" value="no" />
<DIAttribute name="file_location" value="local" />
<DIAttribute name="isstreamdebugfile" value="no" />
<DIAttribute name="loader_load_choice" value="replace" />
...
</DIAttributes>
End the target definition, with the closing tag of the DIFileTarget element.
</DIFileTarget>
102
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Object creation XML toolkit
Available DIAttribute names
The available DIAttribute names correspond to object parameters and properties, but do not necessarily match
the wording or location used in the Designer. For a complete description of each attribute, see the “Descriptions of
objects” section in the Designer Guide.
Table 89:
DIAttribute name
Designer
connection_port
Target File Editor
General
file_location
Target File Editor
Data File(s)
name
Target File Editor
General
root_dir
Target File Editor
Data File(s)
transfer_custom
Target File Editor
General
validate_decimal_data
Target File Editor
Default Format
Make port
Location
isstreamdebugfile
loadler_load_choice
Name
Root directory
Custom transfer program
Validate decimal data
7.3.6 Database datastore
Tip
It's strongly recommended that you use the Designer to create and export your objects, and then use your
application to adapt them as required. Many object options and parameters interact in complex ways, and do
not always match the way they appear in the Designer.
Creating the object definition
Open the database datastore definition with the DIDatabaseDatastore element.
<DIDatabaseDatastore name="<datastore_name>" typeId="3">
Apply database datastore-specific attributes with a DIAttribute block.
<DIAttributes>
<DIAttribute
<DIAttribute
<DIAttribute
<DIAttribute
...
<DIAttribute
Integrator Guide
Object creation XML toolkit
name="DBLiveLoad" value="no" />
name="application_type" value="Custom" />
name="cdc_enabled" value="no" />
name="datastore_repotype" value="local" />
name="ds_configurations" hasNestedXMLTree="true">
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
103
Specify one or more datastore configurations inside the DIAttribute block with a DSConfigurations block. Only one
configuration can be set as default.
<DSConfigurations>
<DSConfiguration default="true" name="<configuration_name>">
<case_sensitive>no</case_sensitive>
<database_type>Microsoft_SQL_Server</database_type>
<loader_xact_size>1000</loader_xact_size>
<locale_codepage>default</locale_codepage>
<locale_language>default</locale_language>
<locale_territory>default</locale_territory>
<mssql_windows_authentication>
no
</mssql_windows_authentication>
<password>;907A8897CEF453232929BD93946</password>
<server_codepage>default</server_codepage>
<sql_server_database>
DS32_Source
</sql_server_database>
<sql_server_dataserver>
testMachine
</sql_server_dataserver>
<sql_server_version>
Microsoft SQL Server 2000
</sql_server_version>
<user>ods</user>
</DSConfiguration>
</DSConfigurations>
Close the DIAttribute block.
</DIAttribute>
</DIAttributes>
End the database datastore definition with the closing tag of the DIDatabaseDatastore element.
</DIDatabaseDatastore>
Available DIAttribute names
The available DIAttribute names correspond to object parameters and properties, but do not necessarily match
the wording or location used in the Designer. The specific DIAttributes and XML elements available vary greatly
depending on which type of database you are accessing. It's recommended that you create your datastore
definitions using the Designer and then export them to XML.
For a complete description of each attribute, see the “Descriptions of objects” section in the Designer Guide.
7.3.7 Database table
Tip
It's strongly recommended that you use the Designer to create and export your objects, and then use your
application to adapt them as required. Many object options and parameters interact in complex ways, and do
not always match the way they appear in the Designer.
104
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Object creation XML toolkit
Creating the object definition
Open the database table definition with the DITable element.
<DITable name="<TableName>" owner="<Owner>"
datastore="<DatastoreName>" database="<DatabaseName>"
description="<Description>">
Apply table-specific properties with a DIProperties block. To define the table as a template table, set the value of
the Loader_Is_Template_Table DIAttribute to yes.
<DIProperties>
<DIAttribute name="Table_Type" value="TABLE" />
<DIAttribute name="Estimated_Row_Count" value="50000" />
<DIAttribute name="Loader_Is_Template_Table" value="no" />
<DIAttribute name="db_alias_name" value="ODS" />
...
</DIProperties>
Specify column definitions with DIColumn elments. You can also define the content type for a column with the
Content_Type attribute.
<DIColumn name="Cust_ID" datatype="VARCHAR" size="10"
nullable="false" />
<DIColumn name="Cust_classf" datatype="VARCHAR" size="2"
nullable="true" />
<DIColumn name="Address" datatype="VARCHAR" size="35"
nullable="true" Content_Type="ADDRESS">
<DIProperties>
<DIAttribute name="Content_Type" value="ADDRESS" />
</DIProperties>
</DIColumn>
Define the primary keys with a DIPrimaryKey block.
<DIPrimaryKey>
<DIPrimaryKeyColumn name="Cust_ID" />
</DIPrimaryKey>
Define the unique table index with a DITableIndex element and specify the column name in a DIIndexColumn
element.
<DITableIndex name="PK__ODS_CUSTOMER__7C8480A" unique="true">
<DIIndexColumn name="Cust_ID" />
</DITableIndex>
End the database table definition with the closing tag of the DITable element.
</DITable>
Available DIAttribute names
The available DIAttribute names correspond to object parameters and properties, but do not necessarily match
the wording or location used in the Designer. For a complete description of each attribute, see the “Descriptions of
objects” section in the Designer Guide.
Integrator Guide
Object creation XML toolkit
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
105
7.3.7.1
Using as a source
To use a database table as a source within a data flow, invoke the table with the DIDatabaseTableSource element.
The DIDatabaseTableSource element must be placed within the DITransforms section of a data flow.
<DIDatabaseTableSource typeId="22" datastoreName="<DatastoreName>"
ownerName="<OwnerName>" tableName="<TableName>">
Specify a name for the output schema with the DIOutputView element.
<DIOutputView name="<SchemaName>" />
Apply source-specific attributes with a DIAttribute block.
<DIAttributes>
<DIAttribute name="array_fetch_size" value="1000" />
<DIAttribute name="cache" value="yes" />
<DIAttribute name="connection_port" value="no" />
<DIAttribute name="enable_partitioning" value="no" />
...
</DIAttributes>
End the source definition, with the closing tag of the DIDatabaseTableSource element.
</DIDatabaseTableSource>
Available DIAttribute names
The available DIAttribute names correspond to object parameters and properties, but do not necessarily match
the wording or location used in the Designer. For a complete description of each attribute, see the “Descriptions of
objects” section in the Designer Guide.
Table 90:
DIAttribute name
Designer
array_fetch_size
Source Table Editor
Performance
Array fetch size
cache
Source Table Editor
Performance
Cache
connection_port
Source Table Editor
Make port
Source Table Editor
Datastore name
enable_partitioning
name
package_size
reader_is_DB2CDC_table
reader_overflow_file
reader_template_table
reader_use_overflow_file
106
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Object creation XML toolkit
DIAttribute name
Designer
table_weight
7.3.7.2
Source Table Editor
Performance
Join rank
Using as a target
To use a database table as a target within a data flow, invoke the table with the DIDatabaseTableTarget element.
The DIDatabaseTableTarget element must be placed within the DITransforms section of a data flow.
<DIDatabaseTableTarget typeId="11" bulkLoader="false"
datastoreName="<DatastoreName>" ownerName="<OwnerName>"
tableName="<TableName>">
Specify a name for the input schema with the DIInputView element.
<DIInputView name="<SchemaName>" />
Apply target-specific attributes with a DIAttribute block.
<DIAttributes>
<DIAttribute name="connection_port" value="no" />
<DIAttribute name="loader_template_table" value="yes" />
...
<DIAttribute name="ldr_configuration_enabled"
value="yes" />
<DIAttribute name="ldr_configurations"
hasNestedXMLTree="true">
Specify the target configuration inside the DIAttribute block with a LDRConfigurations block.
<LDRConfigurations>
<LDRConfiguration database_type="Microsoft_SQL_Server"
database_version="Microsoft SQL Server 2000">
<auto_correct_using_merge>Yes</auto_correct_using_merge>
<bulk_ldr_all_rows></bulk_ldr_all_rows>
<bulk_ldr_max_errors></bulk_ldr_max_errors>
<bulk_ldr_rows_per_commit></bulk_ldr_rows_per_commit>
<enable_partitioning>no</enable_partitioning>
<ignore_column_case>yes</ignore_column_case>
<ignore_columns_null>No</ignore_columns_null>
<ignore_columns_value></ignore_columns_value>
<loader_auto_correct>no</loader_auto_correct>
<loader_bulk_load>0</loader_bulk_load>
...
</LDRConfiguration>
</LDRConfigurations>
Close the DIAttribute block.
</DIAttribute>
</DIAttributes>
End the target definition, with the closing tag of the DIDatabaseTableTarget element.
</DIDatabaseTableTarget>
Integrator Guide
Object creation XML toolkit
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
107
Available DIAttribute names
The available DIAttribute names correspond to object parameters and properties, but do not necessarily match
the wording or location used in the Designer. The specific DIAttributes and XML elements available vary greatly
depending on which type of database you are accessing. It's recommended that you create your database table
targets using the Designer and then export them to XML.
For a complete description of each attribute, see the “Descriptions of objects” section in the Designer Guide.
Table 91:
DIAttribute name
Designer
connection_port
Target Table Editor
Target
Make port
name
Target Table Editor
Target
Datastore name
use_unicode_varchar
7.3.8 Data Quality transforms
The options of Data Quality transforms have complex interactions and do not always match the way the transform
configuration appears in the Designer. It's strongly recommended that you adapt exported versions of these
transforms that have already been mostly configured how you want. By adapting existing objects, you can be
more confident that the objects generated by your application will be free of problems, and function as you
expect.
Because of the complexity of the Data Quality transforms, XSD files are provided for each transform. By default,
the XSD files are installed to LINK_DIR\Admin.
Note
XML exported from the Designer may not validate correctly against the provided XSD files due to element
ordering. However, any objects created by using the XSD files will operate correctly when imported to SAP
Data Services.
Related Information
Adapting objects [page 87]
7.3.8.1
Hierarchy and inheritance
The ability to reuse transform configurations is a powerful feature of all Data Quality transforms available in SAP
Data Services. To successfully use Data Quality transforms with the object creation XML toolkit, it's important to
understand the rules of option inheritance and configuration reuse.
108
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Object creation XML toolkit
Data Quality transforms support three levels of configurations: base configuration, custom configuration, and
instance configuration. Each level of configuration inherits the options and settings from the levels below it.
However, settings defined explicitly at a higher level always take precedence over those inherited from a lower
level.
In the Designer, the base configuration is simply represented in the form of the base transform. For example, the
Global_Address_Cleanse transform. The base configuration carries the default settings for all options available for
that transform. If you double-click any base transform, the configuration is opened in the Transform Configuration
Editor. The Options tab lists all options set on the base configuration.
The custom configuration inherits the default settings from the base configuration, but also provides the ability to
modify the values of any options at the custom level. In the Designer, the custom configuration level is
represented by the available transform configurations. For example, for Global Address Cleanse, custom
transform configurations such as Australia_AddressCleanse, Europe_AddressCleanse, and USA_AddressCleanse
are available. For more information about transform configurations, see the “Data Flows, Transforms” section in
the Designer Guide.
The instance configuration inherits default settings from the custom configuration, and provides the ability to
further modify the values of any options. In the Designer, the instance configuration is represented by a transform
instance within a data flow.
7.3.9 Query transform
Tip
It's strongly recommended that you use the Designer to create and export your objects, and then use your
application to adapt them as required. Many object options and parameters interact in complex ways, and do
not always match the way they appear in the Designer.
Integrator Guide
Object creation XML toolkit
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
109
Creating the object definition
Open the query transform definition with the DIQuery element.
<DIQuery typeId="122">
Specify the name of the query transform and additional user interface options, such as the SQL where clause, in
the DIUIOptions block.
<DIUIOptions>
<DIAttribute name="ui_display_name" value="QryCDC" />
<DIAttribute name="ui_where_text" value="<WhereClause>" />
</DIUIOptions>
Define the output schema with DIElement elements within a DISchema block. The input schema for each field is
defined in the ui_mapping_text attribute, using the format <InputSchemaName>.<InputFieldName>.
<DISchema name="QryCDC">
<DIElement name="CUST_ID" datatype="VARCHAR" size="10" key="true">
<DIAttributes>
<DIAttribute name="Description" value="" />
<DIAttribute name="ui_mapping_text"
value="ODS_CUSTOMER.CUST_ID" />
</DIAttributes>
</DIElement>
<DIElement name="CUST_CLASSF" datatype="VARCHAR" size="2">
<DIAttributes>
<DIAttribute name="Description" value="" />
<DIAttribute name="ui_mapping_text"
value="ODS_CUSTOMER.CUST_CLASSF" />
</DIAttributes>
</DIElement>
...
</DISchema>
Define the expression for each output field with DIExpression elements within a DIProjection block. For exported
XML, additional XML syntax for the output field may be present, but only the form used in the expr attribute is
required.
<DISelect>
<DIProjection>
<DIExpression isString="true" expr="ODS_CUSTOMER.CUST_ID">
<COLUMN_REFERENCE qualifier1="ODS_CUSTOMER"
column="CUST_ID" />
</DIExpression>
<DIExpression isString="true"
expr="ODS_CUSTOMER.CUST_CLASSF" />
</DIProjection>
Specify the input schema in the DIFrom element.
<DIFrom>
<DITableSpec name="ODS_CUSTOMER" />
</DIFrom>
Define the SQL where clause with a DIExpression element within a DIWhere block. For exported XML, additional
XML syntax for the expression may be present, but only the form used in the expr attribute is required. The format
is the same as it appears in the Designer.
<DIWhere>
110
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Object creation XML toolkit
<DIExpression isString="true"
expr="((ODS_CUSTOMER.CUST_TIMESTAMP &gt;=
$GV_STARTTIME) AND$#xA; (ODS_CUSTOMER.CUST_TIMESTAMP
&lt;= $GV_ENDTIME))">
<!-- Additional XML syntax -->
</DIExpression>
</DIWhere>
</DISelect>
Apply query-specific attributes with a DIAttribute block.
<DIAttributes>
<DIAttribute name="distinct_run_as_separate_process"
value="no" />
<DIAttribute name="group_by_run_as_separate_process"
value="no" />
<DIAttribute name="join_run_as_separate_process"
value="no" />
<DIAttribute name="order_by_run_as_separate_process"
value="no" />
...
</DIAttributes>
End the query transform definition with the closing tag of the DIQuery element.
</DIQuery>
Available DIAttribute names
The available DIAttribute names correspond to object parameters and properties, but do not necessarily match
the wording or location used in the Designer. For a complete description of each attribute, see the “Descriptions of
objects” section in the Designer Guide.
Table 92:
DIAttribute name
Designer
distinct_run_as_separate_process
Query Editor
Advanced
Run DISTINCT as a separate process
group_by_run_as_separate_process
Query Editor
Advanced
Run GROUP BY as a separate process
join_run_as_separate_process
Query Editor
Advanced
Run JOIN as a separate process
order_by_run_as_separate_process
Query Editor
Advanced
Run ORDER BY as a separate process
run_as_separate_process
7.3.10 Parameters and variables
You can increase the flexibility and reusability of components generated by your application by using local and
global variables when designing your jobs. For more information about including variables and parameters in the
design of your jobs, see the “Variables and Parameters” section of the Designer Guide.
Integrator Guide
Object creation XML toolkit
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
111
Global variables
Global variables can be accessed in XML within the DIScript element. For example, to assign a constant value to a
global variable, you could use the DIAssignmentStep element:
<DIAssignmentStep typeId="12" variable="$GV_STARTTIME">
<DIExpression isString="true"
expression="'2001.01.01 00:00:000'" />
</DIAssignmentStep>
After the global variable is defined, you can use it elsewhere in script expressions used by your job. For example,
you might insert the value of the variable into a table using a SQL query:
<DIFunctionCallStep typeId="23">
<DIExpression isString="true"
expr="sql('Target_DS', 'INSERT INTO TARGET.CDC_TIME
VALUES ({$GV_STARTTIME})')" />
</DIFunctionCallStep>
For more information about using global variables in your jobs, see the “Variables and Parameters, Using global
variables” section of the Designer Guide.
Substitution parameters
You can import one or more substitution parameter configurations to the repository with the Import_Repo_Object
web service operation, as well as the Designer. In XML, substitution parameters are specified within the
DISubVarStore and SVConfigurations elements.
<DISubVarStore typeId="103">
<SVConfigurations>
A default configuration can be specified with the DIAttribute element. This element is not required to import the
substitution parameters.
<DIAttributes>
<DIAttribute name="SV_Config_Default"
value="Configuration_1" />
</DIAttributes>
Specify a substitution parameter configuration with the SVConfiguration and SubVar elements. You can include
more than one SVConfiguration block to specify additional substitution parameter configurations.
<SVConfiguration name="Configuration_1">
<SubVar name="ReportsAddressCleanse">1</SubVar>
<SubVar name="ReportsMatch">2</SubVar>
<SubVar name="USPSProviderLevel">3</SubVar>
<SubVar name="RefFilesAddressCleanse">4</SubVar>
...
</SVConfiguration>
</SVConfigurations>
</DISubVarStore>
After importing the substitution parameter configurations to the repository, they can be used normally in your
data flows. For more information about using substitution parameters, see the “Variables and Parameters,
Substitution parameters” section of the Designer Guide.
112
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Object creation XML toolkit
7.3.11 Basic example
This example assumes that you have a simple job named myTestJob that calls a data flow named
myTestDataflow. The data flow contains a flat-file source (mySource), a Query transform (FormatFields), and a
flat-file target (myTarget).
Additionally, this example assumes that all objects for the job have been exported to a single XML file.
Example
All object definitions are enclosed in the DataIntegratorExport element.
<?xml version="1.0" encoding="UTF-8" ?>
<DataIntegratorExport repositoryVersion="12.2.0.0000"
productVersion="12.2.0.0">
The NameDate flat-file format definition is contained in the DIFlatFileDatastore element. Field names, types, and
sizes are defined in the DISchema block.
<DIFlatFileDatastore name="NameDate" typeId="3">
<DISchema>
<DIElement name="FirstName" datatype="VARCHAR" size="7">
</DIElement>
<DIElement name="LastName" datatype="VARCHAR" size="7">
</DIElement>
<DIElement name="DateOfBirth" datatype="VARCHAR" size="10">
</DIElement>
</DISchema>
Various attributes, such as file name, directory, file type, column delimiter, and locale settings are specified in the
DIAttributes block, and the flat-file format definition is closed.
<DIAttributes>
<DIAttribute name="abap_file_format" value="no" />
<DIAttribute name="blank_pad" value="leading" />
<DIAttribute name="cache" value="yes" />
<DIAttribute name="column_delimiter" value="," />
<DIAttribute name="column_width" value="1" />
<DIAttribute name="column_width1" value="7" />
<DIAttribute name="column_width2" value="7" />
<DIAttribute name="column_width3" value="10" />
<DIAttribute name="date_format" value="yyyy.mm.dd" />
<DIAttribute name="datetime_format"
value="yyyy.mm.dd hh24:mi:ss" />
<DIAttribute name="file_format" value="ascii" />
<DIAttribute name="file_location" value="local" />
<DIAttribute name="file_name" value="NameDate.txt" />
<DIAttribute name="file_type" value="delimited_file" />
<DIAttribute name="locale_codepage" value="&lt;default&gt;" />
<DIAttribute name="locale_language" value="&lt;default&gt;" />
<DIAttribute name="locale_territory"
value="&lt;default&gt;" />
<DIAttribute name="name" value="NameDate" />
<DIAttribute name="reader_capture_data_conversion_errors"
value="no" />
<DIAttribute name="reader_capture_row_format_errors"
value="yes" />
<DIAttribute name="reader_error_file_name" value="" />
Integrator Guide
Object creation XML toolkit
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
113
<DIAttribute name="reader_error_file_root_dir" value="" />
<DIAttribute name="reader_log_data_conversion_warnings"
value="yes" />
<DIAttribute name="reader_log_row_format_warnings"
value="yes" />
<DIAttribute name="reader_maximum_warnings_to_log"
value="-99" />
<DIAttribute name="reader_write_error_rows_to_file"
value="no" />
<DIAttribute name="root_dir"
value="C:\Data Services\Tutorial Files" />
<DIAttribute name="row_delimiter" value="\n" />
<DIAttribute name="skip_row_header" value="yes" />
<DIAttribute name="table_weight" value="0" />
<DIAttribute name="time_format" value="hh24:mi:ss" />
<DIAttribute name="transfer_custom" value="no" />
<DIAttribute name="use_root_dir" value="no" />
<DIAttribute name="write_bom" value="no" />
</DIAttributes>
</DIFlatFileDatastore>
The myTestJob job definition is contained in the DIJob element. The job contains a single step, calling the
myTestdata flow data flow. Again, attributes related to tracing, statistics, and so on are found in the DIAttributes
block.
<DIJob name="myTestJob" typeId="2">
<DISteps>
<DICallStep typeId="1" calledObjectType="Dataflow"
name="myTestDataflow" >
</DICallStep>
</DISteps>
<DIAttributes>
<DIAttribute name="job_checkpoint_enabled" value="no" />
<DIAttribute name="job_collect_statistics" value="no" />
<DIAttribute name="job_collect_statistics_monitor"
value="no" />
<DIAttribute name="job_enable_assemblers" value="yes" />
<DIAttribute name="job_enable_audit" value="yes" />
<DIAttribute name="job_enable_dataquality" value="yes" />
<DIAttribute name="job_export_repo" value="no" />
<DIAttribute name="job_export_reports" value="no" />
<DIAttribute name="job_isrecoverable" value="no" />
<DIAttribute name="job_mode" value="Multi-Process" />
<DIAttribute name="job_monitor_sample_rate" value="1000" />
<DIAttribute name="job_name" value="myTestJob" />
<DIAttribute name="job_print_version" value="no" />
<DIAttribute name="job_testmode_enabled" value="no" />
<DIAttribute name="job_trace_abapquery" value="no" />
<DIAttribute name="job_trace_all" value="no" />
<DIAttribute name="job_trace_ascomm" value="no" />
<DIAttribute name="job_trace_assemblers" value="no" />
<DIAttribute name="job_trace_audit" value="no" />
<DIAttribute name="job_trace_dataflow" value="yes" />
<DIAttribute name="job_trace_idoc_file" value="no" />
<DIAttribute name="job_trace_memory_loader" value="no" />
<DIAttribute name="job_trace_memory_reader" value="no" />
<DIAttribute name="job_trace_optimized_dataflow"
value="no" />
<DIAttribute name="job_trace_parallel_execution"
value="no" />
<DIAttribute name="job_trace_rfc_function" value="no" />
<DIAttribute name="job_trace_row" value="no" />
<DIAttribute name="job_trace_script" value="no" />
<DIAttribute name="job_trace_session" value="yes" />
<DIAttribute name="job_trace_sql_only" value="no" />
<DIAttribute name="job_trace_sqlfunctions" value="no" />
<DIAttribute name="job_trace_sqlloaders" value="no" />
114
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Object creation XML toolkit
<DIAttribute name="job_trace_sqlreaders" value="no" />
<DIAttribute name="job_trace_sqltransforms" value="no" />
<DIAttribute name="job_trace_stored_procedure" value="no" />
<DIAttribute name="job_trace_table" value="no" />
<DIAttribute name="job_trace_table_reader" value="no" />
<DIAttribute name="job_trace_transform" value="no" />
<DIAttribute name="job_trace_userfunction" value="no" />
<DIAttribute name="job_trace_usertransform" value="no" />
<DIAttribute name="job_trace_workflow" value="yes" />
<DIAttribute name="job_type" value="batch" />
<DIAttribute name="job_use_statistics" value="yes" />
<DIAttribute name="locale_codepage"
value="&lt;default&gt;" />
<DIAttribute name="locale_language"
value="&lt;default&gt;" />
<DIAttribute name="locale_territory"
value="&lt;default&gt;" />
</DIAttributes>
</DIJob>
The myTestdata flow data flow definition is contained in the DIDataflow element.
<DIDataflow name="myTestDataflow" typeId="1">
Transforms are invoked within the DITransforms element. Because this data flow has three transforms, source,
Query, and target, there are three corresponding sections in the DITransforms element.
<DITransforms>
The file-format source definition is contained in the DIFileSource element. The name of the output schema is
specified with the DIOutputView element. By default, the schema is given the same name as the file format.
However, you can change it to any unique name, provided you use the same name in later transforms.
<DIFileSource typeId="33" formatName="NameDate"
filename="NameDate.txt">
<DIUIOptions>
<DIAttribute name="ui_display_name" value="mySource" />
</DIUIOptions>
<DIOutputView name="NameDate" />
<DIAttributes>
<DIAttribute name="adaptable" value="no" />
<DIAttribute name="cache" value="yes" />
<DIAttribute name="connection_port" value="no" />
<DIAttribute name="file_location" value="local" />
<DIAttribute name="name" value="NameDate" />
<DIAttribute name="reader_filename_col"
value="DI_FILENAME" />
<DIAttribute name="reader_filename_col_size" value="100" />
<DIAttribute name="reader_filename_only" value="no" />
<DIAttribute name="reader_include_filename" value="no" />
<DIAttribute name="reader_maximum_warnings_to_log"
value="-99" />
<DIAttribute name="root_dir"
value="C:\Data Services\Tutorial Files" />
<DIAttribute name="table_weight" value="0" />
</DIAttributes>
</DIFileSource>
The FormatFields Query transform definition is contained in the DIQuery element. The output schema name is
specified with the DISchema element.
<DIQuery typeId="122" >
<DIUIOptions>
Integrator Guide
Object creation XML toolkit
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
115
<DIAttribute name="ui_display_name" value="FormatFields" />
</DIUIOptions>
<DISchema name="FormatFields">
Each output field is defined with DIElement and DIAttributes elements. The ui_mapping_text attribute for each
output field is required by the Designer. For the Full Name output field, the expression shows the concatenation of
two input fields (FirstName and LastName). The additional encoded text is used to maintain formatting within the
Designer and is optional.
<DIElement name="FirstName" datatype="VARCHAR" size="7">
<DIAttributes>
<DIAttribute name="Description" value="" />
<DIAttribute name="ui_mapping_text"
value="NameDate.FirstName" />
</DIAttributes>
</DIElement>
<DIElement name="LastName" datatype="VARCHAR" size="7">
<DIAttributes>
<DIAttribute name="Description" value="" />
<DIAttribute name="ui_mapping_text"
value="NameDate.LastName" />
</DIAttributes>
</DIElement>
<DIElement name="DateOfBirth" datatype="VARCHAR" size="10">
<DIAttributes>
<DIAttribute name="Description" value="" />
<DIAttribute name="ui_mapping_text"
value="NameDate.DateOfBirth" />
</DIAttributes>
</DIElement>
<DIElement name="Full Name" datatype="VARCHAR" size="20">
<DIAttributes>
<DIAttribute name="Description" value="" />
<DIAttribute name="ui_mapping_text"
value="NameDate.FirstName ||
NameDate.LastName&#xD;&#xA;&#xD;&#xA;" />
</DIAttributes>
</DIElement>
</DISchema>
The SQL select projection syntax is contained in the DISelect and DIProjection elements, and varies depending on
how the Query transform is configured.
<DISelect>
<DIProjection>
Each output field is defined in a DIExpression element. The expr attribute contains the actual ATL expression as
displayed in the Designer. Note that each field contains an additional XML representation of the expression. This
additional representation is optional, and not required for correct operation.
<DIExpression isString="true" expr="NameDate.FirstName">
<COLUMN_REFERENCE qualifier1="NameDate" column="FirstName" />
</DIExpression>
<DIExpression isString="true" expr="NameDate.LastName">
<COLUMN_REFERENCE qualifier1="NameDate" column="LastName" />
</DIExpression>
<DIExpression isString="true" expr="NameDate.DateOfBirth">
<COLUMN_REFERENCE qualifier1="NameDate"
column="DateOfBirth" />
</DIExpression>
<DIExpression isString="true" expr="(NameDate.FirstName ||
NameDate.LastName)">
<CONCAT>
116
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Object creation XML toolkit
<COLUMN_REFERENCE qualifier1="NameDate" column="FirstName" />
<COLUMN_REFERENCE qualifier1="NameDate" column="LastName" />
</CONCAT>
</DIExpression>
</DIProjection>
The input schema for the Query is defined using the DIFrom element. Attributes for the Query are specified in a
DIAttributes block.
<DIFrom>
<DITableSpec name="NameDate" />
</DIFrom>
</DISelect>
<DIAttributes>
<DIAttribute name="distinct_run_as_separate_process"
value="no" />
<DIAttribute name="group_by_run_as_separate_process"
value="no" />
<DIAttribute name="join_run_as_separate_process"
value="no" />
<DIAttribute name="order_by_run_as_separate_process"
value="no" />
<DIAttribute name="run_as_separate_process" value="no" />
</DIAttributes>
</DIQuery>
The file-format target is defined within the DIFileTarget element
<DIFileTarget typeId="3" formatName="NameDate"
filename="NameDate_out.txt">
<DIUIOptions>
<DIAttribute name="ui_display_name" value="myTarget" />
</DIUIOptions>
The input schema for the target is specified using the DIInputView element, and attributes for the target are
specified using a DIAttributes block.
<DIInputView name="FormatFields" />
<DIAttributes>
<DIAttribute name="connection_port" value="no" />
<DIAttribute name="file_location" value="local" />
<DIAttribute name="isstreamdebugfile" value="no" />
<DIAttribute name="loader_load_choice" value="replace" />
<DIAttribute name="name" value="NameDate" />
<DIAttribute name="root_dir" value="D:\temp" />
<DIAttribute name="validate_decimal_data" value="yes" />
</DIAttributes>
</DIFileTarget>
</DITransforms>
Attributes for the myTestdata flow data flow are specified in a DIAttributes block, and the file is finished by closing
the DataIntegratorExport element.
<DIAttributes>
<DIAttribute name="Cache_type" value="pageable_cache" />
<DIAttribute name="Parallelism_degree" value="0" />
<DIAttribute name="allows_both_input_and_output"
value="yes" />
<DIAttribute name="run_once" value="no" />
<DIAttribute name="use_dataflow_links" value="no" />
<DIAttribute name="use_datastore_links" value="yes" />
<DIAttribute name="validation_xform_exists" value="no" />
<DIAttribute name="validation_xform_stats" value="no" />
Integrator Guide
Object creation XML toolkit
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
117
</DIAttributes>
</DIDataflow>
</DataIntegratorExport>
118
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Object creation XML toolkit
8
Job launcher execution commands
The job launcher, exported as part of a job's execution commands, includes a specific command line option for
server groups. You can use this option to change the job servers in a server group.
For complete information about the job launcher, see the Management Console Guide.
The following table lists job launcher flags and their values.
Table 93:
Flag
Value
-w
The job launcher starts the job(s) and then waits before passing back the job status. If -w is not speci­
fied, the launcher exits immediately after starting a job.
-t
The time, in milliseconds, that the Job Server waits before checking a job's status. This is a companion
argument for -w.
-s
Status or return code. 0 indicates successful completion, non-zero indicates an error condition.
Combine -w, -t, and -s to execute the job, wait for completion, and return the status.
-C
Name of the engine command file (path to a file which contains the Command line arguments to be
sent to the engine).
-v
Prints AL_RWJobLauncher version number.
-S
Lists the server group and Job Servers it contains using the following syntax:
"SvrGroupName;JobSvr1Name:JobSvr1Host:JobSvr1Port;JobSvr2Name:JobS
vr2Host:JobSvr2Port";
For example: "SG_DEV;JS1:HPSVR1:3500;JS2:WINSVR4:3505";
-R
The location and name of the password file. Replaces the hard-coded repository connection values for
-S, -N, -U, -P.
There are two arguments that do not use flags:
● inet address—The host name and port number of the Job Server. The string must be in quotes. For example:
"inet:HPSVR1:3500"
If you use a server group, inet addresses are automatically rewritten using the -S flag arguments. On
execution, the first Job Server in the group checks with the others and the Job Server with the lightest load
executes the job.
● server log path—The fully qualified path to the location of the log files. The server log path must be in
quotes. The server log path argument does not appear on an exported batch job launch command file. It
appears only when the software generates a file for an active job schedule and stores it in the following
directory: <DS_COMMON_DIR>/Log/<JobServerName>/<RepositoryName>/<JobInstanceName>
Integrator Guide
Job launcher execution commands
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
119
You cannot manually edit server log paths.
120
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Job launcher execution commands
9
Legacy adapter information
9.1
Legacy adapter for external web services
Caution
This section is provided for legacy reference only. For improved performance in new web service data flows,
use the native web service datastore type.
You can add functionality to SAP Data Services to invoke web services in external applications from data flows.
This functionality requires configuring the software's built-in Web Services Adapter. The Web Services Adapter
provides support for locating and importing metadata for a web services server as well as invoking web service
operations.
The Web Services Adapter works by sending a request and waiting until it receives a reply from a web services
server.
For example, you might create a web services server as a front-end to a legacy application. You could call the web
services server daily from a data flow to access inventory and update an inventory data mart.
The interaction between the Web Services Adapter and an external web service has these parts:
● Creating an adapter datastore that identifies the WSDL, which describes the web services server.
● Importing metadata to extract the information form the WSDL needed to access the web service server.
● Creating a data flow that uses the imported function call to call the web services server.
Related Information
Accessing a web service using the Designer [page 70]
9.1.1 Legacy adapter installation
The Web Services Adapter is part of each Job Server installation. The installer automatically configures an
adapter instance in the Administrator, which is the only adapter instance that SAP Data Services requires to
configure a web services client. You do not need to configure adapter operations. The software automatically
configures the Web Services Adapter with Autostart set to FALSE so that it does not consume resources when you
do not use Web services. However, you can invoke adapters set with Autostart disabled, when needed. You do not
need to edit the adapter instance that the software provides for the Web Services Adapter.
The installer allows you to configure a Job Server to manage adapters by presenting a list of Job Servers to you
during installation. To view any adapter instance in the Administrator, select
Adapter Instance
<Job
Server> .
Integrator Guide
Legacy adapter information
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
121
The software creates the following values for an adapter instance.
Table 94:
Field name
Value automatically inserted
Adapter Instance Name
WebService
Access Sever host
(not required) Blank
Access Server port
(not required) Blank
Adapter Retry count
(default value) 0
Adapter Retry Interval
(default value) 3000
ClassPath
JAR files required in the classpath to start the Java process:
<LINK_DIR>/lib/acta_adapter_sdk.jar
<LINK_DIR>/lib/acta_broker_client.jar
<LINK_DIR>/lib/acta_tool.jar
<LINK_DIR>/ext/lib/xerces.jar
<LINK_DIR>/lib/acta_webservice_adapter.jar
<LINK_DIR>/ext/lib/qname.jar
<LINK_DIR>/ext/lib/axis.jar
<LINK_DIR>/ext/lib/commons-logging.jar
<LINK_DIR>/ext/lib/commons-discovery.jar
<LINK_DIR>/ext/lib/wsdl4j.jar
<LINK_DIR>/ext/lib/saaj.jar
<LINK_DIR>/ext/lib/jaxrpc.jar
AutoStart
TRUE
Trace Mode
FALSE (If set to TRUE, the adapter writes trace messages to the
WebService_trace.txt file in the <DS_COMMON_DIR>/
adapters/log directory)
Additional Java launcher options
(default values) -Xms64m -Xmx256m
Adapter type name
(Read-only) Name of adapter used to create this instance
Adapter version
(Read-only) Version of adapter used to create this instance
Adapter class
(Read-only) Name that identifies the adapter entry point
9.1.2 Legacy adapter configuration
To configure access to a specific web service, use the Designer. In the Designer's Datastore Editor window,
specify the datastore as an adapter datastore, select the Job Server that is managing the Web Services Adapter,
and select the Web Services Adapter. Data Services provides access to web services as stream-oriented function
calls, which it configures when you import metadata.
122
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Legacy adapter information
When you configure an adapter datastore, in addition to the normal adapter settings, specify the URL of the web
services server for a data flow to access. It must be the same URL that accepts a web service connection and
returns the WSDL.
The adapter connects to the web services server using the URL to locate the definitions of published services.
9.1.2.1
Accessing a web service
1. Create an adapter datastore:
a. Use the Web Services Adapter instance that SAP Data Services automatically creates during installation.
b. In the datastore editor under Adapter Options, configure the following parameters:
○ URL of the Web Service — Enter the URL of the web services server. This URL must accept a web
service connection and return the WSDL. This information is required for data flow access.
○ XML Recursion Level — Enter the number of passes the software should run through the XSD to
resolve names. The default is 0.
○ Keystore Path — If the web services server uses an SSL connection, specify the location of the
keystore used to establish the connection. When unsure, contact your network administrator.
○ User Name — Enter your user name for HTTP basic authentication.
○ Password — Enter your password for HTTP basic authentication.
Note
To obtain user name and password information, contact your web services provider.
c. Click OK.
2. Import metadata:
a. From the object library, double-click a Web Services Adapter datastore.
The Designer calls the adapter. The adapter calls the web services server at the indicated WSDL URL and
obtains a list of published services and ports.
b. Expand the ports to see the published operations available for import.
The list reflects the name and description of operations currently published by the configured web
service.
c. Right-click an operation and select Import.
The software imports web service operations as function calls and lists them under the Web Services
Adapter datastore in the object library. Each function call includes a definition for both the input and
output messages required for communication with a web service operation. The adapter extracts the
details about the request and reply messages and generates XML Schema files that describe the
messages.
3. From the Designer, add a web service function call to a job.
As a web services client, the software calls a web services server twice:
○ During design time to import metadata for the functions and data types that a particular web service
supports.
○ During run time to call the web service and invoke this functionality.
Integrator Guide
Legacy adapter information
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
123
9.1.2.2
Adding web service calls to a job
Once an adapter datastore is created and metadata is imported, use the following procedure to add a function call
to an SAP Data Services job.
1. Open the Designer.
2. Create a Web Services Adapter datastore.
3. Import operation metadata from an external web service.
4. Add a query to your job.
5. Open the query editor, right-click the target schema and select New Function call.
The Function Editor opens listing the operation metadata that you imported under its datastore name.
6. Select a datastore to view the metadata that you want to add to your job.
7. Select the metadata name and click Next.
8. Map the input schema to the output schema.
Note
If you want to nest data in the target schema, use this first query to place the schema in your job and
additional queries to perform the nesting. The Function Editor does not allow complex schema
configuration.
9. Click OK.
The imported schema appears in the query.
10. Configure the remainder of your job by supplying input to the function call and extracting the response
information obtained from the web service.
9.1.3 Configuring SSL with the legacy adapter
With Secure Socket Layer (SSL), the web services adapter can use secure transport over TCP/IP networks.
The overall process is:
● Generate certificates and keystores for both the server and client.
● Configure the web server.
● Configure the SAP Data Services web services adapter.
9.1.3.1
Generating certificates and keystores
1. Generate the server keystore.
2. Export the certificate from the server keystore to a file and get it signed by an authorized Certificate Authority.
3. Generate the client keystore.
4. Export the certificate from the client keystore to a file and get it signed by an authorized Certificate Authority.
124
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Legacy adapter information
5. Import the client's certificate into the server's keystore.
6. Import the server's certificate into client's keystore.
9.1.3.2
Configuring Tomcat and the legacy adapter
1. Uncomment the following entry from the server-di.xml file in the TOMCAT_HOME/conf directory.
<Connector port="8443"
maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" disableUploadTimeout="true"
acceptCount="100" debug="1" scheme="https" secure="true"
clientAuth="false" sslProtocol="TLS" />
2. Inside the Connector tag, add/update the value of the keystoreFile and keystorePass parameters. The
keystoreFile parameter should contain the *.keystore file path created when generating the keystore. The
keystorePass parameter should contain the password used to create the keystore when generating it.
3. You might also need to modify the wrapper.properties file in the LINK_DIR\ext\webserver\conf
directory. In the section Defining the classpath, ensure the following third-party libraries are in the
path:
wrapper.class_path=$(ACTAHOME)\ext\lib\jnet.jar
wrapper.class_path=$(ACTAHOME)\ext\lib\jsse.jar
wrapper.class_path=$(ACTAHOME)\ext\lib\jcert.jar
4. After completing the configuration changes, restart the web server. If the web server starts successfully, then
you should be able to access any web application supported by Tomcat via SSL.
5. In the Designer, configure the web services adapter by opening the adapter datastore, click Advanced, and
enter the client keystore path.
9.1.4 Legacy adapter error messages
In addition to the error logs, the following list identifies web services client error messages and their descriptions:
● Web services client is unable to create a SOAP request to send to a server. Error = <adapter-generated
exception message>
The Web Services Adapter returns this error message if the XML message passed from SAP Data Services as
a Web Services Adapter function call could not be packaged into a SOAP Envelope. Processing stops before a
call to a web services server is made.
To find extended error information, see the Web Services Adapter trace log file (
Adapter Instances
<JobServerName> ). To use extended diagnostics, use debug tracing in the webadmin.log file.
● Web services client is unable to invoke a web services server. Error = <adapter-generated exception
message>
The client returns this error message if the Web Services Adapter cannot call the web services server. It
indicates that the adapter has successfully packaged the XML message passed from the software into a
SOAP Envelope. However, the call to the web services server is not going through. In most cases, this will be
an error in locating the service, not a case of the service refusing a request. If a web service operation is
refusing a request, it will return a fault message.
Integrator Guide
Legacy adapter information
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
125
To find extended error information, see the Web Services Adapter trace log file (
Adapter Instances
<JobServerName> ). To use extended diagnostics, use debug tracing in the webadmin.log file.
● Web services client called a web services server. The server returned the following fault message: <servergenerated error message>
The client returns this error message if the web services server is called and returns a fault message
indicating the call failed. The adapter has successfully packaged the XML message passed from the software
into a SOAP Envelope, called the web services server, and the server received the call.
To find extended error information, see the Web Services Adapter trace log file (
Adapter Instances
<JobServerName> ) and perhaps the server itself if it maintains diagnostics. To use extended diagnostics,
use debug tracing in the webadmin.log file.
● Web services client called a web services server and received a reply that cannot be interpreted. Error = <
adapter-generated exception message >
The client returns this error message if the SOAP Envelope returned from the web services server cannot be
unpacked to extract the XML message to be returned to the job.
To find extended error information, see the Web Services Adapter trace log file (
Adapter Instances
<JobServerName> ). To use extended diagnostics, use debug tracing in the webadmin.log file.
126
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
Integrator Guide
Legacy adapter information
Important Disclaimers and Legal Information
Coding Samples
Any software coding and/or code lines / strings ("Code") included in this documentation are only examples and are not intended to be used in a productive system
environment. The Code is only intended to better explain and visualize the syntax and phrasing rules of certain coding. SAP does not warrant the correctness and
completeness of the Code given herein, and SAP shall not be liable for errors or damages caused by the usage of the Code, unless damages were caused by SAP
intentionally or by SAP's gross negligence.
Accessibility
The information contained in the SAP documentation represents SAP's current view of accessibility criteria as of the date of publication; it is in no way intended to be a
binding guideline on how to ensure accessibility of software products. SAP in particular disclaims any liability in relation to this document. This disclaimer, however, does
not apply in cases of wilful misconduct or gross negligence of SAP. Furthermore, this document does not result in any direct or indirect contractual obligations of SAP.
Gender-Neutral Language
As far as possible, SAP documentation is gender neutral. Depending on the context, the reader is addressed directly with "you", or a gender-neutral noun (such as "sales
person" or "working days") is used. If when referring to members of both sexes, however, the third-person singular cannot be avoided or a gender-neutral noun does not
exist, SAP reserves the right to use the masculine form of the noun and pronoun. This is to ensure that the documentation remains comprehensible.
Internet Hyperlinks
The SAP documentation may contain hyperlinks to the Internet. These hyperlinks are intended to serve as a hint about where to find related information. SAP does not
warrant the availability and correctness of this related information or the ability of this information to serve a particular purpose. SAP shall not be liable for any damages
caused by the use of related information unless damages have been caused by SAP's gross negligence or willful misconduct. All links are categorized for transparency
(see: http://help.sap.com/disclaimer).
Integrator Guide
Important Disclaimers and Legal Information
PUBLIC
© 2015 SAP SE or an SAP affiliate company. All rights reserved.
127
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.
Download PDF