Oracle Portal-to-Go Implementation Guide
Release 1.0.2.2

A86635-02

Library

Service

Contents

Index

Prev Next

4
Walkthroughs

This document provides walkthroughs for implementing Portal-to-Go services. Topics include:

Purpose

The following walkthroughs provide step-by-step instructions for creating and distributing mobile services with Portal-to-Go. In the walkthroughs, you create services based on the Web Integration adapter and the SQL adapter. At the end of each walkthrough, you test your development using a device emulator.

These walkthroughs familiarize you with the Portal-to-Go tools, including the Web Integration Developer and the Service Designer, and how they enable you to create mobile services.

Before You Begin

Before you begin the walkthroughs, make sure that you correctly install and configure the Portal-to-Go server. Also, you must complete the client installation on your development environment.

Creating a Web Service

In this walkthrough, you create a Portal-to-Go Web service. First, you use the Web Integration Developer to map the elements of a sample Web page, quote.yahoo.com, to input and output parameters. You then use the Service Designer to create a Portal-to-Go service that retrieves stock quotes based on the mapping.

For more information on using the Web Integration Developer, see the Portal-to-Go Web Integration Developer User's Guide.

This walkthrough guides you through the following tasks:

Task 1: Creating the WIDL File in the Web Integration Developer

Follow these steps to create a Web page mapping, or Web Integration Definition Language (WIDL) file, using the Web Integration Developer.

Open the Source Page

Open the source page in the Web Integration Developer as follows:

  1. Start the Oracle Web Integration Developer.

  2. Select Open URL from the File menu or toolbar.

  3. In the Open URL dialog box, type the following URL:

    http://quote.yahoo.com
    
  4. Click OK.

The Web Integration Developer retrieves the page, parses it, and adds it to the Document Browser (in the left frame). For this example, the Document Browser shows the following items:

Generate a WIDL File

Next, generate a WIDL file from the source page as follows:

  1. Select FirstForm in the left frame.

  2. Select WIDL from the Generate menu.

  3. Complete the New Service dialog as follows:

In this Field...  Type... 

Interface 

StockInfo 

Service 

QuoteYahoo_GetQuote 

  1. Click OK.

  2. In the Generate New WIDL for Service dialog, type ORCL.

  3. Click the Submit button.

Edit the Input Binding of the WIDL File

The input variables defined in this WIDL service have the same names as those specified in the HTML form. You can edit the input binding to make these names more meaningful as follows:

  1. Expand the Bindings folder in the left frame.

  2. Click the QuoteYahoo_GetQuoteInput binding.

  3. Click the variable "d" in the variable list in the right frame. In the Name field, type ReportType and press Enter.

  4. Click the variable "s" in the variable list. In the Name field, type CoSymbol and press Enter.

Edit the Output Binding of the WIDL File

The output defined by this service extracts all elements from the document returned by the Web page. To extract just the stock quotes to pass back to the client application, you can edit the output binding:

  1. Select the QuoteYahoo_GetQuoteOutput binding in the left frame.

  2. In the right frame, scroll through the variable list until you reach the table variables.

  3. Click the variable table4. Make sure the content of this variable is the stock price of ORCL. If not, click the variable whose content is ORCL's stock price.

  4. On the Sample tab, select the cell that contains the current stock price.

  5. Click the right mouse button and select Create New Variable From Selection from the pop-up menu.

  6. Type CurrentPrice in the New Variable dialog and click OK. The CurrentPrice variable now appears in the variable list.

  7. Delete all other variables from the variable list.

  8. Save the WIDL file.

Test the WIDL File

To test the WIDL file in the Web Integration Developer:

  1. Click QuoteYahoo_GetQuote in the Services folder in the left frame.

  2. Select Test Service from the Tools menu.

  3. Type any valid stock symbol in the CoSymbol field.

Task 2: Publishing the WIDL Interface to the Web Integration Server

Publishing a WIDL interface makes it accessible to Web Integration services that you create in the Service Designer.

You must have administrator authority on the Web Integration Server to perform this procedure. When you publish an interface, the services in that interface are added to those already on the Web Integration Server. If you create a service with the same name as an existing service, the existing service is overwritten.

