Smart Links User Guide<>

Maintaining Smart Links

System and user-defined Smart Links

Quercus is supplied with many pre-defined Smart Links. Some attributes of these pre-defined links are protected – so although you may be able to change the value of some of the display-related fields, such as the label, other fields may be locked.

Warning: You should also be aware that if you do modify the values of a link, the link may be overwritten on your next import of Smart Links unless you choose the ‘Add new links only’ import mode (see To import a file).

Accessing Smart Links maintenance

You access the various Smart Links maintenance options via the Control Centre SET-UP tab. You must be a member of the QPADMIN LDAP group to access these functions.

To access Smart Links

1Go to the Control Centre.

2Select the SET-UP tab.

3Select Smart Links from the Basic option list.

4From the Family pick list select the area of QuercusPlus for which you want to edit Smart Links.

For example, to edit the Smart Links associated with the Course Instance screen select Course Instance.

5Click Search.

A list of Smart Links belonging to the selected family is displayed.

Note: these links may not appear for every user who accesses a screen associated with the link family. If the a link within the family is associated with a user role then the link will only be visible to users with the correct LDAP settings.

6Either:

click the edit icon to edit a link

or

choose one of the the link maintenance options in the Tasks panel:

Create New Link

Allows you to create a new Smart Link.

» For more information see Smart Link options.

Global Parameters

Allows you to edit any global parameters associated with Smart Links.

Import from File

Allows you to enter a new Smart Link.

» For more information see Importing a list of Smart Links.

Export to File

Allows you to export existing Smart Links to an XML file.

» For more information see Exporting a list of Smart Links.

Smart Link options

When you choose the Create New Link option the Create a Smart Link screen opens.

This screen allows you to enter or edit details of the Smart Link. The fields are described below.

Field

Purpose

Name

The text that will appear on the button face. If the graphic for your button already includes the text, check the Hide box. (This text populates the alt attribute of the HTML img element.)

Description

The description of the link’s function that will appear as rollover text. (This text populates the title attribute of the HTML img element.)

Code

A unique identifier beginning with a letter and followed by any alphanumeric characters including. (dot) and _ (underscore). If you leave this empty a code for the link will be generated automatically.

Family

The family to which the link belongs.

Different families are displayed on different screens. The link between families and screens is given in the table in Smart Links on application pages.

Application

Associates a link with an application.

This field is used to group links for import and export purposes. A Smart Link XML export file can only contain the links associated with a specific application. This allows you to control which links are imported into your implementation of Quercus so that you do import links to applications which you are not running.

URL

The URL of the link target.

Use a relative URL for applications running on the same application server as Quercus. If you are targeting another Quercus service you will only need to specify the parameter segment of the URL, e.g. f?p=QP_HESA:91:&APP_SESSION.::::P91_SCD_OBJECT_ID:#ID#

You can use the following substitutions as part of URL

#ID# — Primary family member ID (typically OBJECT_ID)

#ID2# — Alternative family member ID (depends on family)

#DATE# — Current date in the YYYY-MM-DD format

#TIME# — Current time in the HH:MM:SS format

