Skip to content

Command

This document is still under construction. The completed version will be available in IFS Applications 10 Update 6.* *

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.

Command example

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.

Variations

None.

When to use

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.

How to use

Add the command control instead of a regular field, on a page, list, menu etc.


list <list_name> {  
    ...  
    command <command_name> {  
        ...  
    }  
}  

Limitations

None.

Properties

Below is a list of properties that can be used to customize the control.

execute/bulkexecute | emphasis | enabled | icon | label | mode | style | variable | visible

Example

[Comment]: The example code and figure below will be updated to reflect an example of a command.

Below is an example of how a command is used to represent...

Command example

Figure 2 - Command representing... (Show an image of a command)


list DriversList for F1Driver {  
   label = "F1 Drivers";  

   field Id;  
   field Name;  
   field Seasons;  
   field Championships;  
   field Entries;  
   field Starts;  
   field Wins;  
   field Points;  
   field Age;  
   field Birthday;  
   badge Country {  
      emphasis Complementary5 = [Country = "Sweden"];  
      emphasis Complementary6 = [Country = "Spain"];  
      emphasis Complementary7 = [Country = "Germany"];  
      emphasis Complementary8 = [Country = "Italy"];  
      emphasis Complementary9 = [Country = "Brazil"];  
      icon = "home";  
   }  

   badge TeamType {  
      emphasis Complementary1 = [TeamType = "Manufacturer"];  
      emphasis Complementary2 = [TeamType = "Private"];  
      emphasis Complementary3 = [TeamType = "Other"];  
      icon = "star";  
      visible = [TeamType != null];  
   }  

   fieldranking Name, Country, Points, Wins, Starts, TeamType;  
   command GotoDetail;  
}  

Example 1 - Command representing....(give a code example of Command)

Command instructions

This section describes the instructions that can be used in a command.

agentcall


execute {  
   agentenabled into VarAgentEnabled;  
   if[VarAgentEnabled = "TRUE"] {  
         agentcall GetLocalProperty("Document Management/Settings", "FileSettings") into UserSettingsType;  
   }  
}  

agentenabled


execute {  
   agentenabled into VarAgentEnabled;  
   if[VarAgentEnabled = "TRUE"] {  
         agentcall GetLocalProperty("Document Management/Settings", "FileSettings") into UserSettingsType;  
      }  
   }  

alert

Opens a modal message box with a message and an OK button.


alert("Base values updated for ${UpdatedEmployeeCountVar} employees.");  

assistant


assistant NotesAssistant(PackageNameStr, CallingProjectionNameStr, keyref, luname, "") into(NoteIdNum) {  
         when OK {  
            exit;  
         }  
      }  

bulkcall

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.


bulkcall Detach(LuName, CaseId, KeyRef);  

bulkpin

Bulkpin can only be called if placed inside a bulkexecute.


bulkpin(VoucherNoSerials, keyref);  

bulknavigate

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.


bulknavigate "page/AuditFileTaxInfo/Form?contexts=Company:$[Company]";  

bulkset

call

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.


command ReleaseCommand for MyEntity {  
   execute {  
      call Release();  
   }  
}  

confirm

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.


command ReleaseCommand for MyEntity {  
   execute {  
      confirm("Do you want to Release the record?") {  
         when CANCEL {  
            exit;  
         }  
      }  
      call Release();  
   }  
}  

copy


copy AmountStructure into this;  

dialog

Opens a dialog defined in the same client file. Dialogs always operate on structures so you normally send data in and out of it.


command ReleaseCommand for MyEntity {  
   variable Alias;  
   execute {  
      dialog MakeAliasDialog(Name) into Alias {  
         when OK {  
            call CreateAlias(Name, Alias);  
         }  
      }  
   }  
}  

download

Executes a download action and starts download of a file.

When specifying a file, the url needs to be specified as:


<projectionname>.svc/<entitysetname>(<keys>)/<fieldname>  


execute {  
   download OriginalFileData from   
   "FileTemplates(DocClass,LanguageCode,FormatSize)";  
}  

It is also possible to specify the url details directly.