Follow these steps to publish your WIDL file (StockInfo) to the Web Integration Server.

  1. Select StockInfo in the left frame.

  2. From the File menu, select Publishing, then Publish Interface.

  3. In the Specify Server field in the Publish Interface dialog, type the name of the Web Integration Server to which you want to publish this interface. Specify the server name using the format:

    host_name:port

  4. The Web Integration Server uses packages to organize services. You can click Update Packages to view a list of packages on the specified server, then add the service to a specific package. In this case, however, you can add the sample service to the Default package. Click OK.

  5. If the User Name and Password dialog appears, enter a user name and password for the selected server. This user must have administrative privileges. Click OK.

The Web Integration Developer copies the interface to the selected package on the Web Integration Server and notifies you that the interface is successfully published. Assuming the package is enabled, the services in this interface are immediately available for execution.

Task 3: Starting the Portal-to-Go Service Designer

After creating the WIDL service, you create a Portal-to-Go master service based on the WIDL service. You can create Portal-to-Go services using the Service Designer. The Service Designer is a visual tool for creating and managing Portal-to-Go objects.

Start the Service Designer

To start the Portal-to-Go Service Designer, from the Start menu, point to the Oracle for Windows NT menu item. Click Portal-to-Go, then Service Designer.

Connect to the Portal-to-Go Repository

When the Service Designer starts, the Log In dialog appears. Use the Log In dialog to connect the Service Designer to the Portal-to-Go repository that you want to develop. The Log In dialog enables you to select a server name that you have already used, or to enter a new server name.

To connect to the Portal-to-Go repository from the Log In dialog:

  1. In the location field, enter the name of the Portal-to-Go server. Then enter your user name and password in the appropriate fields.

  2. Click OK. The Portal-to-Go server objects appear in the tree view on the left.


    Note:

    The Service Designer displays an Error dialog for invalid entries. By clicking the Show Details button, you can view the Java runtime exception details.  


Task 4: Creating the Master Service

Using the Service Designer, create the master service for the StockInfo WIDL file by following these steps:

  1. Right-click the Master Services folder in the Portal-to-Go repository tree view.

  2. Click Create New Master Service to display the Create New Master Service form sequence. Complete the form as follows:

    1. In the Name field, type Stock Quotes. You can name the new master service that you are creating anything you want. In this example, it is named Stock Quotes.

    1. Click the Browse button next to the Adapter field. Select WebIntegrationAdapter and click OK.

    2. Select the Valid check box.

    3. Select the Visible check box.

  3. Click Finish. The new master service Stock Quotes now appears under the Master Services folder in the Portal-to-Go repository tree view.

  4. Click the Init Parameters tab in the right frame. Complete this form as follows:

    1. For the Web Integration Server, type the machine name of the Web Integration Server in the format: host_name.domain:port

    1. For the Interface field, type StockInfo. This is the name of the WIDL interface you created in "Task 1: Creating the WIDL File in the Web Integration Developer."

    2. Do not supply a value for the WIDL_FILE parameter.

  5. Click Apply. Then click Yes in the dialog asking you if you want to apply the changes. The Service Designer populates the Input Parameters tab with the input parameters for the adapter.

  6. Click the Input Parameter tab and select the User Customizable check box for the CoSymbol parameter.

  7. Click Apply. Then click Yes in the dialog asking you if you want to apply the changes.

This creates the master service Stock Quotes in the Portal-to-Go repository. You can now create aliases to make the master service available to users.

Task 5: Creating an Alias that Points to the Master Service

To add a master service alias in the service tree, you first create a new folder in the service tree and then add an alias to the master service in this folder. Follow these steps to create an alias for the master service Stock Quote in the service tree:

  1. Right-click Service Trees in the Portal-to-Go repository tree view.

  2. Click Create New Folder to display the Create New Folder form.

  3. Complete this form as follows:

    1. In the Name field, type My Folder.

    1. Select the Valid check box.

    2. Select the Visible check box.

  4. Click Finish. My Folder now appears under Service Trees in the Portal-to-Go repository tree.

  5. Right-click My Folder.

  6. Click Create New Alias to display the Create New Alias form.

  7. Complete this form as follows:

    1. In the Name field, enter My Service.

    1. Click the Browse button next to the Service field. A Browse Services dialog appears. Expand the Master Services folder within the Browse Services dialog and select Stock Quotes. Click OK.

    2. Select the Valid check box.

    3. Select the Visible check box.

  8. Click Finish.

  9. Click the Input Parameters tab in the right frame and select the User Customizable check box for CoSymbol.