@MD5() — Calculates MD5 hash of the argument - e.g. @MD5(#ID#.SecretKey)

@SH1() — Calculates SHA1 hash of the argument - e.g. @SH1(#ID#)

You can use these parameters to construct an APEX-parsable URL or you can use them to supply parameters to non-APEX applications. For example:

http://www.google.ie/search?hl=en&source=hp&q=#ID2#

runs a Google search against the alternative family member id (this will usually be the unique record ID assigned by the user).

Also note that you must enter the http:// portion of the URL:

http://www.hesa.ac.uk/ is CORRECT

www.hesa.ac.uk/ is INCORRECT

See the note below relating to JavaScript calls.

Open In

Determines how the link will open.

Same tab — the link page will replace the current page

New tab — the link page will open in a new browser tab

Pop-up window — the link page will open in a pop-up window

Note: in earlier releases of Quercus this behaviour was controlled by specifying the link as a JavaScript call,e.g. javascript:popupURL('http://www.hesa.ac.uk/');

This is no longer necessary. The above functionality can now be achieved by entering http://www.hesa.ac.uk/ in the URL field and selecting Pop-up window in the Open In list..

User Role

Specifies which users can see the link.

To make the link visible only to members of particular LDAP groups, enter the LDAP group names in the form of a colon (:) delimited list.

For example, if you want the link to be visible only to members of the MYADMIN_HR and MYADMIN_FINANCE LDAP groups you would enter:

MYADMIN_HR:MYADMIN_FINANCE

in this field.

A user would have to be associated with at least one of the required roles to see the Smart Link.

If you leave the LDAP role field empty the Smart Link will be visible to all users.

You can associate a user with a LDAP group through:

Control Centre > SET-UP > User Account Management

Condition

Allows you to specify a condition that must be satisfied in order for the link to be displayed., e.g.

“If you are viewing a student’s record in the main STUDENTS tab, a link to the Admissions module should appear only if there is an Admissions record for the student in question.”

The condition must be entered by specifying the name of an existing dynamic condition function. Enter only the name of the function, e.g.

my_condition

my_package.slink_condition_check

You do not need to append any parameters: the primary family member ID and the alternative family member ID are automatically supplied.

The function you are calling must have the following PL/SQL signature:

f(p_smart_link in varchar2, p_id in varchar2, p_id2 in varchar2) return number

If the function is valid it will be evaluated each time the page is called. If the function returns 1 the link will be displayed. Otherwise it will be hidden from the user. Because the function will be evaluated each time the page is called we recommend that you use functions with an execution time of 50ms or less.

If you leave this field empty, then the smart link will be displayed on the pages associated with the link’s family so long as the user meets the role criteria.

Image

The image that will form the face of the Smart Link button.

If the graphic for the button already includes the text, check the Hide box associated with the Name field.

Enabled

Specifies whether or the link should be displayed.

Yes — link will be displayed

No — link will be hidden

Comments

The comment is for internal use only. It is NOT visible as static text or rollover text in the My Smart Links panel.

URL structure

Quercus URLs follow the standard Oracle APEX structure.

Example

https://labs.campusit.net/pls/qdev/
f?p=1001:214:2324068164106021::NO:RP::&cs=3F62C6002D554B06F4576A5B39E695F8D

URL component

Role

labs.campusit.net

URL of the application server

pls

signifies that request should be processed by plsql

qdev

the database access descriptor (identifies the database to use)

f?p

calls the APEX page processor with parameter p

Structure of parameter p is as follows:

f?p=App:Page:Session:Request:Debug:ClearCache:itenNames:itemValues:PrinterFriendly

App

numeric id or application alias

Page

page id or page alias

Session

numeric session id

Request

provides information about the request session item

Debug

YES — run in debug mode

NO — do not run in debug mode

ClearCache

Allows you to specify which parts of the session cache should be cleared

itemNames

List of item names used to set session state

itemValues

List of values used to set session state

PrinterFriendly

YES — render page in printer-friendly mode

NO — render page in normal mode

Caching Smart Links

The SMART_LINKS_IMAGE_CACHE parameter allows you to specify the number of hours images for Smart Links are cached in the client browser. The default is 168 hours (7 days).

To change the value of this parameter go to

SET-UP > PARAMETERS

and search for SMART_LINKS_IMAGE_CACHE.

Import and export

Exporting a list of Smart Links

You can export a list of Smart Links. You can use this to backup an existing set of links or you can use it to transfer links between one environment and another (e.g. from a staging to a live environment).

A simple export file looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<smartLinkSnapshot version="8.1" timestamp="2011-11-10T04:02:20" description="Created by: JA">
  <application name="CUSTOM">
    <smartLink id="BESPOKE_SERVICE_KPIS" family="SERVICE" description="Service KPIs" alternativeDescription="Bespoke Service KPIs" hideDescription="0" windowAction="NEW" url="f?p=1201:701:&amp;APP_SESSION.:::701:P701_SERVICE:#ID#" enabled="1" seq="1">
      <comments/>
      <image encoding="base16">[base16 encoding of button graphic goes here]</image>
    </smartLink>
    <smartLink id="CUSTOM.141379557" family="SERVICE" description="Control Centre User’s Guide" alternativeDescription="Control Centre User’s Guide" hideDescription="0" windowAction="NEW" url="http://docs.campusit.net/publications/quercus-8.0.2.-control-centre-user’s-guide" enabled="1" seq="4">
      <comments/>
      <image encoding="base16">[base16 encoding of button graphic goes here]</image>
    </smartLink>
  </application>
</smartLinkSnapshot>


Note that the Quercus 8.1 XML format has had several new attributes added and is not backwards‑compatible (in other words you cannot take a Smart Links export file created in 8.1 and import the links into an 8.0.2 version of Quercus). You can, however, import files created in earlier versions of Quercus (2.7 and 8.0+).

An example of the format is shown under Importing a list of Smart Links, below.

To export a set of Smart Links

1In the Tasks area of the Smart Links page, select Export to File.

2In the Application drop-down list select the group of Smart Links you want to export.

3Enter a description of the Export in the Description field (this will be stored inside the export file and can be used to help identify specific exports).

4Click Export.

The file will be downloaded to your browser’s download folder.

Importing a list of Smart Links

You can import a list of Smart Links in XML format.

Data model

The imported file must be in XML format valid against the following data model (expressed as an XML DTD):

<!ELEMENT smartLinkSnapshot ( application ) >
<!ATTLIST smartLinkSnapshot description CDATA #IMPLIED >
<!ATTLIST smartLinkSnapshot timestamp CDATA #IMPLIED >
<!ATTLIST smartLinkSnapshot version CDATA #REQUIRED >
<!ELEMENT application ( smartLink+ ) >
<!ATTLIST application name CDATA #REQUIRED >
<!ELEMENT smartLink ( comments | image )* >
<!ATTLIST smartLink alternativeDescription CDATA #IMPLIED >
<!ATTLIST smartLink description CDATA #REQUIRED >
<!ATTLIST smartLink dynamicConditionFunction CDATA #IMPLIED >
<!ATTLIST smartLink enabled ( 0 | 1 ) #REQUIRED >
<!ATTLIST smartLink family CDATA #REQUIRED >
<!ATTLIST smartLink hideDescription ( 0 | 1 ) #REQUIRED >
<!ATTLIST smartLink id CDATA #REQUIRED >
<!ATTLIST smartLink ldap CDATA #IMPLIED >
<!ATTLIST smartLink seq CDATA #IMPLIED >
<!ATTLIST smartLink url CDATA #REQUIRED >
<!ATTLIST smartLink windowAction ( DEFAULT | NEW | POPUP ) #IMPLIED >
<!ELEMENT comments ( #PCDATA ) >
<!ELEMENT image ( #PCDATA ) >
<!ATTLIST image encoding CDATA #IMPLIED >


Note that the validity against the above DTD is a minimal condition for import and does not, by itself, guarantee that links will work. For example the content of the family, ldap and url attributes must be resolvable values.

Below is a minimal XML import file showing, for clarity, only the mandatory elements and attributes:

<?xml version="1.0" encoding="UTF-8"?>
<smartLinkSnapshot version="8.1">
  <application name="CUSTOM">
    <smartLink id="123456" family="COURSE" description="Course Smart Link" hideDescription="0" url="http://docs.campusit.net" enabled="0">
    </smartLink>
  </application>
</smartLinkSnapshot>


A more typical import file is shown under Exporting a list of Smart Links.

To import a file

1In the Tasks area of the Smart Links page, select Import from File.

2Use the Browse button to locate the file you wish to import and click Import.

3Choose which import mode you want to use:

Replace existing links

All existing links will be deleted and replaced by the new links

Update existing links

Existing links will be retained. If there are new links with the same IDs as existing links, the new links will replace the existing links.

Add new links only

Existing links will be retained. If there are new links with the same IDs as existing links, the existing links will be retained and not updated. Only completely new links will be added.

4Click Install.

If the import was successful you will be returned to the Smart Links set up screen with the message ‘Smart Links imported successfully’ at the head of the screen.