execute {  
   download "FileTemplates(DocClass=$[DocClass],LanguageCode=$[LanguageCode],FormatSize=$[FormatSize])/OriginalFileData";  
}  

error

Same as success, but color (red) and icon indicates it is an error message.


error("There are no open periods exist in Accounting Periods.");  

exit

Breaks execution of the command and optionally returns a value. Exiting with CANCEL in general means aborting any further actions done by the framework.


command ReleaseCommand for MyEntity {  
   variable Type;  
   execute {  
      call GetType() into Type;  
      if [Type = "1"] {  
         warning("Can't release this type.");  
         exit;  
      }  
      call Release();  
   }  
}  


exit OK;  

hideselection


    bulkcall StartCreateRebateCreditInvoice(AggregationNo, FinalSettlement, 500) {  
       when SUCCESS {  
          hideselection();  
       }  
       when FAIL {  
          error("${error.Message}");  
       }  
    }  

homepage


execute {  
      homepage(LuName, KeyRef) into VarPageUrl;  
      navigate "${PageUrl}";  
   }  

if

Evaluates an expression and executes a branch conditionally.


command MyCommand for MyEntity {  
   variable Alias;  
   execute {  
      if [Type = "Cancelled"] {  
         exit;  
      }  
      if [Type = "Normal"] {  
         call DoNormal();  
      }  
      else {  
         call DoOther();  
      }  
   }  
}  

ifany

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.


ifany [CostSet = 1] {  
       alert("Rows with Cost Set 1 will not be Updated.");  
    }  

ifall

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.


ifall [LedgerId != "00"] {  
       bulknavigate "page/VoucherRowsAnalysisHoldIl/List?$filter=Company eq Company and VoucherNo eq $[VoucherNo];  
    }  

info

Same as success, but color (blue) and icon indicates it is an information message.


info("Voucher ${VoucherNumber} created.");  

inquire

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 ).


inquire("Canceling this application for payment is an irreversible step. Do you want to continue?") {  
        when YES {  
           call Cancel();  
        }  
    }  

log


log("Techspecno: ${TechnicalSpecNo} tech class: ${TechnicalClass}");  

messagebox

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.


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.


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.

pin

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.


command StartWorkPersonCommand for JtExecutionInstancePerson {  
   label = "Start Work";  
   execute {  
      pin(JtTaskEntitySet, keyref);  
      call StartWork();  
      success("This action will start the assignment ${TaskSeq} - ${ExecutionInstanceSeq}.");  
   }  
}  

printdialog


execute {  
        call GetCaseTaskResultKey("CC_CASE_TASK_REP") into ResultKeyVar;  
        printdialog ResultKeyVar;  
    }  

select

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.


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.");  
            ...  
   }  
}  

set

Sets a value to an attribute or variable.


command ReleaseCommand for MyEntity {   
   variable Name2;  
   execute {  
      set Name = "Acme";  
      set Name2 = Name;  
   }  
}  

stringify


stringify(SelectMultiplePartList, keyref) into VarKeyrefs;  
stringify(records, StartDateTimeZone, JSON) into StartDaysVar;  

success

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.


command ReleaseCommand for MyEntity {  
   execute {  
      call Release();  
      success("Record was successfully released");  
   }  
}  

upload

Executes an upload action and starts upload of a file.

When specifying a file, the url needs to be specified as:


<projectionname>.svc/<entitysetname>(<keys>)/<fieldname>  


execute {  
   upload OriginalFileData to   
   "FileTemplates(DocClass,LanguageCode,FormatSize)";  
}  

It is also possible to specify the url details directly.


execute {  
   upload "FileTemplates(DocClass=$[DocClass],LanguageCode=$[LanguageCode],FormatSize=$[FormatSize])/OriginalFileData";  
}  

warning

Same as success, but color (yellow) and icon indicates it is a warning message.


warning("Entered Control Type does not exist or is not allowed.");  

signdocument

Triggers electronic signature flow.

execute {  
   signdocument into <VariableRef> {
     keyref = <DataitemReference>;
     luname = <DataitemReference>;
     documenttype = pdf;
   }
}


Note! keyref/luname parameters are optional.

Read more on IFS Signature Service.