Document toolboxDocument toolbox

(v1) .Contacts Imports v2.1.4.7

Capability

The Contact Import allows Users to Import records into the Workers / Contacts Grid.

Matches On

The Contact first attempts to match the Customer Number then the Email Address. If there is no match, the record from the Import will INSERT. If there is a match, the remaining fields can UPDATE.

The Import process can be optionally set with Conditional Logic to match on the First Name and Last Name fields with the flag CONTACTS_CHECK_NAMES. See the Conditional Logic section for more information. First Name and Last Names, ONLY IF FLAGS.CONTACTS_CHECK_NAMES is True. If a match is found, that Contact can UPDATE.

Fields

First Name

Required

Datatype is String.

Cannot UPDATE if the CONTACTS_CHECK_NAMES is True in the Conditional Logic.

If no First Name is found, the Import File will INSERT the First Name.

Last Name

Required

Datatype is String.

Cannot UPDATE if the CONTACTS_CHECK_NAMES is True in the Conditional Logic.

If no Last Name is found, the Import File will INSERT the Last Name.

Directory

Datatype is Boolean.

Defaults to False [0].

Permitted Values are 1, Yes, True, and Active

Permitted Values sets the Directory to True [1] (Yes).

All other values enter as False [0].

Contact Type

Required

Datatype is String.

Permitted values are from the CUSTOMER_TYPE (v1) List Values: User, Coordinator, Guest, Service Rep, Vendor, VIP, and Worker.

Any values added by a User to the CUSTOMER_TYPE list can also be used.

The Contact Type can be provided as an array in the Conditional Logic to allow assigning multiple values.

These values can be hard coded into the Conditional Logic, or they can come from multiple fields in the input file.

If any Contact Type value is provided, it always replaces any existing value.

If the Contact Type is Coordinator, the following fields are available:

Billing Group

Conditionally Required

Datatype is String.

Allow Coordinator Bill Email

Datatype is Boolean.

Default value is False.

If the Contact Type is Customer, the following fields are available.

Customer Number

Conditionally Required

Datatype is String.

Cannot UPDATE existing records.

If no match is found, the Import File will INSERT the Customer Number.

Billing Group

Conditionally Required

Datatype is String.

Title

Datatype is String.

Permitted values are Staff, Faculty, Director, Secretary, and any other value from the Title List Values.

Dept. Hierarchy

Datatype is String.

Permitted values must be the full Dept. Hierarchy Path and Code values not the Department Hierarchy Name field.

If the Contact Type is User, the following fields are available.

Approval GLA

Datatype is String.

For the first occurrence of a Contact in the import file, if a GLA Approval value is provided, this will replace the entire list of existing GLA Approvals for this Contact. Successive lines in the import file will append GLA Approvals. There is no way to just append individual values. The entire list will get replaced by the import.

Each GLA value must be on a separate line of Import File.

"NONE" removes all GLA entries from the Approval GLAs.

Permitted values are NONE or any valid GLA.

Minimum Amount

Datatype is String.

Maximum Amount

Datatype is String.

Default GLA

Datatype is String.

Default SLA

Datatype is String.

Default Incident SLA

Datatype is String.

Street Address

Datatype is String.

If any Address field holds a value, all except for the Address2 field becomes Required.

Address2

Datatype is String.

City

Datatype is String.

State

Datatype is String.

Permitted values must be the 2 letter, all caps abbreviation (MI) or the full state name with an uppercase first letter (Michigan).

All other values are ignored.

Zip Code

Datatype is String.

Address Type

Datatype is String.

Blank values are NOT allowed.

Permitted values are from the ADDRESS_TYPE (v1) List Values: Billing, Warehouse, or Office.

Any values added by a User to the ADDRESS_TYPE list can also be used.

Values not in the List are not added.

Email

Datatype is String.

Cannot UPDATE if the value exists.

Otherwise the Email will INSERT.

Permitted GLA

Datatype is String.

Permitted Values are NONE, ALL, or any valid GLA. NONE removes all entries in the list and add the Permit None record.

ALL removes all entries in the list and allow any GLA to be used.

For the first occurrence of a Contact in the import file, if a GLA Permission value is provided, this will replace the entire list of existing GLA Permissions for this Contact. Successive lines in the import file will append GLA Permissions. There is no way to just append individual values. The entire list will get replaced by the import.

Adding any valid GLA to the list removes the Permit None record.

To add multiple Permitted GLAs, each must be on a separate line of the Import File.

Phone

Datatype is String.

Multiple Primary Phone Numbers cause an error.

Status

Datatype is String.

Default value is Active unless the CONTACTS_INSERT_INACTIVE flag is set to True.

Permitted values are Active and Inactive.

Flags / Conditional Logic

UPDATE_CONTACT_EMAIL:

