15 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
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 - 4
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
Service
Portal
15 - 6
User Group
Application
Service/
User Group
User
User Group
/ User
Adding Portals to Menus

If you want a portal to appear
on a menu, you must add its
navigation option to that menu
There is a special button on the
portal page that adds the portal to
a menu
Also note, the user must have
security access to the portal's
application service to see the item
on the menu
Menu
Navigation
Option
Portal
Note, the same navigation

option is also used to add the
portal to users Favorite Links
15 - 7
Menu Line
Menu Item
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 wont 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 - 8
15
Zone Types and Zones
Zone Types versus Zones

These info
zones are
created using
the "info" zone
type
15 - 10
This query zone is

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
15 - 11
Zones Have Parameters

Each zone type has a
variety of parameter
types
Zone Type
Parameter
Type
These are a sample
of the parameters
required to render an
info zone
Info Zone Type
Zone
Zone
When you set up your

zones, you define the
value of each
parameter
Parameter
Parameter
A zones parameters
control what data is
retrieved and how it is
displayed
Accounts Bills Zone
Persons Contacts Zone
name=ACCT_ID datasource=G
name=PER_ID datasource=G
Number of rows to display
24
24
Number of rows to download
200
200
Initial columns to display
C1 C2
C1 C2
SQL 1
SELECT BILL_DT, BILL_ID
SELECT CC_DTTM, CC_ID
Column 1
source=SQLCOL sqlcol=1
source=SQLCOL sqlcol=1
Column 2
source=FKREF fkref=BILL
source=FKREF fkref=CC ID
Filter 1
Filter 2
Filter
Hidden Filter 1
Hidden Filter 2
Hidden Filter
Column 3
15 - 12
Zone Parameters and Mnemonics

In the next walk through, youll set up a new zone by entering zone parameters
Youll 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, youll specify
several mnemonics
Info Zone Type

Filter 1
Filter 2
Filter
Hidden Filter 1
Hidden Filter 2
Hidden Filter
Several mnemonics are used to define how

the column looks and behaves: source=,
fkref=, input=, context=, suppress=

SQL 1
Column 1
Column 2
Column 3
15 - 13
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

sample zones and tips to reduce errors

SQL 1
Column 1
Column 2
Column 3
15 - 14
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:
15 - 15
Special options appear in each zone's tool bar to help you debug
your zone configuration (youll 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 - 16
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 databaseneutral, 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
15 - 18
Conditional From and Where
Imagine a scenario when there's an optional filter value
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
[(F2) AND CLAIM_DT <= :F2]
This line is only included in the WHERE clause

if the 2nd filter is specified by the user
You can use the same technique for:
For example, what if a user can search for claims with a claim date between a date
range and the end date is optional
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 - 19
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 - 21
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
15 - 23
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
15 - 24
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)
15 - 26
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
15 - 27
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
15 - 28
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 users 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 users preferences can be inherited from a template user
This means the users 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)
15 - 30
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
15 - 31
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
15 - 32
Portals Preferences ERD
You create portals and define the

appropriate zones as required
Zone Type
Zone
User
Portal
Portal /
Zone /
User
Portal /
Zone
A zone can be referenced on any
number of portals
Users define which zones they use (and

the order they appear and )
If you add a new zone and dont set up a users
portal preferences, by default, the zone appears at
the bottom of the portal
15 - 33
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 - 35
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
Service
Zone
15 - 37
User Group
Application
Service/
User Group
User
User Group
/ User
Portal and Zone Security and Portal Preferences
Users only see portals that

they can access
All zones appear regardless of

security access
15 - 38
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 users access rights to a zone are revoked, the zone

will be suppressed when the user navigates to the
respective portal page
15 - 39
15
Configurable Query and Info Zones
Validating Filter Values Using Service Scripts
Use Service Scripts To Validate Filters

During the next exercise, youll add another filter to your
query zone to support searching for a customer by
drivers license number
Because this zone will now offer two mutually exclusive
filters, we'll want to configure the zone to validate that a
user doesnt 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
15 - 41
Reminder: A Service Script Defines Its API And Its

