v1.0 - Record Management

Introduction

Now that you have your campaigns and instance level configuration completed, you may be wondering how to insert records into your campaigns, or update records after inserts - after all, what good is a campaign if you aren’t dialling anyone?

In this section, we will cover record insert options, as well as the Attempt Preservation special functionality, which is useful for migration of records from one system to another, and can be used to achieve other operational outcomes.

Let’s first start with the special feature, APF (Attempt Preservation Flag).

Attempt Preservation Flag (APF)

What is APF?

“APF” stands for “Attempt Preservation Flag”. Attempt preservation limits the number of attempts a campaign will make against a record to a lower value than the maximum attempts configured in the campaign container. It is configured at the record level via the insert process, or via the update process, using a specifically named field which the dialler looks for when assessing the record - therefore, APF is activated at the record level. When activating APF, a specific field is set to TRUE in the record payload, and another field denotes the max attempts when this value is true. If the values of this field have been set correctly, APF is activated, and the number of attempts is limited by the value assigned in that secondary field. The record will stop dialling when that updated attempt value is reached.

Potential Use Cases

This field can be used for a variety of purposes, such as:

• Legacy System Migration - when migrating from an old dialler system to a new one, you may have records which have already achieved a number of attempts which you would like to migrate. When moving these records to your new dialler campaign, which may naturally have a maximum attempt setting of (for example) 6 attempts, but the migrating record has already had 3 attempts, you may want to limit this record’s maximum attempts to 3, so that the total attempts over both systems does not exceed 6. APF allows you to do this.

• Campaign Migration - if you have a scenario where you would like a record to transition between campaigns, but maintain a single maximum attempt value (as opposed to being governed by the maximum attempts in each campaign), APF allows you to achieve this dialling cadence

There are countless other business cases, determined by the requirements your business may have, which could trigger the use of this feature.

Activating APF

Every campaign schema contains two non-mandatory fields, which cannot be edited (but do not need to be included in the record payload). These fields are as follows:

• attemptPreservationFlag (BOOLEAN)

• attemptPreservationFlagMaxAttempts (INTEGER)

To activate the APF functionality at the record end, you will need to:

1. Ensure your record payload includes the attemptPreservationFlag field, set to TRUE

2. The attemptPreservationFlagMaxAttempts, set to the new maximum attempt value you would like the record to conform to

As previously stated, this functionality is turned on and applied at the record level, so you can have a mix of records in your campaign which have APF activated, and others which do not. You can also have separate max attempt values for each activated record, making this functionality extremely flexible as it’s settings apply at the record level.

Record Insert

Inserting records into your dialler is a process achieved (at this stage) via API, or sending data to SQS queues. The full technical details of this integration will be supplied with the separate API documentation VoiceFoundry have prepared, however in this section we will operationally describe how records are inserted.

Much of this has been covered in the Schemas and Campaigns section of this guide, however this section provides an easily accessible location for a quick overview.

Record Insert Preparation

Before inserting any records, you need to consider the “Mandatory” field nature of schema fields, and their data types, which you have applied to your campaigns. Any fields configured as mandatory will need to be applied to records which are being uploaded to the campaign with the mandatory field in question. Data types are also important - you must ensure your data type matches the assigned data type for the field in the Schema instance configuration.

It is important to note that, should you attempt to insert a record with incorrect data types, or without a mandatory field attached to the record, the record insert will fail.

Another important note - there is nothing stopping you from inserting more data with a record than set out in your campaign, or instance level schema. This may be useful in certain scenarios (for example, if you want to add a schema field to the instance and campaign at a later stage and that field will be mandatory in the campaign, having the data there already will support easier schema changes. This is because, when adding a mandatory field to a campaign, the system will check existing records assigned to the campaign for that field - if it does not exist already, you will need to update the records to include the field. Inserting the data without mapping to the schema could help to resolve this issue).

Inserting your records

After considering mandatory and field type requirements, you will also need to ensure that the four mandatory system fields are inserted with every record - these are:

• zone (string) - refers to the zones setup in the Zones interface, in the OCM administration portal

• phoneNumber (string) - the phone number of the customer, in E164 format

• campaignId (string) - the ID of the campaign to insert the record into

  • Alternatively, you can use campaignName (string) to achieve the same outcome

• crmId (string) - the CRM ID of the record for purposes of screenpops

With these four fields, plus the mandatory fields, plus any extra optional or non-mapped schema fields applied to the record (at your discretion), you can send the record to the dialler via either the SQS queue method, or the API method directly.

If the record passes the appropriate validation, the record will be inserted, and a message will be sent back advising the record insert was successful.

Record Update

Your records do not have to stay the same after their initial insert. If, for any reason, you need to update any of the record data which you have provided to the dialler on initial insert, or if you need to change the campaign associated with the record, you can do this by updating the record.

The schema for updating the record is provided in the API documentation, supplied separately to this document.

Use Cases

There are a few use cases for updating a record. Some of these are as per below:

• Updating the phone number on the record - if you’d like to dial a new customer phone number, your system can update the record using the record’s primary key (recordId) to identify the record, and update the record with a new phone number.

• Changing the campaign assigned to the record - if you’d like to switch the campaign the record is assigned to, this can be achieved via the update process also, by updating the campaignId or campaignName fields. When switching the record’s campaign, the attempts allowed for the record resets.

• Changing an existing data field for filtering or sorting - if you have filters or sort criteria configured on your campaign, and you have records with fields you would like to change to include/exclude them from the filter on the next dial, or if you’d like to change the sort order of a record, you can update any custom schema field using the update process. This allows you to change your dialling cadence mid-stream

There are many more use cases which will likely be determined by your business requirements and intent.

Updating your record

Use the SQS or API method to send a payload with your target record data (ie, what you want the record to look like after the update). Using the SQS/API method correctly, you will receive a confirmation that the record was updated (or a failure if something went wrong).