OData Change Set¶

An OData change set is made up of an unordered group of one or more create, update, or delete operations.

The OData Change Set action accepts an array of actions and/or rules in the Actions property.

Any OData entities modified via create, update, or delete operations within this array will not be immediately persisted against the OData service. Instead, they will be grouped and stored in memory. Only when the last action or rule in the array is executed and completed, will the change set be committed and persisted. During the commit, if one of the operations fails, then the entire change set will be considered failed and all the change operations inside the change set will be rolled back and no changes will be persisted.

The following OData actions are supported in a change set:

Mobile and Web platforms

Create entity
Update entity
Delete entity
Create related entity

Mobile platforms only

Create Media entity
Create related Media entity
Upload Media entity
Delete Media entity
Upload Stream entity
Call Function entity (only supports the execution of ActionImport and not FunctionImport)

Examples Create related media entity:

{
  "Actions": [
    "/EventApp/Actions/NavToCreateEventAndSessionsModalPage.action",
    "/EventApp/Actions/NavToCreateEventRelatedMediaModalPage.action"
  ],
  "Target": {
    "Service": "/EventApp/Services/EventManagementService.service"
  },
  "OnSuccess": "/EventApp/Actions/CreateEventSessionSuccess.action",
  "OnFailure": "/EventApp/Actions/CreateEventSessionFailed.action",
  "_Type": "Action.Type.ODataService.ChangeSet"
}

Call function:

{
  "Actions": [
    "/EventApp/Actions/UpdateCategory.action"
  ],
  "Target": {
    "Service": "/EventApp/Services/EventManagementService.service"
  },
  "_Type": "Action.Type.ODataService.ChangeSet"
}

Actions or Rules in Actions Property¶

You can set an array of actions or rules in the Actions property.

{
  "Actions": [
    "/EventApp/Actions/CreateEventEntity.action",
    "/EventApp/Rules/CreateSessions.js"
  ],
  "Target": {
    "Service": "/EventApp/Services/EventManagementService.service"
  },
  "OnSuccess": "/EventApp/Actions/CreateEventSessionSuccess.action",
  "OnFailure": "/EventApp/Actions/CreateEventSessionFailed.action",
  "_Type": "Action.Type.ODataService.ChangeSet"
}

export default async function CreateSessions(context) {
  //Assuming the app has stored data for the new entities inside the page's ClientData
  // All of the create entities operations in here will be part of the change set because
  // this rule was executed inside a change set
  let pageProxy = context.getPageProxy();
  let clientData = pageProxy.getClientData();

  for (var i = 0; i < clientData.NewSessions.length; i++){
    pageProxy.setActionBinding(clientData.NewSessions[i]);
    await context.executeAction("/EventApp/Actions/CreateSessionEntity.action");
  }
  return Promise.resolve();
}

Set Rule as Actions Property¶

You can also set the Actions property to a rule. In this case, you must return an array of actions or rules from your assigned rule.

{
  "Actions": "/EventApp/Actions/ReturnListOfActions.js",
  "Target": {
    "Service": "/EventApp/Services/EventManagementService.service"
  },
  "OnSuccess": "/EventApp/Actions/CreateEventSessionSuccess.action",
  "OnFailure": "/EventApp/Actions/CreateEventSessionFailed.action",
  "_Type": "Action.Type.ODataService.ChangeSet"
}

export default async function ReturnListOfActions(context) {
  let arrayOfActions = ["/EventApp/Actions/CreateEventEntity.action"];

  let pageProxy = context.getPageProxy();
  let clientData = pageProxy.getClientData();

  if (clientData.NewSessions.length > 0) {
    arrayOfActions.push("/EventApp/Rules/CreateSessions.js");
  }

  return arrayOfActions;
}

One special use of change set consists of navigating to a modal page inside the Change Set action using the Actions property.

{
  "Actions": [
    "/EventApp/Actions/NavToCreateEventAndSessionsModalPage.action"
  ],
  "Target": {
    "Service": "/EventApp/Services/EventManagementService.service"
  },
  "OnSuccess": "/EventApp/Actions/CreateEventSessionSuccess.action",
  "OnFailure": "/EventApp/Actions/CreateEventSessionFailed.action",
  "_Type": "Action.Type.ODataService.ChangeSet"
}

As long as the modal page remains open, any OData operations you perform within that modal page will be part of the change set. The change set will not proceed to be committed until the modal page is closed using the ClosePage action with Action.Type.ClosePage.Completed in the DismissModal property.

This allows you to perform specific scenarios, such as the following:

Start an OData change set action that contains an action to open a modal page.
The opened modal page allows the user to create an event and an associated session.
The user inputs values in the Create Event form page.
The user presses Next to perform an OData create entity on the Events entity set.
The Create Session form (still within the modal dialog) is displayed, where the user inputs values to create a session.
The user presses Save to perform the OData create entity on the Sessions entity set linked to the previously created Events entity.
Close the modal page as Completed, triggering the OData change set action to be completed and committing the changes.

Create Links to New Entities Created Within a Change Set¶

When entities are created as part of a change set, they do not actually get created in the back-end OData service or offline OData store until the change set is processed (the last action of the change set has been completed). As a result, they would not appear in a list that queries the entity set they belong to if the query is executed as part of the same change set in which the entities were created.

In other words, the following scenario would not complete successfully:

Begin change set.
Create an entity of type Events.
Create an entity of type Sessions.
Display a list of all Events in order to select the newly created Events entity from it, and then link it to the newly created Sessions entity. The newly created Events entity will not show up in the list, as it does not exist yet.

To get around this limitation, when entities get created in a change set, they get assigned a temporary, ordinal ReadLink until the change set action completes. If those entities need to be referred to in subsequent actions that are part of the same change set, use this temporary read link.

The prefix of the read link is pending_, followed by an ordinal, i.e. pending_1, pending_2, etc.

The following code sample, based on the scenario described above, illustrates how the new Sessions entity refers to the newly created Events entity that was created within the change set in the CreateLinks section:

{
  "_Type": "Action.Type.ODataService.CreateEntity",
  "Properties": {
    "Title": "{#Control:TitleSimplePropertyFormCell/#Value}",
    "StartDateTime": "{#Control:StartDateTimeFormCell/#Value}",
    "EndDateTime": "{#Control:EndDateTimeFormCell/#Value}",
    "Description": "{#Control:DescriptionNoteFormCell/#Value}"
  },
  "Target": {
    "EntitySet": "Sessions",
    "Service": "/EventApp/Services/EventManagementService.service"
  },
  "CreateLinks": [
    {
      "Property": "Event",
      "Target": {
        "EntitySet": "Events",
        "ReadLink": "pending_1",
      }
    }
  ],
  "ActionResult": {
    "_Name": "CreateSessionResult"
  },
  "OnSuccess": "/EventApp/Actions/ClosePageAsCompleted.action",
  "OnFailure": "/EventApp/Actions/ActionFailedMessage.action"
}

Last update: August 23, 2023

OData Change Set¶

Actions or Rules in Actions Property¶

Set Rule as Actions Property¶

Use Change Set with Modal Dialog¶

Create Links to New Entities Created Within a Change Set¶