Built-In Actions

VB Studio provides a set of built-in actions that you use to create your action chain. If an action you need isn't available in the Actions palette, use the Code action to add your own block of code, or if a future need warrants it, create a custom action that can be reused.

Description of the illustration jsac-built-actions-palette.jpg

Each action performs a specific function and requires you to set different properties. For example, when you add the Call REST action to your action chain, you need to specify the endpoint and other details about the response to the Call REST action. Similarly, when you add a Navigate To Page action, you'll need to select a page to navigate to:

Description of the illustration jsac-navigate-action-editor.jpg

You can add an action in one of three ways, depending on your preference and where you want it added:

• Drag and drop the action from the Actions palette onto the bottom edge of the action it's to follow, or onto the top edge of the action it's to precede.
  
  
  Description of the illustration jsac-add-or-action.png
  
  
• Double-click the action in the Actions palette to add it to an empty canvas or to the end of an action chain.
• Select the action on the canvas that you want the new action to follow, then double-click the new action in the Actions palette.

If you need more details about an action than are provided in this section, refer to the JavaScript Actions section in the Oracle Visual Builder Page Model Reference.

Add an Assign Variable Action

You use an Assign Variable action to assign a local, page, flow, or application variable a value. This action can also be used to create a local variable.

For example, if your action chain sends a request to a GET endpoint, you can use the Assign Variable action to map the response to a page variable that's bound to a page component. Or, suppose you want to capture the ID of an item selected in a list. You could use a Selection event to start an action chain that assigns the selected item’s ID to a variable.

To use an Assign Variable action to create a local variable:

1. For Variable, enter its name and hit Enter on your keyboard.
2. For Type, select its data type.
3. If necessary, use the Value field to assign it a value.
   
   
   Description of the illustration jsac-assign-new-local-var.png
   
   

To use an Assign Variable action for a value assignment:

1. Add the action in one of three ways, as explained at the end of Built-In Actions.
2. If you need to create a variable for the assignment, click the Variable property's Create link, otherwise, start to type the variable's name in the field and select it when it appears. You could also select the variable from the list.
3. To set the variable's value, hover over the far-right side of the Value property and click to choose the variable that holds the value, or click fx to create an expression for the value.

   In this example, the page variable fullName is assigned the result from a module function:
   
   Description of the illustration jsac-assign-variables-action.jpg
   

If you need to do another assignment, click the + Assign Variable button in the Properties pane:

Description of the illustration jsac-assign-another-var.png

Then make the assignment using the Variable and Value fields that appear for the new variable assignment:

Description of the illustration jsac-assign-another-var2.png

If you'd like to move a variable assignment to a different position, in the Properties pane, click and hold an assignment, then move it to its new position.

Use Filter Builder to Create Filter Criteria for an SDP

If you're using an SDP to provide a table or list's data, and you'd like to filter out rows, you can use the Assign Variable action to create and assign the filter criteria to the SDP's filterCriterion property. For further details about using an SDP to filter a table or list's rows, see Filter Data by Filter Criteria.

When the Assign Variable action's Variable property is set to an SDP's filterCriterion property, the Filter Builder appears under the Variable property for you to create the filter criterion. To directly work with the code, click the Code button. For details, see Filter Builder's Code Editor.

Description of the illustration jsac-assign-action-pick-sdp.png

To use the Assign Variable action's Filter Builder to create the filter criterion for an SDP:

1. Click the Filter Builder's Click to add condition link:
   
   
   Description of the illustration jsac-assign-action-filter-builder-link.png
   
   
2. For the first Attribute textbox, enter the name of the column (field in record, like "city") that you want compared against a specific value (like "Tokyo").
3. For the Operator list, select the operator for the criterion.
4. For the second Attribute textbox, enter the specific value to compare against, or select the variable that contains the value. For instance, the value could be stored by a page variable that was bound to an Input Text component for a user to enter the value.
   
   
   Description of the illustration jsac-assign-action-filter-builder.png
   
   
5. To add another condition, click the Add Condition link to add one with an AND or OR operator, or click the Add Group link to add a group of conditions that are to be evaluated together (conditions enclosed in brackets). To combine conditional expressions with the AND operator, select Match All, and to combine them with the OR operator, select Match Any:
   
   
   Description of the illustration jsac-assign-action-filter-builder-conditions.png
   
   
6. Click Done when you're finished.

Filter Builder's Code Editor

You can use the Filter Builder's Code tab to view and edit the filter's code. After defining a condition on the Builder tab, you will see that the Code tab contains an attribute, op and value property.

Here's an example of a filter with two conditions combined by an AND operator:

{
 "op": "$and",
 "criteria": [
  {
   "op": "$eq",
   "attribute": "name",
   "value": "{{ $page.variables.filterVar }}"
  },
  {
   "op": "$eq",
   "attribute": "id",
   "value": "{{ $page.variables.idVar }}"
  }
 ]
}

In this example:

• The Oracle JET operator is "$eq" (it must include the dollar sign (“$”)).
• The attribute property is set to the name of the field (column) that you want to be evaluated against the value property.
• The value property ($page.variables.customerListSDP.filterCriterion.criteria[0].value) is mapped to a page variable ($page.variables.filterVar) that holds the value to be evaluated against each field (column) value.

Add a Call Action Chain Action

You add a Call Action Chain action to start an action chain. This action can call action chains defined in the same page, flow, or App UI.

Note:

Using this JavaScript action, you can call a JSON action chain, however, you can't call a JavaScript action chain from a JSON action chain.

For API information about this action, see Call Action Chain in the Oracle Visual Builder Page Model Reference.

To use a Call Action Chain action:

