6. Designer Action Blocks

6. Designer Action Blocks

You are here:

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.

Add Header Label

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:

Form Opens

Example Output:

Android Emulator

Close Form

Use Close Form to close the application.

Close Form

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.

Form Opens

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.

Configure Fields

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.

Form Opens

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.

Display Mode

Block Configuration:

Option Description
Log Level The log level to create the entry for.

  • Trace
  • Debug
  • Info
  • Warn
  • Error
  • Fatal
Log Context Indicates if the context is logged as well. Entries are in the form of key/value pairs.

  • None (no context entries are made)
  • Fields (the current columns/fields are included)
  • All (all context entries are included: fields, configuration, custom variables, etc.)
Message The log entry message to create.

Create Log Entry Example

The Application Designer example below uses Create Log Entry:

Form Opens

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.

Display 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:

Android Emulator

Example of Card View:

Android Emulator

Display Mode Example

The Application Designer example below uses Display Mode:

Form Opens

Evaluate Regular Expression

Use Evaluate Regular Expression to evaluate text expressions and retrieve the results.

Form Opens

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

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.

Find First Line With

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:

Form Opens

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.

Find a Matching Line

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:

Scanned Item

Get Dataset

Use Get Dataset to retrieve a dataset from Business Central to use to populate the grid/card controls or interact with programmatically.

Find a Matching Line

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:

  • First: Only the first record in the result is returned.
  • Set: All records are returned.
  • Last: Only the last record in the result is returned.

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:

Find a Matching Line

Output: The first item returned is: 1001

Get Dataset Example 2

The Application Designer example below uses Get Dataset with an existing event:

Find a Matching Line

Output: 104012

Get Dataset Example 3

The Application Designer example below uses Get Dataset with an existing event to populate the data grid:

Find a Matching Line

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.

Find a Matching Line

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.

  • Default
  • Best (0-100 meters)
  • High (0-100 meters)
  • Medium (100-500 meters)
  • Low (500 meters)
  • Lowest (500 meters)
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:

Scanned Item

Output:

Scanned Item

Get Property

Use this block to access the property values of controls on the page.

Scanned Item

Block Configuration:

Option Description
Control Name The name of the control on the page. This is dependent on the generated page contents.

  • page
  • searchbar
  • page_header_layout
  • document_header_layout
  • document_header_frame
  • page_footer_layout
  • document_footer_frame
  • document_footer_layout
  • statusbar
  • landscape_factbox_container
  • portrait_factbox_container
  • grid
  • cardpanel
  • remaining_label
  • footer_label_0
  • footer_label_caption_0
  • footer_label_value_0
  • header_label_0
  • header_label_caption_0
  • header_label_value_0
  • document_header_label_0
  • document_header_label_caption_0
  • document_header_label_value_0
  • card_label_0
  • card_label_caption_0
  • card_label_value_0
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:

  • Text
  • Visible
  • BackgroundColor
Variable The variable to populate with the property value.

Get Property Example

The Application Designer example below uses Get Property:

Open Web

Set Property

Use the Set Property block to modify the property values of controls on the page.

Open Web

Block Configuration:

Option Description
Control Name The name of the control on the page. This is dependent on the generated page contents.

  • page
  • searchbar
  • page_header_layout
  • document_header_layout
  • document_header_frame
  • page_footer_layout
  • document_footer_frame
  • document_footer_layout
  • statusbar
  • landscape_factbox_container
  • portrait_factbox_container
  • grid
  • cardpanel
  • remaining_label
  • footer_label_0
  • footer_label_caption_0
  • footer_label_value_0
  • header_label_0
  • header_label_caption_0
  • header_label_value_0
  • document_header_label_0
  • document_header_label_caption_0
  • document_header_label_value_0
  • card_label_0
  • card_label_caption_0
  • card_label_value_0
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:

  • Text
  • Visible
  • BackgroundColor
Value The value to set the property to.

Set Property Example

The Application Designer example below uses Set Property:

Open Web

Open Web

Use Open Web to open a specified web page.

Open Web

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:

Form Opens

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.

Run Event

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:

Form Opens

Business Central Code:

Code

Example Output:

Android Emulator

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:

Run Event Set Table Field Value

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:

Form Opens

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.

Run Event Set Value

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:

Form Opens

Business Central Code:

Form Opens

Example Output:

Android Emulator

Run Intent

Use Run Intent to execute an Android Intent. This block is only usable by Android devices currently.

Run Intent

Block Configuration:

Option Description
Intent URI The Intent URI string to execute.

Examples:

  • tel:18664407543
  • geo:16.053200,108.20284?q=16.053200.108.20284
  • content://contacts/people/1
  • content://contacts/people
  • http://www.google.com
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:

  • android.intent.action.VIEW
  • android.intent.action.PICK

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:

Form Opens

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.

Scan Barcode

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:

Form Opens

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.

Set Status Bar

Block Configuration:

Option Description
Expression The message to display.

Set Status Bar Example

The Application Designer example below uses Set Status Bar:

Form Opens

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.

Set Title

Block Configuration:

Option Description
Expression The title to set for the page.

Set Title Example

The Application Designer example below uses Set Title:

Form Opens

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.

Show Remaining

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:

Android Emulator

Show Remaining Example

The Application Designer example below uses Show Remaining:

Form Opens

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.

Show Search Control

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:

Android Emulator

Show Search Control Example

The Application Designer example below uses Show Search Control.

Form Opens

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.

Start An 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.

Form Opens

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.

Start Event

Block Configuration:

Option Description
Event Name The custom event to execute.

Start Event Example

The Application Designer example below uses Start Event:

Form Opens

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

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

Form Opens

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

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.

Form Opens

Timer

Timer is used to execute an event after a specified period.

Stop License Plate

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:

Stop License Plate

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.

Update Data

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:

Form Opens

Business Central Code:

Code

PDA Columns:

PDA Columns

Example Output:

Android Emulator

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
  • Vibrate
  • Vibrate and Sound
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:

Was this article helpful?
0 out Of 5 Stars
5 Stars 0%
4 Stars 0%
3 Stars 0%
2 Stars 0%
1 Stars 0%
How can we improve this article?
Please submit the reason for your vote so that we can improve the article.
Need help?

Leave A Comment

Go to Top