Data Services Integrator's Guide
BusinessObjects Data Services XI 3.1 (12.1.1)
Copyright
© 2008 Business Objects, an SAP company. All rights reserved. Business Objects
owns the following U.S. patents, which may cover products that are offered and
licensed by Business Objects: 5,295,243; 5,339,390; 5,555,403; 5,590,250;
5,619,632; 5,632,009; 5,857,205; 5,880,742; 5,883,635; 6,085,202; 6,108,698;
6,247,008; 6,289,352; 6,300,957; 6,377,259; 6,490,593; 6,578,027; 6,581,068;
6,628,312; 6,654,761; 6,768,986; 6,772,409; 6,831,668; 6,882,998; 6,892,189;
6,901,555; 7,089,238; 7,107,266; 7,139,766; 7,178,099; 7,181,435; 7,181,440;
7,194,465; 7,222,130; 7,299,419; 7,320,122 and 7,356,779. Business Objects and
its logos, BusinessObjects, Business Objects Crystal Vision, Business Process
On Demand, BusinessQuery, Cartesis, Crystal Analysis, Crystal Applications,
Crystal Decisions, Crystal Enterprise, Crystal Insider, Crystal Reports, Crystal
Vision, Desktop Intelligence, Inxight and its logos , LinguistX, Star Tree, Table
Lens, ThingFinder, Timewall, Let There Be Light, Metify, NSite, Rapid Marts,
RapidMarts, the Spectrum Design, Web Intelligence, Workmail and Xcelsius are
trademarks or registered trademarks in the United States and/or other countries
of Business Objects and/or affiliated companies. SAP is the trademark or registered
trademark of SAP AG in Germany and in several other countries. All other names
mentioned herein may be trademarks of their respective owners.
Third-party
Contributors
Business Objects products in this release may contain redistributions of software
licensed from third-party contributors. Some of these individual components may
also be available under alternative licenses. A partial listing of third-party
contributors that have requested or permitted acknowledgments, as well as required
notices, can be found at: http://www.businessobjects.com/thirdparty
2008-11-28
Contents
Welcome to Data Services 7Chapter 1
Welcome......................................................................................................8
Documentation set for Data Services..........................................................8
Accessing documentation..........................................................................11
Business Objects information resources...................................................12
Web service support 15Chapter 2
Overview....................................................................................................16
Web services technologies........................................................................17
Accessing documentation on Windows................................................11
Accessing documentation on UNIX......................................................11
Accessing documentation from the Web..............................................12
SOAP...................................................................................................17
WSDL...................................................................................................18
XML Schema........................................................................................18
UDDI.....................................................................................................19
Using Data Services as a web service provider 21Chapter 3
WSDL basics.............................................................................................23
Building a WSDL file.............................................................................25
Tips for using the WSDL file.................................................................31
Creating a client to use web services........................................................31
Supported web service operations............................................................32
Connection operations.........................................................................33
Realtime_Service_Admin operations...................................................34
Batch_Job_Admin operations..............................................................37
Data Services Integrator's Guide 3
Contents
Real-time_Services operations............................................................45
Batch_Jobs operations.........................................................................47
Optimizing real-time web service performance.........................................48
Integrating Global Suggestion Lists functionality.......................................50
Introduction...........................................................................................50
Before you code...................................................................................50
To retrieve Global Suggestion Lists information...................................50
Enabling SSL support................................................................................55
To configure SSL on the web application server..................................55
Error reporting............................................................................................56
Administrator log..................................................................................56
Web Service log...................................................................................57
Error messages....................................................................................57
Consuming external web services in Data Services 61Chapter 4
To access a web service using the Designer.............................................62
To add web service calls to a job...............................................................64
Enabling SSL support................................................................................64
To configure SSL on the native web service datastore........................64
To configure SSL in the runtime execution file.....................................65
Inxight integration for reading unstructured text .......................................65
Using the Message Client API 67Chapter 5
Interface components................................................................................69
Creating the connection.............................................................................69
Sending messages....................................................................................70
Closing the connection..............................................................................70
Sample applications...................................................................................70
To compile and run the C++ sample application on UNIX....................70
To compile and run the Java sample application on UNIX...................72
4 Data Services Integrator's Guide
Contents
C++ API reference.....................................................................................73
Class RTServiceClient.........................................................................73
Class RTServiceClientError.................................................................74
Java API reference....................................................................................75
Class RTServiceClient.........................................................................75
Using the JMS adapter 77Chapter 6
Introduction................................................................................................78
About this section.................................................................................78
Adapter overview..................................................................................79
Installation and configuration.....................................................................80
JMS adapter installation.......................................................................80
JMS adapter configuration...................................................................82
Using the JMS adapter..............................................................................98
To start an instance of the JMS adapter...............................................98
To run the sample...............................................................................100
Testing PutGet: Request/Reply..........................................................102
Testing PutTopic: Request/Acknowledge...........................................104
Testing Get: Request/Reply................................................................106
Testing GetTopic: Request/Acknowledge...........................................108
Testing Get: Request/Acknowledge...................................................109
Testing Put: Request/Acknowledge....................................................111
Technical implementation...................................................................112
Appendix..................................................................................................113
Weblogic as JMS provider..................................................................113
Job launcher execution commands 115Chapter 7
Appendix 119Chapter 8
Legacy adapter for external web services...............................................120
Data Services Integrator's Guide 5
Contents
Legacy adapter installation.................................................................120
Legacy adapter configuration.............................................................122
Configuring SSL with the legacy adapter...........................................126
Legacy adapter error messages........................................................127
Index 129
6 Data Services Integrator's Guide
Welcome to Data Services
1
Welcome to Data Services
1
Welcome
Welcome
Data Services XI Release 3 provides data integration and data quality
processes in one runtime environment, delivering enterprise performance
and scalability.
The data integration processes of Data Services allow organizations to easily
explore, extract, transform, and deliver any type of data anywhere across
the enterprise.
The data quality processes of Data Services allow organizations to easily
standardize, cleanse, and consolidate data anywhere, ensuring that end-users
are always working with information that's readily available, accurate, and
trusted.
Documentation set for Data Services
You should become familiar with all the pieces of documentation that relate
to your Data Services product.
Documentation Map
Release Summary
Release Notes
Getting Started Guide
Installation Guide for Windows
Installation Guide for UNIX
8 Data Services Integrator's Guide
What this document providesDocument
Information about available Data Services books,
languages, and locations
Highlights of key features in this Data Services release
Important information you need before installing and
deploying this version of Data Services
An introduction to Data Services
Information about and procedures for installing Data
Services in a Windows environment.
Information about and procedures for installing Data
Services in a UNIX environment.
Advanced Development Guide
Welcome to Data Services
Documentation set for Data Services
What this document providesDocument
Guidelines and options for migrating applications including information on multi-user functionality and
the use of the central repository for version control
1
Designer Guide
Integrator's Guide
Management Console: Administrator
Guide
Management Console: Metadata Reports Guide
Migration Considerations Guide
Performance Optimization Guide
Reference Guide
Information about how to use Data Services Designer
Information for third-party developers to access Data
Services functionality. Also provides information about
how to install, configure, and use the Data Services
Adapter for JMS.
Information about how to use Data Services Administrator
Information about how to use Data Services Metadata
Reports
Information about:
• Release-specific product behavior changes from
earlier versions of Data Services to the latest release
• How to migrate from Data Quality to Data Services
Information about how to improve the performance
of Data Services
Detailed reference material for Data Services Designer
Data Services Integrator's Guide 9
Welcome to Data Services
1
Documentation set for Data Services
Technical Manuals
What this document providesDocument
A compiled “master” PDF of core Data Services books
containing a searchable master table of contents and
index:
•
Getting Started Guide
•
Installation Guide for Windows
•
Installation Guide for UNIX
•
Designer Guide
•
Reference Guide
•
Management Console: Metadata Reports Guide
•
Management Console: Administrator Guide
•
Performance Optimization Guide
•
Advanced Development Guide
•
Supplement for J.D. Edwards
•
Supplement for Oracle Applications
•
Supplement for PeopleSoft
•
Supplement for Siebel
•
Supplement for SAP
Tutorial
In addition, you may need to refer to several Adapter Guides and
Supplemental Guides.
What this document providesDocument
Salesforce.com Adapter
Interface
Supplement for J.D. Edwards
Supplement for Oracle Applications
Supplement for PeopleSoft
10 Data Services Integrator's Guide
Information about how to install, configure, and use the Data
Services Salesforce.com Adapter Interface
Information about license-controlled interfaces between Data
Services and J.D. Edwards World and J.D. Edwards OneWorld
Information about the license-controlled interface between Data
Services and Oracle Applications
Information about license-controlled interfaces between Data
Services and PeopleSoft
A step-by-step introduction to using Data Services
Welcome to Data Services
Accessing documentation
What this document providesDocument
1
Supplement for SAP
Supplement for Siebel
Information about license-controlled interfaces between Data
Services, SAP ERP, and SAP BI/BW
Information about the license-controlled interface between Data
Services and Siebel
Accessing documentation
You can access the complete documentation set for Data Services in several
places.
Accessing documentation on Windows
After you install Data Services, you can access the documentation from the
Start menu.
1. Choose Start > Programs > BusinessObjects XI 3.1 >
BusinessObjects Data Services > Data Services Documentation.
Note:
Only a subset of the documentation is available from the Start menu. The
documentation set for this release is available in LINK_DIR\Doc\Books\en.
2. Click the appropriate shortcut for the document that you want to view.
Accessing documentation on UNIX
After you install Data Services, you can access the online documentation by
going to the directory where the printable PDF files were installed.
1. Go to LINK_DIR/doc/book/en/.
2. Using Adobe Reader, open the PDF file of the document that you want
to view.
Data Services Integrator's Guide 11
Welcome to Data Services
1
Business Objects information resources
Accessing documentation from the Web
You can access the complete documentation set for Data Services from the
Business Objects Customer Support site.
1.
Go to http://help.sap.com.
2. Cick Business Objects at the top of the page.
You can view the PDFs online or save them to your computer.
Business Objects information resources
A global network of Business Objects technology experts provides customer
support, education, and consulting to ensure maximum business intelligence
benefit to your business.
Useful addresses at a glance:
ContentAddress
12 Data Services Integrator's Guide
Welcome to Data Services
Business Objects information resources
ContentAddress
1
Customer Support, Consulting, and Education
services
http://service.sap.com/
Data Services Community
https://www.sdn.sap.com/irj/sdn/businessob
jects-ds
Forums on SCN (SAP Community Network)
https://www.sdn.sap.com/irj/sdn/businessob
jects-forums
Blueprints
http://www.sdn.sap.com/irj/boc/blueprints
Information about Customer Support programs,
as well as links to technical articles, downloads,
and online forums. Consulting services can
provide you with information about how Business Objects can help maximize your business
intelligence investment. Education services can
provide information about training options and
modules. From traditional classroom learning
to targeted e-learning seminars, Business Objects can offer a training package to suit your
learning needs and preferred learning style.
Get online and timely information about Data
Services, including tips and tricks, additional
downloads, samples, and much more. All content is to and from the community, so feel free
to join in and contact us if you have a submission.
Search the Business Objects forums on the
SAP Community Network to learn from other
Data Services users and start posting questions
or share your knowledge with the community.
Blueprints for you to download and modify to fit
your needs. Each blueprint contains the necessary Data Services project, jobs, data flows, file
formats, sample data, template tables, and
custom functions to run the data flows in your
environment with only a few modifications.
Data Services Integrator's Guide 13
Welcome to Data Services
1
Business Objects information resources
http://help.sap.com/
ContentAddress
Business Objects product documentation.Product documentation
Documentation mailbox
documentation@businessobjects.com
Supported platforms documentation
https://service.sap.com/bosap-support
Send us feedback or questions about your
Business Objects documentation. Do you have
a suggestion on how we can improve our documentation? Is there something that you particularly like or have found useful? Let us know,
and we will do our best to ensure that your
suggestion is considered for the next release
of our documentation.
Note:
If your issue concerns a Business Objects
product and not the documentation, please
contact our Customer Support experts.
Get information about supported platforms for
Data Services.
In the left panel of the window, navigate to
Documentation > Supported Platforms >
BusinessObjects XI 3.1. Click the BusinessObjects Data Services link in the main window.
14 Data Services Integrator's Guide
Web service support
2
Web service support
2
Overview
Overview
This section discusses both how an administrator can configure Data Services
through the Administrator to publish Data Services jobs as callable web
services, and how an application developer can access those web services.
Data Services publishes web services from the Data Services Management
Console Administrator. To use 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 Data Services Management
Console: Administrator Guide.
Web services are modular business applications based on open standards
(WSDL, 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.
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
BusinessObjects 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 Adapter (client functionality)
If you have an application that also supports web services, you can use that
application to run Data Services batch and real-time jobs or to publish your
application's functionality to be called by Data Services data flows.
After you install Data Services, you can immediately start working with its
client functionality because the built-in Web Services Adapter is a web
services client that provides access to a web services server from a Data
Services data flow.
Related Topics
• Using Data Services as a web service provider on page 21
16 Data Services Integrator's Guide
• Consuming external web services in Data Services on page 61
Web services technologies
Data Services web services are fully compliant with Web Services
Interoperabilty (WS-I) Basic Profile 1.0, and support three Java Web Services
technologies.
DescriptionWeb service tech-
nology
Connection protocol (envelope for XML messages)SOAP
Web service support
Web services technologies
2
SOAP
WSDL
Data Services supports SOAP 1.1, WSDL version 1.1 or 2.0, and Apache
Axis 1.1 (an industry-standard SOAP message handler and WSDL parser).
Data Services is also compliant with the Microsoft .NET environment for Web
services. You can import the WSDL that Data Services generates into Visual
Studio .NET and the Data Services Web Services Adapter can call the WSDL
that Visual Studio .Net generates.
Note:
Data Services does not support the Representational State Transfer (REST)
web services architecture or the JSON message format.
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
Language used to request a service and return replies
(subset of XML)
Format used for the WSDL fileXML Schema
In addition, Data Services 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.
Data Services Integrator's Guide 17
Web service support
2
Web services technologies
WSDL
A SOAP gateway is built in to the Data Services Administrator. Data Services
supports SOAP over HTTP and HTTPS protocols.
Web Services Description Language (WSDL) is a subset of XML. It is used
as a transport mechanism for XML messages. 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 Data
Services WSDL.
Data Services 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 Data Services includes tags (such as services,
bindings, ports, and operations) that support the use of the SOAP protocol.
Each tag uses a name that Data Services provides. For example:
• You select which Data Services 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 Data
Services batch jobs or real-time services.
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 Adapter imports metadata into
Data Services using the XML Schema format only.
XML Schema formats are defined in the types element of the WSDL file.
18 Data Services Integrator's Guide
UDDI
Web service support
Web services technologies
UDDI is a method of publishing comments and other reference information
about jobs to an external web site. Data Services does not publish information
to a UDDI web site because most Data Services web services users work
behind enterprise firewalls.
2
Data Services Integrator's Guide 19
Web service support
Web services technologies
2
20 Data Services Integrator's Guide
Using Data Services as a web service provider
3
Using Data Services as a web service provider
3
WSDL basics
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 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. Data Services routes calls to the
appropriate Data Services 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 Data Services job
updates exchange rates in your financial data mart. The rate change
initiates a call to a Data Services-hosted 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.
22 Data Services Integrator's Guide
Data Services 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 Data Services to:
• Perform an initial load of a data mart for real-time reporting
• Refresh the data cache depending on specified business criteria
• Perform complex transforms on hierarchical objects for mapping data
between ERP systems
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 Data Services-generated WSDL file.
Using Data Services as a web service provider
WSDL basics
3
service
DescriptionElement Name
Root elementdefinition
Used to group a set of related ports or endpoints
to which a client application will connect. Data
Services publishes a single service in the WSDL
file it generates.
Data Services Integrator's Guide 23
Using Data Services as a web service provider
3
WSDL basics
port
portType
DescriptionElement Name
Defines a specific Web service endpoint that a
client can access. Each port has a unique name
and a specific address used for binding. Data Services 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)
• Batch_Job_Admin: used for administrative oper-
ations 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
message
type
24 Data Services Integrator's Guide
Defines a specific function call. Data Services
publishes each batch job and real-time service as
an operation. Data Services also publishes connection operations.
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.
Defines the data types used in messages sent
to/from a Web service.
Using Data Services as a web service provider
WSDL basics
Related Topics
• SoapAction element on page 48
Building a WSDL file
Use the information in the WSDL file produced by Data Services to create
an application that can access Data Services 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 Data Services Management Console Administrator,
or open a browser window and search for:
http://hostname:port/DataServices/servlet/webservices?ver=2.0&wsdlxml
To configure web service information using the Administrator
1. Open Data Services Administrator.
2. Log in with Administrator-level privileges. Users with Monitor-level
privileges cannot configure web services.
3
Note:
If you enable security for the WSDL file, 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.
Data Services 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).
Data Services Integrator's Guide 25
Using Data Services as a web service provider
3
WSDL basics
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 real-time services to be published,
enable/disable security for the WSDL file, and to enable/disable access
to full batch job attributes.
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 Securty 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 real-time 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:
26 Data Services Integrator's Guide
Using Data Services as a web service provider
WSDL basics
DescriptionElement
System profile used to run the job.job_system_profile
Monitor sample rate (# of rows).sampling_rate
Enable auditing (true or false).auditing
Enable recovery (true or false).recovery
Job Server or Server Group.job_server
3
Data Services Integrator's Guide 27
Using Data Services as a web service provider
3
WSDL basics
trace
DescriptionElement
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):
• 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
28 Data Services Integrator's Guide
distribution_level
10. Navigate back to the "Web Services Status" page, choose the WSDL
Using Data Services as a web service provider
WSDL basics
DescriptionElement
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 operations.
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: An resource-intensive operation (such
as a sort, table comparison, or table lookup) within a
data flow can execute on an available Job Server.
Note:
Casing and spacing are important for these values.
version you want to create, and click View WSDL.
A new browser window opens with the WSDL displayed. Use the
information in this file to perform the following:
• Confirm that Data Services updated the WSDL file with all jobs and
services without error.
• Create calls to Data Services
3
Use the information in the WSDL file to configure your application to
access Data Services 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 Data Services
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 Data Services jobs, you can
monitor the status of web service operations on the server by viewing the
data on the "Web Services Status" page.
Data Services Integrator's Guide 29
Using Data Services as a web service provider
3
WSDL basics
Web Services Port
Repository/ Access Server
DescriptionColumn name
Same as job or real-time service name.Operation Name
For jobs, the port name is Batch_jobs.
For services, the port name is RealTime_Service.
For built-in operations, the port name is
Connection_Operations.
For administrative operations for batch
jobs, the port name is Batch_Job_Admin.
For jobs, the repository name.
For services, the Access Server name.
Job Information
Requests Processed
Requests Failed
Requests Pending
30 Data Services Integrator's Guide
For jobs, a link to the Batch Job History
page.
For services, a link to the Real-time Services History page.
Number of client requests successfully
processed.
Number of client requests that failed
somewhere between the time that the
Web Server receives the request and the
Job Server receives it.
Number of requests in a queue for Job
Server.
Using Data Services as a web service provider
Creating a client to use web services
DescriptionColumn name
3
Jobs Failed
Tips for using the WSDL file
The WSDL file:
• Appears in the View WSDL window or any browser window by searching
for the following URL:
http://host
name:port/DataServices/servlet/webservices?ver=2.0&wsdlxml
Note:
To support previously-created datastores using a WSDL file with XML
schema simple types, manually delete "ver=2.0&" from the default URL
of Web Service and Apply to save as follows:
http://hostname:port/DataServices/servlet/webservices?wsdlxml
• Displays all real-time services and jobs enabled for Web services in the
Data Services Administrator.
• Only displays log on, log off, and session ID information when security is
enabled.
• Displays XML Schema formats in the types element.
Number of requests that failed due to a
problem with the Job Server.
Creating a client to use web services
To use a published web service, you must know the URL of the target WSDL.
The Data Services Administrator produces a WSDL file with this URL:
http://hostname:port/DataServices/servlet/webservices?ver=2.0&ws
dlxml
The Data Services batch or real-time jobs must have previously been exposed
as web services.
Data Services Integrator's Guide 31
Using Data Services as a web service provider
3
Supported web service operations
This section discusses general steps for using a published 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 Data Services
web services clients.
1. Import the Data Services 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 Data Services web service.
Each available port for the Data Services 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 Data Services 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.
Supported web service operations
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, Data Services creates only one service.
Within the service definition, Data Services defines ports for:
• Connection_Operations
• Batch_Job_Admin
• Real-time_Services
• Batch_Jobs
32 Data Services Integrator's Guide
Connection operations
Data Services generates WSDL that defines connection operations that
belong to web services. Data Services supports the following Connection
operations.
Note:
Data Services generates Logon and Logout operations only if you enable
security for published jobs.
Ping
Using Data Services as a web service provider
Supported web service operations
DescriptionOperation
Verifies the connection to Data Services Web servicesPing
Verifies secure access before establishing a sessionLogon
Terminates a sessionLogout
3
Logon
Logout
The Ping operation is an empty input message with a ping operation request.
The output message is a text string that returns the current Data Services
version, which indicates that a connection has been established.
The Logon operation is required when you enable Data Services to provide
secure communication. To access web services, provide a Data Services
Administrator login name and password (with Administrator-level privileges).
When Data Services validates them, the logon operation returns an
Administrator session ID that you must include in all subsequent calls to Data
Services web services.
The Logout operation is required when you enable Data Services to provide
secure communication. When web service communication is complete, call
the Logout operation to terminate the session.
Data Services Integrator's Guide 33
Using Data Services as a web service provider
3
Supported web service operations
Realtime_Service_Admin operations
Get_RTMsg_Format
Use Get_RTMsg_Format to retrieve the input/output format for a real-time
service as an XML Schema. The real-time service does not need to be
published as a web service.
34 Data Services Integrator's Guide
Input message
Using Data Services as a web service provider
Supported web service operations
DescriptionTypeElement
3
Output message
stringserviceName
stringselector
stringschema
stringrootElementNS
stringschemaName
stringschema
The name of the real-time service as displayed in
the Data Services Administrator.
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.
DescriptionTypeElement
The input or output XML Schema for the real-time
service.
The root element of the returned XML Schema.stringrootElement
The root element namespace of the returned XML
Schema.
The name of a dependent schema used in the returned XML Schema, if applicable. This element may
be returned multiple times.
A dependent schema used in the returned XML
Schema, if applicable. This element may be returned
multiple times.
Get_RTService_List
Use the Get_RTService_List operation to retrieve a list of the names of
published real-time services.
stringerrorMessage
Any error message that resulted while retrieving the
XML Schema for the real-time service.
Data Services Integrator's Guide 35
Using Data Services as a web service provider
3
Supported web service operations
Input message
Get_RTService_List takes no input message.
Output message
DescriptionTypeElement
The list of published real-time services.stringserviceName
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 Data Services
Administrator, and the XML input content must match the input format defined
for the real-time service.
stringerrorMessage
Any error message that occurred while retrieving the
list of real-time services.
36 Data Services Integrator's Guide
Input message
Using Data Services as a web service provider
Supported web service operations
DescriptionTypeElement
3
stringserviceName
stringxmlInput
Output message
stringxmlOutput
stringerrorMessage
The name of the real-time service as displayed in
the Data Services Administrator.
The XML input content used to start the real-time
service. This content must match the input format
required by the real-time service.
DescriptionTypeElement
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.
Any error message that resulted while attempting to
call the real-time service.
Batch_Job_Admin operations
Get_BatchJob_List
Use the Get_BatchJob_List operation to retrieve a list of the names of
published batch jobs.
Input message
Get_BatchJob_List takes no input message.
Data Services Integrator's Guide 37
Using Data Services as a web service provider
3
Supported web service operations
Output message
DescriptionTypeElement
The list of published batch jobs.stringjobName
Get_BatchJob_RunIDs
Each individual run of a Data Services batch job is assigned a unique run
ID.
Use the Get_BatchJob_RunIDs operation to retrieve a list of run IDs
associated with a particular batch job.
stringerrorMessage
Any error message that occurred while retrieving the
list of batch jobs.
38 Data Services Integrator's Guide
Input message
Using Data Services as a web service provider
Supported web service operations
DescriptionTypeElement
The name of the batch job.stringjobName
3
Output message
Get_BatchJob_Status
Use the Get_BatchJob_Status operation to retrieve the status of a particular
batch job run.
stringstatus
stringstatus
The status code for the type of run IDs requested.
Valid codes include: running, succeeded, error,
warning, and all.
DescriptionTypeElement
The unique ID for the batch job run.integerrunID
The status code for the batch job run. Valid codes
include: running, succeeded, error, warning,
and all.
The repository name associated with the batch job.stringrepoName
Data Services Integrator's Guide 39
Using Data Services as a web service provider
3
Supported web service operations
Input message
Output message
DescriptionTypeElement
The run ID for the particular batch job status desired.integerrunID
DescriptionTypeElement
Get_Error_Log
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.
integerreturnCode
The status code for the batch job run. Valid codes
include:
• 0 - The job is currently running.
• 1 - The job ended successfully.
• 2 - The job ended with an error.
40 Data Services Integrator's Guide
Input message
Output message
Using Data Services as a web service provider
Supported web service operations
DescriptionTypeElement
The batch job run ID for the particular log desired.integerrunID
DescriptionTypeElement
3
Get_Job_Input_Format
Use Get_Job_Input_Format to retrieve the input format for a batch job as an
XML Schema.
stringerror
The error log associated with the input batch job run
ID.
Data Services Integrator's Guide 41
Using Data Services as a web service provider
3
Supported web service operations
Input message
DescriptionTypeElement
Output message
Get_Monitor_Log
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.
stringjobName
stringformat
stringerrorMessage
The name of the batch job as displayed in the Data
Services Administrator.
DescriptionTypeElement
The input format for the batch job, as an XML
Schema.
Any error message that resulted while retrieving the
input format for the batch job.
42 Data Services Integrator's Guide
Input message
Output message
Using Data Services as a web service provider
Supported web service operations
DescriptionTypeElement
The batch job run ID for the particular log desired.integerrunID
DescriptionTypeElement
3
Get_Trace_Log
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
Output message
stringmonitor
stringtrace
The monitor log associated with the input batch job
run ID.
DescriptionTypeElement
The batch job run ID for the particular log desired.integerrunID
DescriptionTypeElement
The trace log associated with the input batch job run
ID.
Run_Batch_Job
Use Run_Batch_Job to call a published batch job with the ability to specify
job parameters and global variables.
Data Services Integrator's Guide 43
Using Data Services as a web service provider
3
Supported web service operations
Input message
DescriptionTypeElement
The name of the batch job as displayed in the Data
Services Administrator.
A complex XML element that sets specific job execution parameters.
A complex XML element that defines global job execution variables.
jobParameters
globalVariables
Note:
stringjobName
complex
complex
For detailed information about the jobParameters and globalVariables
elements, view the WSDL from the Data Services Administrator. For more
information about available job parameters and global variables, see the
Data Services Reference Guide.
Output message
DescriptionTypeElement
The process ID number for the batch job execution.intpid
intcid
intrid
stringrepoName
The run ID associated with the specific execution of
the batch job.
The repository name associated with the batch job
execution.
Stop_Batch_Job
Use the Stop_Batch_Job operation to stop a particular batch job run.
44 Data Services Integrator's Guide
stringerrorMessage
Any error message that resulted while attempting to
call the batch job.
Input message
Output message
Using Data Services as a web service provider
Supported web service operations
DescriptionTypeElement
The run ID for the particular batch job run to stop.integerrunID
DescriptionTypeElement
3
integerreturnCode
stringerrorMessage
The success code for the batch job stop attempt.
Valid codes include:
• 0 - The job was stopped successfully.
• 1 - The job failed to stop.
The error message associated with a failure to stop
a batch job run.
Real-time_Services operations
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.
Data Services 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:
Data Services Integrator's Guide 45
Using Data Services as a web service provider
3
Supported web service operations
• Header message
If security is enabled for the message, Data Services defines a secure
session identifier in the message header.
• Input message
When an external web services client invokes it, the input message passes
information to a Data Services real-time service. The name of the input
message is the name of the operation that the Data Services publishes
followed by the suffix _Input. The input message contains the message
source defined by the real-time service.
• Output message
Data Services 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
Data Services returns a fault message when it cannot invoke the real-time
service.
Message formats
The following segment shows the syntax that Data Services generates in an
WSDL file to define an operation's messages. In this example:
• RTService represents the name of the real-time service as defined in
Data Services Administrator.
• XMLSchemaName represents the name of the XML Schema that was used
to create an XML message source or XML message target in Data
Services Designer.
• RootElement represents the root element of the XML Schema.
Data Services 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
46 Data Services Integrator's Guide
imported into Data Services 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 port
Type tag.
Batch_Jobs operations
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:
• Header message
Using Data Services as a web service provider
Supported web service operations
3
When security is enabled for the message, Data Services 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, Data Services defines a secure
session identifier in the message header.
• Output message
Data Services returns the output message when the batch job starts. The
output message contains the job identification. The name of the output
message is the name of the operation followed by the suffix _Output.
The output message contains the following IDs:
• OS process ID of the started job
• Job Server Counter ID of the started job
• Fault message
Data Services Integrator's Guide 47
Using Data Services as a web service provider
3
Optimizing real-time web service performance
Data Services 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.
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.
Security
When publishing a job as a web service, the Administrator can enable secure
access, requiring that web services clients provide authentication and
authorization (a Data Services 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 Topics
• To configure web service information using the Administrator on page 25
Optimizing real-time web service
performance
You can modify the connection pool settings for Data Services' real-time web
services. You can optimize the performance of your installation by configuring
the connection pool to match your Access Server and hardware configuration.
Connection pool configuration settings are found in the
$LINK_DIR/conf/admin.xml file and separated by Access Server.
48 Data Services Integrator's Guide
Using Data Services as a web service provider
Optimizing real-time web service performance
DescriptionSetting
3
ws-conn-maxactive
ws-conn-maxidle
ws-conn-minidle
ws-conn-whenexhausted-ac
tion
Controls the maximum number of connections that can be
borrowed from the pool at one time. When the value is exceeded, the pool is exhausted. Negative values allow unlimited connections. The default value for this setting is 8.
Controls the maximum number of connections that can sit
idle in the connection pool at any time. Negative values allow
unlimited idle connections. The default value for this setting
is 8.
Controls the minimum number of connections that can sit idle
in the connection pool at any time. The default value for this
setting is 0.
Specifies the action to perform when the connection pool is
exhausted. Possible values include:
• fail
Throws an exception.
• grow
Creates and returns a new connection. This can exceed
the maximum specified in ws-conn-max-active.
• block
Blocks requests until a new or idle connection is available.
ws-conn-maxwait
Specifies, in milliseconds, how long to block requests when
ws-conn-when-exhausted-action is set to block. Negative
values block requests indefinitely.
After you modify admin.xml, restart your web application server to activate
the new settings.
Data Services Integrator's Guide 49
Using Data Services as a web service provider
3
Integrating Global Suggestion Lists functionality
Integrating Global Suggestion Lists
functionality
Introduction
Global Suggestion Lists functionality offers a way to complete and populate
addresses with minimal data, or it can offer suggestions for possible matches.
This easy address-entry system is ideal in call center environments or any
transactional environment where data cleansing is necessary at the point of
entry. It's also a beneficial research tool for managing bad adddresses from
a batch process.
Global Suggestion Lists concepts
This section includes information that is specific to integrating Global
Suggestion Lists functionality into your own custom application.
For further information about the Global Suggestion Lists transform, see the
Transforms section in the BusinessObjects Data Services Reference Guide.
Before you code
Before you begin coding, you should work with your data quality expert to
create and appropriate Data Services data flow. For more information about
using the Global Suggestion Lists transform in a data flow, see the Address
Cleanse section of the Data Services Designer Guide.
To retrieve Global Suggestion Lists information
1. Send your input record to your data flow using the web service.
2. If necessary, decode escaped XML in the response document.
Note:
Global Suggestion Lists component tags are an escaped XML string. If
your Data Services dataflow is configured so that the Output Style option
for Global Suggestion Lists is XML, be aware that the XML string that is
50 Data Services Integrator's Guide
Using Data Services as a web service provider
Integrating Global Suggestion Lists functionality
returned is fully escaped (encoded). For example, the POSTCODE tag will
be returned as <POSTCODE>.
You can either decode the string within the PICKINFO tags before using
an XML parser, or configure your dataflow to return a delimited string and
manually parse components out of that string.
3. Parse through the response document to find the value of the STATUS
tag.
4. Use the value of the STATUS tag to determine what steps you take next.
For example, you may use a switch statement like in this pseudo-code
example:
switch{Status}
{
case "C":
CompleteProcessing();
break;
case "D":
RetrieveMoreData();
break;
case "E":
ResolveError();
break;
case "P":
DisplayPickList();
break;
default:
break;
}
3
Each case in the switch statement requires a different procedure to continue
with the Global Suggestion Lists process.
To complete Global Suggestion Lists processing
If the STATUS tag in the response document has a value of C, that means
the processing is complete. At this point, your code might do one or more of
the following steps:
• Display the final data to your user.
• Directly populate a database with the complete record.
• Send the transaction to another Data Services data flow for further
processing.
Data Services Integrator's Guide 51
Using Data Services as a web service provider
3
Integrating Global Suggestion Lists functionality
To retrieve additional data
If the STATUS tag in the response document has a value of D, that means
Data Services requires additional data before Global Suggestion Lists
processing can be completed.
1. Parse through the response document to find the value of the DATA_TYPE
tag.
2. Use the value of the DATA_TYPE tag to determine what steps to take next.
Again, you may use a switch statement to execute different code
depending on the value.
For example, a value of R means that primary range information is needed.
If you receive this value, you might then call a function to create a prompt
box asking the user to enter the primary range.
3. Resubmit the entire record to your data flow using the web service.
However, this time, include the additional field that contains the additional
data required to complete processing.
4. Repeat the steps for retrieving Global Suggestion Lists information.
Usually, submitting the additional data is enough to complete the Global
Suggestion Lists process. Occasionally, however, more information is
required before the process can be completed.
Related Topics
• To retrieve Global Suggestion Lists information on page 50
To resolve errors
If the STATUS stag in the response document has a value of E, that means
Global Suggestion Lists has encountered an error and cannot continue
processing.
1. Parse through the response document to find the value of the ERROR tag.
2. Use the value of the error tag to determine which steps to take next.
a. If the ERROR value is 1, parse through the response document for the
values within the SYSTEM_ERROR_DESCRIPTION and/or SYSTEM_ER
ROR_NUMBER tags. Use those values to determine which action to take
next.
52 Data Services Integrator's Guide
b. If the ERROR value is 2, there was an error with the pick list selection.
For example, there may have been only 3 pick lists generated, but an
index number of 7 was submitted.
3. After resolving the error, repeat the steps for retrieving Global Suggestion
Lists information.
Related Topics
• To retrieve Global Suggestion Lists information on page 50
To display a pick list
The main advantage of Global Suggestion Lists functionality is that your
users can enter minimal data and receive pick lists to help them incrementally
complete an address. For example, they might enter only a locality and
country, and then Global Suggestion Lists returns a pick list with a postcode
and possible street addresses.
Exactly how you choose to display the pick list information is up to you, but
this section explains how you can retrieve the data to display, and what you
must retrieve from the user's selection.
1. Parse through the response document to find the value of the PICK_COUNT
tag.
2. Create a loop to iterate through each LIST tag entry to retrieve--the
information listed in the next step.
3. Query the response document for the values of any fields you want to
display to the user. These fields are represented as tags nested under
each LIST tag.
4. If the SELECTION number of the last LIST tag entry is lower than the value
in the PICK_COUNT tag, you must take some additional steps.
In pseudocode, this logic might be represented like this:
Using Data Services as a web service provider
Integrating Global Suggestion Lists functionality
3
IF (PICK_COUNT value > value of last SELECTION tag)
{Do additional steps;}
5. Display the appropriate information for each pick list to your users.
For example, if you user entered Locality info, you would likely display
the data from primary name and postcode fields, at a minimum. The exact
fields available to you depend on what is set up in your Data Services
data flow.
Data Services Integrator's Guide 53
Using Data Services as a web service provider
3
Integrating Global Suggestion Lists functionality
However, be sure to maintain an association between the value of the
SELECTION tag and each selection from the pick list you display.
6. Allow your users to select one of the available selections you displayed
in the previous steps.
7. Retrieve the value of the SELECTION tag that is associated with the
selection that your user chose.
8. Resubmit the entire record to your data flow using the web service.
However, this time, include the additional ReplyX field with your input.
The value of this field is the index number that you retrieved in the previous
step.
The ReplyX field should be mapped to the Global Suggestion Lists
transform as an input field.
9. Repeat the process for retrieving Global Suggestion Lists information,
starting with the steps that deal with the STATUS tag.
Related Topics
• To handle large pick lists on page 54
• To retrieve Global Suggestion Lists information on page 50
To handle large pick lists
In your Data Services data flow, you define a length for the field that contains
the pick list information. This value is defined in the Global Suggestion Lists
transform as the length of the SUGGESTION_LIST output field.
If the returned pick list exceeds the length specified here, your return
document contains only the first X number of of complete pick selections
that it could fit within this length. In this case, your code must perform some
additional steps.
1. Insert some mechanism in your UI so that the user can request more pick
list selections. For example, a More link that is shown only when the
previous logic condition is met.
2. When you user requests more pick selections, resubmit the entire record
to your data flow using the web service. However, this time, include the
additional START_SELECTION field with your unput. The value of this field
is the value of the SELECTION tag in the last pick selection plus one.
3. Repeat the steps for displaying a pick list to users.
54 Data Services Integrator's Guide
Using Data Services as a web service provider
Enabling SSL support
You may need to repeat this process multiple times, depending on the
length of the returned pick lists and the length allowed in your pick list
field.
Example: Pseudocode
var pick_count = value of PICK_COUNT tag
var selection = value of last SELECTION tag
IF (pick_count > selection)
{
Display the More button;
}
IF (user clicks More button)
{
inputXMLStringData = original input XML string +
"<START_SELECTION>" + ConvertToString(selection+1) +
"</START_SELECTION>"
runTransactionDataflowWithXmlData(hostName, portNumber,
reposPath, dataflowOptions, substVarOptions, shouldBlock,
inputXMLStringData)
}
Related Topics
• To display a pick list on page 53
3
Enabling SSL support
To configure SSL on the web application server
For 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.
Data Services Integrator's Guide 55
Using Data Services as a web service provider
3
Error reporting
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.
Error reporting
Data Services uses web services to define every operation with both an input
and output message. In addition to the output message, Data Services returns
a fault message when an error occurs.
Administrator log
In addition to the fault message, 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 Data Services Administrator components share the Administrator's log.
Data Services pre-fixes 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.
56 Data Services Integrator's Guide
Data Services creates the Administrator's log file in: LINK_DIR\log\webad
min.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
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 LINK_DIR\log.
Error messages
Using Data Services as a web service provider
Error reporting
3
The following are error messages that you might encounter if you are using
Data Services as a web service 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 Data Services 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 Data Services.
To find extended error information, use the WebService.log file in
LINK_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.
Data Services Integrator's Guide 57
Using Data Services as a web service provider
3
Error reporting
To find extended error information, use the WebService.log file in
LINK_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 (LINK_DIR/log/JobServerName/server_event
log.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>
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
LINK_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 Job
ServerName. 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 (LINK_DIR/log/JobServerName/serv
er_eventlog.txt).
58 Data Services Integrator's Guide
Related Topics
• Administrator log on page 56
Using Data Services as a web service provider
Error reporting
3
Data Services Integrator's Guide 59
Using Data Services as a web service provider
Error reporting
3
60 Data Services Integrator's Guide
Consuming external web services in Data Services
4
Consuming external web services in Data Services
4
To access a web service using the Designer
You can add functionality to Data Services to invoke web services in external
applications from Data Services data flows. This functionality requires
configuring Data Services' 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
Services 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 an 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.
To access a web service using the
Designer
To configure access to a specific web services, use the Designer to create
a web service datastore. Data Services provides access to web services as
stream-oriented function calls, which it configures when you import metadata.
When you configure a web service datastore, 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.
1. Create a web service datastore.
62 Data Services Integrator's Guide
type
Consuming external web services in Data Services
To access a web service using the Designer
DetailsParameter
Choose Web Service.Datastore
4
Web Service
URL
User name
Password
XML Recursion Level
Keystore path
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 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.
Data Services 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.
Specify the location of the external web service to accept a
connection and return WSDL.
Enter the user name for HTTP basic authentication. Required
only if basic authentication is needed to connect to the web
service provider.
Enter the password for HTTP basic authentication. Required
only if basic authentication is needed to connect to the web
service provider.
Enter the number of passes Data Services should run
through the XSD to resolve names. The default is 0.
If the web service provider uses an SSL connection, specify
the location of the keystore used to establish the connection.
3. From the Designer, add a web service function call to a job.
As a web services client, Data Services 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 Data
Services Designer Guide.
Data Services Integrator's Guide 63
Consuming external web services in Data Services
4
To add web service calls to a job
To add 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 a 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.
Note:
If you want to nest data in the target schema, use this first Query transform
to palce 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 suppling input to the function call
and extracting the response information obtained from the web service.
Enabling SSL support
To configure 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 Data
Services Designer Guide.
64 Data Services Integrator's Guide
Consuming external web services in Data Services
Inxight integration for reading unstructured text
To configure 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</param
eter>
</transportReceiver>
<transportSender name="https" class="axis2_http_sender">
<parameter name="PROTOCOL" locked="false">HTTP/1.1</param
eter>
</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.
4
<parameter name="SERVER_CERT">/path/to/ca/certificate</param
eter>
6. If you need client authentication, additionally provide the private key and
keystore passphrase.
<parameter name="KEY_FILE">/path/to/client/certifi
cate/chain/file</parameter>
<parameter name="SSL_PASSPHRASE">passphrase</parameter>
Inxight integration for reading
unstructured text
You can extract and transform contents from unstructured text by calling the
Inxight SDX (SmartDiscovery Extraction Server) via Web services. Use the
Data Services Integrator's Guide 65
Consuming external web services in Data Services
4
Inxight integration for reading unstructured text
base64_encode and base64_decode functions to pass data to Inxight using
the required base64 encoding.
The following procedure describes how to use Data Services with Inxight
SDX Web services.
1. In the Designer, create an adapter datastore that connects to the Inxight
SDX Web service.
2. From the Inxight adapter datastore, import an operation, which becomes
the adapter Web service function.
3. Open the adapter function and edit the schema as necessary, for example
increase the column length of the base64 text column.
4. In the data flow query, use the base64_encode function to encode the
input text to base64.
5. Use another Query transform to call the Inxight Web service function and
pass the encoded text as input.
6. Use the base64_decode function to decode the returned result as plain
text again.
For more information, seeReference Guide: Functions and Procedures,
base64_encode and
Reference Guide: Functions and Procedures, base64_decode .
66 Data Services Integrator's Guide
Using the Message Client API
5
Using the Message Client API
5
Interface components
You can integrate 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 Data Services.
In the execution of real-time jobs with real-time services APIs, these steps
take place:
1. A Data Services administrator logs into the Management Console and
2. An administrator chooses which Access Server to run the services on
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,
5. The job servers route requests to an engine to process the real-time job.
chooses which real-time jobs to expose as real-time services. Those job
names are stored in the local repository.
and starts the real-time services.
which then sends information to various job servers.
File location
The Message Client API files for each supported platform are installed to
LINK_DIR\SDK\RTSDK. When Data Services 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 Data Services
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
68 Data Services Integrator's Guide
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.
• 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)
Using the Message Client API
Interface components
5
A class that returns exceptions thrown by the connection object and
system exceptions, if available.
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.
Data Services Integrator's Guide 69
Using the Message Client API
5
Sending messages
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 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 Data Services to process the message. There is a one-to-one
correlation between business operation, service, job, and XML source.
Call the Invoke method with a string return value to process a synchronous
response.
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.
Sample applications
Data Services includes sample applications that use the Message Client
API. By default, the C++ sample application is installed to
LINK_DIR\SDK\RTSDK\Samples\platform and the Java sample application
is installed to LINK_DIR\SDK\RTSDK\Samples\Java.
To compile and run the C++ sample application on UNIX
1. Ensure that your C++ compiler and make utility are found in the PATH
environment variable for your UNIX system.
2. Modify the LINK_DIR parameter in rts_env.sh.
Set %LINK_DIR% to install_path/MessageClient.
70 Data Services Integrator's Guide
Using the Message Client API
Sample applications
rts_env.sh can be found in install_path/MessageClient/SDK/RTS
DK/Sample after extracting the archive.
3. Run rts_env.sh to initialize required environment variables.
. install_path/MessageClient/SDK/RTSDK/Sample/rts_env.sh
4. Change to the Samples directory and modify and compile the sample
application.
Change the host name and port in the sample_client file to the host
name and port for your Access Server. By default, the host name is lo
calhost, and the port is 4000.
cd install_path/MessageClient/SDK/RTSDK/Samples/platform
make
5. Configure the real-time service.
a. Create a functioning real-time job in the Designer by importing
testOrderRT.atl.
b. Add the repository for the Designer in the Management Console
Administrator.
c. Navigate to the Real-time > Real-time services > Real-time services
configuration node in the Administrator.
d. Select TestOrderRT and enter TestOrderRT for the service name to
add the real-time job as a service.
e. Navigate to the Real-time > Real-time services > Real-time services
status node in the Administrator.
f. Select TestOrderRT and click Start to start the service.
The status for the service should change to “Service Started”, indicating
that the service is ready to accept real-time calls. You may need to
refresh the page to see the change in status.
5
6. Run the sample client application.
./sample_client
Data Services Integrator's Guide 71
Using the Message Client API
5
Sample applications
To compile and run the Java sample application on UNIX
1. Modify the JAVA_HOME parameter in rts_env.sh.
Set %JAVA_HOME% to the exact location of your Java installation.
rts_env.sh can be found in install_path/MessageClient/SDK/RTS
DK/Sample after extracting the archive.
2. Run rts_env.sh to initialize required environment variables.
. install_path/MessageClient/SDK/RTSDK/Sample/rts_env.sh
3. Change to the directory where you installed the Message Client API files
and run the javac utility.
cd install_path/MessageClient/SDK/RTSDK/Samples/Java
javac -classpath ../../Java/rtsClient.jar *.java
4. Configure the real-time service.
a. Create a functioning real-time job in the Designer by importing
testOrderRT.atl.
b. Add the repository for the Designer in the Management Console
Administrator.
c. Navigate to the Real-time > Real-time services > Real-time services
configuration node in the Administrator.
d. Select TestOrderRT and enter TestOrderRT for the service name to
add the real-time job as a service.
e. Navigate to the Real-time > Real-time services > Real-time services
status node in the Administrator.
f. Select TestOrderRT and click Start to start the service.
The status for the service should change to “Service Started”, indicating
that the service is ready to accept real-time calls. You may need to
refresh the page to see the change in status.
5. Run the sample client application.
72 Data Services Integrator's Guide
java -classpath ../../Java/rtsClient.jar:. sample_client
C++ API reference
Class RTServiceClient
RTServiceClient
Contains C++ methods for allowing a client to connect to real-time services.
Method summary
Using the Message Client API
C++ API reference
5
virtual void
virtual char*
virtual void
Constructor detail
RTServiceClient
RTServiceClient(){}
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.
hostname - the name or IP address of the machine that hosts the Access
server.
connect (char* hostname unsigned short port )
invoke (char* serviceName char* inData )
disconnect ( )
port - the port number used for the connection.
Data Services Integrator's Guide 73
Using the Message Client API
5
C++ API reference
invoke
virtual char* invoke(char* serviceName, char* inData)
Sends the input data to the real-time service and returns the output data.
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.
Class RTServiceClientError
RTServiceClientError
Represents an error object thrown by the C++ class RTServiceClient.
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.
74 Data Services Integrator's Guide
Java API reference
Class RTServiceClient
com.businessobjects.rtsclient.RTServiceClient
Contains Java methods for allowing a client a connection to real-time services.
Method Summary
Using the Message Client API
Java API reference
5
public void
public java.lang.String
public void
Method detail
connect
public void connect (java.lang.String machineName, int port)
throws RTServiceExceptionThrows:
Establishes a connection between a client and Data Services. You must
establish a connection before a message can be exchanged.
machineName - the name or IP address of the machine that hosts the Access
Server.
port - the port number used for the connection.
connect ( char * machineName int port ) throws RTServiceExceptionThrows:
invoke (java.lang.String serviceName java.lang.String inData ) throws RTServiceExceptionThrows:
disconnect ( ) throws RTServiceExceptionThrows:
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.
Data Services Integrator's Guide 75
Using the Message Client API
5
Java API reference
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 Data Services.
76 Data Services Integrator's Guide
Using the JMS adapter
6
Using the JMS adapter
6
Introduction
Introduction
About this section
This section provides a detailed step-by-step method of installing and
configuring the Data Services JMS adapter. It includes a description of
required support software, including supported versions, details of the adapter
components, environment setup both for Data Services and external
applications, and instructions for executing the adapter.
Who should read this section?
This section assumes the following:
• You understand how to use Data Services Designer to design and run
real-time data flows (RTDFs) and batch jobs.
• You have a basic understanding of how to use Data Services Administrator
to administer Data Services processes. (You administer adapters from
the Administrator.)
• You have a working knowledge of the environment this adapter is
targeting.
• You know the role an adapter plays in business systems integration.
• You have some familiarity with XML and XML configuration schemas.
• Also, to integrate Data Services with an external system, Business Objects
recommends that you be familiar with systems administration and systems
integration issues.
General Data Services product documentation assumes the following:
• You are an application developer, consultant or database administrator
working on data extraction, data warehousing, or data integration.
• You understand your source and target data systems, DBMS, legacy
systems, business intelligence, and messaging concepts.
• You understand your organization's data needs.
• If you are interested in using this product to design real-time processing
you are familiar with:
• DTD and XML Schema formats for XML files
• Publishing Web Services (WSDL, HTTP/S and SOAP protocols, etc.)
78 Data Services Integrator's Guide
• You are familiar with Data Services installation environments: Microsoft
Windows or UNIX.
Adapter overview
Typical enterprise infrastructure is a complex mix of off-the-shelf and custom
applications, databases, ERP applications etc. Data Services combines and
extends critical Extraction Transformation Loading (ETL) and Enterprise
Application Integration (EAI) technology components required for true
enterprise data integration.
Integrating disparate applications with the Data Services platform requires
adapters. These adapters help facilitate otherwise incompatible applications
and systems work together, thereby sharing data.
About Java Messaging Service (JMS)
Enterprise-messaging or Message Oriented Middleware (MOM) products
are fast becoming an essential component for integrating intra-company
operations. They allow separate business components to be combined into
a reliable, yet flexible, system. In addition to the traditional MOM vendors,
several database vendors and Internet-related companies also provide
enterprise-messaging products.
Using the JMS adapter
Introduction
6
Java language clients and Java language middle-tier services must be
capable of using these messaging systems. Java Messaging Service (JMS)
provides a common way for Java language programs to access these
systems.
JMS is a set of interfaces and associated semantics that define how a JMS
client accesses the facilities of an enterprise-messaging product. Since
messaging is peer-to-peer, all users of JMS are generically referred to as
clients. A JMS application is composed of a set of application-defined
messages and a set of clients that exchange them. Products that implement
JMS do this by supplying a provider that implements the JMS interfaces.
Scope of the JMS adapter
• Data Services initiates Request/Reply
Data Services Integrator's Guide 79
Using the JMS adapter
6
Installation and configuration
Data Services initiates the request by sending the message on a
pre-configured request queue and gets the reply on a pre-configured reply
queue.
• Data Services initiates Request/Acknowledgment
Data Services initiates the request by sending the message on a
pre-configured target queue or by publishing a message to a JMS topic.
In this case, only the acknowledgment is sent back to Data Services.
• IR initiates Request/Acknowledgment & Request/Reply
In this case, an external Information Resource (IR is a JMS compatible
application) sends the requests to Data Services and gets the reply or
acknowledgment.
Alternatively, the IR publishes a message to a JMS topic to which the
JMS adapter has subscribed.
Installation and configuration
JMS adapter installation
This section details the components of the Data Services Adapter for JMS
as well as system requirements.
The Data Services Adapter for JMS is automatically installed when you install
Data Services version 12.0.0 or later.
System prerequisites
Before you install your Data Services Adapter for JMS, ensure that the
following software is installed. For specific installation instructions, see the
technical documentation for each product.
80 Data Services Integrator's Guide
Using the JMS adapter
Installation and configuration
CommentVersionSoftware
6
JMS Provider
11.7.0 or laterData Services
2.0.0.0 or laterData Services
Adapter SDK
Adapter product components
The following diagram shows a functional overview of the Data Services
Adapter for JMS with other components and their potential interrelationships:
For example, Weblogic Application
Server
Use Data Services to configure the services and adapter
Data Services Integrator's Guide 81
Using the JMS adapter
6
Installation and configuration
The diagram shows the architecture and functionality of the Data Services
Adapter for JMS as well as how the Data Services Adapter for JMS interacts
with the external JMS application through the JMS Provider. The Data
Services Adapter for JMS sends or receives data on queues using the Point
to Point (P2P) mode of communication, or publishes or subscribes to a JMS
topic using the Publish/Subscribe mode of communication.
The flow of control in the previous diagram is as follows:
1. External application invokes a service on Data Services.
2. Based on the service invoked on Data Services, its respective real-time
3. This operation instance sends the message to the configured queue or
4. External JMS application sends messages to the JMS Provider on a
data flow (RTDF) invokes the Operation instance with XML data sent by
the external application as input.
topic in the JMS provider. Based on the type of operation (such as
Request/Reply or Request/Acknowledge), the JMS provider sends the
Reply/Acknowledgment message back to Data Services.
request queue or publishes the message to a topic. The JMS Adapter
receives these messages after polling them from the JMS Provider and
for P2P, sends the reply back to external JMS application on a configured
reply queue. No reply is sent if the message was from a topic.
JMS adapter configuration
Before the Data Services Adapter for JMS can begin integrating the JMS
Provider with the Data Services system you must create and configure at
least one adapter instance and at least one operation for each instance.
Adapter instances identify the JMS Application used in the integration.
Adapter operations identify the integration operations to be used with the
configured adapter instance.
Operations provided with Data Services Adapter for JMS include the following:
• PutGet Operation (Request/Reply): Data Services initiates a request,
sending a message on a pre-configured request queue. Simultaneously,
Data Services listens on a pre-configured reply queue. An external
JMS-compatible application listens on the request queue, processes the
request, and returns an XML response message to the reply queue. The
adapter sends the message to the Data Services service.
• Put Operation (Request/Acknowledgment): Data Services initiates a
request, sending a message on a pre-configured target queue. If the
82 Data Services Integrator's Guide
Using the JMS adapter
Installation and configuration
message was sent successfully, the adapter sends an acknowledgement
to the Data Services service. The adapter raises an exception if it was
unable to send the message.
• Get Operation (Request/Acknowledgment and Request/Reply from
Information Resource): An external information resource (IR) sends a
request XML message to a JMS queue. The adapter polls the JMS queue
at a time interval you specify in the configuration. When the adapter
receives a message from the JMS queue, it sends the message to the
pre-configured Data Services service.
After processing the XML message, the Data Services service may send
a response message to the adapter. When this happens, the adapter
puts the message in a pre-configured response queue. If the response
queue is not configured, it becomes a request/acknowledgment operation
and no reply is sent. If there is any error in invoking another service from
the Data Services service, the original message is sent to the undelivered
queue for reference by the IR.
• PutTopic Operation (Request/Acknowledgment): A Data Services service
initiates a request, publishing an XML message to a pre-configured target
topic. If the message was sent successfully, the adapter sends an
acknowledgement to the Data Services service. The adapter raises an
exception if it was unable to send the message.
• GetTopic Operation (Request/Acknowledgment): An external information
resource (IR) publishes an XML message to a JMS topic. The adapter
polls the topic at the time intervals specified in the configuration. When
the adapter receives the message from the topic, it sends the message
to the Data Services service that handles the message.
6
To configure the JMS adapter
All Data Services adapters communicate with Data Services through a
designated Adapter Manager Job Server. Install adapters on the computer
containing your designated Adapter Manager Job Server. This special Job
Server integrates adapters with Data Services using the Administrator and
Designer. After you install your adapter:
1. Use the Server Manager utility to configure adapter connections with the
Adapter Manager Job Server.
2. From the Data Services Administrator, perform the following tasks:
• Add at least one instance of the adapter to Data Services system.
• Add at least one operation for each adapter instance.
Data Services Integrator's Guide 83
Using the JMS adapter
6
Installation and configuration
• Start the adapter instance (operations are started automatically).
3. Open the Data Services Designer and create an adapter datastore. Use
metadata accessed through the adapter to create batch and/or real-time
jobs.
Related Topics
• Installation Guide: To configure Job Servers
To configure an adapter instance in the Administrator
From the Data Services Administrator you can add a JMS adapter to the
Data Services system as well as edit existing adapter configurations. Add
the adapter in the Administrator before you run jobs that use information
from that adapter.
1. Select Adapter Instances > Job Server.
2. Select the Configuration tab.
3. Click Add.
4. Select JMSAdapter from the list of adapters available on this Job Server
and click Apply.
5. Enter the required information to create a JMS Adapter instance and click
Apply.
The Administrator makes the adapter instance available to Data Services.
Adapter instance configuration information
To configure a JMS adapter instance in Data Services, you need to complete
the fields in the Administrator under Adapter instance startup configuration.
84 Data Services Integrator's Guide
Using the JMS adapter
Installation and configuration
DescriptionField
6
Adapter Instance
Name
Access Server
Host
Access Server
Port
Adapter Retry
Count
Interval
Classpath
Enter a unique name that identifies this instance of the
adapter.
Enter the host ID of the computer running the Access
Server that connects to this adapter instance. To run a realtime job, you must configure a service that the Access
Server will use to run the job. When a job uses adapterbased data, the Access Server must be able to connect to
the adapter instance.
The message broker port of the Access Server host. After
you log into the Administrator for this Access Server, select
Configuration > Client Interfaces to view message broker
port information.
Applies if adapter instance fails or crashes. Enter 0 for no
retries; enter a negative number for indefinite retries.
Wait in msec. between adapter retry attempts.Adapter Retry
The adapter is a Java program, so you must configure the
jar files required by the adapter CLASSPATH. The adapter
is pre-configured with all necessary jar files except for the
vendor-specific JMS provider jar files. Add your JMS
provider's jar files to the CLASSPATH. For example:
• <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_jms_adapter.jar
• <LINK_DIR>/ext/lib/jms/<JMS Provider Jar
File>
Autostart
Note:
Specify the jar file provided with the JMS provider that you
are using. For Weblogic, the name of jar file is weblog
ic.jar.
When set to True, the adapter interface automatically starts
when the Administrator starts.
Data Services Integrator's Guide 85
Using the JMS adapter
6
Installation and configuration
DescriptionField
Trace Mode
Additional Java
Launcher Options
Adapter Type
Name
Adapter Version
Adapter Class
Set this flag to control the number of trace messages the
adapter produces. There are two settings:
• True: The adapter interface writes information and error
messages to help debug problems. The adapter writes
information and error messages to the adapter_in
stance_name_trace.txt file in the
LINK_DIR\adapters\logs directory.
• False: The adapter interface writes only error information
messages. The adapter writes error messages to the
adapter_instance_name_error.txt file in the
LINK_DIR\adapters\logs directory.
Additional command line parameters used for the
javaw.exe command line and for the adapter itself. (See
specific adapter documentation for details.)
(Read-only) Name of the adapter used to create this instance.
(Read-only) Version of the adapter used to create this instance.
(Read-only) Name that identifies the adapter class. The
name depends on the type of adapter.
In the JMS Adapter section, select a Configuration Type and enter
Configuration parameters.
DescriptionParameter
Configuration
Type
Uses only the configuration parameters associated with the
selected configuration type.
• JNDI configuration type
• MQ configuration type
For the JNDI configuration type, use the following configuration parameters.
86 Data Services Integrator's Guide
Using the JMS adapter
Installation and configuration
DescriptionParameter
6
Server URL
JNDI Context
Factory
Queue Connection Factory
Topic Connection Factory
Represents the URL of the JMS Provider. For example:
t3://<JMS Provider IP Address>:<port number>.
JNDI context factory name is JMS Provider specific. You can
choose the context factory from a list.which includes common
context factories. If you require a context factory that is not
listed, you can add it to the list by editing file
%LINK_DIR%/adapters/config/templates/JM
SAdapter.xml and updating the <jndiFactory> element.
For Weblogic as a JMS Provider, the JNDI Factory name is:
weblogic.jndi.WLInitialContextFactory.
Queue connection factory name. For example: JMSConnec
tions.AdapterConnectionFactory.
Topic connection factory name. For example: JMSConnec
tions.AdapterTopicConnectionFactory.
For the MQ configuration type, use the following configuration parameters.
Data Services Integrator's Guide 87
Using the JMS adapter
6
Installation and configuration
DescriptionParameter
MQ Queue
Manager
Name
MQ Channel
Name
MQ Computer
Name
MQ User ID
MQ Password
(Optional) Specify if not using the default MQ Queue Manager
on the system running MQ.
(Optional) Specify if not using the default MQ Channel on the
system running the adapter.
(Optional) Specify if not using the MQ Queue Manager on the
same system running the adapter.
(Optional) Specify if not using the default MQ port (1414).MQ Port
(Optional) Specify if required to login to the MQ Queue Manager.
(Optional) Specify if required to login to the MQ Queue Manager.
To add an operation instance to an adapter instance
1. Select Configuration > Adapter instances.
2. Click Operations under Dependent Objects.
3. Click Add to configure a new operation. Or, you can click the link of an
existing operation instance to edit its configuration.
4. Select an operation type from the list and click Apply. The options that
appear on this page vary based on operation-specific design.
Complete the operation instance configuration form and click Apply.
Operation instance configuration options
Each operation type contains different configuration options. Operations
include:
• Put Operation (request/acknowledgment) options
• PutTopic Operation (request/acknowledgment) options
• PutGet Operation (request/reply) options
• Get Operation (request/reply and request/acknowledgment) options
• GetTopic Operation (request/acknowledgment only) options
88 Data Services Integrator's Guide
Using the JMS adapter
Installation and configuration
Note:
When specifying a queue or topic, you must provide the JNDI queue name
or the MQ queue name as indicated by the Adapter Configuration Type
property.
Put Operation (request/acknowledgement) options
To set up an operation instance of type Put Operation in Data Services,
complete the following fields in the Administrator.
DescriptionFIeld
6
Operation instance
Thread count
Operation retry
count
Operation retry
interval
Display name
Description
Enable
The unique operation instance name. In the Designer, your
operation metadata object is imported with this name.
The number of copies of Request/Reply operation to run in
parallel. For parallel (asynchronous) processing of messages
coming from real-time service, more than one copy should
be used. But if the sequence of messages is important
(synchronous processing), more than one thread should not
be used. (Multiple copies of real-time services must be supported by multiple instances of Request/Reply.) The default
is 1.
The number of times to retry this operation if it fails. Enter 0
to indicate no retries are to be attempted. Enter a negative
number to indicate the operation should be retried indefinitely.
The time (in milleseconds) to wait between operation retry
attempts.
The display name of the operation instance. This display
name is visible in the Designer's metadata browsing window.
The description of the operation instance. This description
is visible in the Designer's metadata browsing window.
Whether to enable the operation to start at the same time as
the adapter instance. Valid values are true and false.
• When true, the operation starts when the adapter instance
starts.
• When false, the operation needs to be started manually
from "Adapter Operations Status" window of the adapter
administrator.
Data Services Integrator's Guide 89
Using the JMS adapter
6
Installation and configuration
DescriptionFIeld
Destination
Queue
Request Format
Root Element
The name of the destination queue where the message will
be sent.
The DTD or XSD file name that defines the XML message
used in the operation.
The name of the XML root element.Request XML
PutTopic Operation (request/acknowledgement) options
To set up an operation instance of type PutTopic in the Data Services,
complete the following fields in the Administrator.
DescriptionField
Operation instance
Thread count
The unique operation instance name. In the Designer, your
operation metadata object is imported with this name.
The number of copies of Request/Reply operation to run in
parallel. For parallel (asynchronous) processing of messages
coming from real-time service, more than one copy should
be used. But if the sequence of messages is important
(synchronous processing), more than one thread should not
be used. (Multiple copies of real-time services must be supported by multiple instances of Request/Reply.) The default
is 1.
Operation retry
count
Operation retry
interval
Display name
Description
90 Data Services Integrator's Guide
The number of times to retry this operation if it fails. Enter 0
to indicate no retries are to be attempted. Enter a negative
number to indicate the operation should be retried indefinitely.
The time (in milliseconds) to wait between operation retry
attempts.
The display name of the operation instance. This display
name is visible in the Designer's metadata browsing window.
The description of the operation instance. This description
is visible in the Designer's metadata browsing window.
Using the JMS adapter
Installation and configuration
DescriptionField
6
Enable
Destination
Topic
Message Format
Root Element
Persistent Message
Whether to enable the operation to start at the same time as
the adapter instance. Valid values are true and false.
• When true, the operation starts when the adapter instance
starts.
• When false, the operation needs to be started manually
from "Adapter Operations Status" window of the adapter
administrator.
The topic to which the operation is published. Use JNDI or
MQ name as specified by Adapter Configuration Type.
The DTD or XSD file name defining the XML message used
in this operation.
The name of the XML root element.Request XML
Whether to make published messages available to durable
subscribers. Valid values are true and false. When true,
published messages are available to durable subscribers.
PutGet Operation (request/reply) options
To set up an operation instance of type PutGet Operation in Data Services,
complete the following fields in the Administrator.
Data Services Integrator's Guide 91
Using the JMS adapter
6
Installation and configuration
DescriptionField
Operation instance
Thread count
Operation retry
count
Operation retry
interval
Display name
Description
Enable
The unique operation instance name. In the Designer, your
operation metadata object is imported with this name.
The number of copies of Request/Reply operation to run in
parallel. For parallel (asynchronous) processing of messages
coming from real-time service, more than one copy is used.
If the sequence of messages is important (synchronous
processing), more than one thread should not be used.
(Multiple copies of real-time services must be supported by
multiple instances of Request/Reply.) The default is 1.
The number of times to retry this operation if it fails. Enter 0
to indicate no retries are to be attempted. Enter a negative
number to indicate the operation should be retried indefinitely.
The amount of time (in milliseconds) to wait between operation retry attempts.
The display name of the operation instance. This display
name is visible in the Designer's metadata browsing window.
The description of the operation instance. This description
is visible in the Designer's metadata browsing window.
Whether to enable the operation to start at the same time as
the adapter instance. Valid values are true and false.
• When true, the operation starts when the adapter instance
starts.
• When false, the operation needs to be started manually
from "Adapter Operations Status" window of the adapter
administrator.
Request Queue
Reply Queue
Timeout
92 Data Services Integrator's Guide
The name of the destination queue where the message will
be sent.
The name of the destination queue where the message will
be sent.
The maximum time (in milliseconds) the operation should
wait for the reply message.
Using the JMS adapter
Installation and configuration
DescriptionField
6
Continue After
Error
Request Format
Request XML
Root Element
Reply Format
Element
Whether to continue after encountering an error. Valid values
are true and false.
• When true, the operation instance remains in start stage
even after the error.
• When false, the operation instance stops after the error
occurs during the process.
The DTD or XSD file name that defines the Request XML
message used in this operation.
The name of the XML root element in the Request DTD or
XSD.
The DTD or XSD file name that defines the Reply XML
message used in the operation.
The name of the XML root element in the Reply DTD or XSD.Reply XML Root
Get Operation (request/reply and request/acknowledgement) options
To set up an operation instance of type Get Operation in Data Services,
complete the following fields in the Administrator.
DescriptionField
Operation instance
Polling interval
Operation retry
count
Operation retry
interval
The unique operation instance name. In the Designer, your
operation metadata object is imported with this name.
The time interval (in milliseconds) for polling the source queue
by this operation instance. For example, If the polling interval
is 1000, then it polls the source queue after every one second.
The number of times to retry this operation if it fails. Enter 0
to indicate no retries are to be attempted. Enter a negative
number to indicate the operation should be retried indefinitely.
The time (in milliseconds) to wait between operation retry
attempts.
Data Services Integrator's Guide 93
Using the JMS adapter
6
Installation and configuration
DescriptionField
Enable
Source Queue
Service
Timeout
Continue After
Error
Whether to enable the operation to start at the same time as
the adapter instance. Valid values are true and false.
• When true, the operation starts when the adapter instance
starts.
• When false, the operation needs to be started manually
from "Adapter Operations Status" window of the adapter
administrator.
The name of the queue where the message is sent by the
IR and received by the adapter. Use JNDI or MQ name as
specified by the Adapter Configuration Type.
The name of Data Services real-time service invoked by the
operation when it receives a new message from the Source
Queue.
The maximum time (in milliseconds) that the Service takes
to process a message. If the operation instance is unable to
invoke the service within the Timeout limit, it sends the error
message to the undelivered queue.
Whether to continue after encountering an error. Valid values
are true and false.
• When true, the operation instance remains in start stage
even after the error.
• When false, the operation instance stops after the error
occurs during the process.
94 Data Services Integrator's Guide
Using the JMS adapter
Installation and configuration
DescriptionField
6
Default Response Queue
Undelivered
Queue
Request DTD
Root Element
[optional]: Used only for Request/Reply operation. In case
of Request/Acknowledgment operation, it remains blank. The
application sends the reply back to external JMS application
(IR) on this queue. Use JNDI or MQ name as specified by
the Adapter Configuration Type.
[optional]: The undelivered queue for receiving the error
messages, if any. Use JNDI or MQ name as specified by the
Adapter Configuration Type.
The name of the root element for the input DTD for this operation.
GetTopic Operation (request/acknowledgement only) options
To set up an operation instance of type GetTopic in Data Services, complete
the following fields in the Administrator.
DescriptionField
Operation instance
Polling interval
The unique operation instance name. In the Designer, your
operation metadata object is imported with this name.
The time interval (in milliseconds) for polling the source topic
by this operation instance. For example, if the polling interval
is 1000, then it polls the source topic after every one second.
Operation
retry count
Operation
retry interval
Enable
The number of times to retry this operation if it fails. Enter 0 to
indicate no retries are to be attempted. Enter a negative number
to indicate the operation should be retried indefinitely.
The time (in milliseconds) to wait between operation retry attempts.
Whether to enable the operation to start at the same time as
the adapter instance. Valid values are true and false.
• When true, the operation starts when the adapter instance
starts.
• When false, the operation needs to be started manually
from "Adapter Operations Status" window of the adapter
administrator.
Data Services Integrator's Guide 95
Using the JMS adapter
6
Installation and configuration
DescriptionField
Source Topic
Durable subscriber
Service
Timeout
Continue After Error
The topic to which the operation subscribes. Use JNDI or MQ
name as specified by Adapter Configuration Type.
The subscription name of Durable subscriber. If not applicable,
leave this field blank.
The name of Data Services real-time service invoked by the
operation when it receives a new message from the source
topic.
The maximum time (in milliseconds) that the service takes to
process a message.
Whether to continue after encountering an error. Valid values
are true and false.
• When true, the operation instance remains in start stage
even after the error.
• When false, the operation instance stops after the error
occurs during the process.
Defining a JMS adapter datastore
Use the Data Services Adapter for JMS with a batch job or real-time data
flow (RTDF) when the batch job or RTDF passes a message to an operation
instance, using either:
• An Outbound message (for Request/Acknowledge operations)
• A Message Function (for Request/Reply operations)
You must first define an adapter datastore in the Data Services Designer.
Then, the batch job or RTDF can pass a message to one of the adapter
operation instances defined in that datastore. To define an adapter, you
must:
• Define a datastore object for each adapter instance
• Define one function or one outbound message for each operation instance
to which you want to pass a message.
96 Data Services Integrator's Guide
Using the JMS adapter
Installation and configuration
For each adapter instance, define a corresponding datastore object in the
Datastore Editor window of the Designer object library.
To define a JMS adapter datastore
1. From the Datastore Editor:
a. Select the Job Server configured to manage your JMS adapter.
b. Select the Adapter instance name you configured in the Administrator.
2. Select the Adapter Properties tab and enter values for each property.
3. Click OK to save values and create the datastore.
Importing message functions and outbound messages to the datastore
You can pass messages from a batch job or RTDF to an operation instance.
Import either a function or an outbound message (depends on the type of
operation involved) in the Designer Datastore library for each operation
instance.
Real-time data flows use following methods.
6
DescriptionMethod
Message functions
Outbound
messages
Operation types in the Data Services Adapter for JMS have the following
invocation types.
Pass messages to an operation instance if the RTDF waits for
a return XML message from the IR.
Outbound messages Pass messages to an operation instance
if the RTDF waits for a confirmation only (not a return XML
message) from the IR.
Data Services Integrator's Guide 97
Using the JMS adapter
6
Using the JMS adapter
To import message functions and outbound messages
1. In Data Services Designer, double-click the datastore associated with
your JMS Adapter Instance to display the Adapter metadata browser
window.
2. Right-click the operation instance to be imported and select Import.
The selected operation instance is added to the datastore.
These message functions and outbound message functions can be used for
creating Batch Jobs or RTDFs in Data Services.
Using the JMS adapter
Invocation typeOperation type
Message FunctionRequest/Reply Operation
Outbound MessageRequest/Acknowledge Operation
To start an instance of the JMS adapter
1. From the Data Services Administrator go to Adapter Instance > Job
Server and select the Status tab.
2. Select the check-box next to the previously configured adapter instance.
3. Click Start.
When the adapter instance and its operations start, the message “Started”
appears in the Status column.
Operations from Data Services to the JMS adapter
Request/Reply - PutGet operation
Data Services initiates the request by sending a message on a pre-configured
request queue. Simultaneously, Data Services also listens on a pre-configured
reply queue. An external JMS-compatible application listening on this request
queue, after processing, sends back the response on response queue. This
response, in the form of the reply XML message, is returned back to Data
Services.
98 Data Services Integrator's Guide
Using the JMS adapter
Using the JMS adapter
Related Topics
• Testing PutGet: Request/Reply on page 102
Request/Acknowledge - Put operation
Data Services initiates the request by sending the message on a
pre-configured target queue.
Related Topics
• Testing Put: Request/Acknowledge on page 111
Request/Acknowledge - PutTopic operation
Data Services initiates the request by publishing the message to a
pre-configured target topic.
Related Topics
• Testing PutTopic: Request/Acknowledge on page 104
Operations from Information Resource (IR) to Data Services
6
Request/Reply - Get operation
IR initiates the request by putting a message in the source queue of the Get
operation. The Get operation receives the message from the source queue
during a polling cycle and sends the message to the configured Data Services
service. The service sends a reply message to the Get operation, which then
puts the message in the response queue. The IR then gets the message
from the response queue.
Related Topics
• Testing Get: Request/Reply on page 106
Request/Acknowledge - Get operation
IR initiates the request by putting a message in the source queue of the Get
operation. The Get operation receives the message from the source queue
during a polling cycle and sends the message to the configured Data Services
service.
Related Topics
• Testing Get: Request/Acknowledge on page 109
Data Services Integrator's Guide 99
Using the JMS adapter
6
Using the JMS adapter
Request/Acknowledge - GetTopic operation
IR initiates the request by publishing a message to the source topic of the
GetTopic operation. The GetTopic operation receives the message from the
source queue during a polling cycle and sends the message to the configured
Data Services service.
Related Topics
• Testing GetTopic: Request/Acknowledge on page 108
To run the sample
This section details the JMS adapter operations.
1. Import the JMSAdapter.atl file into Data Services Designer. Find the
ATL file in %LINK_DIR%/adapters/jms/samples. The imported project
name is Acta_JMSAdapter_Sample.
2. Change the input and output XML files path for all the batch jobs
depending on your location of your Data ServicesLINK_DIR environment
variable.
3. Use the Administrator Real-Time Services Configuration tab to create the
service Queue.TestService referencing job TestService_Job and
Topic.TestService referencing job TestServiceTopic_Job.
4. Open Data Services Web Administrator and configure a JMS adapter.
Define the operations detailed in the following tests.
5. Use the Data Services Designer to edit the JMSAdapter datastore and
rename it to the name of the adapter you just created.
Before running the sample, create the following queues and topic using your
JMS provider utilities:
• Queue.MyQueue
• Queue.ActaQueuePutGet
• Queue.ActaQueuePutGet1
• Queue.ActaQueueGet
• Queue.ActaReplyQueueGet
• Queue.ActaUndeliveredQueue
• Topic.MyTopic
100 Data Services Integrator's Guide
Loading...