Query Zones

15 Query Zones
Copyright © 2009, Oracle. All rights reserved.

A Portal Can Contain Query Zones
• In the previous section we said there were two types of

zones:
• Info zones. These display lists of information about the object in
context.
• Map zones. We'll describe these a bit later.
• There's actually a 3rd type of zone that users use to find
objects; we refer to these as query zones
• Note, in the last exercise, you used a query zone to find a customer
15 - 2 Copyright © 2009, Oracle. All rights reserved.

15
Configurable Query Zones
Look and Feel

Query Zones Look Almost Identical To Info Zones
• All of the “look and feel” features described for info zones apply to query zones
• The major differences are:
• The filter area appears at the top of the zone
• No drag and drop is available on query zones
Query Zone
Info Zone

15
Security and Menu Access

An Aside: Portal Security
• Users can only open a portal if they have access rights to

its application service
• Note, when you add a portal, the system creates a corresponding
application service
• The name of the service is displayed on the portal page
• After creating the portal, you must grant access rights to
the appropriate user groups
Application
User Group User
Service
Application
User Group
Portal Service/
/ User
User Group

Adding Portals to Menus
• If you want a portal to appear

on a menu, you must add its Menu
navigation option to that menu
• There is a special button on the
portal page that adds the portal to Navigation
Menu Line
a menu Option
• Also note, the user must have
security access to the portal's
application service to see the item Portal Menu Item
on the menu
• Note, the same navigation
option is also used to add the
portal to users’ Favorite Links

Team Walk Through - Add A Query Portal (20 Minutes)
• During this exercise, you will use the following:

• Admin – Portal
• Admin – User Group
• User Preferences – Favorite Links
• Please break up into teams
• In this walk-thru, each team will create a new portal and
put it on the main menu
• Note, the portal won’t have any zones on it until after the next walk
thru
• Please note, your workbook has detailed instructions for
this one; we might suggest that you try to write down what
you think you'd have to do to add a portal before you peek
at the answer

15
Zone Types and Zones

Zone Types versus Zones
These info
zones are
created using
the "info" zone This query zone is
type created using the
"query" zone type

Zone Types and Zone ERD
• Think of a zone type as a program responsible for
presenting data using a specific graphical metaphor
Zone Type Zone

Zone
Both of these zones reference

the "info" zone type

Zones Have Parameters
Each zone type has a When you set up your
variety of parameter Zone Type Zone
Zone
zones, you define the
types value of each
parameter
A zone’s parameters
Parameter control what data is
Parameter
Parameter
Type retrieved and how it is
displayed
These are a sample Info Zone Type Account’s Bills Zone Person’s Contacts Zone
of the parameters Filter 1
required to render an Filter 2
info zone Filter …

Hidden Filter 1 name=PER_ID datasource=G
Hidden Filter 2 name=ACCT_ID datasource=G
Hidden Filter …
Number of rows to display 24
Number of rows to download 24 200
Initial columns to display 200 C1 C2
SQL 1 C1 C2 SELECT CC_DTTM, CC_ID
Column 1 SELECT BILL_DT, BILL_ID … source=SQLCOL sqlcol=1 …
Column 2 source=SQLCOL sqlcol=1 … source=FKREF fkref=‘CC ID’ …
Column 3 source=FKREF fkref=‘BILL’ …

Zone Parameters and Mnemonics
• In the next walk through, you’ll set up a new zone by entering zone parameters
• You’ll find that many parameters have “sub parameters” that are defined using a variety
of mnemonics
• For example, when you populate the zone parameter to define a column on a query zone, you’ll specify
several mnemonics
Info Zone Type

Filter 1
Filter 2
Filter …
Hidden Filter 1
Hidden Filter 2 Several mnemonics are used to define how
Hidden Filter … the column looks and behaves: source=,
Number of rows to display fkref=, input=, context=, suppress=
Number of rows to download
Initial columns to display
SQL 1
Column 1
Column 2
Column 3
…

Zone Parameter Validation
• The framework validates the zone parameters when you set up the query zone
• However, there is some validation we don't do (e.g., we don't validate that the
SQL is valid)
• This means that sometimes you won't find out that you've entered invalid
parameter values until you use the zone
Info Zone Type

