Creating a New Local Service

Creating a New Local Service
This tutorial walks you through creating a new local service for your application. In this example, we create a very simple Python service that takes no arguments and returns a string. We create a Page to display the string and we put a button on the HomePage to call the service.
Before You Begin
Before you begin, closed all open projects (Project > Close Project) and files (File > Close All).
About Local Services
Within an ActiveGrid Application, a service is anything that has one or more defined operations that the application can run. Services might be defined in custom code (Python or PHP) files within your application or they might be web services available on the Internet. ActiveGrid Applications use a Service Definition to access all services.
The Service Definition file specifies input and output messages for all the Services in the application. 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.
Your Python or PHP code file represents a service that is available to the application. Functions or methods within your code file represent operations that the application can call. For each service operation, the Service Definition file must define the following:
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.
Create a Simple Process
First, create a simple process flow:
1.
Select the File menu option then, select New.
2.
In the New dialog box, leave New Project selected.
3.
Under Type, select Skeleton Application and then click OK (Figure 1).
Fig. 1 Create a New Project
4.
The Page Settings screen appears. Type in the following settings:
In the Title field, type:
Local Service
In the Footer field, type:
Copyright 2006.
5.
Click Next. The Skin Settings screen appears.
6.
Leave the default skin settings and click Next. The Name and Location screen appears.
7.
In the Name field, type:
LocalService
8.
Click Finish.
The next step is to create the Pages.
Create the Pages
For this simple service call application, we need two Pages. The first Page contains a button that launches the custom service. The second Page displays the result of the service call.
Create the Pages:
1.
If it is not already open, double-click on the Page Flow, LocalService.bpel file in the Project Panel.
2.
Right-click in the Page Flow Editor and, from the Insert Page menu select the Custom... option. Name the Page requestPage and accept the defaults for the other settings.
3.
In the same way, insert another custom Page, but this time, name the Page responsePage, again accepting the defaults for the other settings.
4.
The new Pages appear in the Page Flow Editor (Figure 2).
Fig. 2 The New Pages in the Page Flow Editor
Create a Skeleton Custom Code Action
Before we can add the submit button to the requestPage, we need to define an Action for it in the underlying Page Flow (.bpel) file.
1.
2.
From Insert Action select the Call Custom Code... option. This launches the Call Custom Code Wizard.
3.
In the Action Source Page screen, select requestPage and then click Next. The Custom Code Details screen appears.
4.
In the Action Name field, type in:
ServiceCallAction
5.
Click the New... button for the Code File Name field and type in:
myService
6.
Click Finish.
7.
Back in the Custom Code Details screen, click the New... button for the Function Name field. This launches the Service Operation Wizard.
8.
In the Operation Name field, type:
sayHi
9.
Click Next. The Input Message screen appears.
10.
Click the Add button to add a new message part. For the name of the message part, type in sayHiRequest and for the type, select xs:string.
Fig. 3 Add an Input Message
11.
Click Next. The Output Message screen appears.
12.
On the Output Message screen click Add and add a new message part. For the name of the message part, type in sayHiResponse and for the type, select xs:string.
Fig. 4 Add an Output Message
13.
Click Next.
14.
On the Custom Code Language screen, select python from the Language field and click Finish.
15.
Back on the Custom Code Details screen, in the After function go to Page field, select responsePage from the drop-down menu (Figure 5).
Fig. 5 Custom Code Details
16.
Click Finish
The wizard generates a python skeleton function for you in a file called myService.py. The python skeleton function takes an argument (called sayHiRequest) and returns a value (sayHiResponse). The wizard also generates the corresponding service definition for you in the myService.wsdl file.
The next step is to complete the Python code.
Complete the Python Code
In this step we edit the skeleton Python code to return a simple string:
1.
In the Project Panel, double-click on the Python file, myService.py, to open the skeleton Python file (.py) you created.
2.
sayHiResponse = None
3.
sayHiResponse = “Hello!”
4.
The Python file is complete (Figure 6).
Fig. 6 The Finished Python Code
Next we complete the skeleton process by editing the Begin Action to point at the requestPage.
Edit Begin Action to Point at requestPage
To finish up the skeleton process, we point the Begin Action at the requestPage and delete the Home Page:
1.
In the Page Flow Editor double-click the Begin Action. The Begin Action Wizard appears.
2.
From the Begin Page pull-down menu, select RequestPage and click Finish.
The Begin Action now has an arrow pointing to the requestPage.
3.
Now we can delete the default Home Page. Right-click on the HomePage Page and select Delete from the resulting pop-up menu.
The process flow should look like the one pictured in Figure 7.
Fig. 7 Finished Skeleton Process
The skeleton of the Page Flow is complete with this step. We have a request Page that contains an Action that loads the response Page. The next step is to build a Page Message for the responsePage.
Create a Message Part for the responsePage
Next, we create a place in the responsePage message to store the output from the Python code.
1.
In the Project Panel, double-click on the responsePage.xform file. The file opens in the Page Editor.
2.
Right-click on the Page Message and select the Insert Message Part... menu option (Figure 8).
Fig. 8 Insert Message Part in Input Message
The Insert Message Part screen appears.
3.
Click the Name field and type in:
pythonOutput
4.
Click the Service Call radio button.
5.
From the Service pull down menu, select myService (local).
6.
From the Operation pull down menu, select sayHi (Figure 9).
Fig. 9 Insert Message Part
.
7.
In the Page Editor, your Page Message now contains the pythonOutput Message Part (Figure 10).
Fig. 10 The pythonOutput Message Part
Add the Output Field to the responsePage to Show the Service Results
Add an output field to the responsePage:
1.
2.
In the Page Editor, right-click on the Page:responsePage icon and select Insert Group... > Bordered Group.
3.
A Bordered Group appears on the Page. Next, right-click on the Bordered Group icon and select the Insert Output Field… > Plain Text Output option from the resulting menu. The Pick a Reference screen appears.
4.
Click the expand button (+) and select /pythonOutput from the tree. Then click OK.
5.
Finishing the SayHi Action
When you use a wizard to create a predefined Action, the wizard sets all the local (Action) variables for you. Because we created a custom Action, to call our local service, we need to do some of this work manually.
Open the SayHi Action in the Custom Action Editor
The first step is to open the SayHi Action in the Custom Action Editor:
1.
Double-click on the process file, simpleService.bpel, to open the process (.bpel) file for the application.
2.
In the Process Editor, right-click on the SayHi Action and select the Customize Action... option. This opens the SayHi Action in the Custom Action Editor (Figure 11).
Fig. 11 The SayHi Action in the Custom Action Editor
The Action contains the following three variables:
sayHiRequestMsgVar: The wizard created this variable to represent the input message we defined for our service operation.
sayHiResponseMsgVar: The wizard created this variable to represent the output message we defined for our service.
responsePageRequestMsgVar: The wizard created this variable to represent the backing message for the Page we’re invoking.
The Action contains two invokes, or calls:
The Custom Action Editor displays invokes in ovals, as shown in Figure 11.
We need to populate the responsePageRequestMsgVar variable. That is the variable the server uses to build the backing Page Message for the responsePage.
Set the Input Variable for the responseXForm Invocation
To set the responsePageRequestMsgVar, follow these steps:
1.
In the Custom Action Editor, right-click on the service Invoke (sayHiResponseMsgVar = myService:sayHi(sayHiRequestMsgVar)) and select Add Set... from the menu (Figure 12).
Fig. 12 Insert a “Set”
The BPEL Set screen appears.
2.
Click the top XPath Ref… button next to the Set field at the top of the screen (Figure 13).
Fig. 13 Click the Top XPath Button
The Select an XPath dialog appears.
3.
Select responsePageRequestMsgVar/pythonOutput (Figure 14).
Fig. 14 Select XPath
4.
5.
In the bottom half of the BPEL Set screen, under XPath Expression, click the XPath Ref… button (Figure 15).
Fig. 15 Click the Bottom XPath Button
The Select an XPath dialog again appears.
6.
Select sayHiResponseMsgVar/sayHiResponse (Figure 16).
Fig. 16 Set the Variable
7.
8.
On the BPEL Set screen, click OK (Figure 17).
Fig. 17 The Completed Set Details Screen
 
9.
Fig. 18 Custom Action Editor with Set
Run the Process
Run the process (Figure 19).
Fig. 19 The Running Process
When you click the SayHi button, your Hello! message should appear (Figure 20).
Fig. 20 The Hello Message
 

ActiveGrid
ActiveGrid Studio Tutorial
Version 2.0