1 Web service configuration

This chapter includes the following sections:

Overview
Configuring users
Security
WSDL
Connecting to the Topics Web Service

Overview

Using the Topics web service, you can integrate your proprietary application with Empirica Topics for users to attach artifacts from your application to new or existing topics.

Figure 1-1 API overview

In your application, you must add integration points that implement the Empirica Topics web service API, which is available using the Topics WSDL.

In this document, code snippets are displayed using Java. For a .NET application, C# techniques are comparable.

Note:

Empirica Topics is installed as part of the Empirica Signal application and includes:

The Empirica Topics web service that implements the Empirica Topics API for Save to Topic in your proprietary application.
The Topics tab in Empirica Signal for end users to view and edit their topics.
Topics administration in Empirica Signal for administrators to manage topic workflow configurations, work teams, user accounts and their permissions.

Configuring users

The Topics web service acts on behalf of your application's end users. Any of your application's end users that are accessing Topics through your application must also be provisioned with the same username and the appropriate Topics permissions and work teams on the Empirica Signal server. The Topics web service validates these Topics-specific privileges and work team permissions for that username. When you implement an API call, you must set the username field in the TopicsServiceContext. For more information, see . If your application tries to access a topic on behalf of either an unknown username or a user without valid permissions, a TopicsServiceException is generated. Only topics, actions, topic templates, and work teams that the user has permission to access are returned from any call.

Security

The WebLogic administrator must create a user for exclusive use by your application and the Topics web service. The Topics web service username and password credentials are provisioned on the Topics WebLogic server. Your application then sets this username and password along with the standard WS-SECURITY Username Token Policy as part of every web service call. The Topics server validates access to the Topics web service using these credentials. The Topics server can return an exception if the web service credentials are not correct or the Username Token Policy has not been set. The Topics web service will then not be available to your application.

WSDL

You import the Empirica Topics WSDL to generate Java or .NET proxy classes in order to access the Topics Service API. For more information on the WSDL, see the Empirica Signal distribution file, Signal_Install.tar.gz and the following files:

Topics_Service/EmpiricaTopicsService.wsdl
Topics_Service/EmpiricaTopicsService_schema1.xsd

Alternatively, your application may import from an active Empirica Topics server such as http://<hostname>:<port>/Signal/ws/topicsService?wsdl to generate a stub for the Topics web service.

Connecting to the Topics Web Service

To connect your application to the Topics web service, you need to set up web service properties in your code:

The end point address

This is the URL address of the Topics web service such as

https://<hostname>:<port number>/Signal/ws/topicsService

It is recommended that the topics web service run with SSL so that your application attaches to the service using HTTPS.
Http chunk size when sending large attachments (for Java only)

This property specifies the maximum chunking size that the web service uses when sending attachments.
Username

This is the Topics service username.
Password

This is the Topics service password.

You also need to enable the MTOMFeature in your proprietary application when calling Topic service APIs that send attachments.

Java integration

For Java applications, set the MTOMFeature for your web service. Also set up WS SECURITY and the username token policy by defining the SecurityPoliciesFeature for your web service.

The following example demonstrates how to connect to the Topics web service for each call:

// Instantiate the Topics web service proxy
EmpiricaTopicsService topicsService = new EmpiricaTopicsService(
  new URL(”https://<hostname>:<port number>/Signal/ws/topicsService?wsdl"), 
  new QName(”http://oracle.hsgbu.topics.com”, "EmpiricaTopicsService"));
BindingProvider bindingProvider = (BindingProvider)topicsService;
// Set the endpoint address for the Topics web service
bindingProvider.getRequestContext().put(
  BindingProvider.ENDPOINT_ADDRESS_PROPERTY, 
  ”https://<hostname>:<port number>/Signal/ws/topicsService");
// Set the username token policy
SecurityPoliciesFeature securityFeatures = new SecurityPoliciesFeature(
  new String[]{"oracle/wss_username_token_over_ssl_client_policy"});
// Include MTOM if this API call sends attachments
topicsService.getEmpiricaTopicsPort(new MTOMFeature(), securityFeatures);
// Set the topics username and password
bindingProvider.getRequestContext().put(
  BindingProvider.USERNAME_PROPERTY, <topics service username>);
bindingProvider.getRequestContext().put(
  BindingProvider.PASSWORD_PROPERTY, <topics service password>);
// Set a maximum chunk size when calling an API that streams attachments
bindingProvider.getRequestContext().put(
  "com.sun.xml.ws.transport.http.client.streaming.chunk.size", 8192);

Substitute your environment's values for <hostname>, <port number>, <topics service username>, and <topics service password>.

.NET integration

If your application uses .NET, you specify similar properties to the Java integration to connect to the Topics web service, but for .NET, the calls to connect are different. For example, your application will pass the Topics service URL as a parameter to connect to the Signal web service.

You must use standard .NET practices to integrate with WS Security and the Username Token Policy.