10 Accessing User Interface Functions Through URL Tools

This chapter has the following sections:

The examples used in this chapter assume that there is an existing Imaging application, that it has one or more saved documents, and that it has a search previously saved.

10.1 About Accessing User Interface Functions Through URL Tools

URL tools are a set of URLs in the Imaging user interface that provide direct access to specific user interface functions, such as executing a search or viewing a document. These tools are exposed through a specific access page and are supported as official APIs into the application. Imaging 11g URL tools are implemented in a manner similar to the previous Imaging 10g URL tools.

This section covers basic information about how URL tools are implemented in Imaging 11g. They are useful for determining what URL tools are installed on a specific server, or for maintaining installed URL tools. Because of the centralized nature of URL tool implementations in an imaging-ui project, it is easy to determine what tools are available on a particular code base. Additionally, through examination of the code, it is possible to determine the expected parameters and behavior of a particular URL tool.

10.2 Using URL Tools

The access point for the URL tools is currently the "UrlTools.jspx" page found in the following location: http://<server>:<port>/imaging/faces/Pages/UrlTools.jspx

The following tools are currently supported:

10.2.1 Supported URL Tool Parameters

The following URL parameters are used by all the tools and can be added as a parameter to any of the URL tools. Semicolon delimited Parameter Names indicate that multiple parameter names mean the same thing. This is for backward compatibility with the names used in Imaging 10g.

Parameter Name Description Valid Values Default

HideBanner

Indicates the banner should be shown or not shown. By default, the banner is shown. Not used by the ViewDocument tool.

1 or true:

Hide the banner

0 or false (default):

Show the banner

0 - Show the banner on all URL tools unless otherwise noted

HideWorkcenter

Indicates the Navigation Pane of the UI should not be shown. Not used by the ViewDocument tool.

1 or true:

Hide the Navigation Pane

0 or false:

Show the Navigation Pane

1 - Hide the Navigation Pane on all URL Tools (unless otherwise noted)

LockBanner

Indicates the banner should be locked or not locked. Locking the banner means that it is hidden and there is no way to expand it.

HideBanner=0 will override the existence of this parameter on the URL.

1 or true:

Lock the banner

0 or false:

Unlock the banner

0 - Unlock banner on all URL Tools (unless otherwise noted)

LockWorkcenter

Indicates the Navigation Pane should be locked or not locked. Locking the Navigation Pane means that it is hidden and there is no way to expand it.

HideWorkcenter=0 will override the existence of this parameter on the URL.

1 or true:
Lock the Navigation Pane

0 or false:

Lock the Navigation Pane

1 - Lock the Navigation Pane on all URL tools (unless otherwise noted)

ToolName

Indicates which tool should be used to process the request.

Currently there are only two tools. They are ExecuteSearch (or AWSER) and ViewDocument (or AWVWR).

None

skin

Indicates which skin to use.

Any value that is deployed with the application. Typically:

  • blafplus-rich

  • blafplus-medium

  • blafplus

  • fusion

  • fusion-11.1.1.3.0

  • skyros

The current user's preference setting is used.


10.2.2 Supported URL Tools

The following URL tools are supported:

10.2.2.1 Search URL Tool

The Search URL tool (ExecuteSearch) exposes the Search Results user interface as a directly accessible tool. The following is a summary of the URL parameters that are expected by the ExecuteSearch tool. Any remaining parameters are assumed to be field values that should be inserted into the search conditions.

Parameter Name Description Valid Values Default

SearchId

This is the ID of the search that you want to run. If this is not specified then SearchName will be used. If there is no SearchId and no SearchName specified an error will be presented to the user.

Any values of Search Ids that exist in the Imaging system and the current user has access to.

None

SearchName

If SearchId is not found in the Parameters then SearchName will be looked for. If there is no SearchId and no SearchName specified an error will be presented to the user.

Any values of Search Names that exist in the Imaging system and the current user has access to. Note that the hexadecimal (base 16) code should be substituted for any special ASCII characters used in the search name. For example, an ampersand used in a search named This&That should be defined in the URL as http://machinename:port/imaging/faces/Pages/UrlTools.jspx?ToolName=AWSER&SearchName=This%26That