1. Add the action in one of three ways, as explained at the end of Built-In Actions.
2. Select an existing action chain from the Action Chain ID list, or click Create to create a new action chain.

   The dialog lets you choose between a new JavaScript or JSON action chain, and has a list for you to choose the action chain's scope (page, flow, or application). Depending on where you are creating the action chain, the list might have entries for action chains defined in the page, in the current flow, or in the App UI. If you're creating an action chain in a flow, you can only select other action chains defined in the same flow or in the current App UI, and you won't see an entry for page level action chains.
   
   Description of the illustration jsac-create-action-chain-popup.jpg
   

3. If the called action chain requires input parameters, the input parameters will be listed under the Parameters section of the Properties pane. For each input parameter, hover over the far-right side of the parameter and click to choose its source. If you need to create a variable, use the appropriate Create link in the Variables dialogue to create it at the appropriate scope level.
   
   
   Description of the illustration jsac-create-variable-assigner.jpg
   
   

   If a value is returned by the action, it is assigned to the auto-generated variable shown by the Store Result In property.

   Here's an example of a completed Call Action Chain action with specified input parameters:
   
   Description of the illustration jsac-call-action-chain-action-example.jpg
   

Add a Call Component Action

You add a Call Component action to call a method on a component.

For API information about this action, see Call Component Method in the Oracle Visual Builder Page Model Reference.

To use a Call Component action:

1. Add the action in one of three ways, as explained at the end of Built-In Actions.
2. In the Properties pane, select the component name from the Selector list, which is only populated with components that have their ID properties specified.

   For example, if your page contains three buttons whose IDs are Create, Update, and Save, you'll see those options available for selection in the list.

3. With the component selected, select or enter the Method Name to call:
   
   
   Description of the illustration jsac-call-component-action-example.jpg
   
   
4. If the method requires input parameters, hover over the far-right side of the parameters under the Parameters section and click to choose their source.

If a value is returned by the action, it is assigned to the auto-generated variable shown by the Store Result In property.

Add a Call Function Action

You add a Call Function action to call a function defined for the current page, flow, or App UI, and you can also call a global function. For more about global functions, see Add JavaScript Modules As Global Functions. Functions for a page, flow and App UI are created using their JavaScript editor.

For API information about this action, see Call Function in the Oracle Visual Builder Page Model Reference.

To use a Call Function action:

1. Add the action in one of three ways, as explained at the end of Built-In Actions.
2. In the Properties pane, select an existing function from the Function Name list, or click Create to create a new function. You can select or create a function that is defined for the current page, flow, or App UI.
3. If you want to view or modify the function's code, click Go to Module Function to go to the JavaScript editor to do so.
4. If the function requires input parameters, they'll be listed under the Parameters section of the Properties pane. For each input parameter, hover over the far-right side of the parameter and click to choose the variable that holds the value, or click fx to create an expression for the value. If you need to create a variable, use the appropriate Create link in the Variables dialogue to create it at the appropriate scope level.
   
   
   Description of the illustration jsac-create-variable-assigner.jpg
   
   

   Here's an example of a Call Function action, with its input parameter, arg1, needing specification:
   
   Description of the illustration jsac-call-function-action-example.jpg
   

If a value is returned by the action, it is assigned to the auto-generated variable shown by the Store Result In property.

Add a Call REST Action

A Call REST action is used to call a REST API endpoint to create, update, delete or display records.

For API information about this action, including details about error handling and its return object, see Call REST in the Oracle Visual Builder Page Model Reference.

After you add a Call REST action, you need to specify the endpoint for the request. Depending on the endpoint, you might also need to provide input parameters, such as an ID to identify a record.

This table lists the parameters that you typically need to provide for a Call REST action, for each type of endpoint. For a code example of a call to each endpoint type, see Call REST in the Oracle Visual Builder Page Model Reference. Regarding the action's returned result, it's assigned to the automatically generated variable set for the Store Result In property.

Type of Endpoint	Use	Typical Requirements
POST	Add a new record.	Provide the new record: In the Parameters section of the Properties pane, assign the variable containing the data to the body property. Provide endpoint's input parameters, if any: If the endpoint requires input parameters, use the Input Parameters section in the Properties pane to provide the required input parameters. Required input parameters are marked with an asterisk.
GET	Get one or many records.	To get single record, provide the record's ID: In the Input Parameters section of the Properties pane, provide the record's ID using the input parameter for the record's ID.
DELETE	Delete a record.	Provide the record's ID: In the Input Parameters section of the Properties pane, provide the record's ID using the input parameter for the record's ID.
PATCH	Update a record.	Provide the updated data: In the Parameters section of the Properties pane, assign the variable containing the updated data to the body property. Provide the record's ID: In the Input Parameters section of the Properties pane, provide the record's ID using the input parameter for the record's ID.

To use a Call REST endpoint:

1. Add the action in one of three ways, as explained at the end of Built-In Actions.
   
   
   Description of the illustration jsac-call-rest-action-example-blank.jpg
   
   
2. Click Select beside Endpoint in the Properties pane.

   The Select Endpoint window displays a list of endpoints that are available in your application. Each business object and service usually exposes multiple endpoints, each one for a different purpose. For instance, you can have an endpoint for getting multiple records, one for getting a single record, one for updating a record, and one for deleting a record. Each endpoint has different properties that you need to specify. For instance, for an endpoint that retrieves a single record, the record's ID must be provided.
   
   Description of the illustration action-chain-editor-selectendpoint-dialog-appui.png
   

3. Select an endpoint from the list and click Select.
   The properties for the REST call are displayed in the Properties pane, with required properties marked with an asterisk (*):
   

   
   Description of the illustration jsac-call-rest-action-parameters-app-ui.jpg

   
   
