Modifying Scenario Data

The changes are expressed as a list of changes to be applied in the specified order then they are committed to the server for processing. If any of these changes fail to be applied they will all be rolled back and nothing will be modified. Upon completion the server will either respond as successful or if a failure occurs it will provide an error message and status code.

Note Changes to scenario data are not applied to the scenario object within a particular invocation of a scenario observer. When a scenario observer is called it is passed immutable scenario data.

The key features of scenario data modification are:

• Batched: Changes are created as a batch request and committed to the server as one request.
• Atomic: All changes are applied as an atomic operation on the server.
• Transactional: If an error is encountered while applying the changes everything will be rolled back.
• Asynchronous: When changes are sent to the server, a Promise is returned which either will be resolved or rejected based on the server response.
• Ordered: The order in which you specify the changes is the order in which they are applied on the server.
• Scenario-oriented: Each batch request is applied to a specific scenario.
• Applied server-side: Changes are not applied to any existing scenario objects in your view. The changes will not be available until scenario observers update themselves.

From a scenario observer

view.withFirstScenario()
   .withEntities('SCALAR1', 'ARRAY1')
   .notify(function(scenario) {
       // Create a ScenarioDataChange object for 
       // the first scenario
       var changes = scenario.modify();
   })
   .start();

Outside a scenario observer

// Create a new ScenarioDataChange object for the first scenario.
// The number argument is the selection index of the scenario
var changes = view.modifyScenario(0);

The ScenarioDataChange object offers a chainable API (each call returns the ScenarioDataChange instance) to express your changes and then commit them. When the changes are committed a Promise is returned so you can detect and respond to success or failure.

scenario.modify()
   .setScalar('SCALAR1', 55)
   .addToSet('SET1', [15, 16, 17])
   .setArrayElement('ARRAY1', {key: [15], value: 'fifteen'})
   .removeFromSet('SET1', [16, 17])
   .commit()
   .then(function() {
       // Applied successfully
   })
   .catch(function(error) {
       // Error applying changes
       // Server rolled back any partial changes
       console.log('Could not apply changes, reason: ' +
           error.message +', status code: ' + error.status);
   });