1. Oracle Visual Builder Page Model Reference
  2. Understand the Page Model
  3. JavaScript Action Chains
  4. JavaScript Actions
  5. Fire Data Provider Event

Fire Data Provider Event

The Fire Data Provider Event action causes the DataProvider specified via the target parameter to dispatch an oj.DataProvider event as a way to notify all listeners registered on that DataProvider to react to changes to the underlying data. For example, a component using a particular ServiceDataProvider may need to render new data because new data has been added to the endpoint used by the ServiceDataProvider.

The action can be called either with a mutation or a refresh event. The refresh event is used to re-fetch and re-render 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 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 Visual Builder, 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.

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.

This table provides details about the parameters for the Fire Data Provider Event action. For further details, see DataProviderOperationEventDetail in Oracle JET API Reference.

Name Type Description
target string Target of the event, usually a variable of type vb/SDP.

Example:

target: $page.variables.employeeSDP
refresh null Indicates a data provider refresh event needs to be dispatched to the data provider identified by the target. A null value is specified because the refresh event does not require a payload.

Example:

      await Actions.fireDataProviderEvent(context, {
        target: $page.variables.employeeListSDP,
        refresh: null,
      });

For further details, see DataProviderRefreshEventDetail in Oracle JET API Reference.

add object The following properties may be present in the payload:

  •  data: Array<Object>; required. Passes the added records from the add operation’s returned result. If you are using an SDP variable, the structure of the data passed to this parameter must match the structure specified by the itemsPath parameter of the SDP variable’s definition:


    Description of jsac-sdp-items-path.jpg follows
    Description of the illustration jsac-sdp-items-path.jpg

    The SDP's itemsPath property specifies where the added records are in the response payload, relative to the root of the response. Here are three different structures for an add operation's response and the corresponding itemsPath specification:

    1. Added records (just one in this example) are provided as an array, at the root of the response: 
      [
    {
      "id": 149,
      "firstName": "Qinqin",
      "lastName": "Han"
    }
]

      The itemsPath specification for this case is: "itemsPath": ""

      Here's an example of the data parameter for the Fire Data Provider Event action for this case: 

            //Add new employee record
      const callRestCreateEmployeeResult = await Actions.callRest(context, {
         endpoint: 'businessObjects/create_Employee',
         body: $page.variables.newEmpData,
      });

      const fireDPEResult = await Actions.fireDataProviderEvent(context, {
         target: $page.variables.employeeListSDP,
         add: {
           data: [callRestCreateEmployeeResult.body],
           keys: [callRestCreateEmployeeResult.body.id], 
           metadata: [{key: callRestCreateEmployeeResult.body.id,}],
         },
      });
    2. Added records (just one in this example) are provided in an array, which is in an object's property, such as this object's items property:
      {
  "items": [
    {
      "id": 149,
      "firstName": "Qinqin",
      "lastName": "Han"
    }
  ],
  "count": 1,
  "hasMore": false,
  "offset": 0
}

      The itemsPath specification for this case is: "itemsPath": "items"

      Here's an example of the data parameter for the Fire Data Provider Event action, for this case: 

            //Add new employee record
      const callRestCreateEmployeeResult = await Actions.callRest(context, {
         endpoint: 'businessObjects/create_Employee',
         body: $page.variables.newEmpData,
      });

      const fireDPEResult = await Actions.fireDataProviderEvent(context, {
         target: $page.variables.employeeListSDP,
         add: {
            data: {items: [callRestCreateEmployeeResult.body]},
            keys: [callRestCreateEmployeeResult.body.id], 
            metadata: [{key: callRestCreateEmployeeResult.body.id,}],
         },
      });
    3. Added records (just one in this example) are provided as an array in a nested structure that matches the itemsPath property. In this example, the added records are in the bar property of this object's foo property:
      {
  "foo" : {
    "bar" : [
        {
          "id": 149,
          "firstName": "Qinqin",
          "lastName": "Han"
        }
      ]
  }
}

      The itemsPath specification for this case is: "itemsPath": "foo.bar"

      Here's an example of the data parameter for the Fire Data Provider Event action code for this case: 

            //Add new employee record
      const callRestCreateEmployeeResult = await Actions.callRest(context, {
         endpoint: 'businessObjects/create_Employee',
         body: $page.variables.newEmpData,
      });

      const fireDPEResult = await Actions.fireDataProviderEvent(context, {
         target: $page.variables.employeeListSDP,
         add: {
            data: {foo: {bar: [callRestCreateEmployeeResult.body]}},
            keys: [callRestCreateEmployeeResult.body.id], 
            metadata: [{key: callRestCreateEmployeeResult.body.id,}],
         },
      });
  • keys: Set<*>; required for optimal performance. Ensure that the keyAttributes parameter is set for the SDP variable. Here's an example value for this parameter: 
    keys: [callRestCreateEmployeeResult.body.id],

  •  metadata: Array.<ItemMetadata.<KeyValue>>; required for optimal performance. Passes the key values of the added records. Here's an example value for this parameter: 

    metadata: [{key: callRestCreateEmployeeResult.body.id,}],
  • addBeforeKeys: Array<keys>; optional. Array of keys for items located after the items involved in the operation. They are relative to the data array, after the operation was completed, and not to the original array. If null and the index is not specified, then insert at the end.

  • indexes: Array<number>; optional. Indexes of items involved in the operation, relative to after the operation completes and not to the original dataset. Indices are with respect to the DataProvider with only its implicit sort applied.

    For further details, see DataProviderAddOperationEventDetail in Oracle JET API Reference.

remove   Only the keys parameter is required to identify the records. For details about the keys parameter, refer to the add event above.

Example:

await Actions.fireDataProviderEvent(context, {
        target: $page.variables.employeeSDP,
        remove: {
           keys: [$page.variables.productId],
        },
      });

For further details, see DataProviderMutationEventDetail in Oracle JET API Reference.

update   The update event's payload is similar to that of the add event, except addBeforeKeys is not present.

Example:

await Actions.fireDataProviderEvent(context, {
        target: $page.variables.employeeSDP,
        update: {
          data: {items: [callRestUpdateEmployeeResult.body]},
          keys: [callRestCreateEmployeeResult.body.id], 
          metadata: [{key: callRestCreateEmployeeResult.body.id,}],
        },
      });

For further details, see DataProviderMutationEventDetail in Oracle JET API Reference.