Logic
Script
(Service)
Schema
The scripts
schema defines its
input and output
<name/>
<driversLicense/>
Step
15 - 42
The scripts steps control

the logic that executed when
the service script is invoked
This service script

is passed 2 fields
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 drivers 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 users 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 - 43
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 - 45
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
15 - 47
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
15 - 48
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 - 49
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 MOs 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

15 - 51
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)
15 - 52
The Explorer Service Interprets Zone Parameters

Invoker
Web / Application Server
1
Info / Query
Zones
Zone: Bill History

Filter 1: Account=123212
The Explorer
Service
Database
Zone Parm
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
15 - 53
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
Service
Script
2
3
Account
=123212
1 Business
Service
Database
Zone: SQL-FindAccount
Filter1: Account=123212
The
Explorer
Service
Zone:
SQL-FindAccount
Filter 1:
Account ID
SQL Parm: SELECT ACCT_ID
FROM CI_ACCT
WHERE ACCT_ID = :F1
You can invoke this business service from any script (BPA or service)
15 - 54
Updates Aren't Allowed

We don't allow the SQL in these zones to perform updates
so don't even try
15 - 55
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
15 - 56
15
Business Services
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)
15 - 58
15
Business Services
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
15 - 60
Review Questions
Please take the time to go through the review questions
15 - 61
15 - 62

15 Query Zones

Uploaded by

Document Information

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

15 Query Zones

Uploaded by

Copyright:

Available Formats

15

Copyright 2009, Oracle. All rights reserved.

A Portal Can Contain Query Zones

In the previous section we said there were two types of

There's actually a 3rd type of zone that users use to find

Copyright 2009, Oracle. All rights reserved.

Configurable Query Zones

Look and Feel

Copyright 2009, Oracle. All rights reserved.

Query Zones Look Almost Identical To Info Zones

Copyright 2009, Oracle. All rights reserved.

Configurable Query Zones

Security and Menu Access

Copyright 2009, Oracle. All rights reserved.

An Aside: Portal Security

After creating the portal, you must grant access rights to

Copyright 2009, Oracle. All rights reserved.

Adding Portals to Menus

Note, the same navigation

Copyright 2009, Oracle. All rights reserved.

Team Walk Through - Add A Query Portal (20 Minutes)

Please break up into teams

Please note, your workbook has detailed instructions for

Copyright 2009, Oracle. All rights reserved.

Configurable Query Zones

Zone Types and Zones

Copyright 2009, Oracle. All rights reserved.

Zone Types versus Zones

Copyright 2009, Oracle. All rights reserved.

This query zone is

Zone Types and Zone ERD

Both of these zones reference

Copyright 2009, Oracle. All rights reserved.

Zones Have Parameters

Info Zone Type

When you set up your

Accounts Bills Zone

Persons Contacts Zone

Number of rows to display

Number of rows to download

Initial columns to display

SELECT BILL_DT, BILL_ID

SELECT CC_DTTM, CC_ID

Copyright 2009, Oracle. All rights reserved.

Zone Parameters and Mnemonics

Info Zone Type

Several mnemonics are used to define how

Number of rows to download

Copyright 2009, Oracle. All rights reserved.

Zone Parameter Validation

Info Zone Type

It'd be a good idea to copy / paste from the

Initial columns to display

Copyright 2009, Oracle. All rights reserved.

Reminder, to enable this mode, enter ?debug=true at the end of

When you start the system in configuration mode:

Team Walk Through Add A Query Zone (30 Minutes)

Copyright 2009, Oracle. All rights reserved.

Configurable Query Zones

Copyright 2009, Oracle. All rights reserved.

Avoid Database-Specific SQL Functions

There are a few more - TRIM, AS CHAR, AS DATE, etc.

As you know, we want our SQL to be database-neutral

Copyright 2009, Oracle. All rights reserved.