Oracle Web Determinations is a web application that must interpret the user's request in order to determine what action is required.
In order to provide a high level of security and to prevent unauthorized changes to interview session data, it is not possible to manipulate the interview data through the URL.
The general structure of the URL follows the Representational State Transfer (REST) schema, where the action comprises the first part of the URL and the resource to be acted upon constituting the rest.
Note that the very first request to Oracle Web Determinations must contain the user=<username> query parameter in the URL if a particular user name is to be assigned to an Oracle Web Determinations session. Also note that the encoding to be used both in the URLs and the request and response content objects is UTF-8.
Click on the following topic links to display information about the basic and advanced URL structures. Please refer to the Placeholder Definitions topic below for further information about each placeholder.
Go to:
Go to the Default Data Review screen
Select Rulebase screen:
http://<webserver-url>/<web-determinations app>/Description
This URL directs the user to the Select Rulebase screen. From here, the user is able to select a rulebase to run.
Alternate outcomes
The user may not be presented with the Select Rulebase screen depending on the rulebases and their locales available to the Oracle Web Determinations. This is because Web Determinations will automatically select the rulebase and locale if there is only one choice to select.
Conditions Outcome Expected - many rulebases available Select Rulebase screen Only one rulebase available - but rulebase has multiple locales Locale Select screen (rulebase autoselected) Only one rulebase available, and rulebase has one locale Summary screen (rulebase/locale autoselected) Example
http://localhost:8080/web-determinations/
Locale Select screen:
http://<web-determinations url>/startsession/<rulebase>Description
This URL allows selection of the rulebase via the URL, therefore causing Oracle Web Determinations to bring the user to the Locale Select screen.
Alternate outcomes
The user may not be presented with the Locale Select screen depending on whether the selected rulebase has more than one locale to choose from. This is because Oracle Web Determinations will automatically select the locale if there is only one choice to select.
Conditions Outcome Expected - multiple locales available for current rulebase Locale Select screen Only one locale available for current rulebase Summary Screen (of current rulebase) Example
http://localhost:8080/web-determinations/startsession/My+Rulebase/
Start an interview session:
http://<web-determinations url>/startsession/<rulebase>/<locale>/Description
This URL allows selection of the rulebase and locale via the URL, therefore causing Oracle Web Determinations to start a session using the rulebase and locale provided. This brings the user to the default first screen - the Summary screen.
Example
http://localhost:8080/web-determinations/startsession/My+Rulebase/en-US/
Go to the Summary screen:
http://<web-determinations url>/screen/<rulebase>/<locale>/summaryDescription
In a current interview session, this URL goes to the Summary screen.
Note: this URL will not work if there is no current interview session.
Example
http://localhost:8080/web-determinations/screen/My+Rulebase/en-US/summary
Go to the Default Data Review screen:
http://<web-determinations url>/screen/<rulebase>/<locale>/Default+Data+ReviewDescription
In a current interview session, this URL goes to the Data Review screen.
Note: this URL will not work if there is no current interview session.
Example
http://localhost:8080/web-determinations/screen/My+Rulebase/en-US/Default+Data+Review
Retrieve an image:
http://<web-determinations url>/images/<image-filename>Description
This is the URL structure for retrieving the specified image file inside the 'images' folder of the web application, using the <image-filename>.
A developer can add a new image into the 'images' folder,then use that new image by using the URL above to reference it.
Location of 'images' folder
The 'images' folder is located in /<webapp root>/WEB-INF/classes/images, where <webapp root> is the root of the Web Determinations application; for example: C:\Tomcat\webapps\web-determinations\WEB-INF\classes\images
Example
http://localhost:8080/web-determinations/images/oralogo_small.gif
Retrieve a resource:
http://<web-determinations url>/resources/<resource-filename>Description
This is the URL structure for retrieving a resource file inside the 'resources' folder of the web application, using the <resource-filename>.
A resource is classified as files that are needed by the Oracle Web Determinations as part of displaying the web pages, such as CSS files, Javascript files.
A developer can add a new resource file into the 'resources' folder, then use that new resource by using the URL above to reference it.
Location of 'resources' folder
The 'resources' folder is located in /<webapp root>/WEB-INF/classes/resources, where <webapp root> is the root of the Web Determinations application; for example: C:\Tomcat\webapps\web-determinations\WEB-INF\classes\resources
Example
http://localhost:8080/web-determinations/resources/reset.css
URL's with the 'startsession' as the action are the only URLs that can be used without a current interview session. All others require usage within the context of an interview session, and will return an error page if used outside of an interview session.
Go to:
Start an interview session with a goal
Start a new interview session and load session data
Start a new interview session, load and investigate a goal
Go to the Decision Report screen
Save current interview session
Restart current interview session
Start an interview session with a goal:
http://<web-determinations url>/startsession/<rulebase>/<locale>/<goal-id>Description
Starts an interview session for the specified rulebase, with the specified goal-id.
The first screen of the goal investigation will be displayed to the user.
Example
http://localhost:8080/web-determinations/startsession/My+Rulebase/en-US/Attribute~a1~global~global
Investigate a goal:
http://<web-determinations url>/investigate/<rulebase>/<locale>/<goal-id>Description
Within a current interview session of the same rulebase - this URL structure can be used to investigate a goal.
The next screen for the goal is displayed. It is possible that some session data already exists, therefore for Attribute goals the screen that is displayed to the user may not be the first screen for the goal.
This URL structure works similar to Start an interview session with a Goal. The difference is that this URL is used once a session is started, so that current session data is not lost (as starting a new session resets session data). This URL cannot be used if:
- there is no current interview session in progress.
- if the current interview session is of a different rulebase.
Example
http://localhost:8080/web-determinations/investigate/My+Rulebase/en-US/Attribute~a1~global~global?
Start a new interview session and load session data:
http://<web-determinations url>/startsession/<rulebase>/<locale>/?caseID=<case-id>Description
Allows starting a new interview session with session data loaded from a specified case ID.
The screen displayed is the Summary screen. When the user selects a goal, the next screen is displayed.
This works the same as Start an interview session but also loads a 'case ID' at the same time so the user does not need to manually load it.
Example
http://localhost:8080/web-determinations/startsession/My+Rulebase/en-US/?caseID=JohnSmith
Start a new interview session, load and investigate a goal:
http://<web-determinations url>/startsession/<rulebase>/<locale>/<goal-id>?caseID=<case-id>Description
This starts a new session for the specified rulebase, loads session data from the specified case ID, and starts investigation on the specified goal ID.
This is exactly the same as Start a new interview session and load session data but selects a goal to investigate - therefore the first screen the user sees is the 'next screen' of the goal as opposed to the Summary screen.
This is a useful and more direct URL for users that need to start an interview session for a goal with pre-seeded data (which is usually data already known about the user).
Example
http://localhost:8080/web-determinations/startsession/My+Rulebase/en-US/Attribute~a1~global~global?caseID=JohnSmith
Go to an Authored screen:
http://<web-determinations url>/screen/<rulebase>/<locale>/<authored-screen-name>?postredirect=<screen-post-url>Description
Directs the user to the specified screen <authored-screen-name>. If the screen has a POST action, the postdirect value <screen-post-url> is used. The postdirect is necessary for question screens, as question screens need to post the form to a URL different to itself. The postdirect is not necessary for data review screens.
Note: this URL needs to be used within a current interview session.
Example
encoded <screen-name> qs%24s1%40Interviews_Screens_xint%24global%24global unencoded <screen-name> qs$s1@Interviews_Screens_xint$global$global encoded <screen-post-url> %2fscreen%2fControlling%2bScreen%2bOrder%2fen-US%2freport%2524attr%2524eligible%2524global%2524global%2524Relevant%2524false%2524false double-unencoded <screen-post-url> /screen/Controlling Screen Order/en-US/report$attr$eligible$global$global$Relevant$false$false
http://localhost:8080/web-determinations/screen/My+Rulebase/en-US/qs%24s1%40Interviews_Screens_xint%24global%24global?postredirect=%2fscreen%2fMy%2bRulebase%2fen-US%2freport%2524attr
%2524eligible%2524global%2524global%2524Relevant%2524false%2524falseGo to the Decision Report screen:
http://<web-determinations url>/screen/<rulebase>/<locale>/<decision-report-values>Description
Opens the Decision Report screen. The <decision-report-values> acts as settings that are used by Oracle Web Determinations to tweak the Decision Report display.
Note: this URL needs to be used within a current interview session.
Example
http://localhost:8080/web-determinations/screen/My+Rulebase/en-US/report%24attr%24a1%24
global%24global%24Relevant%24false%24falseGo to the Save As screen:
http://<web-determinations url>/save/<rulebase>/<locale>/save-as?postredirect=<screen-post-url>Description
Opens the Save As screen. The postredirect value is used on the Save Successful screen - the screen after saving the current interview session successfully.
Example
http://localhost:8080/web-determinations/save/My+Rulebase/en-US/save-as?postredirect=%2f
screen%2fMy%2bRulebase%2fen-US%2fsummary%3fcaseID%3d123Save current interview session:
http://<web-determinations url>/save/<rulebase>/<locale>/save-as?caseID=<case-id>&postredirect=<screen-post-url>Description
Saves the current interview session. This URL will only work if the current interview session has been saved, and saved to the <case-id> specified. Otherwise the error 'Invalid value '2' for parameter 'caseID' in request' will be displayed
The postredirect value is used on the Save Successful screen - the screen after saving the current interview session successfully.
Example
http://localhost:8080/web-determinations/save/My+Rulebase/en-US?caseID=1&postredirect=
%2fscreen%2fMy%2bRulebase%2fen-US%2fsummary%3fcaseID%3d1End current interview session:
http://<web-determinations url>/endsession/<rulebase>/<locale>?cancelURI=<relative-screen-url>Description
Goes to the screen that confirms the ending of the current interview session. When the user confirms, the next screen will be the Select Rulebase screen for default installations of Oracle Web Determinations.
If the user cancels, Oracle Web Determinations directs the page to the value of <relative-screen-url>.
Example
http://localhost:8080/web-determinations/endsession/My+Rulebase/en-US?cancelURI=%2fscreen%2fMy%2bRulebase%2fen-US%2fsummary
Restart current interview session:
http://<web-determinations url>/endsession/<rulebase>/<locale>?okURI=<relative-screen-url>&cancel-URI=<relative-screen-url>Description
Goes to the screen that confirms the restarting of the current interview session. When the user confirms, Oracle Web Determinations displays the value of <relative-screen-url> for okURI.
If the user cancels, Oracle Web Determinations directs the page to the value of <relative-screen-url> for cancelURI.
Example
http://localhost:8080/web-determinations/endsession/My+Rulebase/en-US?okURI=%2fstartsession
%2fMy%2bRulebase%2fen-US&cancelURI=%2fscreen%2fMy%2bRulebase%2fen-US%2fsummaryRetrieve a document:
To generate sample xml:
http://<web-determinations url>/document/<rulebase>/<locale>/<document public name or global name>/true
To generate a document:
http://<web-determinations url>/document/<rulebase>/<locale>/<document public name or global name>/false
Description
Allows direct linking to a Document. The document must first be made available - that is, it has been added in the Oracle Policy Modeling Screen Authoring in the Summary screen as a New Document.
The URL structure above is the same as the Document link added in the Summary screen, therefore the simplest way to create this URL is to copy the URL from the Document link. Alternatively, the ID can be found in the Screen xgen file (.exs).
Examples
sample xml:
http://localhost:8080/web-determinations/document/My+Rulebase/en-US/dbdcdcb6-7a5a-42a1-8743-3a05bb9ac5b8/true
the document:
http://localhost:8080/web-determinations/document/My+Rulebase/en-US/dbdcdcb6-7a5a-42a1-8743-3a05bb9ac5b8/false
Retrieve a commentary:
http://<web-determinations url>/commentary/<rulebase>/<locale>?target=<commentary-target>Description
Opens commentary content for the commentary-target in the current page. Note that the value of the commentary-target is encoded.
Example
http://localhost:8080/web-determinations/commentary/My+Rulebase/en-US?target=default
http://localhost:8080/web-determinations/commentary/My+Rulebase/en-US?target=screen
%2fs2%40Screens_screens_xinthttp://localhost:8080/web-determinations/commentary/My+Rulebase/en-US?target=attribute%2f
school_nameAdvanced usage of Goal ID
Attribute Goals - investigating a non-global attribute as a goal
As mentioned in the Goal ID Format section below, Attribute goals are almost always of the format of Attribute~<AttributeID>~global~global.
It is also noted that it is possible to use the attribute of an entity instance as a goal. While the need for this would be rare, it is possible to do with the URL API.
Note that before using an entity instance attribute as a goal:
- the entity instance must exist in the current session data. This is ideal for situations where the interview session is pre-seeded with data using the 'load' feature - it ensures that the entity instance exists. Otherwise if the instance does not exist, an error will occur
- Since the format for the Attribute goal requires the entity instance name, this makes the URL dynamic. It is important to note that when pre-seeding sessions via the 'load' feature - entity instances from the load feature will have a predictable entity instance name based on the value from the save file.
To create the Goal ID, simply follow the format: Attribute~<AttributeID><entity><entity-instance-name>.
By default, instance names are 'instance #X' from the Oracle Policy Modeling Screen Authoring, where X is a number. This can be modified so that a more meaningful text is prepended to 'X' ; for example: 'personX'.
Procedural Goals (Flow) - investigating a non-global Flow as a goal
Flows are linked to an entity. The main flow will usually be connected to the global entity, and from there the main flow can have sub-flows.
Sub-flows are very useful for collecting entity instances and their attributes. It allows collecting of entity instances through several screens and also contain sub-flow themselves to collect child entities.
It is possible to go through a Flow of a specific entity instance. This can be done by specifying the flow, entity, and entity instance in the Goal ID.
To create the Goal ID, simply follow the format: Procedural~<flow-name>{<entity><entity-instance-name>}. Using this as a Goal ID will bring the user to the start of the 'Flow' for the specified entity instance name.
The following is a table containing the definitions for the placeholders to be used in the URL structures (Note: The encoding to be used both in the URLs and the request and response content objects is UTF-8):
Placeholder | Description | Notes |
---|---|---|
<webserver-url> | The address of the webserver http://localhost:8080/ |
For a Tomcat install the address of the webserver would be: http://localhost:8080/ |
<web-determinations app> | The name of the Oracle Web Determinations webapp inside the webserver | The default Oracle Web Determinations webapp name is 'web-determinations' |
<web-determinations url> |
The address of the Oracle Web Determinations webapp |
Usually <webserver-url> and <web-determinations app> combined; for example: http://localhost:8080/web-determinations/ |
<rulebase> | The rulebase to use |
usually the normal name of the rulebase (for example, My Rulebase) and convert space to + (e.g. My+Rulebase) |
<locale> | The locale to use, follows a strict format | en-GB, fr-FR, zh-CN. For a list of the locale codes that Oracle Policy Automation supports out of the box, see: Implement support for non-English language For more information about the format see: Locale Format |
<goal-id> | The goal-id, follows a strict format | For more information about the format see: Goal ID Format Examples:
|
<authored-screen-name> | The screen name, has URL encoded chars. Follows a format |
For more information about the format see:
Authored Screen Name Format Example: http://localhost:8080/web-determinations/screen/Controlling+Screen+Order/en-US/qs%24s1%40Interviews_Screens_xint%24global%24global?postredirect=%2fscreen%2fControlling%2bScreen%2bOrder%2fen-US%2freport%2524attr%2524eligible%2524global%2524global%2524Relevant%2524false%2524false%3fuser%3dguest
|
<screen-post-url> | The POST URL to be used by the screen being invoked. Follows a format | For more information about the format see Screen Post URL Format Example: http://localhost:8080/web-determinations/screen/Controlling+Screen+Order/en-US/qs%24s1%40Interviews_Screens_xint%24global%24global?postredirect=%2fscreen%2fControlling%2bScreen%2bOrder%2fen-US%2freport%2524attr%2524eligible%2524global%2524global%2524Relevant%2524false%2524false%3fuser%3dguest %2fscreen%2fControlling%2bScreen%2bOrder%2fen-US%2freport%2524attr%2524eligible%2524global%2524global%2524Relevant%2524false%2524false%3fuser%3dguest |
<non-authored-screen-name> | Screen names for non-authored screens | To see the values for the non-authored screen names see: Non-authored Screen values Examples:
|
<document-id> |
identifies the document to display. This ID is generated during the Build process in OPM. |
An example of a document ID is: 6e2d1953-3a8c-493e-a36e-c82ebbb45b9b This ID can be found in the Screen xgen file (.exs) in the rulebase output folder, or can be extracted from the Document link itself in the Summary screen. |
<commentary-target> |
specifies the commentary-target, the value is encoded. Follows a format |
For more information about the format see: Commentary Target Format Example: %2fs2%40Screens_screens_xint (URL decoded - /s2@Screens_screens_xint) |
When looking at the placeholder descriptions that follow, use the following table as a handy reference for URL character encoding:
Character | Encoding |
---|---|
$ |
%24 |
@ |
%40 |
% |
%25 |
? |
%3d |
+ |
%2b |
; |
%3b |
& |
%26 |
& |
%26amp%3b |
(whitespace) |
%20 |
/ (slash) |
%2f |
œ | %c5%93 |
Note: in cases when an entity instance identifier contains a forward slash (for example: "person/0-1"), use %c5%93 instead of %2f, so that url parsing will not be broken.
Click on any of the following topics for a description of each of the placeholders that requires a strict format:
The locale format follows the 'xx-XX' format e.g. en-US.
There are two types of Goal-IDs: Attribute and Procedural (Flows).
Attribute goals can be broken up into 4 parts, separated by tilde (~). An example Attribute Goal: Attribute~a1~global~global.
Attribute goals are almost always of the format Attribute~<AttributeID>~global~global. It is possible to investigate an entity instance attribute for non-global entities, which is covered in Advanced usage of Goal ID.
Procedural Goals (Flows) can be broken up into 3 parts. An example Procedural Goal: Procedural~MyFlow{global~global~}.
There is a simple way to obtain Goal IDs. It is done by using the Goal links in the Summary screen. By right-clicking on the Goal links, it is possible to inspect the full URL of the Goal links, and extract the Goal ID.
If the Attribute goal that you want to build the URL for is not in the Summary screen, simply add it in Oracle Policy Modeling then run the rulebase.
Authored Screen Names are URL-encoded, so characters like $ and @ is converted to %24 and %40 respectively.
There are two types for Authored Screen Names: Question Screen and Data Review.
The screen name for Question screens can be broken down into 4 parts. It is separated by the URL encoding %24 ('$' when unencoded); for example: qs%24s1%40Interviews_Screens_xint%24global%24global.
The screen name for Data Review screens can be broken down into four parts. It is separated by the URL encoding %24 ('$' when unencoded); for example: dr%24My+Data+Review%24global%24global.
The Screen Post URL is an extra parameter added to the URL of a Question screen.
The URL is used by the form of the Question screen for when the screen submits the form as a POST.
The Screen Post URL is essentially a relative URL to a screen (that is, without the http://<web-determinations-url>). Therefore the Screen Post URL template would look like:
The target screen can be an authored or un-authored screen. The whole Screen Post URL is also encoded, resulting in the screen-name part becoming double-encoded. Encoding the templates above converts to:
%2fscreen%2f<rulebase>%2f<locale>%2f<authored-screen-name>
%2fscreen%2f<rulebase>%2f<locale>%2f<non-authored-screen-name>
Below are 3 steps that demonstrate an un-encoded screen-name being encoded to double-encoding. The sample screen-name below is of a Question Screen
From the above, note that because encoding always has a '%' sign, for double-encoding this is further encoded encoded to '%25'; for example, 'qs$s1' is encoded to 'qs%24s1'. Encoding again changes 'qs%24s1' to 'qs%2524s1'.
Decision Report screen can take in values; for example, which attribute to use as the top-level attribute for the Decision Report screen.
The Decision Report value can be broken down into eight parts. The format is separated by the %24 (which is '$' in encoded format). Each part is mandatory; that is, there should always be eight parts.
For example: report%24attr%24a1%24global%24global%24Relevant%24false%24false.
There are three items that can have commentary in Oracle Web Determinations - the rulebase, the current screen, or a control.
Below are the format of the value to use for each item:
Item | Value Format | Example Value | Example Full URL |
---|---|---|---|
rulebase |
default |
default |
http://localhost:8080/web-determinations/commentary/My+Rulebase/en-us?target=default |
screen |
screen%2f<screen-id> | screen%2fs2%40Screens_screens_xint (screen/s2@Screens_screens_xint) |
http://localhost:8080/web-determinations/commentary/My+Rulebase/en-us?target=screen%2fs2%40Screens_screens_xint |
control |
attribute%2f<attribute-id> |
attribute%2fb1 (attribute/b1) |
http://localhost:8080/web-determinations/commentary/My+Rulebase/en-us? |