None

ClearSearches

Removes all the searches that have been run to this point in the session.

1 or true:

Clear the searches

False or 0

_ipmOperator.<FieldName>

Specifies the Operator for the field identified by <FieldName>. For example a field named Company would use _ipmOperator.Company. This parameter is optional and only used when Picklist Operators are used in a search.

String values for the Search.Operator enum in the Java API. Options for text type fields include:

  • BEGINS_WITH

  • ENDS_WITH

  • EQUAL_TEXT

  • NOT_EQUAL_TEXT

  • CONTAINS

Options for number, decimal, and date field types include:

  • EQUAL

  • GREATER_THAN

  • GREATER_THAN_OR_EQUAL

  • LESS_THAN

  • LESS_THAN_OR_EQUAL

  • NOT_EQUAL

If no value is provided then none is specified to the API and the API will behave as if none was specified.

ORAIPM_EMPTY_URL_PARAMETER

Removes the default value of a search field if one exists.

ORAIPM_EMPTY_URL_PARAMETER

None


When a parameter is entered as a search field in the URL, and that search condition allows the user to select the operator for the condition, then the operator defaults to the value specified for the parameter in the saved search unless a different one is entered by the user. Example 10-1 and Example 10-2 are sample URLs for running a search using the ExecuteSearch URL Tool.

Example 10-1 Running a Search

In this example, the search named Find HR Docs returns a result listing of all documents where the Employee Name field equals Jon Doe.

http://<server>:<port>/imaging/faces/Pages/UrlTools.jspx?ToolName=ExecuteSearch&SearchName=Find+HR+DOCS&EmployeeName=Jon+Doe

Example 10-2 Removing a Search Field Default Value

The ExecuteSearch search tool uses the default value of a search field if one exists. If you want to remove the default value you can add a URL parameter that indicates an empty URL parameter. You do this by specifying a value of "ORAIPM_EMPTY_URL_PARAMETER" for the parameter. For example, if the field "AText80" normally has a default value that should be removed when running the search, specify the following URL:

http://<server>:<port>/imaging/faces/Pages/UrlTools.jspx?ToolName=ExecuteSearch&SearchName=Search%20Documents&AText80=ORAIPM_EMPTY_URL_PARAMETER

Note that by default the ExecuteSearch tool locks down the banner and the navigation pane of the Imaging user interface. This tool also locks down the form for the search results.

10.2.2.2 Viewer URL Tool

The Viewer URL tool exposes the Imaging Viewer UI tool as a directly accessible tool. The following is a summary of the URL parameters that are expected by the ViewDocument tool.

Parameter Name Description Valid Values Default

showHistory

Causes the history pane of the viewer to be shown or hidden

1 or true:
Show History

0 or false:
Hide history

False

showProperties

Causes the Properties pane of the viewer to be shown or hidden

1 or true:

Show properties

0 or false:

Hide properties

False

showStickyNotes

Causes the Sticky Notes pane of the viewer to be shown or hidden

1 or true:

Show Sticky Notes

0 or false:

Hide Sticky Notes

False

DocumentId

The document id of the document that should be shown to the user. If this is missing the view of the document will fail with an error.

Any valid document id obtained through searching or as a result of indexing a document through the user interface or the Web service API.

None

supportingKey

The key for the supporting information that should be shown

Any valid supporting information key value.

None

folder

The name of the folder the viewer should be placed in. This is an optional value that allows different sets of documents to be accumulated into segregated set in the UI cache.

Any string value that can be used as a name of a folder.

If this is not specified the folder name will be "default". This is the same folder the search results place viewed documents.

showTabs

Indicates if the tabs should be shown allowing the user to switch between documents in a folder.

1 or true - Hide the tabs 0 or false - Show the tabs

False

closeAllTabs

Tells the URL Tool to close all the tabs in the folder that the document will be opened in.

1 or true - Close all the documents in the folder. 0 or false - Do not close any of the documents in the folder.

