updateRecord Documentation

Purpose

The updateRecord function is an integral part of the Vantage analytics & data platform, designed for updating existing records within the contacts application. By using this function, users can modify one or more records by specifying the necessary data and identifying the records to be updated. This function is essential for maintaining accurate and up-to-date information within the platform.

Settings

The updateRecord function has several settings that dictate its behavior and the data it requires to execute properly. Below is an exhaustive breakdown of each setting:

1. recordId

• Input Type: String
• Description: This setting specifies a particular record to update if it is not provided through the input data. When used, all provided updates will apply to this single record.
• Impact: Specifying a record ID will override any id field in the provided data. If omitted, the function will require an id in each record to update.
• Default Value: undefined (no default; must be provided via input or config).

2. idColumn

• Input Type: String
• Description: This defines the column name that contains the record ID in the upstream data. If the input data does not provide a specific recordId, the function will look up the identification of the record to update based on this column name.
• Impact: Changing this setting alters which field the function references within the input data to find the record ID. Incorrectly setting this may lead to updates failing to target the intended records.
• Default Value: id.

How it Works

The updateRecord function operates asynchronously to update records in the contacts app. Here's a high-level overview of its functioning:

1. Context Evaluation: The function begins by trying to extract the application type from the execution context or defaults to contacts.
2. Configuration: It retrieves the application configuration using the clientId and the appType. It uses this configuration to create an adapter that interacts with the underlying data storage.
3. Input Handling: The function expects data in the form of an object or an array of objects. Each object must include an id field to identify the record that needs to be updated, or must correspond to the identifier provided via idColumn. If the input is a single object, it converts this to an array.
4. Record Update: For each item in the input data, the function determines the appropriate record ID. It then calls the adapter’s updateRecord method, passing the record ID and the updates.
5. Error Handling: If any issues arise during execution, an error message is returned detailing the problem.

Expected Data

The function anticipates the following data structure as input:

{
    "data": [
        {
            "id": "123",
            "field1": "new value",
            "field2": "another new value"
        },
        {
            "id": "456",
            "field1": "other value",
            "field2": "xyz"
        }
    ]
}

This data can either be provided directly in the input or defined as a property in an object. Each object must include either an id or comply with the idColumn specification to be processed correctly.

Use Cases & Examples

Use Cases

1. Updating Customer Contact Information: A business needs to update the contact details of its clients after collecting new information from a survey. This function allows them to batch update records with new email addresses and phone numbers.

2. Correcting Errors in Database Records: An organization realizes that several records are misspelled or contain incorrect values. The updateRecord function can bulk update these records with the correct information quickly.

3. Bulk Modifications for Marketing Campaigns: As part of a marketing effort, a company needs to mark several customer records to indicate their participation in a specific campaign, requiring updates to existing records with campaign-related details.

Example Configuration

To illustrate how to use the updateRecord function in a real-world scenario, consider a company that wants to update the contact details of the user with ID 123. They have the following configuration:

{
    "config": {
        "recordId": "123",
        "idColumn": "userId"
    },
    "inputs": {
        "data": [
            {
                "field1": "new.email@example.com",
                "field2": "+1234567890"
            }
        ]
    }
}

In this configuration:

• The recordId is hardcoded to 123, meaning the updates will only apply to this specific record, ignoring other potential matches based on input data.
• The input includes the new email and phone number which will replace the corresponding fields in the existing record.

When this data structure is executed via the updateRecord function, the record corresponding to ID 123 in the database will be updated with the new contact information.