Filter 1
Filter 2
Filter …
Hidden Filter 1
Hidden Filter 2
Hidden Filter …
It'd be a good idea to copy / paste from the
Number of rows to display
sample zones and tips to reduce errors
Number of rows to download
Initial columns to display
SQL 1
Column 1
Column 2
Column 3
…

Configuration Mode
• In an earlier section, you learned how debug mode is

used when you want logs of script steps to be recorded
for debugging purposes
• You can use this same mode to facilitate zone set up
• Reminder, to enable this mode, enter ?debug=true at the end of
the URL that you use to access the system
• For example,
– if the standard URL was http://sf-pdnt-009:7031/cis.jsp,
– you'd enter http://sf-pdnt-009:7031/cis.jsp?debug=true to enable
configuration mode
• When you start the system in configuration mode:
• Special options appear in each zone's tool bar to help you debug
your zone configuration (you’ll see these in the next walk thru)

Team Walk Through – Add A Query Zone (30 Minutes)

• Admin – Zone
• Add a very simple query zone to your portal to look for persons with
an input name
• Note, you should be familiar with the person data model before doing
this exercise (we'll just be using CI_PER_NAME table)
• Again, your workbook has the answer, but we'd recommend trying to
work it out on your own before peeking…

15
Dynamic SQL

Avoid Database-Specific SQL Functions
• There are SQL functions whose syntax differs depending

on the database being used, e.g., the syntax to check for
a null value in Oracle is NVL, whereas in DB2 it's
COALESCE
• There are a few more - TRIM, AS CHAR, AS DATE, etc.
• As you know, we want our SQL to be database-neutral
• In order to use these functions while remaining database-
neutral, you should enter generic function names in your
SQL; these will be transformed at run-time into the
vendor-specific SQL
• For a complete list of these functions, please see the
Examples tip on the zone page

Conditional From and Where
• Imagine a scenario when there's an optional filter value

• For example, what if a user can search for claims with a claim date between a date
range and the end date is optional
• To support this type of zone, the SQL's WHERE clause can be authored to
include additional criteria if a given filter value is non-blank
• Our scenario's SQL could now be authored as follows:
• SELECT CLAIM_ID
• FROM C1_CLAIM
• WHERE CLAIM_DT >= :F1 This line is only included in the WHERE clause
if the 2nd filter is specified by the user
• [(F2) AND CLAIM_DT <= :F2]
• You can use the same technique for:
• The SELECT clause (to include mutually exclusive columns based on filter values)
• the FROM clause (to include additional join criteria based on optional filter values)
• See the SQL zone parameter's adjacent help info for the exact syntax

15
You Now Have Very Sharp Knives

Check Your SQL Before Production
• In a configuration environment, you can write inefficient

SQL and never know because the volumes are low
• Before you release a zone to "production", please involve
someone who can verify that your zone's SQL is efficient

15
Columns Are Much More Than FK References

source=
• You used a value

of source=FKREF
when you set up
your query zone
• There are many
other values
• The tips are
always up-to-date
with the supported
functions…

Tips Are In The Dashboard
• When you were adding your zone, you may have noticed
the “tips” that appeared in the dashboard
• When you have a moment, take the time to read the tips
as they have several interesting examples
• Warning - some of these examples might be a little advanced

15
There's Another Query Zone Type

1 Zone With Many Filters (And SQL Statements)
• The following query zone was set up with many filters

(and many SQL statements)

Introducing The Multi-Query Zone Type
• Rather than build a single complex zone, you can:

• Create a separate, simple query zone for each search metaphor
• Create a multi-query zone that references the simple query zones
• The multi-query zone contains a drop down that lists each of the
simple query zone
This multi-query zone references 7

simple query zones

The Pay Back
• The major reason to "atomize" your complex query into

several simple queries is for re-use purposes
• For example, if an implementation wants to add a few new
search metaphors to what the base-package releases,
they can
• If we had released a single, complex zone, they'd have to
duplicate this zone and then they'd lose the upgrades / bug fixes

15
Portal Preferences

A User Has Portal Preferences
• A user’s portal preferences control:

• The zones that appear on each portal
• The order in which the zones appear
• Whether the zones are initially collapsed or shown when a portal is
displayed
– Collapsing zones will speed up the rendering of a portal
• A user can be set up in one of two ways:
• A user’s preferences can be inherited from a template user
– This means the user’s portals and zones are preset and unchangeable
• A user can define their own preferences; these users can:
– Reorder the zones on a portal
– Suppress specific zones on a portal
– Indicate specific zones are initially collapsed (or displayed)

Changing Portal Preferences
1. Click the User Preference
button
2. Click on the Portal Preferences tab
3. Click on the Portal to see its zones, note, to

see all of the zones, click the purple button in
the upper corner
4. Toggle the Display and Initially Collapsed

switches and change the Sequence as desired

Settings to Improve Response Time
• It is recommended that you configure portal preferences

to collapse zones that are not needed every time a portal
is displayed
• The system does not perform the processing necessary to build
collapsed zones until a user expands them, so configuring them
as initially collapsed improves response times

Portals Preferences ERD
You create portals and define the

appropriate zones as required
Zone Type Zone Portal User
Portal /
Portal /
Zone /
Zone
User
A zone can be referenced on any Users define which zones they use (and
number of portals the order they appear and …)
If you add a new zone and don’t set up a user’s

portal preferences, by default, the zone appears at
the bottom of the portal

15
Query and Info Zone Differences

A Few More Differences Between Info and Query Zones
• Besides the “look and feel” differences described earlier, there are a
few other differences:
• Query zones execute the first SQL statement that satisfies the condition,
whereas info zones execute every SQL statement that satisfies the
conditions
– Remember the account activity info zone – it contains the results of several SQL
statements
• For query zones, the number of columns (and their headings) is dependent
on the SQL statement that is executed. This means that the columns can
be radically different depending on the SQL that is executed
– This is why drag and drop isn't available on query zones (the fields can be
completely different on the different SQL statements)
• Info zones are triggered when a portal first opens and whenever
broadcasting occurs; query zones are not triggered when a portal first
opens (the user has to press Refresh after entering search criteria)

