Save services for shared business objects

Service variables

Save service examples

• givenName (String): the customer's given name
• surname (String): the customer's surname
• address (Address): the customer's address
• dateOfBirth (Date): the customer's date of birth
• status (String): the status of the customer, for example new, gold, or platinum
• creditScore (Decimal): the customer's credit score

Example: Verifying that a variable was not changed

You might want to verify that a variable, such as the date of birth, in a shared business object was not changed after it was initially set. You can use a server script in the save service for the verification.

The example script iterates over the changes list. If the value of the dateOfBirth variable is changed, the script checks whether the old value is not null. If it is not null, the variable was changed by the user and a validation error is added to the validationErrors variable.

for(var i = 0; i < tw.local.changes.listLength; i ++) {
    var change = tw.local.changes[i];
    if(change.property == "dateOfBirth" && change.oldValue != null) {
        if(tw.local.validationErrors == null) {
            tw.local.validationErrors = new tw.object.listOf.BPMBOValidationError();
        }

        var validationError = new tw.object.BPMBOValidationError();
        validationError.property = change.property;
        validationError.errorText = "The date of birth must not be changed.";
        tw.local.validationErrors[tw.local.validationErrors.listLength] = validationError;
    }
}

Example: Verifying user permissions

You might have variables in your shared business object that can be changed only by a specific set of users. In this case, the save service must check whether the user who made the changes was authorized to do so. For example, the status of a customer can be changed only by a team lead.

The following example server script shows you how to check user permissions. The script determines whether the current user is a member of the team lead team. If the user is not a member of the team, the script iterated over the changes list. If there is an item for the status variable, the value was changed by someone who is not a team lead and a validation error is added to the validationErrors variable.

// check if current user is team lead
var teamLeadTeam = tw.system.org.findTeamByName("Team Lead");
var isTeamLead = tw.system.user.isInTeam(teamLeadTeam);

if(!isTeamLead) {
    for(var i = 0; i < tw.local.changes.listLength; i ++) {
        var change = tw.local.changes[i];
        if(change.property == "status" && (change.oldValue != null || change.newValue != "new")) {
            if(tw.local.validationErrors == null) {
                tw.local.validationErrors = new tw.object.listOf.BPMBOValidationError();
            }

            var validationError = new tw.object.BPMBOValidationError();
            validationError.property = change.property;
            validationError.errorText = "The status must only be changed by a team lead.";
            tw.local.validationErrors[tw.local.validationErrors.listLength] = validationError;
        }
    }
}

Attention: When a shared business object is saved, the save service is started by the system with the permissions of the user who caused the save to happen. If changes to shared business objects are made directly in a system task, the user is a technical user.

Example: Merging data

You can use the baseVersion and latestVersion variables to add custom merge logic to the save service to detect when an outdated version of the shared business object is updated.

The following example server script checks whether the baseVersion and latestVersion values are different. If they differ, updates are merged. The script then retrieves the different status values from the different versions of the shared business object. The value of the status variable is checked to determine whether the value was changed in both versions and whether the latest status is “platinum”. If so, the platinum status is enforced to prevent downgrading a customer from that level.

// check if a merge happened because an outdated version was updated
if(tw.local.baseVersion != tw.local.latestVersion) {
    var baseStatus = tw.local.baseVersion.status;
    var latestStatus = tw.local.latestVersion.status;
    var newStatus = tw.local.object.status;

    // check if the status was updated and merged
    if(newStatus != baseStatus && baseStatus != latestStatus) {
        // Make sure a downgrade from platinum does not happen
        if(latestStatus == "platinum") {
            tw.local.object.status = "platinum";
        }
    }
}

Example: Including calculations in save services

In a save service, you can apply modifications to the value of a shared business object variable. For example, you can call a nested service that calculates the credit score for a customer that you pass in customer information, such as the customer's address, and map the returned credit score to the tw.local.object.creditScore property.

Error handling

If the error is not caught on the activity or the step, it is propagated to the parent instance. If the error is not caught at all, all the updates are discarded and the instance is marked as Failed.

Shared business objects that have validation errors are excluded from automatic synchronization until another change is made and the user saves the shared business object or it is saved automatically.

Error handling examples

Example: Show error information to users in client-side human services

The following example shows the logic that you can add to an error event handler to map validation errors from a save service into a data structure that can be displayed in a coach. The error event handler maps the validation errors to the sharedBOSaveError variable in the client-side human service. The variable is of the BPMBOSaveFailedError type.

  tw.system.coachValidation.populateFromBPMBOSaveFailedError(tw.local.sharedBOSaveError);

For more information, see Handling errors in client-side human services.

Example: Show error information to users in heritage human services (deprecated)

If you have a coach that allows users to make updates to shared business objects in a heritage human service, you can add an error intermediate event to the coach. You use the BPMBOSaveFailedError variable as the error code and map the error data into a private variable of type BPMBOSaveFailedError, for example sharedBOSaveError.

The following image shows a heritage human service that combines coach validation with the error handling for validation errors that are returned by save services for shared business objects.

In the example, the steps are run in the following order.

1. First, the coach validation is done by the script Validate before save. The script ensures that valid data is passed into the service flow.
2. When Validate before save returns a validation error, the execution goes directly back to the coach and no save service is invoked.
3. When a user enters data that does not cause any coach validation errors, the run time tries to save all the data from the user. If the user data includes shared business objects and the Automatically sync shared business objects option is enabled on the heritage human service definition, the shared business objects are also saved. Save services are also run as part of the save. If a save service returns validation errors, the run time throws a BPMBOSaveFailedError.
4. The BPMBOSaveFailedError is caught as a boundary event on the coach and the error data is mapped into a local variable sharedBOSaveError.
5. The Populate coach validation errors script in the error path invokes a system function to transform all validation errors from the BPMBOSaveFailedError into the coach validation:

   tw.system.populateCoachValidationFromBPMBOSaveFailedError(tw.system.coachValidation, tw.local.sharedBOSaveError);

6. The stay-on-page event causes the run time to give control back to the coach, and the user sees errors.

For more information about coach validation, see Validating coaches in heritage human services.

CAUTION:

When you model error handling by repairing the invalid shared business object and wiring back into the original flow, you might model an endless loop. In a situation where you do not need the context information of the caller (such as other process instance variable data) to automatically repair data inconsistency, do the automatic repair in the save service itself and not in an error handler in the service or process.