- Stage: Definition
- Planned Release: MP5
- Status Notes: Implementation
- Platform Team - Contact: User:Iperdomo
Parameter Windows are defined in the Application Dictionary (AD) and used for generating user interface, usually a pop-up window, to ask the user the values of process parameters.
Sample of a parameter window generated by WAD based on 2.50 parameter implementation.
In the current implementation, parameters are associated only to a Process or Report. The definition of the Processes and Reports is made in the same table
AD_Process table, and this definition is bloated with too many columns (flags at user level) that is hard to maintain and understand.
The goal of this project is to provide a new infrastructure to define Processes and Reports and the Parameters associated to them. The new infrastructure will enable to define parameter for any Entity that requires it.
Users & use cases
- Implement all simple references.
- Implement Multiple Selector Reference.
- Support for displayed. 2.50 implementation doesn't support it, e.g. I want to always pass a parameter always to my process. I define the default value (fixed or dynamically evaluated) but the User is not allowed to change it, so I hide it.
- Callable from menu
- Support for return of complex actions. When a 2.50 process is executed it just can return a message to display to the user. It should be able to return complex actions such as show message, open window in a concrete record, print report... External modules should be able to provide new kinds of actions.
Nice to have
- Support for read only fields.
- Support for display logic. Show/hide some fields depending on a Dynamic_Expressions.
- Support for read only logic. Show/hide some fields depending on a Dynamic_Expressions.
- Support for validation rules, so available values in combos can depend on another field's value.
- Processes shouldn't need of a physical column in DB just as a holder for the field. It should be possible to directly define the process in the tab (as a field) without linking to a column.
- Support for picking more than one record pass it to the process. Current implementation only process the first record.
- Processes can implement different interfaces (extensible by modules) that affect the UI at execution time, such as process completion, process status (textual), cancellable...
- Support for callouts so values of fields are calculated based on values of other ones.
- Support to schedule parameter window processes.
- Support for persist the parameter values entered by the User.
- This feature makes special sense in case the process is schedulable, so user can schedule a process with a set of values.
- Persisted parameters could also be used à la saved views, having a list of persisted parameters to be reused for processes, reports...
- Implement Date Range reference.
- When process is invoked from menu, it should be possible to use the "Help" menu action so show online help.
- When in windows, online help for the process should be visualized.
Parameter Windows will make use and extend infrastructure created for Pick and Execute pattern (
OBUIAPP_Parameter tables). This means a new infrastructure for process is provided, but 2.50 style one will still be kept and old processes will not be automatically migrated.
Based on functional specifications described above, the following sections discuss technical details on each of them.
Implement all references
Currently, widgets are using the same parameter definition table and they are already implementing a good portion of existent references. Ideally, code for both artifacts (parameters in widgets and parameter windows) should be reused.
Display and read only logic
Note fields participating in these logics can be other parameters, which should be evaluated as they change, but they can also be session attributes as well as fields in window invoking the process. For this latter case, it must be decided whether in order to use a field in this logic, it is mandatory to set it as stored in session.
Currently validation rules restrict the selectable values in 2.50 style drop down lists (Table, TableDir and List references). With the following problems/limitations:
- They use FIC to compute the values, if implementing this for parameter windows we would have to create a new FIC mode to handle it.
- They are implemented in SQL.
- They cannot be applied to 3.0 selectors.
Knowing all this, should we still use validation rules? should we extend them? should we create something else?
Return complex actions
No need of physical column
This would simplify development of new processes. Computed fields currently don't need physical column behind them, so this should be extended also to parameter windows.
Execute on more than one record
This is already implemented for manual UI process definition. It just requires to be extended to this functionality.
Some Parameter Windows need to be invoked from menu.
Old 2.50 processes are opened in a popup which in most of the cases is modal. UI for this case must be decided: popup (modal/no modal), new tab...
Currently P&E processes are secured in the same fashion old processes are: by default, having access to a window, implicitly gives access to the process. It is through a preference that this behavior can be changed to force to have explicit access to the process.
In case of menu, explicit access is always required.
Additionally, process access must be checked in backend to ensure it is not executed by ungranted users. This should be implemented centrally.
A possible approach to implement reports:
Reports are processes that implement a known Handler, they must have a hidden parameter with the jrxml that prints the report. The handler receives this parameter as well as the rest of parameters, and generates the report.
The UI during process execution can vary depending on which interfaces implements the java processes. In this way it would be possible for example:
- Progress completion interface. Processes implementing this interface would have a
int getCompletionPercentage()method returning a number between 0 and 100, in UI a progress bar could be shown based on this.
- Status interface. Implementing a method like
String getStatus()which returns a text explaining what the process is doing (such as calculating prices, generating invoices...). In UI this text should be shown.
- Cancelable interface. with a
void cancel(), which should handle how to cancel the process.
This interfaces, as well as UI implementation should be deployable by modules, so new modules could implement different visualizations for processes in execution.
To implement this feature it would be needed to have a pool of in execution processes, so it is possible to retrieve the instance of a known process to ask for its status.
From client side, this could be implemented doing pings for current processes each x time, or through webSockets or a similar technology.
If the pool defined above is current quartz scheduler, it might be relatively easy to make all Parameter Window processes schedulable. In fact, when calling from button, they would be scheduled tasks to be immediately executed.
This also would make visible all process executions from current Process Monitor window.
Implementing persisted parameters feature would make possible to schedule based on some parameters.
Persisted parameter values
Persisting parameter values, together with schedulable processes, allows to schedule the same process with different values.
OBUIAPP_Parameter_Value table is used to store param values used for widget params. This is the table that should be used for this purpose.
Initially, it could appear as child of Process Request window to add all parameters for the scheduled process.
In a second phase parameters should be editable through a rich interface which would be displayed similarly to the parameter window.
Date Range reference
In case of parameter windows it makes sense to define a complex date reference that defines a range (from-to) in a similar way currently is implemented in grid filters.
User experience design
Notes to be considered when designing UI:
- Currently Pick & Execute is opened as a modal popup within the tab that launched it. Should this pattern be kept for processes opened from tabs?
- 2.50 parameter processes invoked from menu are opened in a modal popup. How should parameter window processes invoked from menu be opened: modal popup/new tab...?
- Currently when P&E is being processed, user has no visual hint. In 2.50 processes a processing spin was shown. For processes taking long to be executed it makes sense not to show a frozen window but at least some "processing" hint. Ideally, processes should be able to inform about their completion rate (allowing to display a status bar) or status (allowing to display some info like "Processing line 2/50").
- Currently P&E accepts a single parameter which is the grid. Name of this parameter is shown as pop up's header. When supporting several parameters this must be revisited.
- 2.50 processes show in the top side of the popup a message with the help/description of the processes. P&E doesn't do it and there's no way of displaying process help.
This project is divided in different phases.
Status: Implemented in 3.0MP20.
Implement all must have options:
- Implement all simple references:
- Implement multiple selection reference
- Support for displayed
- Callable from menu
- Support for return of complex actions
Status: In progress, planned for 3.0MP25
- Subordinated search combos based on HQL Validation Rules
- Field groups
- Read only logic
- Multiple selector for list reference
Status: Not commited yet
- Filter the selector parameters using the context organization. The selected organization will depend on how the parameter window is executed:
- Executed from the menu: There is no context, so the organization the user is logged in will be picked.
- Executed from a window, one record selected: The picked organization will be the organization of the document
- Executed from a window, several records selected: To be determined
- When a parameter window is opened, show the loading dialog until the parameter default values have been loaded.
- Implement read only logic
- Allow using in the display logic and in the read only logic fields from the tab where the parameter window was executed from.
- See issue 18439