15
Zone Security

Individual Zones Can Be Secured
• Each zone can be secured independently

• i.e., a user may have access to a portal but be restricted from seeing
specific zones
• If your implementation gives all users access to all zones, simply set
up a single "dummy" application service and define it on all of your
zones
• This way, you only have to grant security rights to this “dummy” application
service once
Application
User Group User
Service
Application
User Group
Zone Service/
/ User
User Group

Portal and Zone Security and Portal Preferences
Users only see portals that

they can access
All zones appear regardless of

security access

Portal and Zone Security (continued)
• If a user does not have access to a portal,

• All related menu items will be suppressed (even those on context
menus)
• Clicking a favorite link will result in a security error
• If a user’s access rights to a zone are revoked, the zone
will be suppressed when the user navigates to the
respective portal page

15
Configurable Query and Info Zones
Validating Filter Values Using Service Scripts

Use Service Scripts To Validate Filters
• During the next exercise, you’ll add another filter to your

query zone to support searching for a customer by
driver’s license number
• Because this zone will now offer two mutually exclusive
filters, we'll want to configure the zone to validate that a
user doesn’t enter both Name and Drivers License
• To do this:
• You'll create a service script that performs this validation
• You'll update the query zone's parameters to indicate that you want
this script invoked whenever the query is requested
• Note, you can also use this technique for info zones with
filters

Reminder: A Service Script Defines Its API And Its
Logic
Script
The script’s
(Service) schema defines its
Schema input and output
<name/>
<driversLicense/>
This service script

is passed 2 fields
The script’s steps control
Step the logic that executed when
the service script is invoked

Team Walk Through (60 Minutes)
• Admin – Field
• Admin – Zone
• In this exercise you will:
• Add a new search option to your query zone to search by driver’s license
• Set up a service script to validate the filter values entered by the end-user
• Update your query zone to invoke your service script to validate the user’s input
• Again, the answers are in your workbook, but you should try to work it out
before peeking
• Note, you should be familiar with the CI_PER_ID table

15
Configurable Query and Info Zones
Suppressing Zones Using Service Scripts