Default Value is True.

  • True: If True and the provided email address is not associated with the Contact, the Import adds the provided Email Address to the Contact and makes it the Primary Email Address. Any previous Email Address values are left in the list. This Import never updates or removes existing Email Addresses.
  • False: If this flag is False, the email field is not saved.

UPDATE_CONTACT_PHONE:

Default Value is True.

  • True: If the provided phone is not in the Contact, the Import appends the provided Phone to the Contact and makes it the Primary Phone. If the Phone Number is already on the Contact, the Primary flag does not change. Any previous Phone values are left on the list. This Import never updates or removes existing phone numbers.
  • False: The Phone field is not saved.

UPDATE_CONTACT_ADDRESS:

Default Value is True.

  • True: The Import will UPDATE the existing Contact Address.
  • False: The Import does not save the Contact Address.

CONTACTS_CHECK_NAMES:

Default Value is False.

  • True: The First Name and Last Name are used to see if the Contact already exists. If BOTH First Name and Last Name match, the Contact is considered matched, and the Import attempts to UPDATE the existing record with the data from the Import File. Otherwise, the Import attempts to INSERT the Import Record.
  • False: This check is not performed.

NEW_CONTACT_DEFAULT_BILLING_GROUP:

Default Value is Blank.

  • This sets the Billing Group value for new Customer Contacts.

NEW_CONTACT_DEFAULT_CONTACT_TYPE:

Default Value is Blank.

  • This sets the Contact Type value for new Customer Contacts.

CONTACTS_INSERT_INACTIVE:

Default Value = False

  • True: If set to True, new Contacts attempts to INSERT with an Inactive Status.
  • False: If set to False, the new Contact attempts to INSERT with an Active Status.

Errors

There are a large number of possible errors for Imports. There are two types: errors that prevent the record from importing, and those that don't but cannot update related Import record information.

The following errors occur if the Contact INSERT or UPDATE fails:

  • Error : No Contact Number or Name or Email specified
  • Error : Found multiple duplicate customer numbers and emails in existing records for Customer Number <customerNumber>
  • Error : Found multiple duplicate names in existing records for Name <firstName> <lastName>
  • Error : FLAGS.NEW_CONTACT_DEFAULT_CONTACT_TYPE value '<defaultContactType>' is invalid
  • Error : Billing group is required for new Customer contacts for Contact '<contactId>'
  • Error : Failed to save Contact record <database error Message>

These do NOT cause the Contact INSERT or UPDATE to fail. The Contact will INSERT or UPDATE. However, the subsequent Child record may have a warning generate, and the child record is not added to the Contact. They are non-essential for the Contact, or they happen after the Contact save.

  • Warning : Could not find the Permission GLA for <GLA>
  • Warning : Could not find the Dept Hierarchy '<Dept Hierarchy>' for Contact '<contactId>'
  • Warning : Could not find Default SLA '<Default SLA Catalog>' for Contact '<contactId>'
  • Warning : Could not find Default Incident SLA '<Default Incident SLA Catalog>' for Contact '<contactId>'
  • Warning : Could not find Default GLA '<Default GLA>' for Contact '<contactId>'
  • Warning : Could not find Billing Group '<Billing Group>' for Contact '<contactId>'
  • Warning : Minimum Amount is greater than Maximum Amount for Approval GLA '<Approval GLA>' for Contact '<contactId>'
  • Warning : Could not find Approval GLA '<Approval GLA>' for Contact '<contactId>'
  • Warning : Contact '<contactId>' is not type User, so cannot have Approval GLAs"; "Error adding email, email belongs to someone else

These errors are caused as a result of Child data conflicts. The Import Validation should catch these before the Import is attempted. However, if an edge case is missed, these errors are presented to the User. Their occurrence should be rare.

  • Error adding email
  • Error adding phone number
  • Error : Failed to save Address record <database error Message>
  • Error : Failed to Add Contact Address record; <database error Message>
  • Error : Failed to Save null GLARestrict record; <database error Message>
  • Error : Failed to Save GLA Restrict record; <database error Message>
  • Error : Failed to Save GLA Approval record; <database error Message>
  • Error : Failed to Save Contact Type record; <database error Message>

Notes

The Import first checks if the Contact information you are providing matches an existing record. For each of the following fields, it tries to find an existing match if you provide a non-empty value. It stops searching when it finds a match.

  • Customer Number
  • Email address
  • First Name and Last Names ONLY IF FLAGS.CONTACTS_CHECK_NAMES is True. If a match is found, the Import will UPDATE that Contact.

UDF Associations

User Defined Fields on any given Import are all handled the same way with Conditional Logic. For more information about adding a UDF to the Import, see the (v1) User Defined Fields section of the Imports main page.

Help Desk Portal - Email: help@pcr.com - Phone: 616.259.9242