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

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: $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: $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>; optional. However, we recommend always passing this parameter because, without data, VB Studio won't know what kind of record to create, and you'll get an error.

    data 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: $variables.newEmpData,
      });

      const fireDPEResult = await Actions.fireDataProviderEvent(context, {
         target: $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: $variables.newEmpData,
      });

      const fireDPEResult = await Actions.fireDataProviderEvent(context, {
         target: $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: $variables.newEmpData,
      });

      const fireDPEResult = await Actions.fireDataProviderEvent(context, {
         target: $variables.employeeListSDP,
         add: {
            data: {foo: {bar: [callRestCreateEmployeeResult.body]}},
            keys: [callRestCreateEmployeeResult.body.id], 
            metadata: [{key: callRestCreateEmployeeResult.body.id,}],
         },
      });
  • keys: Set<*>; optional. Recommended 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>>; optional. Recommended 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   The payload has one parameter, keys. Use it to tell VB Studio which records to remove. Although optional, we recommend including keys - without it, VB Studio won’t know what to remove, and you'll get an error.

For details about this parameter, see the add event in the preceding row.

Example:

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

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

update   The payload is similar to the add event, with one difference: there's no addBeforeKeys. All parameters are optional, but we recommend always passing data (which tells VB Studio what changes to make) and keys (which tells VB Studio which record to update). If you don’t pass either of these parameters, you’ll get an error.

Example:

await Actions.fireDataProviderEvent(context, {
        target: $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.