Use Service Scripts To Suppress A Zone
• Query, info and map zones can be configured to call a

service script before they are displayed on a portal
• This script will return a value of true (meaning to show the
zone on the portal) or false (meaning to suppress the zone
on the portal)
• You'd use this feature if a zone should only be displayed if
some condition is true, for example:
• Only display a display-only map zone that contains the details of a
bill if the user has broadcast a bill ID from another zone
• Only display a "cancellation zone" if the state of the object that was
broadcast is "cancelled"
• …
• You'll get to use such a script in a future exercise

15
Configurable Info Zones
Changing Search Results Using Service Scripts

Case Study
• Our case study - if the user is considered "restricted" (e.g., has some
type of char that indicates they don't have complete access), only
customer names are shown as the search results

Use Service Scripts As A Conditional Criteria
• Query (and info) zones can be configured to call a service

script before they execute an SQL group in the zone
• This script will return a value of True (meaning to execute
the SQL) or False
• To implement the case study you could:
• Invoke a service script and pass it the user's ID
• It will do a BO interaction to read the user
• It will then return a value of True if the user has the restricted
element and any of the input values is non-blank
• The SQL associated with this statement will then just show the
customer's name

Service Scripts To Show Different Rows
• You can use the same technique on info zones to show

different rows for a broadcast value
For example, you might only show High Bill

Complaint rows if the account has a customer class
of Industrial

15 Business Services
Using The Explorer Zone Service To

Execute SQL In Plug-in and Service Scripts

Why SQL In Plug-in / Service Scripts?
• Up to now, you've seen two ways a plug-in / service script can

perform SQL:
• BO interaction (i.e., this executes the SQL embodied in the MO’s service)
• Business service interaction (i.e., this executes the SQL in the application
service)
• However, there are many reasons why you'll want to execute your
own SQL, for example,
• When a tax form is added, you might need to find the person ID
associated with the tax identifier on the form
• You might want to validate that an existing customer doesn't already
exist with the driver's license number entered for a new customer
• You might want to check if an account's service agreements are all in
"good standing" before allowing the customer to sign up for autopay
• …

No Inline SQL In Plug-in / Service Scripts
• We don't support inline SQL in service scripts for many reasons:

• We want the script-writers to work in a world of XML documents that are
accessed using xpath
– Allowing SQL would involve a completely different metaphor
• We want to encourage re-use of SQL
– If script-writers can write SQL, there will be a proliferation of redundant SQL
• We want to encourage SQL experts to write the SQL that's needed in
scripts
– If script-writers can write SQL, there will be a proliferation of inefficient SQL
• We want to make it easy to test the SQL that's going to be used at run time
– Testing inline SQL means that you have to execute the business process and
this can sometime be rather time-consuming
• We want to make it possible to include columns that don't reside on the
database
– For example, if you want to retrieve a list of an account's service agreements
along with their info string, you can't do this with raw SQL)

The Explorer Service Interprets Zone Parameters
Invoker Web / Application Server Database
1
2 Zone Parm
Info / Query Zone: Bill History The Explorer
Zones Filter 1: Account=123212
Service
3
When info and query zones build, they invoke a service that:
1. Reads the supplied zone's parameters (this is cached for performance
reasons)
2. Splices in the supplied filter values and column order
3. Executes the zone's SQL
4. Appends any derived columns (e.g., it appends icons, FK references, business
service elements, business object elements, formula results, etc.)
5. Returns the rows and columns back to the client for display in the zone
In other words, there's a single, sophisticated Java service that interprets

zone parameters and performs the processing for all info and query zones

Create A Zone And A Business Service
• Therefore, if you want to execute SQL in your plug-in / service scripts:
• Set up a zone that contains the desired SQL, the filters (the bind variable),
and the columns to return
• Set up a business service to invoke the explorer service (passing the zone)
• Invoke this business service in your script (passing any filter values)
Application Server Database
Service
Script 2 Zone:
Filter 1:
SQL-FindAccount
Account ID
3 SQL Parm: SELECT ACCT_ID
FROM CI_ACCT
WHERE ACCT_ID = :F1
Account
=123212
The
Explorer
1 Business Service
Zone: SQL-FindAccount 4
Filter1: Account=123212
Service
You can invoke this business service from any script (BPA or service)