4. If the REST call requires header or input parameters, click the associated Assign or Not Mapped link and use the assignment window to specify the value for the property. Click Save.

   You map variables to parameters in the assignment window by dragging the variable in the Sources pane onto the parameter in the Target pane. In some cases, you might need to make multiple mappings. To delete a line mapping a variable to a parameter, right-click the line and select Delete. You can also select a parameter in the Target pane to view and edit the expression for its assignment in the lower pane.
   
   Description of the illustration action-chain-map-inputparameters.png
   

   If a suitable variable does not exist, use the + icon beside the relevant node (Action Chain, Page, and so on) to create a new variable.

5. Specify any other properties that may be required for the REST call.
6. To handle a REST call error, drag the first action to take if an error occurred onto the Create Error Handle area that appears at the bottom of the Call REST card on the canvas:
   
   
   Description of the illustration jsac-call-rest-create-error-handler.png
   
   The dropped action is added in an If condition that checks if an error occurred during the REST call. Configure the action in the Properties pane and add any other required actions to the condition.
   
   
   Description of the illustration jsac-call-rest-create-error-handler-done.png
   
   

The object returned by the Call REST action is automatically named and shown by the Store Result In property.

If the underlying REST API request returns a status code, the error object is returned for you to handle the error yourself, otherwise an auto-generated error notification is shown.

Add a Call Variable Action

You add a Call Variable action to an action chain to call a method on an InstanceFactory variable defined for the current scope (flow, page, or App UI). Using this action with any other type results in an error.

You can call any method on the current instance associated with the InstanceFactory variable, including asynchronous ones. However, since actions are by design synchronous, this action will wait for the asynchronous call to resolve before proceeding to the next action in the chain.

Before you use a Call Variable action, make sure an InstanceFactory type variable is already defined for the App UI. See Create a Type From Code.

For API information about this action, see Call Variable in the Oracle Visual Builder Page Model Reference.

To use a Call Variable action:

1. Add the action in one of three ways, as explained at the end of Built-In Actions.
2. From the Variable list, select an InstanceFactory type variable defined for the App UI.
3. For the Method list, select the method you want to call. The available methods are based on the definition file imported for the type.
   
   

   
   Description of the illustration jsac-call-variable-action-example.jpg

   
   
4. If the method requires input parameters, hover over the far-right side of a parameter and click to choose the value, or click fx to create an expression for the value.

   If the method returns a value, it is assigned to the auto-generated variable shown by the Store Result In property in the Properties pane.

Add a Code Action

You use a Code action to add JavaScript code to an action chain.

To use a Code action:

1. Add the action in one of three ways, as explained at the end of Built-In Actions.
2. Using the Properties pane, write your JavaScript code. In this example, the data for a new employee is passed to an action chain through input parameters, and a new object with the data is returned:
   
   
   Description of the illustration jsac-code-action.jpg
   
   

Add a Fire Data Provider Event Action

You add a Fire Data Provider Event action to dispatch an event on a data provider in order to reflect changes to your data. For example, a component using a particular Service Data Provider (SDP) may need to display new data because new data has been added to the endpoint used by the SDP.

The action can be called either with a mutation or a refresh event. The refresh event re-fetches and re-renders all data, and the mutation event is used to specify which changes to show.

Note:

This action is not necessary for a VB Array Data Provider (ADP) variable, since the data array of an ADP variable, exposed via the data property, can be updated directly using the Assign Variable action. Assigning the data array is automatically detected by VB Studio, and all listeners are notified of this change. Users will be warned of this when the fireDataProviderEvent is used with an ADP, prior to mutating the data property directly.

For API information about this action, including further details about its properties, see Fire Data Provider Event Action in the Oracle Visual Builder Page Model Reference.

To use a Fire Data Provider Event action:

1. Add the action in one of three ways, as explained at the end of Built-In Actions.
   
   
   Description of the illustration jsac-fire-data-provider-event-example.jpg
   
   
2. Update the ID field in the Properties pane to make the action more identifiable.
3. For Event Target, set the target of the event by hovering over the far-right side of the property and clicking to choose the relevant ServiceDataProvider or ArrayDataProvider.
4. Select the type of event you want to dispatch:
   • Refresh: Used to show all changes.
   • Mutate: Used to specify which changes to show.

     A mutation event can include multiple mutation operations (add, update, remove) as long as the ID values between operations do not intersect. This behavior is enforced by JET components. For example, you cannot add a record and remove it in the same event, because the order of operations cannot be guaranteed.

5. If you chose the Mutate event, ensure that the keyAttributes property is set for the SDP variable. The parameters for showing the added, removed and updated records are under the add, remove and update sections. Here's what's required for each section, for the mutate event to perform optimally:
   1. add section: Use the data parameter to pass the added record or records from the add operation’s returned result. If you are using an SDP variable, the structure of the data must match the structure specified by the itemsPath parameter of the SDP variable’s definition:
      
      
      Description of the illustration jsac-sdp-items-path.jpg
      
      Use the keys parameter to pass the key values of the added records with the Set<*> format. Lastly, use the metadata parameter to pass the key values of the added records with the format Array.<ItemMetadata.<KeyValue>>.
      Example:

      data: {items: [callRestCreateEmployeeResult.body],},
      keys: [callRestCreateEmployeeResult.body.id],
      metadata: [{key: callRestCreateEmployeeResult.body.id,}],

   1. remove section: Use the keys parameter to pass the key values of the deleted records with the Set<*> format
   1. update section: Same as the add section.

Add a Fire Event Action

You add a Fire Event action to invoke a predefined event or a custom event that you have defined in your application.

A custom event, created using the Events tab, is defined for an App UI, flow, page, or fragment. It can be used to perform some action, such as navigating to a page, and it can carry a payload that you define when you create the event.

You can trigger a custom event by using a Fire Event action in an action chain, which can be started in several ways (see Start an Action Chain). You could also trigger a custom event by using an event helper's fireCustomEvent() method (see Module Function Event Helper) in a module function (JavaScript function). For more about triggering a custom event this way, see Start an Action Chain By Firing a Custom Event.

For API information about this action, see Fire Event in the Oracle Visual Builder Page Model Reference.

