6. Designer Action Blocks
The designer action blocks are used to facilitate process logic between elements. They do not typically show input/dialog controls to the user. Examples include:
- Initializing the application
- Sending and getting data from Business Central
- Triggering internal processes
The following table provides a summary of the available actions. Select an action or scroll down to see more details about each action.
| Block | Description |
| Add Header Label | Adds text to the top of an application. |
| Close Form | Closes the application. |
| Configure Fields | Initializes the application when working with document line data. |
| Create Log Entry | Creates log entries in the application log. |
| Display Mode | Controls whether records are displayed in a grid view (all records) or a card view (one record at a time). |
| Evaluate Regular Expression | Evaluates text expressions and retrieve the results. |
| Find First Line With | Finds and selects the first line with a specific value in the specified column. |
| Find a Matching Line | Finds and selects a line based on the scanned barcode. |
| Get Dataset | Populates the grid/card controls or interact with programmatically. |
| Get GEO Location | Retrieves information about the physical location of the device. |
| Get Property | Retrieves the property values of controls on the page. |
| Set Property | Modifies the property values of controls on the page. |
| Open Web | Opens a web page. |
| Run Event | Sends data to Business Central without expecting a dataset in response. |
| Run Event Set Table Field Value | Updates a table field without the need for custom code. |
| Run Event Set Value | Sends data to Business Central and populates the application variable with the response. |
| Run Intent | Executes an Android intent. |
| Scan Barcode | Simulates a barcode scan. |
| Set Status Bar | Adds text to the bottom status bar of the application. |
| Set Title | Sets the title of the application. |
| Show Remaining | Controls whether the top right corner of the page shows how many lines or how much quantity is remaining to be handled. |
| Show Search Control | Displays a search/filter option at the top of the page. |
| Start an Application | Launches the specified application. |
| Start Event | Executes a custom event within the current application. |
| Start License Plate | Triggers the “When a License Plate is Started” application event. |
| Stop License Plate | Triggers the “When a License Plate is Stopped” application event. |
| Timer | Executes a custom event within the current application after a specified delay. |
| Update Data | Retrieves header and line document data from Business Central. |
| Notification | Generates a sound or vibration. |
Add Header Label
Use Add Header Label to add instructions to the top of the application.
Block Configuration:
| Option | Description |
|---|---|
| Label | The label to put beside the value (e.g., Document #).
You can leave the label blank with only text being displayed. The label is bolded if displayed. |
| Text | The value to display (e.g., PO123456). |
Add Header Label Example
The Application Designer example below uses Add Header Label:
Example Output:
Close Form
Use Close Form to close the application.
Close Form Example
The Application Designer example below uses Close Form. This illustrates a common request to get some value from the user and the closes the screen. In a real application, you would call Business Central to do something with that result prior to closing the screen.
Configure Fields
Configure Fields is used to initialize the application when working with document line data. This block maps up the columns being returned by Business Central to the internal workings of the application and other assumed behaviors. Primary interactions are with Scan Behaviors and Find Line Templates.
For example, this allows Enter Quantity dialog to understand Scan Behavior option of Default to Line Quantity. Without this block, the application does not know which column to reference.
An error is thrown on the handhelds if this block has been forgotten and is required. Fields names must match those being returned by Business Central.
Block Configuration:
| Option | Description |
|---|---|
| Quantity to Handle Field | The field that the user would be updating quantity on. |
| Already Handled Field | The field that indicates any posted quantities. |
| Total Quantity Field | The field that indicates the original starting quantity. |
| Line No. Field | The unique identifier for the line (primary key). |
| Bin Code Field | The field that indicates the line’s bin code. |
| Shelf Field | The field that indicates the line’s shelf number. |
| Item No. Field | The field that indicates the line’s item number. |
| Variant Field | The field that indicates the line’s variant code. |
| Lot No. Field | The field that indicates the line’s lot number. |
| Serial No. Field | The field that indicates the line’s serial number. |
| Unit of Measure Field | The field that indicates the line’s unit of measure. |
| Expiry Date Field | The field that indicates the line’s expiry day. |
| Package No. Field | The field that indicates the line’s package number. |
Configure Fields Example
The Application Designer example below uses Configure Fields. The example users the PDA columns returned from the Sales Order (event 70000). Shelf, Lot, Serial, and Expiry fields are not required as they are not available on the sales line.
Create Log Entry
Use Create Log Entry to insert log statements. The log entries can later be viewed from the main landing page Show Log menu action. Log entries are created if the log level is equal or higher to the level specified in the configuration.
Block Configuration:
| Option | Description |
|---|---|
| Log Level | The log level to create the entry for.
|
| Log Context | Indicates if the context is logged as well. Entries are in the form of key/value pairs.
|
| Message | The log entry message to create. |
Create Log Entry Example
The Application Designer example below uses Create Log Entry:
Display Mode
Use Display Mode to control whether a data grid view (all lines) displays to the user or if the records display one at a time in a card panel. If this block is not encountered when data is being loaded, then the application defaults to displaying in grid view mode.
Block Configuration:
| Option | Description |
|---|---|
| Mode | Select Grid View to view data in grid view.
Select Card View to display lines one record at a time in a panel. |
| Auto Advance | Applicable only to Card View. Specify True if you want the panel to advance to the next record if the current line quantity is finished being handled. Specify False if users must manually use the next button to advance. |
| Find Line | Applicable only to Card View. Specify True if panels can be found using Find Matching Line (e.g., scan an item and have it find an appropriate panel). Specify False if the user must manually navigate to the records required. |
Example of Grid View:
Example of Card View:
Display Mode Example
The Application Designer example below uses Display Mode:
Evaluate Regular Expression
Use Evaluate Regular Expression to evaluate text expressions and retrieve the results.
Block configuration:
| Option | Description |
| Case Sensitivity | False if the matches should ignore case. True if it should consider case. |
| Input String | The text to evaluate. |
| Regular Expression | The regular expression to use to evaluate the text against. |
After execution the following variables are set:
- regex_result: True if the expression is a match; False if not.
- regex_result.”MatchNumber”: Results of the expression matching. “MatchNumber” is replaced by the match’s number (e.g., regex_result.1, regex_result.2, regex_result.3).
Evaluate Regular Expression Example
The Application Designer example below uses Evaluate Regular Expression:
Find First Line With
Find First Line With can be used when you are display a data grid (or card panel) to find the first line that has a specific value in the specified column. If a match is found, the line (or panel) is selected.
Block Configuration:
| Option | Description |
|---|---|
| Column Name | The name of the column to find the value in. |
| Value to Look For | The value to try and find. |
After execution, the following variables are set:
- Found: True if the record is found; False if not found.
Find First Line With Example
The Application Designer example below uses Find First Line With:
Find a Matching Line
Use Find a Matching Line to find/select a line based on the barcodes scanned. This block requires a Configure Fields to be defined and utilizes Find Line Templates defined in Business Central.
After execution, the following variables are set:
- Found: True if a matching line found; False if no matching line found.
Find a Matching Line Example
The Application Designer example below uses Find a Matching Line:
Get Dataset
Use Get Dataset to retrieve a dataset from Business Central to use to populate the grid/card controls or interact with programmatically.
Block Configuration:
| Option | Description | Example |
| Table Number | The table to retrieve the records from.
This property is not applicable if using the Event ID property. |
27 (Item) |
| Table Filter | The filter to apply to the table results.
This property is not applicable if using the Event ID property. |
WHERE (No.=FILTER(*1)) |
| Table Fields | A comma separated list of fields to return.
This property is not applicable if using the Event ID property. |
No.,Description |
| Find | Indicates the record(s) to be returned.
Options are:
This property is not applicable if using the Event ID property. |
|
| Dataset Name | The name of the dataset to use when interacting with the results. | ItemDataset |
| Event ID | A Business Central event to be executed instead of specifying the generic table information. | 50001 |
After execution the following variables are set:
- DatasetName.Count: The number of rows returned.
- DatasetName_RowNumber.FieldName: The row and field value (e.g., ItemDataset_4_Description, ItemDataset_1_No.).
Get Dataset Example 1
The Application Designer example below uses Get Dataset with a generic table query:
Output: The first item returned is: 1001
Get Dataset Example 2
The Application Designer example below uses Get Dataset with an existing event:
Output: 104012
Get Dataset Example 3
The Application Designer example below uses Get Dataset with an existing event to populate the data grid:
Output:
| No. |
| 104012 |
| 104004 |
| 104005 |
| 104006 |
| 104007 |
| 104008 |
| 104009 |
| 104010 |
| 104011 |
Get GEO Location
Use Get GEO Location to retrieve information about the device’s physical location.
Block Configuration:
| Option | Description |
|---|---|
| Use Last Known | True if the location is based off the device’s last cached location. It may be faster to use the cache instance than forcing the device to re-query for the current location but may be less accurate. |
| Accuracy | The accuracy to fetch the location to.
|
| Timeout (seconds) | The time to wait for a query to return. Default 30 seconds. |
After execution, the following variables are set:
- geo_latitude: The latitude.
- geo_longitude: The longitude.
- geo_altitude: The altitude in meters. May not be available on all devices.
- geo_accuracy: The accuracy that was used for the locations.
- geo_mockprovider: True if a mock provider was used to get the location.
Get GEO Location Example
The Application Designer example below uses Get GEO Location:
Output:
Get Property
Use this block to access the property values of controls on the page.
Block Configuration:
| Option | Description |
| Control Name | The name of the control on the page. This is dependent on the generated page contents.
|
| Property Name | The name of the property. This is dependent on the control being accessed. Only simple properties may be accessed and used.
For example:
|
| Variable | The variable to populate with the property value. |
Get Property Example
The Application Designer example below uses Get Property:
Set Property
Use the Set Property block to modify the property values of controls on the page.
Block Configuration:
| Option | Description |
| Control Name | The name of the control on the page. This is dependent on the generated page contents.
|
| Property Name | The name of the property. This is dependent on the control being accessed. Only simple properties may be accessed and used.
For example:
|
| Value | The value to set the property to. |
Set Property Example
The Application Designer example below uses Set Property:
Open Web
Use Open Web to open a specified web page.
Block Configuration:
| Option | Description |
|---|---|
| URL | The URL to open. Must be fully specified (e.g., include the http). |
Open Web Example
The Application Designer example below uses Open Web:
Run Event
Use Run Event to send data to Business Central when you do not expect a dataset in response. Any errors or message returned from Business Central is displayed. If an error is thrown, no further processing occurs.
Block Configuration:
| Option | Description |
|---|---|
| Event ID | The Business Central event to call. All context params are sent to Business Central as part of the request. |
Run Event Example
The Application Designer example below uses Run Event:
Business Central Code:
Example Output:
Run Event Set Table Field Value
Run Event Set Table Field Value can be used to update a table field without the need to write custom code:
Block Configuration:
| Option | Description |
|---|---|
| Table Number | The ID of the table being modified. |
| Field Name | The name of the field being modified. |
| Filter Fields | A comma-separated list of fields that is used to filter the table.
The Filter Fields must be defined as variables prior to block execution and the filter values set accordingly. |
Run Event Set Table Field Value Example
The Application Designer example below uses Run Event Set Table Field Value:
This example illustrates updating the Warehouse Receipt Line (ID: 7317) Qty. to Receive with a value of 5. The table filters are set for: No.: RE000051 and Line No.: 10000.
Run Event Set Value
Use Run Event Set Value to call Business Central and populate the application variable with the response.
Block Configuration:
| Option | Description |
|---|---|
| Event ID | The Business Central event to call. All context params are sent to Business Central as part of the request. |
| Variable | The variable to populate with the result. |
Run Event Set Value Example
The Application Designer example below uses Run Event Set Value:
Business Central Code:
Example Output:
Run Intent
Use Run Intent to execute an Android Intent. This block is only usable by Android devices currently.
Block Configuration:
| Option | Description |
| Intent URI | The Intent URI string to execute.
Examples:
|
| Extra Data | Any additional data required for the Intent. Value is a comma-separated list of key value pairs.
Example: firstname=John,lastname=Doe The fields are passed via the Intent Extra properties. This can be left blank if no additional data required. |
| Intent Action | The Intent action.
Examples:
Default if left blank is “android.intent.action.VIEW”. |
| Intent Category | The Intent category.
This can be left blank if no category is required. |
| Package | The package you wish to run the intent on (explicit intent).
This can be left blank if executing an implicit intent (e.g., accepting any application that can respond to the intent). |
| Class | The class name in the package you are running the intent on.
This can be left blank if executing an implicit intent. |
| Wait For Result | True if the Intent will be returning data. False if not.
Default value is False. |
After execution the following variables are set:
- intent_result: “OK” if the Intent completed successfully.
- intent_uri: The data URI returned from the Intent. Applicable if “Wait for Result” was set to true.
- Each extra data returned from the Intent is added with the following format (applicable if “Wait for Result” was set to true):
- “intent_”
- Example: “intent_weight”
- Any rows/columns returned from resolving the data URI are added as with the following format (applicable if “Wait for Result” was set to true):
- “intent_row_”
- Example: “intent_row0_weight”
- intent_error: Contains the error message if the Intent was canceled or failed.
Run Intent Example
The Application Designer example below uses Run Intent:
Scan Barcode
Use Scan Barcode to simulate a barcode scan. The scan is processed exactly as if it had been scanned on the device by the user, including firing events back into your application.
Block Configuration:
| Option | Description |
|---|---|
| Barcode | The barcode to scan. This needs to include any prefix information as well (e.g., %LP%LP123456). |
Scan Barcode Example
The Application Designer example below uses Scan Barcode:
Set Status Bar
Use Set Status Bar to populate a message in the bottom status bar of the application. The status bar text persists until overwritten with another message or cleared.
Block Configuration:
| Option | Description |
|---|---|
| Expression | The message to display. |
Set Status Bar Example
The Application Designer example below uses Set Status Bar:
Set Title
Use Set Title to set the title of the Application. If this block is not present, the title is the Business Central-defined Application code.
Block Configuration:
| Option | Description |
|---|---|
| Expression | The title to set for the page. |
Set Title Example
The Application Designer example below uses Set Title:
Show Remaining
Show Remaining controls whether the top right corner of page shows how many lines or how much quantity is remaining to be handled. This control is designed to be used when displaying document type data (grid or panel) as Configure Fields requires to be set.
Block Configuration:
| Option | Description |
|---|---|
| Mode | Selecting Quantities displays a sum of the remaining quantity to handle from all lines. The label shown is Open Qty: xxx.
Selecting Lines displays a count of all the lines that having remaining quantity to handle. The label shown is Open Lines: xxx. |
When executed, users see a label like this:
Show Remaining Example
The Application Designer example below uses Show Remaining:
Show Search Control
Use Search Control to display a search/filter option at the top of the application page. This is used for lookup type list pages.
When the search control loses focus, When Loading Document Data event fires, and a context variable called filter is added containing the current search text.
When executed, users see a something like this:
Show Search Control Example
The Application Designer example below uses Show Search Control.
Start an Application
Use Start an Application to launch another custom application. When the new application is launched, the current context is passed to the new application.
Block Configuration:
| Option | Description |
|---|---|
| Application Name | The application name to launch. |
Start an Application Example
The Application Designer example below uses Start an Application. The example displays a list of items and waits for the user to scan an Item barcode. ITEM_DETAILS application is not illustrated here but takes the scanned barcode data and populates the results accordingly.
Start Event
Use Start Event to execute a Custom Event defined in the application. Execution of the current sequence resumes once the custom event has completed.
Block Configuration:
| Option | Description |
|---|---|
| Event Name | The custom event to execute. |
Start Event Example
The Application Designer example below uses Start Event:
Start License Plate
Start License Plate triggers the Start License Plating action. Internally, this toggles any menus that have LP Create standard action to say Stop License Plating. The application event When a License Plate is Started is raised and can be processed further.
Start License Plate Example
The Application Designer example below uses Start License Plate. This example responds to a License Plate scan and if there are no lines on the License Plate (blank), treats it as if they were starting it (packing/loading).
Stop License Plate
Stop License Plate triggers the Stop License Plating action. Internally, this toggles any menus that have LP Create standard action to say Start License Plating. The application event When a License Plate is Stopped is raised and can be processed further.
Stop License Plate Example
The Application Designer example below uses Stop License Plate. This example responds to a license plate scan, and if there is an active License Plate, triggers the Stop License Plate event, which asks to print out a label.
Timer
Timer is used to execute an event after a specified period.
Block Configuration:
| Option | Description |
|---|---|
| Event Name | The name of the custom event to call when the timer triggers. |
| Interval (seconds) | The number of seconds to wait before calling the event. Default 30 seconds. |
| Run When Hidden | True if the event should fire even if the page is currently not visible (e.g., if there is a quantity dialog on top). If false and the timer triggers while the page is hidden, the timer resets and fires again at the next interval. |
Timer Example
The Application Designer example below uses Timer:
Update Data
Update Data is used to retrieve header/line document data from Business Central. If there is a grid/panel present on the page, it causes the grid/panel to be populated/updated.
Block Configuration:
| Option | Description |
|---|---|
| Event ID | The Business Central event to call to get the data from. All context params are sent to Business Central as part of the request. |
| Mode _ Data | Selecting Replace Entire causes the entire grid/panel dataset to be cleared and repopulated. Use this option if first loading or the result being returned is the full data. Dataset must include the header data as well if applicable.
Selecting Update Existing causes the lines returned in the line dataset to be Updated. This uses Configure Fields Line No. configuration to determine line matches. If the line cannot be found, it is inserted/created. |
Update Data Example
The Application Designer example below uses Update Data to retrieve item (header) and bin content (line) information:
Business Central Code:
PDA Columns:
Example Output:
Notification
Use the Notification block to generate a sound or vibration.
Block Configuration:
| Option | Description |
| Notification | The type of notification to generate.
Options are:
|
| Sound Title | The name of the sound to play. The title must match an existing sound notification on the device. |
Notification Example
The Application Designer example below uses Notification:
