global.beforeValidation

$().beforeValidation is a page-level lifecycle hook that fires just before the agent saves a disposition (submits the script page). It gives you a chance to run custom validation logic, make API calls, or update field values — and optionally block the save by returning false.

$().beforeValidation = function(disposition) {
  // your logic here
  // return false to block saving
};

Parameters

Disposition object

Returns

Tip: Always pair return false with an alert() call so the agent knows why the save was blocked.

Common use cases

Use case 1 Validate callback date

Prevent agents from scheduling a callback for any day other than today:

$().beforeValidation = function(disposition) {
  if (disposition.id === 1 || disposition.id === 2) {
    var callbackDate = disposition.next_calldate.slice(0, 10);
    var today = new Date().toJSON().slice(0, 10);
    if (callbackDate !== today) {
      alert('Callback must be scheduled for today only!');
      return false;
    }
  }
};

Use case 2 Block save based on assessment type

Run a server-side check before allowing an “Ordered” disposition through:

$().beforeValidation = function(disposition) {
  if (disposition.assesment === vcc.DISPOSITION_ORDERED) {
    var xhr = vcc.httpRequest();
    var numberid = vcc.getScriptVariable('numberid');
    var projectid = vcc.getScriptVariable('projectid');

    xhr.open('GET', 'https://your-api.example.com/check?numberid=' + numberid + '&projectid=' + projectid, false);
    xhr.send();

    var result = JSON.parse(xhr.responseText);
    if (!result.valid) {
      alert('Order validation failed. Please review the record.');
      return false;
    }
  }
};

Use case 3 Sync field data to an external system before saving

Write back updated contact info to a CRM before the disposition is committed:

$().beforeValidation = function(disposition) {
  var projectid = vcc.getScriptVariable('project.id');
  var numberid  = vcc.getScriptVariable('numberid');

  var contact = {
    name:  vcc.getFieldValue('name'),
    phone: vcc.getFieldValue('phone1'),
    email: vcc.getFieldValue('email'),
  };

  vcc.callCustomerApi(
    'PUT',
    '/v2/projects/' + projectid + '/records/' + numberid + '/contacts/1',
    contact,
    function(success, response) {}
  );
};

Use case 4 Restore a field value before saving

Ensure a field is never left blank when the agent saves:

$().beforeValidation = function() {
  if (vcc.getFieldValue('phone1') === '') {
    vcc.setFieldValue('phone1', original_phone);
  }
};

Notes

• $().beforeValidation applies to the entire page, not a specific component. Use disposition.id or disposition.assesment to limit logic to specific dispositions.
• Only one $().beforeValidation handler can be active per page. Defining it multiple times will overwrite the previous definition.
• The disposition parameter is undefined if called in contexts outside a normal disposition save — guard accordingly.