Here's an overview of how to use the Fire Event action in an action chain to trigger a custom event that starts a different action chain to handle the event:

1. Create a custom event, defining parameters if required.
2. Create an event listener, which can start more than one action chain:
   1. In the Create Event Listener wizard, assign the event listener the custom event:
      
      
      Description of the illustration jsac-assign-listener-custom-event.png
      
      
   2. Create an action chain for the custom event, which will be started when the event is triggered by a Fire Event action. Create the action chain through the Event Listener tab, because if the listener's custom event has input parameters, the action chain is created with and passed an event object that contains the input parameters (example: event.param1, event.param2...).
3. To trigger the custom event and start its action chain, create an action chain and add a Fire Event action to trigger the custom event, providing any parameters defined for the event.

To use a Fire Event Action:

1. Add the action in one of three ways, as explained at the end of Built-In Actions.
2. In the Properties pane, select an existing event from the Event Name list of available events, or click Create to create a new custom event at the appropriate scope level (page, flow, or App UI). The list contains events that are available within the current scope.
3. If the event has input parameters, the Parameters property is shown. To pass in a parameter, hover over the far-right side of the parameter and click to choose the variable. If you need to create a variable, use a Create link in the Variables dialogue to create it at the appropriate scope level.
   
   
   Description of the illustration jsac-fire-event-action-example.jpg
   
   
4. If the event returns a value, it is assigned to the auto-generated variable shown by the Store Result In property.

Add a Fire Notification Action

You add a Fire Notification action to display a notification to the user in the web browser.

There are four types of notifications: Info, Error, Warning, and Confirmation. They display a summary and a message underneath:

Description of the illustration jsac-notification-types.jpg

For API information about this action, see Fire Notification Event in the Oracle Visual Builder Page Model Reference.

To use a Fire Notification action:

1. Add the action in one of three ways, as explained at the end of Built-In Actions.
   
   
   Description of the illustration jsac-fire-notification-action-example.jpg
   
   
2. Update the ID field in the Properties pane to make the action more identifiable.
3. Enter a summary of the notification in the Summary field.
4. Enter the message you want to display in the Message field.

   The message can be a static string (The name was updated.) or it can contain variables ({{ 'Could not create new Contacts: status ' + $chain.results.createContacts.payload.status }}).

5. For Display Mode, choose how the notification is dismissed: Transient — goes away after a few seconds, or Persist — stays until the user closes it.
6. Select a Notification Type to specify the look of the notification window.

Add a For Each Action

You add a For Each action to execute actions for each item in an array.

For API information about this action, see For Each in the Oracle Visual Builder Page Model Reference.

To use a For Each action:

1. Add the action in one of three ways, as explained at the end of Built-In Actions.
2. Configure the action's properties in the Properties pane:
   1. For Parameters, hover over the property's far-right side and click to choose the array to loop through, such as this array, $page.variables.expenseRecordsToUpdate.data:
      
      
      Description of the illustration jsac-variables-dialogue-items-array.jpg
      
      
   2. For Mode, select whether your called actions run serially (default) or in parallel. Regardless of the mode, the For Each action will not complete until the actions for each item in the array are complete.
   3. For Item Alias, optionally, enter an alias for the current item in the array; the default is item.
   4. For Index Alias, optionally, enter an alias for the loop index, which starts at 0 and increases by 1 for each iteration. The default alias is index.
3. Add the actions you want to take for each item of the array to the Add Action area of the For Each action. Here's an example that loops to call a REST endpoint (PATCH /ExpenseReport/{ExpenseReport_Id}) that updates the expense record at the current iteration:
   
   
   Description of the illustration jsac-each-call-rest.jpg
   
   

An array is returned with each element containing the return value from the last action in the loop, from each iteration. For instance, if the loop contains two actions that return results, actionA → actionB, and the loop iterates 5 times, the returned array will have 5 elements, each corresponding to an iteration and containing actionB's result from that iteration.

Add a Get Dirty Data Status Action

Use a Get Dirty Data Status action to check if any of the values have changed for the tracked variables within a particular scope (application, flow, page, fragment, layout), within any contained flows, pages, fragments, and layouts, and within any extensions of them. Tracked variables outside of the scope for which the check is done aren't considered. For example, in this image, both variables defined at the page level (their scope), have their Dirty Data Behavior property set to Track:

Description of the illustration jsac-variable-dirty-data.png

Whenever the value for any of these tracked variables changes, the dirty data status for their scope (referred to as context in code) is automatically changed from 'notDirty' to 'dirty'. And, if any tracked variables are defined for a layout, fragment, or extension of this page, and one of those variables changes, the page's dirty data status is also automatically set to 'dirty'. To reset the scope's dirty data status back to 'notDirty', use the Reset Dirty Status action.

When checking the dirty data status of a particular scope and its subscopes, it’s the scope from which the action chain is called that matters, not the scope in which the action chain is defined. For instance, if a page event initiates a flow or a page action chain with a Get Dirty Data Status action, the Get Dirty Data Status action returns that page's dirty data status, because the action chain is called from the page.

This functionality works with all data types except Service Data Providers (SDPs). You'll have to handle tracking value changes for SDPs manually, if needed.

For information about this action in the Oracle Visual Builder Page Model Reference, see Get Dirty Data Status.

Get Dirty Data Status Action vs Dirty Data Status Property

The Get Dirty Data Status action is used to check the dirty data status of a scope's tracked variables, so you can do things like implement a Save button that checks if a page actually has dirty data before posting its data to a database. The action doesn't take into consideration the consequences of navigating away from the page. If you want to check if navigating away from a page will result in the tracked variables losing their data, use the page's vbBeforeExit event listener. This event listener is triggered by navigating away from the page, and it starts an associated action chain that's passed an event parameter with a dirtyDataStatus property. Here's an example of an action chain that's started by a page's vbBeforeExit event listener, which doesn't allow navigating away from the page if the tracked variables will lose their data:

Description of the illustration jsac-dirty-data-exit-event-action-chain.png

The event.dirtyDataStatus property, unlike the Get Dirty Data Status action, does consider the effect that navigating away from the page would have on the tracked variables. The property is set to 'dirty' if navigating away from the page will cause the tracked variables to lose their data, otherwise, it's set to 'notDirty'. Variables within a scope retain their values as long as the destination of the user's navigation is within the scope or its subscopes. For instance, variables defined for a flow retain their values when a user navigates to a different page in the same flow, but not when a user navigates to a page in a different flow. Variables defined for a page do not retain their values when a user navigates to a different page in the same or a different flow.

Example:

This example shows an Add Employee page for adding a new employee's information. The page has two fields, one for a name and one for a birthdate, and their dirty data status needs to be tracked. The page also has a Save, Cancel, and Go to Home Page button. When the Save button is clicked, the employee's information is posted to storage.

Description of the illustration jsac-personal-info-form.png

The name and birthdate components are bound to page variables to hold their values:

Description of the illustration jsac-dirty-data-bind-component.png

To add dirty data functionality to this example:

1. Set the page variables' Dirty Data Behavior property to "Track".
2. For the Save button's action chain, add a Get Dirty Data Status action to check if the page actually has dirty data (unsaved changes) before posting the new employee's information to storage.
3. To warn users of unsaved changes due to navigating away from the page, add a vbBeforeExit event listener and use the event parameter's dirtyDataStatus property to check if navigation away from the page will result in the tracked page variables losing their data.
4. For the Cancel button's action chain, which navigates to the home page, add a Reset Dirty Data Status action to reset the page's dirty data status. This is needed for the vbBeforeExit event listener's action chain to allow the navigation to the home page when there is dirty data.

To begin:

1. Go to the page's Variables tab and set the page variables' Dirty Data Behavior property to Track:
   
   
   Description of the illustration jsac-dirty-data-info-change-variables.png
   
   
2. To add the dirty data functionality to the Save button's action chain, to check if there's actually dirty data before posting:
   1. Go the Save button's action chain. Here's an example, which passes a new employee's information to an action chain that posts the data to storage:
      
      
      Description of the illustration jsac-dirtydata-action-chain.png
      
      
   2. Add a Get Dirty Data Status action to the top of the action chain.
   3. Wrap the code for posting the new employee's data in an If action to check if there's dirty data to post. If there's no dirty data, do nothing.
   4. At the end of the If action's code, add a Reset Dirty Data Status action to reset the dirty data status back to 'notDirty'.

   Here's the action chain with the added dirty data functionality:
   
   Description of the illustration jsac-dirtydata-action-check.png
   

3. Next, we need to create a vbBeforeExit event listener to listen for when a user tries to navigate away from the page, which includes using the browser's Back and Forward buttons. If there are unsaved changes, a notification will warn the user of the unsaved changes and prevent the navigation. The event listener's action chain will be automatically passed an event object with a dirtyDataStatus property to check if the navigation away from the page will result in the tracked page variables losing their data.

   To begin:

   1. Open the Event Listeners tab and click the + Event Listener button to create a new event listener.
   2. Select vbBeforeExit, which starts its associated action chain whenever a user tries to navigate away from the page. Click Next:
      
      
      Description of the illustration jsac-dirty-data-exit-event.png
      
      

      We now need to create the action chain that's started by this event listener.

   3. On the Select Action Chain step of the Create Event Listener wizard, select the Create Page Action Chain option, under Page Action Chains. Click Finish.
      
      
      Description of the illustration jsac-dirty-data-exit-listener-action.png
      
      
   4. Back on the Event Listeners tab, hover over the new event listener that you just created and click the Go to Action Chain link that appears:
      
      
      Description of the illustration jsac-dirty-data-exit-event-action-link.png
      
      

      You're taken to the Action Chain editor to create the action chain that warns the user of unsaved changes.

   5. Add an If action to check if the navigation away from the page results in the tracked variables losing their data.

      Use the event parameter that was passed to the action chain, which has a dirtyDataStatus property. The property is set to 'dirty' if there will be lost tracked data, otherwise it's set to 'notDirty'.

   6. To handle the case in which the navigation results in a lose of tracked data, within the If action, add a Fire Notification action to notify the user of unsaved changes. To prevent the navigation away from the page, add a Return action to return the return object with its cancelled property set to true.
   7. To handle the case in which there is no dirty data, return the return object with its cancelled property set to false.

      Here's the completed action chain:
      
      Description of the illustration jsac-dirty-data-exit-event-action-chain.png
      

4. Finally, go to the Cancel button's action chain, which navigates to the home page. Add a Reset Dirty Data Status action to reset the page's dirty data status back to 'notDirty'. This is needed in case there's dirty data, which would prevent the vbBeforeExit event listener's action chain from allowing the navigation to the home page.
   
   
   Description of the illustration jsac-dirtydata-cancel-button.png
   
   

Add a Get Location Action

You add a Get Location action to get a user’s live location.

This action requires the user's consent. As a best practice, it should only be fired on a user gesture, so the users can associate the system permission prompt for access with the action they just initiated.

For API information about this action, see Get Location in the Oracle Visual Builder Page Model Reference.

To use a Get Location action:

1. Add the action in one of three ways, as explained at the end of Built-In Actions.
   
   
   Description of the illustration jsac-get-location-action-example.jpg
   
   