This creates an alias object in the Portal-to-Go repository. Aliases, like master services, have input parameters. You can use the input parameters of an alias to override any input values specified by the master service. For this walkthrough, you use the default settings provided by the master service.

Task 6: Creating a User Group and a User

Now you create a user group and then a user.

First, you create an overall folder which will later contain a unique "root folder" for each user that you create. Each "root folder" will have the same name that you used to name the user. You can call the overall folder anything you like that is meaningful to you, keeping in mind that this folder will contain the root folders for all the users. In our example, the overall folder is called "Users Home." Create this folder in the Service Trees node of the repository tree in the left frame.

The root folder of a particular user contains the services (including aliases, master services, and folders) which the specified user can access.

One benefit is that if you have many users, you can create an overall folder for each grouping of users. For example, using the label "Users Home" as an illustration, you can create "Users Home A" for all users whose name starts with A, "Users Home B" for users whose name starts with B, and so on. In this fashion, grouping the users' root folders within higher-level folders minimizes the number of objects that are displayed in the Service Designer's tree view. (For performance reasons, the default view in the Service Designer's tree view does not display more than 100 objects of any type.)

Second, you create a user group.

Finally, you create the user and add the user to a group.

Create the Overall Folder for the Users' Root Folders

To create the overall folder for the users' root folders (using "Users Home" as an example):

  1. Right-click Service Trees in the repository tree view.

  2. Click Create New Folder to display the Create New Folder form.

  3. Complete this form as follows:

    1. In the Name field, enter Users Home.

    1. Select the Valid check box.

    2. Select the Visible check box.

  4. Click Finish.

The folder named "Users Home" now appears under Service Trees in the repository tree.

Create the User Group

To create a user group:

  1. Select the Groups folder in the Portal-to-Go repository tree.

  2. Right-click and select Create New Group.

  3. In the Name field of the Create New Group dialog, type MySampleGroup.

  4. Click Finish. Because there are no changes to make at this point, do not click Apply when the panel for the General tab appears.

This creates a user group called MySampleGroup in the repository.

Create the User and the User's Root Folder

To create the user:

  1. Select the Users folder in the Portal-to-Go repository tree.

  2. Right-click and select Create New User.

  3. Configure the user as follows:

    1. In the Name field, type Sam.

    1. For the Display Name, type Sam.

    2. For the Password, type welcome.

    3. For the Password Hint, type welcome.

    4. Click the Browse button next to the User Root Parent field and select the folder "Users Home," then click OK.

      This action creates a user folder named "Sam" under the overall folder named "User's Home." You will see the user folder for Sam when you expand the User's Home node in the tree view.

    5. Click the down arrow on the list box for the list of groups and select MySampleGroup, which you had created earlier.

    6. Select the Enabled check box.

  4. Click Finish to create the user in the Portal-to-Go repository.

Task 7: Making the Service Available to a Group

To make the service you created available to a group of users:

  1. Expand the Groups folder in the Portal-to-Go repository tree view.

  2. Click MySampleGroup. The parameters for the group appear in the right frame.

  3. Click the Service Folders tab in the right frame to display the Service Folders panel. The Service Folders panel includes two fields, Service Folders and Selected Service Folders.

  4. Under Service Folders, expand the Services folder.

  5. Click My Folder.

  6. Click the right arrow (>) button to move My Folder to the Selected Folders field.

  7. Click Apply.

  8. Click Yes in the Confirm Apply Changes dialog.

This makes the service available to all users in the group MySampleGroup. In "Task 8: Testing the Service", you test this service as the user Sam.

Task 8: Testing the Service

In this walkthrough, you test your Portal-to-Go service using the Personalization Portal and a phone simulator. For more information on the Personalization Portal, see Chapter 7, "Rebranding the Personalization Portal".

Accessing the Personalization Portal

Log on to the Personalization Portal to view the service you created. To access the Personalization Portal:

  1. From a Web browser, enter the following URL:

    http://PTGServer.domain/panama/server/papz/login.jsp

  2. Enter the following for the user name and password:

    In this Field...  Type... 

    Username 

    Sam (Note: Sam is case sensitive) 

    Password 

    welcome 

    The services available to the user Sam appear in the left frame.

  3. Click My Folder, then My Service.

  4. Click on QuoteYahoo GetQuote.

  5. Enter a valid stock symbol and click Submit.

Portal-to-Go retrieves and displays the current price of the stock.

Testing the Service on a Phone Simulator

You can use any WML- or HDML-based phone simulator to test the service. If you do not already have one, download and install a simulator. If you are working behind a firewall, you must configure the proxy server settings in the simulator before using it to access external sites.


Note:

Phone.com provides a WML-enabled phone simulator in the UP.SDK, a software development kit for creating WML and HDML services. The development kit is freely available from the Phone.com Web site.  


Follow these steps to test the service from a phone simulator.

  1. Start the simulator.

  2. Enter the following URL in the Go window:

    http://PTGServer.domain/panama/server/papz/alias for the oracle.panama.ParmImpl servlet

    This is the URL of the device portal for your Portal-to-Go installation.

  3. Log in using Sam and welcome as the user name and password. The preconfigured Portal-to-Go services for the user Sam appear.

  4. Select My Folder, then My Service.

  5. Enter a valid stock symbol and click OK.


    Note:

    If the phone simulator returns an HTTP error, you should refresh the cookie cache and source cache. Go to the phone simulator install directory and refresh (or delete) the files CookieCache and SourceCache


Portal-to-Go retrieves and displays the current price of the stock.

Creating a SQL Service

In this walkthrough, you create a Portal-to-Go service based on the SQL adapter. You create a service that checks the current time from the system table DUAL and displays it to the user.

Before you begin the walkthrough, make sure you can access a Portal-to-Go server from your development environment. Start the Service Designer, as described in Step 1 of the Web Integration walkthrough, and follow these steps:

  1. Right-click the Master Services folder in the Portal-to-Go repository tree view.

  2. Click Create New Master Service to display the Create New Master Service form sequence. Complete this form as follows:

    1. For the Name field, enter SQL Time.

    1. For the adapter, click Browse. Select SQLAdapter and click OK.

    2. Select the Valid check box.

    3. Select the Visible check box.

  3. Click Finish. The new master service SQL Time appears under the Master Services folder in the Portal-to-Go repository tree view.

  4. Click the Init Properties tab in the right frame. Complete this form as follows:

    1. For the SQLTYPE, type Query.

    1. For the STATEMENT, type:

      select sysdate from dual
      
    2. For the JDBC_CONNECT_STRING, enter the JDBC connect string for the database on which to query, as follows:

      jdbc:oracle:thin:@host_name:port:SID
      
    3. For the PASSWORD and USERNAME, type the password and user name of any database user. You can use the sample user Scott with the password tiger.

  5. Click Apply.


    Note:

    For more information on creating master services, see Chapter 5, "Portal-to-Go Services"


You can now test the service from a simulator, as described in steps 5 through 8 of the Web Integration service walkthrough.

Creating Chained Services

Chained services link services to each other in a sequential way so that each chained service is dependent for input on the service that immediately precedes it. Chained services are needed for Web sites which require the user to interact with a Web page to access the rest of the content on the Web site. For example, the first Web page prompts the user for a username and password before the user can access the form on the second page, which then produces the information on the third page. Chaining one service (Service A) to another service (Service B) works in such a way that when the Output Binding of Service A completes successfully, it chains to the Input Binding of Service B.

The chained service you build in this walkthrough illustrates a typical use of chained services. Based on the Yahoo finance site, the chained service you build in this section allows the user to enter a stock ticker symbol, receive the current stock quote, select details, and receive detailed information about the stock, such as a chart. The first service requests that the user enter a stock ticker symbol. It returns the current quote for that stock. When the user clicks on Details and selects Charts, the second service returns the chart for that stock.

You should become familiar with a site you want to base a service on by first opening it in a browser. Opening the site and viewing its HTML source code lets you become familiar with the structure of a site. In a browser, open the Yahoo site for getting stock quotes:

http://quote.yahoo.com

The query form on this page takes a stock's ticker symbol. It returns that stock's current quote.

This walkthrough assumes that you are familiar with the basic steps required to create a Web service in the Oracle Web Integration Developer. If you are not, complete the Web Integration walkthrough in "Creating a Web Service" before attempting to follow this walkthrough.

This walkthrough does not include error checking. Usually, you would add error catching logic to the service.

Task 1: Creating the First Service in the Chain

The overall interface name for the chained services in this walkthrough is YahooFinance. The first service in the chain sequence is called Quote. This service prompts the user for a stock ticker symbol (such as, ORCL) and returns the stock quote. The following steps provide a basic method for creating the first service in the chain.

Generate the WIDL File and Edit the Input Binding

  1. In the Oracle Web Integration Developer, open the following URL:

    http://quote.yahoo.com

    Two nodes appear in the document browser, Document and FirstForm.

  2. Highlight the FirstForm node and click Generate, then WIDL. Complete the New Service dialog as follows and click OK:

In this Field...  Type... 

Interface 

YahooFinance 

Service 

Quote 

  1. In the Generate a New Widl for Service "Quote" dialog box, enter the stock symbol ORCL. Click Submit.

  2. Expand the bindings node and highlight the QuoteInput binding by selecting it. The variables in the Quote service's input binding appear in the edit pane of the Variables tab.

  3. Rename the variable s to s1, and d to d1.

Edit the Output Binding of the WIDL File

  1. Select the QuoteOutput binding. In the variables list, highlight the row for table4 by clicking on it. The Sample tab shows the values in table4. You can create new variables based on these values.

  2. In the Sample tab, highlight the ORCL cell. Right click. Select Create new variable from Selection. Name the new variable symbol.

  3. Similarly, highlight the cell that shows the ORCL stock price (in the table4 sample result). Right click. Select Create new variable from Selection. Name the new variable price.

  4. Follow the same procedure as in the above two steps to create the new variable change from the cell that shows the value for change.

  5. Delete all output variables from QuoteOutput, except for the three new output variables (symbol, price, change) that you just created in steps 7, 8, and 9 above.

  6. Save the WIDL file.

  7. Test the first service, Quote, with other stock symbols.

Task 2: Creating the Second Service in the Chain

This walkthrough takes you through the steps to build the second service, named Detail, in the chained service YahooFinance. While you can create chained services using separate interfaces, in this walkthrough you add the second service to the YahooFinance interface.

The Detail service takes the stock quote as input and returns stock charts.

Create the second service as follows:

Open the Source Page for the Second Service

  1. Open the following page in a browser:

    http://finance.yahoo.com

  2. Enter ORCL as the quote symbol and select Chart as the type of search (instead of Basic).

  3. Click Search. As you see, a chart search returns more information than a basic search. The second service in the chain returns this detailed information.

  4. Select the URL in your browser's Location field, http://finance.yahoo.com/q?s=orcl&d=b, and open this URL in the Web Integration Developer.

Generate the WIDL for the Second Service

  1. Select FirstForm in the left frame.

  2. Select WIDL from the Generate menu.

  3. Complete the New Service dialog as follows:

    In this Field...  Type... 

    Interface 

    YahooFinance 

    Service 

    Detail 

  4. Click OK.

  5. In the Generate a New Widl for Service "Detail" dialog box, enter the stock symbol ORCL. Click the Submit button.

Edit the Input and Output Binding of the WIDL File

  1. Expand the Bindings folder in the left frame.

  2. Select DetailInput. Rename the variable s to s2, and d to d2.

  3. Select DetailOutput. In the variables list, highlight table4.

  4. Find the cell with the Open price. Highlight the cell, right click and create a new variable from selection. Name the new variable opened.

  5. From the day's range cell, create a new variable named range.

  6. Similarly, from the cell showing volume, create a new variable named volume.

  7. From the cell showing the 52-week range, create a new variable named annualrange.

  8. Create a new variable named pe from the cell that shows the P/E value.

  9. Create a new variable named mktcap from the cell that says Mkt cap.

  10. Delete all variables other than the ones that you just created in steps 9 to 14 above.

Edit the URL of the Second Service

  1. Highlight Detail under the Services node.

  2. Remove q?s=orcl&d=b from the Source URL.

  3. Save the WIDL file.

Publish the Service

Publish the new service to the WIDL server, as described in "Task 2: Publishing the WIDL Interface to the Web Integration Server."

Add the Service to Portal to Go

The new Master Service is YahooFinance. It points to the interface YahooFinance; it includes the two chained services Quote and Detail. To add this service to the Portal-to-Go repository, start the Service Designer and follow these steps:

Create the Master Service

  1. Right click the Master Services node in the repository tree and choose Create new Master Service.

    1. Type YahooFinance as the service name.

    1. Browse for Adapter, and select WebIntegrationAdapter

    2. Select Valid and Visible. Click Finish.

  2. In the new service, click the Init Parameters tab.

    1. For the WebIntegrationServer, specify the URL of the Web Integration Server to which you published the Web Integration interface, in the form: machine.domain:port

    1. For the interface, type YahooFinance and click Apply.

  3. Click the Input Parameters tab.

    1. Make s1 User Customizable.

    1. Click the Value field of the PAsection variable. A drop-down arrow should appear. Click the arrow and choose Quote.

    2. For the variable OutputType, select a value of RawResult.

  4. Click the Add button. Click in the name field of the new input variable and type PAdebug. Set the value to 1.

  5. Deselect the User Customizable check box for PAsection, if set.

  6. Click Apply.

Create the Result Transformer

  1. Click the Result Transformer tab.

  2. Click the Add button. In the name field, delete the default name, and enter Quote. Click the Edit button, and paste the following style sheet in the XSL Editor window and click OK. Be sure to replace the existing template text in the window.

    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
       <xsl:template match="/">
          <xsl:apply-templates 
    select="ServiceRequest/Result/AdapterResult"></xsl:apply-templates>
       </xsl:template>
       <xsl:template match="AdapterResult">
          <SimpleResult>
             <SimpleMenu>
                <SimpleMenuItem>
                   <xsl:attribute
    name="target">___REQUEST_NAME__?PAservicepath=___SERVICE_URL_ENC__
    &#38;PAsection=Detail&#38;s2=<xsl:value-of
    select="symbol"></xsl:value-of></xsl:attribute>
                   <xsl:value-of select="symbol"></xsl:value-of>
                   <!-- this xsl:text is just for beautifying the output -->
                   <xsl:text> - </xsl:text>
                   <xsl:value-of select="price"></xsl:value-of>
                   <!-- this xsl:text is just for beautifying the output -->
                   <xsl:text> - </xsl:text>
                   <xsl:value-of select="change"></xsl:value-of>
                </SimpleMenuItem>
             </SimpleMenu>
          </SimpleResult>
       </xsl:template>
    </xsl:stylesheet>
    
    
  3. Click the Add button. A name field for a new stylesheet appears with a default name.

  4. Replace the default name with Detail. Click the Edit button.

  5. Replace the existing template with the following and click OK:

    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
       <xsl:template match="/">
          <xsl:apply-templates
    select="ServiceRequest/Result/AdapterResult"></xsl:apply-templates>
       </xsl:template>
       <xsl:template match="AdapterResult">
          <SimpleResult>
             <SimpleContainer>
                <SimpleText>
                   <SimpleTextItem>
                      <xsl:value-of select="opened"></xsl:value-of>
                   </SimpleTextItem>
                   <SimpleTextItem>
                      <xsl:value-of select="range"></xsl:value-of>
                   </SimpleTextItem>
                   <SimpleTextItem>
                      <xsl:value-of select="volume"></xsl:value-of>
                   </SimpleTextItem>
                   <SimpleTextItem>
                      <xsl:value-of select="annualrange"></xsl:value-of>
                   </SimpleTextItem>
                   <SimpleTextItem>
                      <xsl:value-of select="pe"></xsl:value-of>
                   </SimpleTextItem>
                   <SimpleTextItem>
                      <xsl:value-of select="mktcap"></xsl:value-of>
                   </SimpleTextItem>
                </SimpleText>
             </SimpleContainer>
          </SimpleResult>
       </xsl:template>
    </xsl:stylesheet>
    
    

Create a User and an Alias and Test the Service

  1. Create a new user and a new alias as described in the first walkthrough.

  2. Test the service from the Personalization portal.


Prev Next
Oracle
Copyright © 2000 Oracle Corporation.

All Rights Reserved.

Library

Service

Contents

Index