Skip to end of metadata
Go to start of metadata

Last Updated: Thursday, August 22, 2019



You can upload custom field data about any Persons in your Mobile Database, or Persons who may join your Mobile Database at some point in the future. This allows you to keep Vibes Mobile Engagement Platform in sync with updates that happen to your Customer Relationship Management (CRM) system. We recommend that you do a one-time load of initial data, then keep systems in sync with real-time Application Program Interface (API) calls. Alternatively, you can also provide a daily or weekly file to update the Platform to changes in your system.


Note: UTF-8 or ASCII encoding for integration files is recommended.

File Name 

<filename>.persons

File Format

The file format is a Comma-Separated Values (CSV) file. This stores tabular data (numbers and text) in plain text, where the line of the file is a data record. Each record consists of one or more fields, separated by commas.

When specifying data for a Date field, the format is "YYYY-MM-DDTHH:MM:SSZ" for UTC time, or "YYYY-MM-DDTHH:MM:SS-TTTT" where TTTT is the time offset.

Headers

You can include the following headers in your Person Import.

Note: Using headers is entirely optional.

Header Name

Description

Fields

This is a comma separated list of the fields that will be in the body of the text file. If omitted, then the first row of the body must contain the field names with the same delimiter as the body.

Delimiter

The character used to delimit the columns. Defaults to a comma ",".

Multi-Select-Delimiter

The character used to delimit the multi-select values within a column. Defaults to a pipe "|".

File Body

The file body can contain the following fields as data, separated by the delimiter.

Note: The field names must be lowercase.

Field Name

Data Type

Description

person_id

Integer

The Mobile Database Person ID to include in the file body when updating the Person record.

person_keyStringThe Person Key is a UUID to include in the Person Import. The person_key must be lowercase.

external_person_id

String

The external system's Person ID to include in the file body when updating the Person record.

mdn

String

A Mobile Directory Number (mdn) is the mobile_phone number to include in the file body when updating the Person record.

  • For non-US numbers, the Mobile Directory Number (mdn) must be in E.164 format.

Example:

mdn

+12295551234.

  • US numbers can use the 10-digit mdn format.

custom

String

A Person custom field.

Note: "Custom" is not a specific string. It means that any custom field name may be used in the data file.

For a particular row, only one of person_id, external_person_id, person_key, or mdn need to be specified, as these are alternate means of referencing a Person. If more than one value is specified, we will use the value with the highest precedence. The precedence order is shown in the table above.

Data

  • Data in the file will override existing data in the Platform.
  • The header row must match the name of the custom field.

Single and Multi-Select Fields

  • For single and multi-select fields, the "option key" should be specified, not the value or ID. Note: The option key is case sensitive.
  • For multi selects, use a "|" pipe symbol to delineate multiple values in the same field.

Error Messages

The following tables show the error codes that can occur when importing a file.

Row Level Errors

Error Class

Error Message

Description

MobilePhoneErrors::InvalidMDNFormat
The mdn is incorrectly formatted. It should be an E.164 mdn.
PersonErrors::CustomFieldNotFoundCustom field not foundThere is a custom field column in the file that doesn't map to a valid custom field.
PersonErrors::InvalidSelectCustomFieldValueCustom field value is incompatible with the field’s character setThe value for a string custom field contains characters outside the custom field's character set.
PersonErrors::InvalidSelectCustomFieldValueInvalid custom field valueThe value for a single-select or multi-select custom field in this row is not valid.
PersonErrors::PersonNotFoundPerson not foundThe given person_id or person_key doesn't point to an actual Person.
the mdn belongs to a person other than the one indicatedMobile Phone Already AssignedThe mdn is already associated with an existing person.
PersonErrors::InvalidPersonIDInvalid person_idThe person_id is incorrectly formatted.
PersonErrors::MdnChangeNotAllowedmdn change not allowedThe Person in this row already has an mdn.
PersonErrors::PersonCreateRequiresDeviceOrExternalPersonIdCreating a Person requires a device or an external person idThe row doesn't contain a value needed to create a Person. It is missing either a mdn, vibes_device_id, or external_person_id.
PG::UniqueViolationduplicate key value violates unique constraintThe external_person_id is already assigned to an existing person
CarrierLookupService::TransientLookupFailureError
A temporary issue with the carrier lookup service prevented the row from being processed. Please try again later.
CarrierLookupService::PermanentLookupFailureError
The mdn supplied is not a valid mobile phone active on a valid carrier.

File Level Errors

Error Class

Error Message

Description

PersonErrors::InvalidImportFileFormatCouldn't find a person_id, external_person_id, mdn, or vibes_device_id fieldThere is not a column in the file that identifies a Person.

Common Errors

The following errors can occur in imports of all file types.

File Level Errors

Error Class

Error Message

Description

TenantEngine::SchemaErrors::InvalidSchemaNameError

Schema name for company <company_id> (is nil|was not found)The company that the file is target for is not set up in MobileDB, or there was some other system level error.


Example File

file name: customer_test.persons
person_id,gender,first_name
56451,M,Sam
699554,F,Dianne
65234,F,Amy

See the attached files for additional examples of Person Import files.

  File Modified
File import_data_by_mdn.persons Jun 06, 2018 by dean.lappi
File import_data_by_person_id.persons Jun 06, 2018 by dean.lappi
File import_data.persons Dec 19, 2018 by dean.lappi
File multi_select.persons Jan 07, 2019 by Sam Benediktson

  • No labels

4 Comments

  1. When specifying data for a Date field the format is "YYYY-MM-DDTHH:MM:SSZ" for utc time or "YYYY-MM-DDTHH:MM:SS-TTTT" where the TTTT is the time offset.

    1. Unknown User (dean.lappi)

      I added this to the Headers table at the beginning of this topic. Can you verify this was the correct place and what I added is accurate?

      Fields

       

      No

      This is a comma separated list of the fields that will be in the body of the text file. If omitted, then the first row of the body must contain the field names with the same delimiter as the body.

      When specifying data for a Date field, the format is "YYYY-MM-DDTHH:MM:SSZ" for UTC time, or "YYYY-MM-DDTHH:MM:SS-TTTT" where TTTT is the time offset.

  2. The option keys for select fields are case sensitive

    1. Unknown User (dean.lappi)

      Added as a note under single and multi-select fields.