2. Update the ID property in the Properties pane to make the action more identifiable.
3. Set the Maximum Age (in milliseconds) of a possible cached position that is acceptable to return. If set to 0 (default), the device cannot use a cached position and must attempt to retrieve the real current position. If set to Infinity, the device must return a cached position regardless of its age.
4. Set the Timeout value, representing the maximum length of time (in milliseconds) that the device is allowed to take in order to return a position.
5. Set the Enable High Accuracy value that indicates whether the application would like to receive the best possible results. If true and if the device is able to provide a more accurate position, it will do so. This can result in slower response times or increased power consumption. If false (default), the device can save resources by responding more quickly or using less power. For mobile devices, you should set this to true in order to use GPS sensors.

If a value is returned by the action, it is assigned to the auto-generated variable shown by the Store Result In property.

Add an If Action

You use this action to add If, Else and Else If conditions.

To use an If action:

1. Add the action in one of three ways, as explained at the end of Built-In Actions.
2. With the If block selected on the canvas, add a condition using the Condition property. As a reminder, enclosing the expression in double curly brackets in the Properties pane indicates that it's a direct expression and not a string.
   
   
   Description of the illustration jsac-if-action-first-condition.jpg
   
   
3. Add the action to take for the If block to the Add Action area. You can either select the block and double-click the action, or you can drop the action onto the Add Action area. If another action is to follow, double-click the next action, or drop it onto the bottom edge of the preceding action.
   
   
   Description of the illustration jsac-if-action-first-action.jpg
   
   
4. To add an Else or Else If condition, you have to options:
   • Drop the action to take for the condition onto the Create Branch area at the bottom of the If block, which appears when you hover over it with an action.
     
     
     Description of the illustration jsac-if-action-drop-branch.jpg
     
     
   • Right-click an If or Else If block and select Duplicate:
     
     
     Description of the illustration jsac-duplicate-if-block.png
     
     
5. By default, an Else condition is created. To turn the Else into an Else If, enter a condition for it in the Properties pane:
   
   
   Description of the illustration jsac-if-action-else-if-block.jpg
   
   
6. To add an Else or another Else If condition, drop the first action to take for the condition onto the Create Branch area of the Else If block. Again, an Else condition is created by default, but it can be turned into an Else If by entering a condition in the Properties pane.
   
   
   Description of the illustration jsac-if-action-complete.jpg
   
   Here's the completed example:
   
   
   Description of the illustration jsac-if-condition-example.png
   
   

Add a Navigate Back Action

Add a Navigate Back action to return to the previous page in a browser's history.

For API information about this action, see Navigate Back in the Oracle Visual Builder Page Model Reference.

To use a Navigate Back action:

1. Add the action in one of three ways, as explained at the end of Built-In Actions.
   
   
   Description of the illustration jsac-nav-back-blank.jpg
   
   
2. Optional: For Parameters, specify a key/value pair map of parameters to pass to the previous page. If a parameter is not specified, the original value of the input parameter on the destination page is used. If a parameter is specified, it has precedence over fromUrl parameters.

Add a Navigate To Application Action

You use this action to navigate to an App UI. By default this action navigates to the specified App UI's default page, but you can also specify which flow and page to navigate to, as long as that flow or page has been set as navigable. For details on how to use the navigable setting, see steps 3 and 4 below.

For API information about this action, see Navigate To Application in the Oracle Visual Builder Page Model Reference.

To use a Navigate To Application action:

1. Add the action in one of three ways, as explained at the end of Built-In Actions.
   
   
   Description of the illustration jsac-nav-app-blank.jpg
   
   
2. For the App UI property, select the App UI to navigate to. To find it more quickly, start to type the name of the App UI in the text area and select it when it appears.
3. For the Flow in App UI property, which appears after selecting an App UI, select the flow within the selected App UI to navigate to. Only default flows and flows that have their "Let other App UIs navigate to this flow" setting enabled can be navigated to and are available in the dropdown list:
   
   
   Description of the illustration jsac-nav-app-let-nav-flow.jpg
   
   
4. For the Page in Flow property, select the page within the selected flow to navigate to. Only default pages and pages that have their "Let other App UIs navigate to this page" setting enabled on their Settings tab can be navigated to and are available in the dropdown list:
5. If the selected App UI has input parameters, enter them under Parameters, which appears after selecting the App UI.
   
   
   Description of the illustration jsac-nav-app-example.jpg
   
   
6. For the Browser History property, select either push (default), skip, or replace to define the effect on browser history. This value is used only if the resource is used in the same window. If you choose skip, the URL is not modified. If you choose replace, the current browser history entry is replaced instead of pushed, meaning that the back button will not go back to that page.

If a value is returned by the App UI, it is assigned to the auto-generated variable shown by the Store Results In property.

Add a Navigate To Flow Action

You use this action to navigate to a flow in the current App UI, and if necessary, to pass parameters to the flow. To navigate to a flow in a different App UI, use the Navigate to Application action.

For API information about this action, see Navigate To Flow in the Oracle Visual Builder Page Model Reference.

To use a Navigate To Flow action:

1. Add the action in one of three ways, as explained at the end of Built-In Actions.
   
   
   Description of the illustration jsac-nav-flow-blank.jpg
   
   
2. For the flow options, the Flow in Current Page option is only available if the page includes a Flow Container component. Selecting it provides you with the options for navigating to a flow or page within the current page. Selecting Flow in Parent Page provides you with the options for navigating to a flow of the parent page.
3. For the Flow property, select a flow or click the Create link to create a new flow to navigate to.
4. If the selected flow has input parameters, enter them for the Input Parameters property that appears after selecting the flow.
   
   
   Description of the illustration jsac-nav-flow-example.jpg
   
   
5. For Browser History, select either push (default), skip, or replace to define the effect on browser history. This value is used only if the resource is used in the same window. If you choose skip, the URL is not modified. If you choose replace, the current browser history entry is replaced instead of pushed, meaning that the back button will not go back to that page.

If a value is returned by the flow, it is assigned to the auto-generated variable shown by the Store Result In property.

Add a Navigate To Page Action