Updates Aren't Allowed
• We don't allow the SQL in these zones to perform updates

so don't even try

Team Walk Through (45 minutes)
• Explore a plug-in and its use of zones

• Break up into teams and follow the instructions in the workbook

Organizing Your SQL Statements

Multiple SQL Statements In A Single Zone
• You might find it easier to say that you will have one
business service for each SQL statement
• But remember that query zones support multiple mutually
exclusive SQL statements so you could adopt a technique
like:
• Create a single query zone that contains separate SQL statements
that support all the methods that you can use to retrieve an
account ID
• Create a business service for this zone
• Invoke this business service passing it different filter values (as
per the search criteria)

Dealing With Multiple Rows

Dealing With Multiple Rows
• Some of your processing needs may involve iterating

through multiple rows returned from your "SQL zones"
• For example, you might need to look for a given element
on active SA's linked to the account
• Keep in mind that the element may reside in a true column or in the
CLOB
• Because the business service that communicates with the
explorer service simply returns a list of results, you can
use any of the classic Xpath commands to iterate through
the list results

Review Questions
• Please take the time to go through the review questions


Query Zones

Uploaded by

Copyright:

Available Formats

You might also like

Query Zones

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Query Zones

Uploaded by

Copyright:

Available Formats

15 Query Zones

Copyright © 2009, Oracle. All rights reserved.

• In the previous section we said there were two types of

15 - 2 Copyright © 2009, Oracle. All rights reserved.

Look and Feel

Copyright © 2009, Oracle. All rights reserved.

15 - 4 Copyright © 2009, Oracle. All rights reserved.

Security and Menu Access

Copyright © 2009, Oracle. All rights reserved.

• Users can only open a portal if they have access rights to

15 - 6 Copyright © 2009, Oracle. All rights reserved.

• If you want a portal to appear

15 - 7 Copyright © 2009, Oracle. All rights reserved.

• During this exercise, you will use the following:

15 - 8 Copyright © 2009, Oracle. All rights reserved.

Zone Types and Zones

Copyright © 2009, Oracle. All rights reserved.

15 - 10 Copyright © 2009, Oracle. All rights reserved.

Zone Type Zone

Both of these zones reference

15 - 11 Copyright © 2009, Oracle. All rights reserved.

required to render an Filter 2

info zone Filter …

15 - 12 Copyright © 2009, Oracle. All rights reserved.

Info Zone Type

15 - 13 Copyright © 2009, Oracle. All rights reserved.

Info Zone Type

15 - 14 Copyright © 2009, Oracle. All rights reserved.

• In an earlier section, you learned how debug mode is

15 - 15 Copyright © 2009, Oracle. All rights reserved.

• During this exercise, you will use the following:

15 - 16 Copyright © 2009, Oracle. All rights reserved.

Copyright © 2009, Oracle. All rights reserved.

• There are SQL functions whose syntax differs depending

15 - 18 Copyright © 2009, Oracle. All rights reserved.

• Imagine a scenario when there's an optional filter value

15 - 19 Copyright © 2009, Oracle. All rights reserved.

You Now Have Very Sharp Knives

Copyright © 2009, Oracle. All rights reserved.

• In a configuration environment, you can write inefficient

15 - 21 Copyright © 2009, Oracle. All rights reserved.

Columns Are Much More Than FK References

Copyright © 2009, Oracle. All rights reserved.

• You used a value

15 - 23 Copyright © 2009, Oracle. All rights reserved.

15 - 24 Copyright © 2009, Oracle. All rights reserved.

There's Another Query Zone Type

Copyright © 2009, Oracle. All rights reserved.

• The following query zone was set up with many filters

15 - 26 Copyright © 2009, Oracle. All rights reserved.

• Rather than build a single complex zone, you can:

This multi-query zone references 7

15 - 27 Copyright © 2009, Oracle. All rights reserved.

• The major reason to "atomize" your complex query into

15 - 28 Copyright © 2009, Oracle. All rights reserved.

Copyright © 2009, Oracle. All rights reserved.

• A user’s portal preferences control:

15 - 30 Copyright © 2009, Oracle. All rights reserved.