Commands are developer defined scripts which are usually visualized as buttons or menu items.
Not all commands are visualized though, for example an init command in an Assistant. The script language is common for all commands, regardless if it is visualized or not.
Figure 1 - Command example
(A) - Toolbar Page
A Concat button with a command is available in the toolbar in the page. For example, when the Concat button is clicked, a function or an action can calculate something, and a result can be displayed in an alert box.
(B) - Toolbar List
Also a Concat button with the same functionality is available in the list when a row is selected. The command can be executed for each row in the list as well.
Context
A command operates on a context object, which normally is a record. This means the command can access the attributes on that record, both for reading and setting. When a command is defined it is necessary to set the type of record it will operate on. Technically it is possible to skip setting the type, but without the type information it is not possible to check if attributes are misspelled. When Global mode is used, it does not work without setting the type of the record.
Server calls and performance
Calling the server is typically a very slow operation. Each call gets an overhead cost in that it needs to send the request to the server. The server needs to unpack the request and interpret it, and then send the actual call to the database, which then replies and optionally returns and answer to the server, which packs the response and sends it back to the client. The client then needs to unpack and handle the response. As this happens for every call to the server, making a lot of server calls can slow down the command considerably.
If a call to the server needs to be done, then consider doing as much as possible in PL/SQL instead. In this way the number of server calls can be reduced.
None.
Use a command to run event handlers when the user clicks on a command control, for example a button or menu item.
A command control can be placed, instead of a regular field, on a page, list, menu etc.
Add the command control instead of a regular field, on a page, list, menu etc.
Define a command in the client model file using the following format:
list <list_name> {
...
command <command_name> {
...
}
}
<command_name> - Identity of the command, always use a meaningful identifier.
<list_name> - The container name the command control is added to, like a page, list, menu etc.
Functions are operations without side-effects. They are read-only operations, and it is possible to call functions, which are written in the projection file, to do some calculations and then get back data as a result.
The code examples describe how to define and add a simple function to a command in the projection, PL/SQL and client file.
For more detailed instructions on adding a command, refer to Add a function to a command.
---- Example code in the projection file ----
function ConcatText Text {
parameter Text1 Text;
parameter Text2 Number;
}
---- Example code in the PL/SQL file ----
layer Core;
FUNCTION Concat_Text(
text1 IN VARCHAR2,
text2_ IN NUMBER ) RETURN VARCHAR2
IS
BEGIN
RETURN text1_ || ' - ' || text2_;
END Concat_Text_;
-------------- Example code in the client file ---------------
client EAPDemo;
component FNDBAS;
layer Core;
------------------------- NAVIGATOR ENTRIES -------------------
------------------------- MAIN PAGES --------------------------
//Added for the command function example
command ConcatText;
------------------------- COMMANDS ----------------------------
//Added for the command function example
command ConcatText {
label = "Concat";
mode = SelectedRecords;
execute {
call ConcatText(OrderNo, PreAccountingId) into Result;
alert("$(Result)");
}
}
Actions are similar to functions, but are operations with side-effects. They are read and write operations, and it is possible to call actions, which are written in the projection file, to do some calculations and then write the result to the database.
---- Example code in the projection file ----
action AddLead Text {
initialcheck none;
ludependencies = BusinessLead;
parameter Id Text;
parameter Name Text;
}
PROCEDURE Add_Lead (
id IN VARCHAR2,
name_ IN VARCHAR2)
IS
attr_ VARCHAR2(4000);
keyref_ VARCHAR2(100);
BEGIN
attr_ := '';
Client_SYS.Add_To_Attr('LEAD_ID', id_, attr_);
Client_SYS.Add_To_Attr('NAME', name_, attr_);
Business_Lead_API.New(attr_);
END Add_Lead_;
-------------- Example code in the client file ---------------
client EAPDemo;
component FNDBAS;
layer Core;
------------------------- NAVIGATOR ENTRIES -------------------
------------------------- MAIN PAGES --------------------------
page LeadPage using Leads {
...
command AddLead;
}
------------------------- COMMANDS ----------------------------
//Added for the command function example
command AddLead {
label = "Add Lead";
execute {
call AddLead("L1", "My first Lead");
}
}
A variant of an action is called state action. A state action does not need to be defined in the projection file by the user, because there is already a state machine in the entity, which is automatically generated from the Aurena framework.
The code example describes how to define and add a state action to a command in the client file.
For more detailed instructions on adding a command, refer to Add a state action to a command.
-------------- Example code in the client file ---------------
client EAPDemo;
component FNDBAS;
layer Core;
------------------------- NAVIGATOR ENTRIES --------------------
------------------------- MAIN PAGES --------------------------
//Added for the state action example
command SetCancelled;
------------------------- COMMANDS ----------------------------
//Added for the state action example
command SetCancelled for CustomerOrder {
label = "Cancel";
execute {
call SetCancelled();
}
}
For a complete list of the available command instructions, refer to the section Command instructions.
None.
Below is a list of properties that can be used to customize the control.
execute/bulkexecute | emphasis | enabled | icon | label | mode | style | variable | visible
Below is an example on how to add the commands HelloWorld and MainContact in the projection and client files.
------ Example code - projection file ------------ projection EAPDemo; component DEMO; layer Core; description "Example of adding command"; category Users; entityset Leads for BusinessLead;
Example code - Entityset used for the commands (projection file)
------ Example code - client file ------------ client EAPDemo; component DEMO; layer Core; page LeadDetails using Leads { selector BusinessLeadSelector; group LeadMainGroup; command HelloWorld; command MainContact; } group LeadMainGroup for BusinessLead { field LeadId; field Name; field PotentialId; field Turnover; field LastModified; } command HelloWorld for BusinessLead { execute { info("Hello World!"); } } command MainContact for BusinessLead { execute { inquire("Do you want to see the Main contact for the Lead?") { when YES { info("The Main Contact is '${MainContactName}'"); } when NO { info("You said No."); } } } }Example code - Added commands (client file)
This section describes the instructions that can be used in a command.
Calls the agent to perform a method.
Note! For Chrome on Windows there is a an extension that can be installed. This extension mainly handles printing and document scenarios.
------------ Example code --------------
execute {
agentenabled into VarAgentEnabled;
if[VarAgentEnabled = "TRUE"] {
agentcall GetLocalProperty("Document Management/Settings", "FileSettings") into UserSettingsType;
}
}
Checks if the agent extension is installed and available to the application.
------------ Example code --------------
execute {
agentenabled into VarAgentEnabled;
if[VarAgentEnabled = "TRUE"] {
agentcall GetLocalProperty("Document Management/Settings", "FileSettings") into UserSettingsType;
}
}
Opens a modal message box with a message and an OK button.
------------ Example code --------------
alert("Base values updated for ${UpdatedEmployeeCountVar} employees.");
Opens a defined assistant as a modal dialog. The assistant can be in the same or a different client file.
When the assistant is in the same client it is enough to use the name of the assistant. When the assistant is in a different client file you need to provide the client name also, <ClientName.AssistantName>.
------------ Example code, assistant in same client -------------- assistant NotesAssistant(PackageNameStr, CallingProjectionNameStr, keyref, luname, "") into(NoteIdNum) { when OK { exit; } }------------ Example code, assistant in different client -------------- assistant NotesDialog.NotesAssistant(PackageNameStr, CallingProjectionNameStr, keyref, luname, "") into(NoteIdNum) { when OK { exit; } }
The same as call but with the difference that if more than one record is selected it puts all requests together in one call to the server, and processes all request before returning. Only actions without return values are applicable for this instruction. A transaction is done around the actions so if one request fails the transaction is rolled back.
Bulkcall can only be called if placed inside a bulkexecute.
------------ Example code -------------- bulkcall Detach(LuName, CaseId, KeyRef);
Bulkpin can only be called if placed inside a bulkexecute.
------------ Example code -------------- bulkpin(VoucherNoSerials, keyref);
Same as navigate but if multiple records are selected it changes the provided filter to fit all selected records.
Bulknavigate can only be called if placed inside a bulkexecute.
------------ Example code -------------- bulknavigate "page/AuditFileTaxInfo/Form?contexts=Company:$[Company]";
Same as set, but it sets the value to multiple records.
Call is used to invoke an action or function defined in the projection. An action and function are server calls defined by the developer to get data or to do things not possible in the command language.
------------ Example code --------------
command ReleaseCommand for MyEntity {
execute {
call Release();
}
}
Opens a modal message box with a message and two buttons OK and CANCEL. It is used for the user to continue with the script or not. The instruction returns either OK or CANCEL.
------------ Example code --------------
command ReleaseCommand for MyEntity {
execute {
confirm("Do you want to Release the record?") {
when CANCEL {
exit;
}
}
call Release();
}
}
Copies values from a structure to this (context object) or vice versa. It is common that the two objects do not have exactly the same attributes.
Copy only performs on attributes that exist in both places.
There is an option to not copy for null values (skip nulls).
This means that if an attribute to copy is null, then the attribute is skipped and the attribute to copy to is left as it is.
In contrast, when skip nulls is not present, the attributes with null values are copied to the destination attribute which will then be null also.
------------ Example code -------------- copy AmountStructure into this;------------- Example code ------------- copy AmountStructure into this; copy this into AmountStructure skip nulls;
Opens a dialog defined in the same client file. Dialogs always operate on structures so you normally send data in and out of it.
------------ Example code --------------
command ReleaseCommand for MyEntity {
variable Alias;
execute {
dialog MakeAliasDialog(Name) into Alias {
when OK {
call CreateAlias(Name, Alias);
}
}
}
}
Executes a download action and starts download of a file.
When specifying a file, the url needs to be specified as:
------------ Example code -------------- <projectionname>.svc/<entitysetname>(<keys>)/<fieldname>------------ Example code -------------- execute { download OriginalFileData from "FileTemplates(DocClass,LanguageCode,FormatSize)"; }
It is also possible to specify the url details directly.
------------ Example code --------------
execute {
download "FileTemplates(DocClass=$[DocClass],LanguageCode=$[LanguageCode],FormatSize=$[FormatSize])/OriginalFileData";
}
Same as success, but color (red) and icon indicates it is an error message.
------------ Example code --------------
error("There are no open periods exist in Accounting Periods.");
Breaks execution of the command and optionally returns a value. Exiting with CANCEL in general means aborting any further actions done by the framework.
------------ Example code -------------- command ReleaseCommand for MyEntity { variable Type; execute { call GetType() into Type; if [Type = "1"] { warning("Can't release this type."); exit; } call Release(); } }------------ Example code -------------- exit OK;
Temporary removes the selected records from a list or a selector. If the user performs a search or refreshes the list, then the records reappear again.
------------ Example code --------------
bulkcall StartCreateRebateCreditInvoice(AggregationNo, FinalSettlement, 500) {
when SUCCESS {
hideselection();
}
when FAIL {
error("${error.Message}");
}
}
Returns a url to the page which is set as the default page for the given entity.
If keyref is provided it also filters the page to only show that particular record.
------------ Example code --------------
execute {
homepage(LuName, KeyRef) into VarPageUrl;
navigate "${PageUrl}";
}
Evaluates an expression and executes a branch conditionally.
------------ Example code --------------
command MyCommand for MyEntity {
variable Alias;
execute {
if [Type = "Cancelled"] {
exit;
}
if [Type = "Normal"] {
call DoNormal();
}
else {
call DoOther();
}
}
}
Same as an if statement but it is applied to all selected records and returns true if at least one them satisfies the condition.
ifany can only be called if placed inside a bulkexecute.
------------ Example code --------------
ifany [CostSet = 1] {
alert("Rows with Cost Set 1 will not be Updated.");
}
Same as if statement but is applied to all selected records and returns only if all of them satisfies the condition.
ifall can only be called if placed inside a bulkexecute.
------------ Example code --------------
ifall [LedgerId != "00"] {
bulknavigate "page/VoucherRowsAnalysisHoldIl/List?$filter=Company eq Company and VoucherNo eq $[VoucherNo];
}
Same as success, but color (blue) and icon indicates it is an information message.
------------ Example code --------------
info("Voucher ${VoucherNumber} created.");
Opens a modal message box with a message and three buttons. It allows the user to either select one of two options (YES or NO), or do a rollback (Cancel).
------------ Example code --------------
inquire("Canceling this application for payment is an irreversible step. Do you want to continue?") {
when YES {
call Cancel();
}
}
Logs a text to the Debug windows in the application. Mainly used for debugging.
------------ Example code --------------
log("Techspecno: ${TechnicalSpecNo} tech class: ${TechnicalClass}");
Opens a modal message box with a message. Title, icon, text, number of preselected buttons and their text are set by the user.
Note! This is for complex choices, to help the user clearly see the consequences of their actions. For all other cases, use the standard message boxes alert, confirm and inquire.
------------ Example code --------------
messagebox("Set DM Sources Active", question, "This action will set the selected Data Mart sources as active. Do you want to continue?") {
when YES {
info("Set active action started");
call SetActiveFlag(SelectedSourcesList, true);
success("Set active action completed");
}
when NO {
info("Set active action was cancelled");
exit CANCEL;
}
Navigates to a page inside the application or to an external site. For internal destinations there is a simplified syntax to specify the destination.
------------ Example code --------------
command GoToProductDetailCmd for Product {
execute {
navigate ProductDetailPage(CatalogNo);
// Same as
navigate "page/CreateB2bShopCartOrder/ProductDetailPage?$filter=CatalogNo eq $[CatalogNo]";
// Not exactly the same as
navigate "page/CreateB2bShopCartOrder/ProductDetailPage?$filter=CatalogNo eq '${CatalogNo}'";
}
}
Note: When doing string interpolation in a URL you should generally use \$[Attribute] instead of \${Attribute}. The former correctly encodes any special characters, and adds quotes around the attribute when necessary. So for strings you don’t need to add the quotes yourself.
Pins record in an entityset. A pinned record is shown even if it does not satisfy current filter or search conditions. It is typically used when when there is a list which is filtered for a specific state. When changing state the record normally disappears from the list, but if the record is pinned it stays in the list. Pinned records are cleared when a new search is done on the page, or when navigating to a new page (exception is when a browser back is done, then pinned records are kept).
When pinning a record it is necessary to provide which entityset the record belongs to, the keyref of the record. All records have a keyref attribute which is automatically provided by the framework.
------------ Example code --------------
command StartWorkPersonCommand for JtExecutionInstancePerson {
label = "Start Work";
execute {
pin(JtTaskEntitySet, keyref);
call StartWork();
success("This action will start the assignment ${TaskSeq} - ${ExecutionInstanceSeq}.");
}
}
Opens the print dialog for printing archived reports.
------------ Example code --------------
execute {
call GetCaseTaskResultKey("CC_CASE_TASK_REP") into ResultKeyVar;
printdialog ResultKeyVar;
}
Selects a record on the page. This useful if you programmatically want to change the selection on the page to something else. Selecting is done by providing the selector or list on which you want to change the selection. The record is identified either by the keyref attribute which is provided on all records by the framework, or by creating your own keyref.
------------ Example code --------------
command AddRevision {
label = "New Revision...";
execute {
...
call GetNewKeyRef(DocClass, DocNo, DocSheet, DocRevNew) into NewKeyRef;
pin(DocIssueSet, NewKeyRef);
select(DocumentDetailSelector, NewKeyRef);
info("New Revision ${DocRevNew} is created.");
...
}
}
Sets a value to an attribute or variable.
------------ Example code --------------
command ReleaseCommand for MyEntity {
variable Name2;
execute {
set Name = "Acme";
set Name2 = Name;
}
}
Takes either the selected records in a list or all records in the list, and creates a string of it. The default format is a string with the keyref delimited with a separator (ASCII code 30).
The value for each record can be set with a string interpolation expression. The JSON option changes the output format of the string to a JSON array.
------------ Example code -------------- stringify(SelectMultiplePartList, keyref) into VarKeyrefs; stringify(records, StartDateTimeZone, JSON) into StartDaysVar;
Shows a toast message with color (green) and an icon that indicates a successful operation. The message is visible for a short period (around 5 seconds), and then closes itself.
------------ Example code --------------
command ReleaseCommand for MyEntity {
execute {
call Release();
success("Record was successfully released");
}
}
Executes an upload action and starts upload of a file.
When specifying a file, the url needs to be specified as:
------------ Example code -------------- <projectionname>.svc/<entitysetname>(<keys>)/<fieldname>------------ Example code -------------- execute { upload OriginalFileData to "FileTemplates(DocClass,LanguageCode,FormatSize)"; }
It is also possible to specify the url details directly.
------------ Example code --------------
execute {
upload "FileTemplates(DocClass=$[DocClass],LanguageCode=$[LanguageCode],FormatSize=$[FormatSize])/OriginalFileData";
}
Same as success, but color (yellow) and icon indicates it is a warning message.
------------ Example code --------------
warning("Entered Control Type does not exist or is not allowed.");