You use this action to navigate to a page in the current App UI, and if necessary, to pass parameters to the page. To navigate to a page in a different App UI, use the Navigate to Application action.

For API information about this action, see Navigate To Page in the Oracle Visual Builder Page Model Reference.

To use a Navigate To Page action:

1. Add the action in one of three ways, as explained at the end of Built-In Actions.
   
   
   Description of the illustration jsac-nav-page-blank.jpg
   
   
2. For the Page property, select a page or click the Create link to create a new page to navigate to.
3. If the selected page has input parameters, enter them for the Input Parameters property that appears after selecting the page.
   
   
   Description of the illustration jsac-nav-page-input-params.jpg
   
   
4. For Browser History, select either push (default), skip, or replace to define the effect on browser history. This value is used only if the resource is used in the same window. If you choose skip, the URL is not modified. If you choose replace, the current browser history entry is replaced instead of pushed, meaning that the back button will not go back to that page.

If a value is returned by the page, it is assigned to the auto-generated variable shown by the Store Result In property.

Add an Open URL Action

You add an Open URL action to navigate to an external URL. In a web app, this action opens the specified URL in the current window or in a new window.

For API information about this action, see Open URL in the Oracle Visual Builder Page Model Reference.

To use an Open URL action:

1. Add the action in one of three ways, as explained at the end of Built-In Actions.
2. In the Properties pane, enter the URL to navigate to.
3. Optional: For URL Parameters, if required, provide a key/value pair map of query parameters to pass to the specified URL.
4. Optional: For Hash, specify the hash entry to append to the URL. 
5. For Browser History, select either replace or push (default) to define the effect on browser history. This value is used only if the resource is used in the same window. If you chose replace, the current browser history entry is replaced instead of pushed, meaning that the back button will not go back to that page.
6. For Window Name, specify a name identifying the window as defined in the window.open() API. If not defined, the URL opens in the current window. For apps on mobile devices, you have three possible values: _self (default), _blank, or _system. For local file types, this property is ignored.

   Here's an example to open a new browser window with the specified URL. If you specify a value for the Window Name property (as shown here), once on the URL, the browser back button will re-enter the last page and the page input parameters will be remembered.
   
   Description of the illustration jsac-open-url-example.jpg
   

Add a Reset Dirty Data Status Action

You use a Reset Dirty Data Status action to reset the Dirty Data status of the scope (application, page, fragment, layout, flow) that the action is used in to 'notDirty'. The Dirty Data status also gets reset for any tracked variables within any contained pages, fragments, layouts, and flows, and within any extensions of them. The Dirty Data status of a scope (referred to as context in code) changes from 'notDirty' to 'dirty' when one of its tracked variables has its value changed.

This action takes no parameters and is used with the Get Dirty Data Status action.

Add a Reset Variables Action

You add a Reset Variables action to reset variables to their default values, as specified in the variable definitions.

For API information about this action, see Reset Variables in the Oracle Visual Builder Page Model Reference.

To use a Reset Variables action:

1. Add the action in one of three ways, as explained at the end of Built-In Actions.
2. Update the ID field in the Properties pane to make the action more identifiable.
3. Click the Variables to Reset box to select the variables that you want to reset. You can also start to type the variable's name in the box and select it when it appears.
   
   

   
   Description of the illustration jsac-reset-variables-action-example.jpg

   
   

Add a Return Action

The Return action is used to return a payload for an action chain and to return control back to where the action chain was called. For instance, action chain A can call action chain B, which returns a value, then action chain A can use that returned value for further processing.

The Return action can also be used to exit an action chain early due to an exception, such as an invalid value, or some other condition. If no value is returned by the Return action, the value of undefined is returned by default.

For the Run In Parallel action, which uses aysc() functions to run blocks of code in parallel, the Return action can be used to return a value for a block of code. For further details, see the Use 2: Run Multiple Action Chains in Parallel to Produce a Combined Result section here.

To use a Return action:

1. Add the action in one of three ways, as explained at the end of Built-In Actions.
2. For the Payload property, hover over the far-right side of the property and click to choose the variable to return.
   
   
   Description of the illustration jsac-return-action-example.jpg
   
   

Add a Run In Parallel Action

The Run In Parallel action is used to run multiple code blocks in parallel, and you can also use this action to wait for their results in order to produce a combined result.

For API information about this action, see Run in Parallel in the Oracle Visual Builder Page Model Reference.

Use 1: Run Multiple Action Chains in Parallel

To use a Run In Parallel action to just run multiple action chains in parallel:

1. Add the action in one of three ways, as explained at the end of Built-In Actions.
2. Drop the actions to run for each block in the Add Actions area of the Run in Parallel action. For example, you could make two REST calls and assignments in parallel:
   
   
   Description of the illustration jsac-run-parallel-action-example.jpg
   
   
3. To add another block of code to run in parallel, you have two options:
   • Right-click a block and select Duplicate from the context menu.
   • Drag the first action for the block from the Action's palette onto a Create Block area that appears at the bottom of the action's blocks:
     
     
     Description of the illustration jsac-run-parallel-add-third-block.png
     
     

Use 2: Run Multiple Action Chains in Parallel to Produce a Combined Result

To use a Run In Parallel action to produce a combined outcome from the results of multiple action chains:

1. Add the Run In Parallel action in one of three ways, as explained at the end of Built-In Actions.
2. For the Store Result In property, provide a name for the array that will hold the result from each block. The first block's result is stored at index 0, the second block's result is stored at index 1, and so on.
   
   
   Description of the illustration jsac-run-parallel-action-blank.jpg
   
   
3. Drop the actions to run for each block in the Add Action area of the Run in Parallel action.
4. To add another block of code to run in parallel, you have two options:
   • Right-click a block and select Duplicate from the context menu.
   • Drag the first action for the block from the Action's palette onto a Create Block area that appears at the bottom of a block when you drag an action over it.