False

forceHideProperties

Causes the Properties pane of the viewer to close. This option overrides the system default and any user preferences.

1 or true - Force close the Properties pane.

0 or false - Do not force close the Properties pane.

False

forceHideStickyNotes

Causes the StickyNotes pane of the viewer to close. This option overrides the system default and any user preferences.

1 or true - Force close the StickyNotes pane.

0 or false - Do not force close the StickyNotes pane.

False

forceHideHistory

Causes the History pane of the viewer to close. This option overrides the system default and any user preferences.

1 or true - Force close the History pane.0 or false - Do not force close the History pane.

False

HideBanner

Causes the banner in the viewer to be shown or hidden

1 or true - Hide the banner

0 or false - Show the banner

True


Example 10-3 is a sample URL for opening a document in the viewer using the ViewDocument URL Tool.

Example 10-3 Opening a Document for Viewing

In this example, the document with the ID of 123.RPO_456 and is placed in a folder named EBS1. The parameter showTabs=0 suppresses the document tabs in the viewer to prevent users from switching to other documents in the folder.

http://<server>:<port>/imaging/faces/Pages/UrlTools.jspx?ToolName=ViewDocument&DocumentId=123.RPO_456&folder=EBS1&showTabs=0

10.2.2.3 Upload URL Tool

The Upload URL tool exposes the Upload user interface as a directly accessible tool. The following is a summary of the URL parameters that are expected by the UploadDocument tool. Any remaining parameters are assumed to be field values that should be used to automatically populate the Application Fields in the Upload form.

Parameter Name Description Valid Values Default

AppId

This is the ID of the Application into which you want to index a document. If this is not specified then AppName will be used. If there is no AppId and no AppName specified an error will be presented to the user.

Any values of Search Ids that exist in the Imaging system and the current user has access to.

None

AppName

If AppId is not found in the Parameters then AppName will be looked for. If there is no AppId and no AppName specified an error will be presented to the user.

Any values of Search Names that exist in the Imaging system and the current user has access to.

None

ShowFieldsWithValues

Normally all fields that are specified on the URL will be removed from the Upload form. If this parameter is set to true then those fields will be displayed along with the other fields.

1 or true - Clear the searches

0 or false - Do not clear the searches

False


Example 10-4 and Example 10-5 are sample URLs used to upload a document using the UploadDocument URL Tool.

Example 10-4 Uploading a Document Using AppId

In this example the Upload tool loads and displays the application with an ID of 157. The fields MyTextField and MyNumberField are populated automatically and removed from the list of fields available to the user.

http://<server>:<port>/imaging/faces/Pages/UrlTools.jspx?ToolName=UploadDocument&AppId=157&MyTextField=Text%20Value&MyNumberField=123

Example 10-5 Uploading a Document Using AppName

In this example, the Upload tool loads and displays the Application with name of My App. The fields MyTextField and MyNumberField would be populated automatically but are not removed from the list of fields available to the user because the ShowFieldsWithValues parameter is set to true.

http://<server>:<port>/imaging/faces/Pages/UrlTools.jspx?ToolName=UploadDocument&AppName=My%20App&MyTextField=Text%20Value&MyNumberField=123&ShowFieldsWithValues=true

By default the UploadDocument tool locks down the banner and the navigation pane of the Imaging user interface.

Note:

The required format for a date field is a standard ISO date and time format which is represented by the following:

yyyy-MM-dd'T'HH:mm:ss.SSSZ
 

For example:

2022-12-30T00:00:00.000-0700

10.2.2.4 User Preferences URL Tool

The User Preferences URL tool exposes the Preference Page user interface as a directly accessible tool. There are currently no UserPreferences URL parameters other than the tool name. Example 10-6 is a sample URL that can be used to access the User Preferences URL Tool.

Example 10-6 Loading User Preferences

This loads the User Preferences user interface tool showing all of the user's Imaging user preferences. When using the User Preferences Tool the Close button is removed from the user interface:

http://<server>:<port>/imaging/faces/Pages/UrlTools.jspx?ToolName=UserPreferences