Accessing Services (Web and Local)

Accessing Services (Web and Local)
This chapter explains how to access services from your ActiveGrid application. Your application can access Web services, such as SOAP services and RSS feeds or local services, such as custom Python or PHP code. This chapter contains the following sections:
About Services
A service, in an ActiveGrid application, is a group of one or more operations that is specified in a Service Definition file for that application. In an ActiveGrid application, a service can be a SOAP service, a REST service, an RSS Feed, or your own custom Python or PHP code. ActiveGrid bases the Service Definition file on an industry standard, the Web Services Definition Language (WSDL) document. Service Definition files end in the .wsdl suffix.
ActiveGrid uses Service Definition files to orchestrate communication to and from services. Each service publishes the list of operations that it supports in a WSDL file. Each operation specifies an Input Message and an Output Message that defines the inputs and outputs for that operation. ActiveGrid applications can call the service operation by sending a request (as specified by the operation’s Input Message) and receiving a response (as specified by the operation’s Output Message):
Each operation has an Input Message that specifies the input parameters for that operation. For each input parameter the operation takes, the Input Message defines a Message Part.
Each operation has an Output Message that contains a Message Part specifying the data that operation returns.
Defining a Message Part is just like declaring a variable. You name the Message Part and you specify the data type, which can be a simple type or a complex type. (Web services have only one message part in each Input and Output Message).
ActiveGrid currently supports the following types of services:
SOAP services. SOAP (Simple Object Access Protocol) is a standard XML protocol for exposing and calling Web services. A SOAP service is described by a WSDL document, often available through a URL from the service itself.
RSS Feeds. RSS (Really Simple Syndication) defines services that provide periodically-updated lists of items. Many Web sites now provide a syndication feed that news readers and blog summaries may subscribe to. You can add a feed to ActiveGrid applications by registering the URL. ActiveGrid then connects to the service and automatically generates appropriate WSDL. Supported versions include RSS 0.91, RSS 2.0, Atom 0.3, and Atom 1.0.
REST Services. A REST (Representational State Transfer) Web Service is comprised of resources accessed through unique URLs (requests) and returned as XML responses. An XML Schema typically defines the structure of those XML responses. Before you can add a REST service to the ActiveGrid environment, you need to generate a WSDL document describing how the service will be used.
Local Services. You can also implement your own PHP or Python service according to a simple, well-defined interface. Use the Service Definition Editor to describe the service's API and register it in the ActiveGrid environment. The local service is then accessible to applications. See Adding a Local Service to an Application.
ActiveGrid Studio provides tools to help you generate WSDL files for services.
Registering Services
Your ActiveGrid Applications can consume local services (your own custom Python or PHP code, for example) as well as external Web services. For a service to be accessible to an ActiveGrid Application, it must be registered with the ActiveGrid Studio.
To register a service, you provide a service WSDL (either as a local file or as a URL) and you assign a service name.
Registering a service works differently for different types of Web services. See Registering Services.
Working with the Service Definition Editor
Use the Service Definition Editor to create, view, or edit any Service Definition (.wsdl) file in your project. This could be WSDL files associated with a specific Web or local service, or it could be the project WSDL file, which holds the session information. Note that you do not edit WSDL files for external Web services.
To open the Service Definition Editor, open the application in the ActiveGrid Studio, and double-click on the WSDL (.wsdl) file in the Project Panel. The Service Definition Editor appears.
The Project Panel and the Message panel are also accessible when you open the Service Definition Editor:
Project Panel: Displays all the files for the project.
Service Definition Editor: Displays the available operations in the WSDL file, as well as the input and output messages for the selected operation.
Property Editor: Displays properties for the selected item.
The Service Definition Editor Panel
The Service Definition Editor panel groups items into folders:
Schema: The Schema folder defines schema for the session.
Page Messages: The Page Messages folder defines the messages for each Page.
Local Service (Port Types): The Local Service folder contains service operations that you’ve defined, along with the input and output messages for each operation.
Working with the Service Definition Editor, you typically select the item you want to modify, right-click, and select an item from the menu:
Insert Operation: Launches the WSDL Operation wizard to help you add a new operation. You’re prompted to type a name for the operation and select (or create) appropriate input and output messages for it. You can add a new operation only to an existing Local Service (Port Type).
Insert Message: Create a new message. A dialog prompts you to name the message. Once the message is created, you can add parts to the message.
Insert Message Part: Launches a message part tool to allow you to add a message part to an Input or Output message. Click the Add button in the tool. A new row appears in the list of message parts. Type in a name for the new message part, and select a type from the drop-down list.
Edit Code: To edit an existing operation, select the operation from the Operations list and then click the Edit Code button. Do not edit operations published in WSDLs for external Web services.
Registering Services
Before a service may be used in an application, it must first be registered in the ActiveGrid development environment. Once a service is registered, it will be available to the application.
Registering a SOAP Service
To register a SOAP Service for use in ActiveGrid Applications, follow these steps:
1.
From the main menu bar, select Tools > Options. The Options dialog appears.
2.
3.
4.
From the Type pull-down list, select SOAP.
Click the Download button to the right of the WSDL Path field and type the URL where the WSDL file is published, then click OK. Make sure to type in the complete URL (for example, http://www.google.com/apis).
The Save WSDL As dialog appears. Browse to the directory where you want to store the WSDL file locally, type in a name for the file, and click Save.
5.
Click OK. The SOAP Service is now registered with the ActiveGrid Studio and you can add operations from the service to your ActiveGrid Applications.
Overriding SOAP Service URLs
The WSDL file for your SOAP service defines the URL where the service actually resides. In some cases you want to override this URL, typically for testing purposes. To override the Service URL defined in the WSDL, follow these steps:
1.
From the main menu bar, select Tools > Options. The Options dialog appears.
2.
3.
4.
In the Service and Port fields, type in the service name and port name for the service as they are defined in the WSDL file. For example, in the Google Search demo application, the following lines at the bottom of the GoogleSearch23.wsdl file define the service and port:
<service name="GoogleSearchService">
<port name="GoogleSearchPort" binding="typens:GoogleSearchBinding">
<soap:address location="http://api.google.com/search/beta2"/>
</port>
</service>
So, for the Google Search demo application, you would type in GoogleSearchService for the service name and GoogleSearchPort for the port name.
5.
In the Override URL field, type in the URL you want to use for the override.
6.
Adding an Extensions File for a SOAP Service (Implementing Next and Previous Buttons)
For SOAP services that return lots of results in scrolling or paging tables (search results for example) you might want to implement Next and Previous paging functionality. In order for the ActiveGrid runtime to know how to handle Next and Previous for an external service, you need to create an extensions file for that service.
The extensions file defines the Next and Previous operations so that the ActiveGrid runtime can correctly interpret them. The extensions file can also define any additional operations that you want to perform for the service. To get an idea of how extensions files work, look at the example in An Example Extensions File. For now, if you need an extensions file, you should contact ActiveGrid.
Extensions files are optional. They do not appear in the list of project files in the Project Panel.
Adding the Extensions File to the Project
To add an Extensions file, follow these steps:
1.
From the main menu bar, select Tools > Options. The Options dialog appears.
2.
3.
4.
Click the Browse button to the right of the Extensions File field and browse to the extensions file. Make sure the Extensions file is selected in the Extensions File field.
5.
Click OK. The extensions file is now registered with the SOAP Service.
An Example Extensions File
The following extensions file was written to add Next and Previous functionality to the Googlezon demo that is included in the ActiveGrid Studio. Note that the extensions file, GoogleSearch23.wsdlxt, does not appear in the Project Panel. It is located in the same directory as the .wsdl file for the project, (GoogleSearch23.wsdl).
<ag:serviceExtensions xmlns:ag="http://www.activegrid.com/ag.xsd" ag:version="10">
<ag:serviceExtension portType="GoogleSearchPort" operation="doGoogleSearch">
<ag:command type="Next">
<ag:rewrite ref="doGoogleSearch/q" value="message/data/searchQuery" />
<ag:rewrite ref="doGoogleSearch/start" value="message/data/endIndex" />
</ag:command>
<ag:command type="Prev">
<ag:rewrite ref="doGoogleSearch/q" value="message/data/searchQuery" />
<ag:rewrite ref="doGoogleSearch/start" value="message/data/endIndex - 20" />
</ag:command>
</ag:serviceExtension>
</ag:serviceExtensions>
Registering an RSS Service
When you register an RSS Service, the ActiveGrid Studio generates a WSDL for the service. To register an RSS Feed for use in ActiveGrid Applications, follow these steps:
1.
From the main menu bar, select Tools > Options. The Options dialog appears.
2.
3.
4.
In the Name field, type in a name for the service.
From the Type pull-down list, select RSS.
In the Feed URL field, type in URL for the RSS Feed.
Click the Test button to check that the feed is working.
5.
Click OK. The RSS Service is now registered with the ActiveGrid Studio and you can add the feed to your ActiveGrid Applications.
Registering a REST Service
In order to register a REST service for use in ActiveGrid Applications, you must first construct a WSDL file that describes the request and response messages for the service. To see an example of a WSDL file constructed for a Web Service, open the Amazon REST service demo that is included in the ActiveGrid Studio and look at the WSDL file AmazonREST.wsdl.
Once you’ve created a WSDL file for your REST service, you can access it just as you would a SOAP service.
Registering a Local Service
In order to register a local service, you need a WSDL file that defines the service operations and their inputs and outputs. When you use the ActiveGrid Studio to create a new local service. To register an existing local service for use in ActiveGrid Applications, follow these steps:
1.
From the main menu bar, select Tools > Options. The Options dialog appears.
2.
3.
4.
In the Name field, type in a name for the service.
From the Type pull-down list, select Local.
In the WSDL Path field, type in the path to the WSDL file for the local service, or click the Browse button to browse to it.
In the Code File field, type in the path to the code file for the local service, or click the Browse button to browse to it.
5.
Click OK. The local service is now registered with the ActiveGrid Studio and you can invoke it from your ActiveGrid Applications.
Adding Services to an Application
Before you can add a SOAP or RSS service to your application, you need to register it in the ActiveGrid Studio (Registering Services). Once your service is registered, you can include it in your application:
To add a REST service to your application, first register it (Registering a REST Service), then follow the instructions for adding a SOAP service.
Adding a SOAP Service
In order to create a Page based on a SOAP operation, you either need a SOAP service that is already registered with an ActiveGrid Application or you need to have identified a service that you can register when you create the Page.
In either case, you need to have a thorough knowledge of the WSDL file that defines the SOAP operation. You need to understand the WSDL file that defines the service, you need to know the operations defined by the service, and you need a clear understanding of all the messages and their parts, that you plan to use.
To invoke a SOAP service from an application, open the Page Flow (.bpel) file for your application and right-click to bring up the Page Flow Editor menu. Choose the Insert Service Call and Response... option. This launches the Service Invocation Wizard, which steps you through the process of invoking the SOAP service. For a step-by-step walkthrough on the Service Invocation Wizard, refer to the ActiveGrid Studio Tutorial. Look at the tutorial on Creating a New Web services Application.
Adding an RSS Feed
When you register an RSS, you are essentially registering the URL for the feed (Registering an RSS Service). ActiveGrid then connects to the service and automatically generates a WSDL for the service. ActiveGrid Applications use WSDL to access all external Web services, even non-SOAP services. To add the RSS feed to your application, you add an Action that calls the RSS service and you create a Page that displays the response from the service.
To add an RSS feed to your ActiveGrid Application, follow these steps:
1.
Open the Page Flow (.bpel) file for your application.
2.
Right-click to bring up the Page Flow Editor menu and click the Insert Service Call and Response... option. The Choose a Service screen appears.
3.
From the Service list, select the RSS service that you want to access. The Service list contains all the services that are currently registered. If the service you want does not appear in the list, click the New... button to register a new RSS feed (Registering a SOAP Service).
4.
Click Next. The Pick an Operation screen appears.
5.
Select the operation that you want to access and click Next. The Use Standard Result Page? screen appears. If you want the ActiveGrid Studio to automatically generate a Page to display the RSS feed, leave this box checked. If you want to create your own Page to show the RSS feed, click to uncheck this box. Click Next.
 
6.
If you chose to use a generated results Page in the previous screen, the How to Get to the Request Page screen now appears. Otherwise, move on to the next step.
In the How to Get to the Request Page screen you specify how you want users to access the request Page. You have two choices:
Insert a button that links to the request page. This choice inserts a button into a selected Page. When users click that button, the RSS feed result is loaded. When you choose this option, make sure to also select a Page from the pull-down list. The Page you select will contain a button linking to the request Page.
Include the request page in another Page. This choice includes the request as part of a selected Page. You can edit the layout by editing the selected Page in the Page Editor. When you choose this option, make sure to also select a Page from the pull-down list.
Make your selection and click Next. The Name the Pages screen appears. Here you name the Page that shows the results of the RSS feed.
7.
Name the Page, then click Next. The new Action appears in the Page Flow Editor.
Adding a Local Service to an Application
To invoke a local service from an application, open the Page Flow (.bpel) file for your application and right-click to bring up the Page Flow Editor menu. Choose the Insert Service Call and Response... option. This launches the Service Invocation Wizard, which steps you through the process of invoking the local service. For a step-by-step walkthrough on the Service Invocation Wizard, see the ActiveGrid Studio Tutorial. Refer to the tutorial on Creating a New Web Services Application.
Web Service Response Caching
ActiveGrid supports web service response caching. It is Python-only, works for SOAP, REST, and RSS services, and can be configured by role. This feature is available only in the commercial version of the ActiveGrid Studio.
Currently you configure caching by editing the .wsdlag file for the project. Follow these steps:
1.
2.
Open the Web Service's .wsdlag file in a text editor, such as vi or notepad. The .wsdlag file contains the serviceref definition for the web service.
3.
Under the ag:serviceref element, insert an ag:serviceCache element. The ag:serviceCache element has the following attributes:
operation=" operation-name "
where operation-name is the name of the web service operation for which you’re configuring caching.
duration="seconds"
where seconds is the number of seconds that an individual response will remain in the cache after an access (default is 600 seconds)
rolesDisabled=" role1 | role2 |...| roleN "
where role1, role2 and so on are the roles for which you’re disabling caching. Authenticated users who are in any of these roles do not use cached data. They always call the web service and get “live” data (which then updates the cache).
Here's an example of the USHolidayDates.wsdlag with no caching:
<?xml version="1.0" encoding="utf-8"?>
<serviceref name="USHolidayDates" filePath="C:\projects\wsdl\usholidays.wsdl" service­Type="SOAP" stateful="False" ag:version="11" objtype="activegrid.tool.WsdlAgEditor.Ser­viceRef"/>
After you add the ag:serviceCache element, the file might look like this:
<?xml version="1.0" encoding="utf-8"?>
<ag:serviceref name="USHolidayDates" filePath="C:\projects\wsdl\usholidays.wsdl" ser­viceType="SOAP" stateful="False" ag:version="11" objtype="activegrid.tool.WsdlAgEdi­tor.ServiceRef">
<ag:serviceCache operation="GetGoodFriday" rolesDisabled="monster" duration="60"/>
</ag:serviceref>
In this example, everybody gets caching on the GetGoodFriday operation, except users who possess the monster role. The cache duration for this operation's responses is one minute.
About Service References (.wsdlag File)
When you invoke a service in an ActiveGrid application, the ActiveGrid Studio adds the Service Definition (.wsdl) file for that service to your project folder. It also creates a .wsdlag file and adds that to your project folder as well. Each .wsdl file in an ActiveGrid project has an associated .wsdlag file.
The .wsdlag file provides the service references for the service. The deployment wizard uses these service references to deploy the application. You can edit the .wsdlag file by double-clicking on it in the Project Panel. The file appears in a very simple editor. You don’t typically need to edit this file manually.
 

ActiveGrid
Application Developer's Guide
Version 2.0