5. Drop a Return action at the end of each block to return its result in the array that was named using the action's Store Result In property:
   
   
   Description of the illustration jsac-run-parallel-combine-example.jpg
   
   

   An array is returned by the Run in Parallel action (empInfo for this example, set in step 2): the first element contains the first block's result, the second contains the second block's result, and the third contains the third block's result.

Add a Scan Barcode Action

You can add the Scan Barcode action when you want your application to decode information such as URLs, Wi-Fi connections, and contact details from QR codes and barcodes.

For API information about this action, see Scan Barcode in the Oracle Visual Builder Page Model Reference.

Note:

The Scan Barcode action relies on the Shape Detection API for browsers and is only supported by these operating systems: Operating system support.

To use a scan barcode action:

1. Add the action in one of three ways, as explained at the end of Built-In Actions.
   
   
   Description of the illustration jsac-scan-barcode-action-example.jpg
   
   
2. Specify the action's properties in the Properties pane:
   1. Update the ID field to make the action more identifiable.
   2. In the Image field, enter an image object (either a CanvasImageSource, Blob, ImageData, or an <img> element) to decode.

      Note:

      If you're using the camera component to pass a Blob to the Scan Barcode action, you might run into the Failed to execute 'detect' on 'BarcodeDetector error. To get around this error, convert the Blob to an ImageBitmap before passing it to the Scan Barcode action. For example:

      1. Add a module function to do the image conversion, something like:

           // Convert Blob to ImageBitmap
           //
          PageModule.prototype.createImageBitmap = function(fileBlob) {
             return window.createImageBitmap(fileBlob);
           };

      2. Add a Call Function action to the action chain, similar to:
         
         
         Description of the illustration jsac-scan-barcode-example-chain.jpg
         
         
      3. Pass the converted ImageBitmap as the Image property for the Scan Barcode action.
   3. Optional: For the Formats property, select the barcode formats you want the browser to search for.

      Barcode formats unlock a variety of use cases. QR codes can be used for online payments, web navigation, or social media connections, aztec codes can be used to scan boarding passes, and shopping apps can use EAN or UPC barcodes to compare prices of physical items.

      If Formats is not specified, the browser will search all supported formats, so limiting the search to a particular subset of supported formats may provide better performance.

On success, a DetectedBarcode object is returned using the auto-generated variable shown by the Store Result In property. If the browser does not support the Shape Detection API or if a specified format is not supported, an exception is thrown.

Add a Share Action

You add a Share action to share content with other applications, such as Facebook, Twitter, Slack, and SMS, by invoking the native sharing capabilities of the host platform. This action requires the user's consent, and as a best practice, consent should only be sought on a relevant user action.

For API information about this action, see Share in the Oracle Visual Builder Page Model Reference.

Note:

Web apps require the web browser running the app to support the Share action. Currently, not all browsers support this native feature.

To use a Share action:

1. Add the action in one of three ways, as explained at the end of Built-In Actions.
2. Update the ID field in the Properties pane to make the action more identifiable.
3. Configure the Title, Text, and URL. All properties are individually optional, but at least one property must be specified. Any URL can be shared, not just those under the website's current scope. Text can be shared with or without a URL.
   1. In the Title field, enter the title of the document to be shared.
   2. In the Text field, enter the text that will form the body of the message being shared.
   3. In the URL field, enter the URL that refers to the resource being shared.

   Here's an example that shares the current page's title and URL:
   
   Description of the illustration jsac-share-action-example.jpg
   

Add a Switch Action

You add a Switch action when you want to match a value against a set of values, in order to execute appropriate actions for that case.

For API information about this action, see Switch in the Oracle Visual Builder Page Model Reference.

To use a Switch action:

1. Add the action in one of three ways, as explained at the end of Built-In Actions.
2. For Value, hover over the far-right side of the property and click to select the variable that is to be compared against each case value. If the value doesn't match any case value, or if it's null or undefined, the default case is executed.

   For example, when a menu defines a set of options, you can use the Switch action to determine which option was selected and to perform actions for that option. In this case, the page variable menuItemId holds the selected menu option, and it's selected using the Switch action's Value property:
   
   Description of the illustration jsac-switch-action.jpg
   

3. To define a case:
   1. Set a value for the case by selecting it within the Switch action, then using the Value property to enter its value or to select the variable that holds it. To select a variable, hover over the properties far-right side and click .
      
      
      Description of the illustration jsac-switch-action-case1.png
      
      
   1. Drop the actions to execute for the case in the Add Action area of the case block and configure their properties in the Properties pane:
      
      
      Description of the illustration jsac-switch-action-case-action.png
      
      
   1. If the rest of the cases are to be ignored, select Break after. If not selected, the rest of the cases get executed, regardless of their values, until running into a break statement (if at all).
4. To add a new case block, right-click a case and select Duplicate:
   
   
   Description of the illustration jsac-switch-action-duplicate-case.png
   
   

Add a Try-Catch Action

You add a Try-Catch action to gracefully handle errors and avoid program crashes.

To use a Try-Catch action:

1. Add the action in one of three ways, as explained at the end of Built-In Actions.
2. To change the alias for the error object, which has the name and message properties, select the Catch block on the canvas and change the alias in the Properties pane:
   
   
   Description of the illustration jsac-try-catch-error-alias.png
   
   
3. To add an action to a Try-Catch block, select the block and double-click the action in the Actions palette, or drag an action from the Action's palette onto the desired block:
   
   
   Description of the illustration jsac-try-catch-example.png
   
   

You can also surround an action with a Try-Catch action by right-clicking it and selecting Surround with Try-Catch:

Description of the illustration jsac-surround-try-catch.png

If you need a Finally block, drag the first action that you want to add to the block over the Try-Catch action and drop it into the Create Finally area that appears:

Description of the illustration jsac-create-finally-block.png