1. Batch Processing and Web Services Guide
  2. Customer Requests

2 Customer Requests

This chapter provides developers with request formats for customer requests sent to the Customer Engagement application. The following requests are recognized by the Customer Engagement application:

Customer Validation

Note:

Whether Customer Validation is performed or not is configurable. Contact your Project Manager for details.

Whenever a new customer is added, the customer information (first name, last name, prefix, suffix, gender, address, postal code, phone number, and email address) is validated. If any of the information provided does not meet the criteria of the Customer Engagement application, the customer, address, phone, or email address is marked as invalid and a validation error is recorded. This does not affect how the information is saved or used, it just means the information did not meet the criteria.

If, during the add process, information is missing or incorrect; a validation error is generated and recorded in the database.

Names

All numbers, punctuation, and any repeating spaces except (, -, ‘, or) are removed from the first, middle, and last names. The first letter of each name, if applicable, is capitalized. If the middle initial is included as part of the first or last name, it is stripped out and saved into the data object.

If the first or last name is missing, the customer is marked as invalid and the appropriate validations errors are generated.

Prefix (Salutation)

The prefix is checked to see if it matches or is very close to one of the following:

Mr

Miss

Mrs

Ms

Dr

Imam

Rev.

Sir

Sister

Father

Hon.

HRH

If the prefix does not match or is not close, the customer is marked as invalid and a validation error is generated. If the prefix is close (for example, MR rather than Mr) the prefix will be changed to the format above.

Suffix

The suffix is checked to see if it matches or is very close to one of the following:

Table 2-1 Suffix Table

Esq.

Sr.

Jr.

II

III

IV

V

2nd

3rd

4th

If the suffix does not match or is not close, the customer is marked as invalid and a validation error is generated. If the suffix is close (for example, sr rather than Sr.) the suffix will be changed to the format above.

Gender

Any value can be entered for gender as long as the value starts with M, m, or 1 for male and F, f, W, w, or 0 for female. If one of these values is found, the value is replaced with M or F and saved. If one of these values is not found; the original value is saved, the customer is marked as invalid, and a validation error is generated.

Address

The address does not need to be complete. Partial addresses are created.

Postal Code

Any non-numerical or non-alphabetic characters except for -, , and . are removed from the postal code. If the results do not match 99999, 99999-9999, or A1A1A1 the address is marked as invalid and a validation error is generated.

Email Address

The system looks for a @ in the email address. If found, the system verifies that the email address is in the proper format: accountname@sub-domain.domain. If there is no @ symbol, the system looks for a # symbol. If one is found, it is replaced with an @ symbol and the system verifies that the email address is in the proper format. If the email address is in the wrong format, the email address is marked as invalid and a validation error is generated.

Phone

The application looks for and removes any non-numeric character except for E, e, X, x, T, or t. Any leading 1 characters are removed. If the phone number starts with a 0, the phone is marked as invalid and a validation error is generated.

The extension, if any, is identified, removed, and saved in the extension field.

Area Code

The telephone area code is not in the schema and cannot be included in a request as a separate item. Therefore, you must include the area code in the telephone number. If the telephone number is 10 digits in length (excluding alpha and special characters), the first three digits of the telephone number are used as the area code.

If the telephone number is eleven digits in length (excluding alpha and special characters) and starts with a 1, the second, third, and fourth digits of the telephone number are used as the area code. If the telephone number starts with anything other than a 1, none of the digits are used as the area code.

Customer Attributes

Custom attributes provide a flexible way for retailers to customize the customer database and describe individual customers. Custom attributes are added or updated according to the following rules:

  • When updating custom attributes, all old values are deleted and the new value(s) added in their place. A new attribute cannot simply be added to the list of old ones, it must be sent as part of the entire list.

  • If an update request contains an empty value tag in the <CustomAttribute> section, all current values in the database for that attribute are deleted.

  • Data types are enforced during the customer add or customer update. Logical can only be Yes/No, Number must be numeric, etc. If an incorrect format is used, an error response will be returned, and the customer add/update will be rejected.

    • If the attribute type is Date, the date should be in MM-DD-YYYY format.

  • If the attribute type is List and a value which is not defined in the list is provided in a customer add/update, the add/update request will be rejected (failed).

  • Some attribute types have an Editable option. If the attribute is not editable, once it is defined it cannot be updated through web services.

  • A Unique attribute type defines whether Customer Engagement can accept more than one attribute for that type per customer, or, whether only one attribute can be provided (unique).

    For example: Customer’s Favorite Color:

    • Unique = Yes - Only one favorite color can be specified

    • Unique = No - More than one favorite color can be specified.

Note:

Information that maps to a Customer’s identity is not protected if stored in Customer Attributes. Oracle does not recommend using Customer Attributes to store personal data.

Multiple Actions

Do not try to perform more than one action on the same customer in the same batch file. Due to the method in which records are processed and saved to the database, performing more than one action on the same customer may have undesired results.

Multiple Names

Customer Engagement allows for second first and last names. This feature is configurable by organization. Although these names are included in the Fields tables in some of the customer requests, some organizations may not be configured to use these names.

Including these additional names in a request when your organization is not configured to use them will not cause any harm.

Primary Telephone/Address/Email

Customer Engagement will only allow one primary phone number, address, or email address regardless of type (Home, Business, Work, and so on) or active status (active or inactive). If you try to add more than one primary phone, address, or email address in a Add Customer request, Customer Engagement will assign the last phone, address, or email address processed as the primary.

If you already have a primary phone, address, or email address designated (active or inactive) and you try to add another primary phone, address, or email address in an Update Customer request, Customer Engagement will make the phone, address, or email address in the request the primary and demote existing primary phone, address, or email address.

Empty XML Tags

When processing batch files, do not include empty XML tags (that is, <Name></Name>). These empty tags will generate warnings that are placed in the log files. These warnings will not affect the operation of Customer Engagement but may unnecessarily increase the size of the log files. These warnings can be reviewed using the Batch Import Review pages (see Batch Import Review).

Add Customer

The purpose of this action is to add a new customer to the client’s active customer database.

All customer data can be duplicated with the exception of <AlternateID> and <CustID> data. As customers are added, they are assigned a unique Customer Engagement <CustomerID>. You can have several customers with the same names, addresses, emails, and phones; but they must have unique <AlternateID> values.

Note:

If a CustomerID is included in the batch file, the server will ignore it and generate a new one.

Anonymous Customer

An anonymous customer (see Anonymous Customer) can be created by including an Add request with only an alternate ID.

Fields

The elements in the table below are the elements that can be included in an add customer request. The placement/use of these elements is shown in the sample.

Table 2-2 Elements

XML Tag Description

<Prospect>

Indicates whether the customer is a prospect.

<Source>

This is the source for the customer.

<BusinessName>

This is the name of the business associated with the customer.

<CustomerClass>

This is the class to which the customer belongs.

<CustomerID>

Customer Engagement Customer ID. Ignored in this request type.

<RetailStoreID>

This is the location where the request originated.

<SignupDate>

This is the date the customer signed up.

<CustomerNumber>

<CustomerReference>

<OrgName>

This is the name of the organization.

<CustOrgTypcode>

The type of organization (for example, School, Club, and so on)

<EmployeeID>

This is the employee ID or employee code.

<LastUpdateInfo>

<UpdateUserID>

User ID of person/POS adding customer.

<UpdateDate>

Date customer is added. Format = 2015-07-24T15:25:27 (timestamp). If date is left off, Customer Engagement will fill in local time.

<Affiliation Action="Add">

<RetailStoreID>

This is the customer’s home location.

<Individual>

<Suffix>

A title that comes after a person’s name. See Fields.

<Name>

First, Middle, and Last names of the customer.

<Name Location="First" />

Location: Position of name: First, First2, Middle, Last, or Last2. For descriptions of First2 and Last2 names, see Multiple Names.

<Name Location="First2" />

<Name Location="Middle"/>

<Name Location="Last" />

<Name Location="Last2" />

<Salutation>

A formal prefix that comes before a person’s name. See Fields.

<Nickname>

A nickname that the customer has provided.

<Address PrimaryFlag=" "

PrimaryFlag: true = customer’s primary address, false = not the customer’s primary address. If this attribute is missing, the default is false. Only one primary address is permitted regardless of TypeCode.

ValidFlag=" "

ValidFlag: true sets the Valid Flag to true regardless of the results of Customer Engagement’s internal validation. See Address for Validation information.

Label=" "

Label: The label used for the address.

ContactPreferenceCode=" "

ContactPreferenceCode: Code indicating the customer contact preferences for the email address.

TypeCode=" ">

TypeCode: Indicates the type of the address (e.g. HOME or BUSINESS).

<Country>

Country where the customer lives.

<AddressLine1>

First line of the address.

<AddressLine2>

Second line of the address.

<AddressLine3>

Third line of the address.

<AddressLine4>

Fourth line of the address.

<ApartmentNumber>

Apartment number.

<City>

City

<Territory>

State or province. Be consistent in use of abbreviation or full name.

<PostalCode>

Postal/Zip code.

<County>

County or parish.

<EMail PrimaryFlag=" "

PrimaryFlag: true = customer’s primary email address, false = not the customer’s primary email address. If this attribute is missing, the default is false. Only one primary email is permitted regardless of TypeCode.

ValidFlag=" "

ValidFlag: true sets the Valid Flag to true regardless of the results of Customer Engagement’s internal validation. See Email Address for Validation information.

Label=" "

Label: The label used for the email address.

ContactPreferenceCode=" "

ContactPreferenceCode: Code indicating the customer contact preferences for the address.

TypeCode=" ">

TypeCode: Indicates the type of the Email address (for example, HOME or BUSINESS).

<EMailAddress>

Email address.

<Telephone PrimaryFlag=" "

PrimaryFlag: true = customer’s primary telephone, false = not the customer’s primary telephone. If this attribute is missing, the default is false. Only one primary phone is permitted regardless of TypeCode.

ValidFlag=" "

ValidFlag: true sets the Valid Flag to true regardless of the results of Customer Engagement’s internal validation. See Phone

for Validation information.

Label=" "

Label: The label used for the telephone number.

ContactPreferenceCode=" "

ContactPreferenceCode: Code indicating the customer contact preferences for the telephone.

TypeCode=" ">

TypeCode: Indicates the type of telephone (e.g. HOME or BUSINESS).

<PhoneNumber>

Telephone number.

<Extension>

Telephone extension.

<PersonalSummary>

<GenderType>

Gender. Must start with M, m, or 1 for male or F, f, W, w, or 0 for female. See Gender.

<BirthDate>

Date of birth (Format = YYYY-MM-DD). The use of any other format will result in the BirthDate not being written to the database.

<MaritalStatusCode>

Marital status.

<Ethnicity>

Ethnic background.

<LanguageCode>

The 2-letter ISO language code for the customer’s preferred language.

<Rent>

Indicates whether the customer is part of a rented customer list.

<SocioEconomicProfile>

<HighestEducationalLevelName>

Highest level of education. Must be SECONDARY, BACHELORS, GRADUATE, or PHD. This field is limited to 10 characters.

<AnnualIncomeAmount>

Amount the customer earns annually (must be a whole number between 0 and 100,000,000).

<NetWorth>

Value of customer’s assets (must be a whole number between 0 and 1,000,000,000,000).

<PersonalPreferences>

<ContactPreference>

Specifies if and how the customer wants to be contacted.

ContactType=" "

ContactType: Method used to contact customer. Can be Mail, Email, Phone, or Fax.

SubTypeCode=" "

SubTypeCode: Customer location for contact. Must be HOME for Mail, Email, and Phone. Must be FAX for Fax.

Permission=" ">

Permission: true - customer gives permission to be contacted via ContactType, false - customer does not give permission to be contacted via ContactType.

<AlternateKey TypeCode=" ">

TypeCode: The type of alternate key (e.g. EMAIL, PHONE, TWCUSTID, and so on).

<AlternateID>

Unique number/code for the specific type of alternate key.

Note: Information that maps to a Customer’s identity is not protected if stored in Alternate Keys. Oracle does not recommend using Alternate Keys to store personal data

<CustomAttribute name=" ">

User-defined customer attributes.

name: The name of the attribute. Name must be defined in dtv_attribute_type database table (Note lowercase n).

<AttributeValue>

The value of the attribute; must be of the type defined for the attribute. If the attribute is a list, the value must match a value contained in the dtv_attribute_type_value table.

Information that maps to a Customer’s identity is not protected if stored in Customer Attributes. Oracle does not recommend using Customer Attributes to store personal data.

<CustomerNotes>

User-entered customer notes.

<CustomerNote

The text of the customer note. There is no maximum number of CustomerNotes for a request. A customer note sent to Customer Engagement will always be added, not updated. However, an AddOrUpdate or Update request will check for duplicate comments to prevent note duplication.

type=""

The type of note. The type is specified by the user and can have any value. All notes without a specified type will be given a note type of COMMENT.

createDate=" "

Date the note was created.

createUser=" "

ID for the user who created the note.

location=" ">

ID for the location where the note was created.

action=""

Indicates whether to ADD, UPDATE, or DELETE a customer note.

sequence=""

Indicates the sequence number of the note.

privateFlag=""

Indicates if the note content is private.

Note: Information that maps to a Customer’s identity is not protected if stored in Customer Notes. Oracle does not recommend using Customer Notes to store personal data.

Not all of these elements have to be used in any one request.

If any fields other than the ones listed above are included in a request, they will be ignored.

Example

An Add request should appear similar to the example below. The customer data included in the body will vary according to each particular request. The <Customer> block is highlighted below.

If the request is in a batch file and more than one customer is being added, there should be multiple <Customer> blocks 

  <?xml version="1.0" encoding="UTF-8"?>
  <Customers>
    <Customer Action="Add">
      <LastUpdateInfo>
        <UpdateUserID><USERID></UpdateUserID>
        <UpdateDate>2015-04-15</UpdateDate>
      </LastUpdateInfo>
      <RetailStoreID>HOME_OFFICE</RetailStoreID>
      <SignupDate>2006-07-13</SignupDate>
      <CustomerNumber><CUSTOMER_NUMBER></CustomerNumber>
      <CustomerReference><CUSTREF>/CustomerReference>
      <OrgName><ORG_NAME></OrgName>
      <CustOrgTypcode>Company</CustOrgTypcode>
      <EmployeeID><USERID></EmployeeID>
      <Affiliation>
        <RetailStoreID>243</RetailStoreID>
      </Affiliation>
      <Prospect>true</Prospect>
      <Source>StoreWalkIn</Source>
      <BusinessName><BUSINESS_NAME></BusinessName>
      <CustomerClass>BusinessClass</CustomerClass>
      <EntityInformation>
        <Individual>
          <Suffix></Suffix>
          <Salutation>MR</Salutation>
          <NickName><NICKNAME></NickName>
          <Name>
            <Name Location="First"><FIRST></Name>
            <Name Location="First2"></Name>
            <Name Location="Middle"></Name>
            <Name Location="Last"><LAST></Name>
            <Name Location="Last2"></Name>
          </Name>
          <ContactInformation>
            <Address PrimaryFlag="true" ValidFlag="true" 
                     TypeCode="HOME" 
                     ContactPreferenceCode="Order Info Only" 
                     Label="Special Address label">
              <AddressLine1><ADDRESS></AddressLine1>
              <AddressLine2></AddressLine2>
              <AddressLine3></AddressLine3>
              <AddressLine4></AddressLine4>
              <ApartmentNumber></ApartmentNumber>
              <City>Oklahoma City</City>
              <Territory>OK</Territory>
              <PostalCode>49136</PostalCode>
              <County>Desert</County>
              <Country>US</Country>
            </Address>
            <EMail PrimaryFlag="true" TypeCode="HOME"
                   ContactPreferenceCode="Promotion Info Only"
                   Label="Special Email Address label">
              <EMailAddress>f<USERID>@<TNS_ALIAS>             </EMailAddress>
            </EMail>
            <Telephone PrimaryFlag="true" TypeCode="HOME"
                       ContactPreferenceCode="No Phone Contact" 
                       Label="Special Phone Address label">
              <PhoneNumber>4405550100</PhoneNumber>
              <Extension></Extension>
            </Telephone>
          </ContactInformation>
          <PersonalSummary>
            <GenderType>M</GenderType>
            <BirthDate><BIRTHDATE></BirthDate>
            <MaritalStatusCode>MARRIED</MaritalStatusCode>
            <Ethnicity></Ethnicity>
            <Rent>true</Rent>
            <LanguageCode>FR</LanguageCode>
          </PersonalSummary>
          <SocioEconomicProfile>
            <HighestEducationalLevelName>PHD
            </HighestEducationalLevelName>
            <AnnualIncomeAmount>123456</AnnualIncomeAmount>
            <NetWorth>1234567</NetWorth>
          </SocioEconomicProfile>
        </Individual>
      </EntityInformation>
      <PersonalPreferences>
       <ContactPreference ContactType="Mail" SubTypeCode="HOME" 
        Permission="true"></ContactPreference>
       <ContactPreference ContactType="Email" SubTypeCode="HOME"
        Permission="false"></ContactPreference>
       <ContactPreference ContactType="Phone" SubTypeCode="HOME"
        Permission="false"></ContactPreference>
       <ContactPreference ContactType="Fax" SubTypeCode="FAX" 
         Permission="true"></ContactPreference>
      </PersonalPreferences>
      <AlternateKey TypeCode="TWCUSTID">
        <AlternateID>0000000043</AlternateID>
      </AlternateKey>
      <CustomAttribute name="Spending Level">
        <AttributeValue>Silver</AttributeValue>
        <AttributeValue>Gold</AttributeValue>
        <AttributeValue>Platinum</AttributeValue>
      </CustomAttribute>
      <CustomerNotes>
       <CustomerNote action="UPDATE" createDate="2017-09-22"         createUser="<USERID>" type="COMMENT" location="<LOCATION>"
         sequence="326212" privateFlag="false">sample note content
        </CustomerNote>
      </CustomerNotes>
    </Customer>
  </Customers>

Batch Processing Errors

The following table contains a list of errors that may occur and possible causes:

Error Cause

ALTERNATE_KEY_TYPECODE_UNSPECIFIED

A typecode was not specified for an alternate key to be added.

ALTERNATE_KEY_VALUE_UNSPECIFIED

A value was not specified for an alternate key to be added.

ATTRIBUTE_VALUE_TOO_LARGE

Number of characters or numbers exceed field length.

CUSTOMER_ALREADY_EXISTS

The customer being added already exists in the database, with the same alternate keys.

CUSTOMER_NOTE_EMPTY

Customer note parameters defined, but the customer note is blank

GENERAL_ERROR

A general, non-specific error. If you cannot determine the cause of the problem, contact your Project Consultant.

INVALID_ATTRIBUTE_VALUE

Invalid data based on attribute type. For example, characters included in a value for a numeric attribute.

INVALID_DATE_FORMAT

The data in a date field is not valid date information.

MULTIPLE_VALUES_ON_UNIQUE_ATTRIBUTE_TYPE

The request includes multiple values for an attribute defined as unique.

NAME_POSITION_INVALID

The location (e.g. First, Last, First2, etc.) of the name element is not specified, or the location is not valid.

UNKNOWN_ATTRIBUTE_TYPE

Unknown attribute type.

VALUE_NOT_IN_ENUMERATED_ATTRIBUTE_TYPE_VALUES

The value entered for an attribute is not among the possible enumerated values.

Batch File Response

A complete copy of the incoming request is placed in the /complete/[Fileset Name]/archived directory.

Each <Customer> block in the request that was not successfully processed is placed in a file with _failures appended to the original filename in the /complete/[Fileset Name]/failed directory.

You may be able to determine the reason for the failure by using the Batch Import Review pages (see Batch Import Review).

Add or Update Customer

The purpose of this action is to add a new customer to the client’s active customer database or update an existing customer.

  • If a customer in the file does not already exist in the database, he/she will be added as a new customer.

  • If a customer in the file already exists in the database, the customer record will be updated.

  • If a customer Address, Email Address, Phone Number, or Alternate Key included in the request exactly matches the existing information in the database, that information is not updated.

  • If a customer Address, Email Address, Phone Number, or Alternate Key that does not exist in the database is included in the request, all other corresponding elements of the same type that are already in the database will be deactivated and the included element added.

If Alternate Keys are included in the request, they will first be used as a lookup. After the customer in the request is either added or updated, any Alternate Keys not in the database, but in the request, will be added.

All customer data can be duplicated between customers, with the exception of <AlternateID> and <CustomerID>. You can have several customers with the same names, addresses, emails, and phones; but each must have a unique <AlternateID>. As each customer is added, they are assigned a unique Customer Engagement <CustomerID>.

Note:

If a CustomerID is included in the request, Customer Engagement will try to locate the customer to update based on the Customer ID and Alternate Keys. If the customer is not found, a new Customer ID will be generated, ignoring the included Customer ID.

Anonymous Customer

An anonymous customer (see Anonymous Customer) can be created by sending an Add or Update Customer request with only an alternate ID.

Fields

The elements in the table below are the elements that can be included in an add or update request. The placement/use of these elements is shown in the sample.

Not all of these elements have to be used in any one request�.

XML Tag Description

<CustomerID>

Customer Engagement Customer ID.

<Prospect>

Indicates whether the customer is a prospect.

<Source>

This is the source for the customer.

<BusinessName>

This is the name of the business associated with the customer.

<CustomerClass>

This is the class to which the customer belongs.

<RetailStoreID>

This is the location where the request originated.

<SignupDate>

This is the date the customer signed up.

<CustomerNumber>

<CustomerReference>

<OrgName>

This is the name of the organization.

<CustOrgTypcode>

The type of organization (for example, School, Club, and so on.)

<EmployeeID>

This is the employee ID or employee code.

<LastUpdateInfo>

<UpdateUserID>

User ID of person/POS adding customer.

<UpdateDate>

Date customer is added. Format = 2015-07-24T15:25:27 (timestamp). If date is left off, Customer Engagement will fill in local time.

<Affiliation Action="Add">

<RetailStoreID>

This is the customer’s home location.

<PersonalPreferences>

<ContactPreference>

Specifies if and how the customer wants to be contacted.

ContactType=" "

ContactType: Method used to contact customer. Can be Mail, Email, Phone, or Fax.

SubTypeCode=" "

SubTypeCode: Customer location for contact. Must be HOME for Mail, Email, and Phone. Must be FAX for Fax.

Permission=" ">

Permission: true - customer gives permission to be contacted via ContactType, false - customer does not give permission to be contacted via ContactType.

<Individual>

<Suffix>

A title that comes after a person’s name. See Fields.

<Name>

First, Middle, and Last names of the customer.

<Name Location="First" />

Location: Position of name: First, First2, Middle, Last, or Last2. For descriptions of First2 and Last2 names, see Multiple Names.

<Name Location="First2" />

<Name Location="Middle"/>

<Name Location="Last" />

<Name Location="Last2" />

<Salutation>

A formal prefix that comes before a person’s name. See Fields.

<Nickname>

A nickname that the customer has provided.

<Address PrimaryFlag=" "

PrimaryFlag: true = customer’s primary address, false = not the customer’s primary address. If this attribute is missing, the default is false. Only one primary address is permitted regardless of TypeCode.

ValidFlag=" "

ValidFlag: true sets the Valid Flag to true regardless of the results of Customer Engagement’s internal validation. See Address for Validation information.

Label=" "

Label: The label used for the address.

ContactPreferenceCode=" "

ContactPreferenceCode: Code indicating the customer contact preferences for the email address.

TypeCode=" ">

TypeCode: Indicates the type of the address (for example, HOME or BUSINESS).

<Country>

Country where the customer lives.

<AddressLine1>

First line of the address.

<AddressLine2>

Second line of the address.

<AddressLine3>

Third line of the address.

<AddressLine4>

Fourth line of the address.

<ApartmentNumber>

Apartment number.

<City>

City

<Territory>

State or province. Be consistent in use of abbreviation or full name.

<PostalCode>

Postal/Zip code.

<County>

County or parish.

<EMail PrimaryFlag=" "

PrimaryFlag: true = customer’s primary email address, false = not the customer’s primary email address. If this attribute is missing, the default is false. Only one primary email is permitted regardless of TypeCode.

Label=" "

Label: The label used for the email address.

ContactPreferenceCode=" "

ContactPreferenceCode: Code indicating the customer contact preferences for the address.

TypeCode=" ">

TypeCode: Indicates the type of the Email address (e.g. HOME or BUSINESS).

<EMailAddress>

Email address.

<Telephone PrimaryFlag=" "

PrimaryFlag: true = customer’s primary telephone, false = not the customer’s primary telephone. If this attribute is missing, the default is false. Only one primary phone is permitted regardless of TypeCode.

Label=" "

Label: The label used for the telephone number.

ContactPreferenceCode=" "

ContactPreferenceCode: Code indicating the customer contact preferences for the telephone.

TypeCode=" ">

TypeCode: Indicates the type of telephone (for example, HOME or BUSINESS).

<PhoneNumber>

Telephone number.

<Extension>

Telephone extension.

<PersonalSummary>

<GenderType>

Gender. Must start with M, m, or 1 for male or F, f, W, w, or 0 for female. See Gender.

<BirthDate>

Date of birth (Format = YYYY-MM-DD). The use of any other format will result in the BirthDate not being written to the database.

MaritalStatusCode>

Marital status.

<Ethnicity>

Ethnic background.

<LanguageCode>

The 2-letter ISO language code for the customer’s preferred language.

<Rent>

Indicates whether the customer is part of a rented customer list.

<SocioEconomicProfile>

<HighestEducationalLevelName>

Highest level of education. Must be SECONDARY, BACHELORS, GRADUATE, or PHD. This field is limited to 10 characters.

<AnnualIncomeAmount>

Amount the customer earns annually (must be a whole number between 0 and 100,000,000).

<NetWorth>

Value of customer’s assets (must be a whole number between 0 and 1,000,000,000,000).

<AlternateKey TypeCode=" ">

TypeCode: The type of alternate key (for example, EMAIL, PHONE, TWCUSTID, etc.).

<AlternateID>

Unique number/code for the specific type of alternate key.

Note: Information that maps to a Customer’s identity is not protected if stored in Alternate Keys. Oracle does not recommend using Alternate Keys to store personal data

<CustomAttribute name=" ">

User-defined customer attributes.

name: The name of the attribute. Name must be defined in dtv_attribute_type database table (Note lowercase n).

<AttributeValue>

The value of the attribute; must be of the type defined for the attribute. If the attribute is a list, the value must match a value contained in the dtv_attribute_type_value table.

Information that maps to a Customer’s identity is not protected if stored in Customer Attributes. Oracle does not recommend using Customer Attributes to store personal data.

<CustomerNotes>

User-entered customer notes.

<CustomerNote

The text of the customer note. There is no maximum number of CustomerNotes for a request. A customer note sent to Customer Engagement will always be added, not updated. However, an AddOrUpdate or Update request will check for duplicate comments to prevent note duplication.

type=""

The type of note. The type is specified by the user and can have any value. All notes without a specified type will be given a note type of COMMENT.

createDate=" "

Date the note was created.

createUser=" "

ID for the user who created the note.

location=" ">

ID for the location where the note was created.

action=""

Indicates whether to ADD, UPDATE, or DELETE a customer note.

sequence=""

Indicates the sequence number of the note.

privateFlag=""

Indicates if the note content is private.

Note: Information that maps to a Customer’s identity is not protected if stored in Customer Notes. Oracle does not recommend using Customer Notes to store personal data.

If any fields other than the ones listed above are included in a request, they will be ignored.

Example

An Add or Update Customer request should appear similar to the example below. The customer data included in the body will vary according to each particular request. The data that is added is in boldface.

If more than one customer is being added or updated in a batch file, there should be multiple <Customer> blocks. 

<?xml version="1.0" encoding="UTF-8"?>
<Customers>
  <Customer Action="AddorUpdate">
    <LastUpdateInfo>
      <UpdateUserID><USERID></UpdateUserID>
      <UpdateDate>2015-04-15</UpdateDate>
    </LastUpdateInfo>
    <RetailStoreID><STORE_ID></RetailStoreID>
    <SignupDate>2006-07-13</SignupDate>
    <CustomerNumber><CUST_NO></CustomerNumber>
    <CustomerReference>CUSTREF</CustomerReference>
    <OrgName><ORG_NAME></OrgName>
    <CustOrgTypcode>Company</CustOrgTypcode>
    <EmployeeID><USERID></EmployeeID>
    <Affiliation>
      <RetailStoreID><STORE_ID></RetailStoreID>
    </Affiliation>
    <Prospect>true</Prospect>
    <Source>XstoreWalkIn</Source>
    <BusinessName>Sample Business</BusinessName>
    <CustomerClass>BusinessClass</CustomerClass>
    <EntityInformation>
      <Individual>
        <Suffix>SR</Suffix>
        <Salutation>MR</Salutation>
        <NickName>G</NickName>
        <Name>
          <Name Location="First"><FIRST></Name>
          <Name Location="First2"></Name>
          <Name Location="Middle"></Name>
          <Name Location="Last"><LAST></Name>
          <Name Location="Last2"></Name>
        </Name>
        <ContactInformation>
          <Address PrimaryFlag="true" ValidFlag="true" TypeCode="HOME"
                   ContactPreferenceCode="Order Info Only" 
                   Label="Special Address label">
            <AddressLine1><ADDRESS></AddressLine1>
            <AddressLine2></AddressLine2>
            <AddressLine3></AddressLine3>
            <AddressLine4></AddressLine4>
            <ApartmentNumber></ApartmentNumber>
            <City>Oklahoma City</City>
            <Territory>OK</Territory>
            <PostalCode>49136</PostalCode>
            <County>Desert</County>
            <Country>US</Country>
          </Address>
          <EMail PrimaryFlag="true" TypeCode="HOME"
                 ContactPreferenceCode="Promotion Info Only"
                 Label="Special Email Address label">
            <EMailAddress><USERID>@<TNS_ALIAS>            </EMailAddress>
          </EMail>
          <Telephone PrimaryFlag="true" TypeCode="HOME"
                     ContactPreferenceCode="No Phone Contact" 
                     Label="Special Phone Address label">
            <PhoneNumber>4405550101</PhoneNumber>
            <Extension></Extension>
          </Telephone>
        </ContactInformation>
        <PersonalSummary>
          <GenderType>M</GenderType>
          <BirthDate>1957-04-16</BirthDate>
          <MaritalStatusCode>MARRIED</MaritalStatusCode>
          <Ethnicity></Ethnicity>
          <Rent>true</Rent>
          <LanguageCode>FR</LanguageCode>
        </PersonalSummary>
        <SocioEconomicProfile>
          <HighestEducationalLevelName>PHD
          </HighestEducationalLevelName>
          <AnnualIncomeAmount>123456</AnnualIncomeAmount>
          <NetWorth>1234567</NetWorth>
      </Individual>
    </EntityInformation>
    <PersonalPreferences>
     <ContactPreference ContactType="Mail" SubTypeCode="HOME" 
      Permission="true"></ContactPreference>
     <ContactPreference ContactType="Email" SubTypeCode="HOME"
      Permission="false"></ContactPreference>
     <ContactPreference ContactType="Phone" SubTypeCode="HOME"
      Permission="false"></ContactPreference>
     <ContactPreference ContactType="Fax" SubTypeCode="FAX" 
       Permission="true"></ContactPreference>
    </PersonalPreferences>
    <AlternateKey TypeCode="<TYPECODE>">
      <AlternateID><ALT_ID></AlternateID>
    </AlternateKey>
    <CustomAttribute name="Spending Level">
      <AttributeValue>Silver</AttributeValue>
      <AttributeValue>Gold</AttributeValue>
        </SocioEconomicProfile>
      <AttributeValue>Platinum</AttributeValue>
    </CustomAttribute>
      <CustomerNotes>
       <CustomerNote action="UPDATE" createDate="2017-09-22"
         createUser="<USERID>" type="COMMENT" location="<LOCATION>"
         sequence="326212" privateFlag="false">sample note content
        </CustomerNote>
      <CustomerNotes>
  </Customer>
</Customers>

Batch Processing Errors

The following table contains a list of errors that may occur and possible causes:

Error Cause

ALTERNATE_KEY_TYPECODE_UNSPECIFIED

A typecode was not specified for an alternate key to be added.

ALTERNATE_KEY_VALUE_UNSPECIFIED

A value was not specified for an alternate key to be added.

ATTRIBUTE_VALUE_TOO_LARGE

Number of characters or numbers exceed field length.

CUSTOMER_NOTE_EMPTY

Customer note parameters defined, but the customer note is blank

GENERAL_ERROR

A general, non-specific error. If you cannot determine the cause of the problem, contact your Project Consultant.

INVALID_ATTRIBUTE_VALUE

Invalid data based on attribute type. For example, characters included in a value for a numeric attribute.

INVALID_DATE_FORMAT

The data in a date field is not valid date information.

MULTIPLE_VALUES_ON_UNIQUE_ATTRIBUTE_TYPE

The request includes multiple values for an attribute defined as unique.

NAME_POSITION_INVALID

The location (for example, First, Last, First2, etc.) of the name element is not specified, or the location is not valid.

UNKNOWN_ATTRIBUTE_TYPE

Unknown attribute type.

VALUE_NOT_IN_ENUMERATED_ATTRIBUTE_TYPE_VALUES

The value entered for an attribute is not among the possible enumerated values.

Batch File Responses

A complete copy of the incoming request is placed in the /complete/[Fileset Name]/archived directory.

Each <Customer> block in the request that was not successfully processed is placed in a file with _failures appended to the original filename in the /complete/[Fileset Name]/failed directory.

You may be able to determine the reason for the failure by using the Batch Import Review pages (see Batch Import Review).

Update Customer Information

The purpose of this action is to update information contained in customer record(s).

Requirements/Restrictions

You must use <CustomerID> or <AlternateID> to identify the correct customer.

Customer Engagement updates customer information in two ways:

  • For address, phone, email, and alternate ID information; old data is deactivated and new data is added; however, you also have the option to delete an alternate ID.

    • This information can also be set; existing information is deactivated and the included information is set as the primary, active information.

  • For all other customer information that can be updated, the new data just overwrites the old data.

Anonymous Customer

The Update operation can be used to convert an anonymous customer into an identified customer. The old data is the current customer information, blank in this case; and the new data is the identifying information.

Fields

For an Update Customer Information request, the elements that can be updated are in the table below. The placement/use of these elements is shown in the sample request.

XML Tag Comments

<CustomerID>

Customer Engagement Customer ID - Used for identification; cannot be updated.

The elements below are updated by overwriting the existing or old values.

<RetailStoreID>

This is the location where the request originated.

<SignupDate>

This is the date the customer signed up.

<CustomerNumber>

<CustomerReference>

<OrgName>

This is the name of the organization.

<CustOrgTypcode>

The type of organization (e.g. School, Club, etc.)

<EmployeeID>

This is the employee ID or employee code.

<LastUpdateInfo>

<UpdateUserID>

User ID of person/POS adding customer.

<UpdateDate>

Date customer is added. Format = 2015-07-24T15:25:27 (timestamp). If date is left off, Customer Engagement will fill in local time.

The customer’s home location is updated by adding a RetailStoreID which overwrites the existing or old data.

<Affiliation Action="Add">

<RetailStoreID>

This is the customer’s home location.

The elements below are updated by overwriting the existing or old values.

<Prospect>

Indicates whether the customer is a prospect.

<BusinessName>

This is the name of the business associated with the customer.

<CustomerClass>

This is the class to which the customer belongs.

The elements below are updated by overwriting the existing or old values.

<PersonalPreferences>

<ContactPreference>

Specifies if and how the customer wants to be contacted.

ContactType=" "

ContactType: Method used to contact customer. Can be Mail, Email, Phone, or Fax.

SubTypeCode=" "

SubTypeCode: Customer location for contact. Must be HOME for Mail, Email, and Phone. Must be FAX for Fax.

Permission=" ">

Permission: true - customer gives permission to be contacted via ContactType, false - customer does not give permission to be contacted via ContactType.

The elements below are updated by overwriting the existing or old values.

<Individual>

<Suffix>

A title that comes after a person’s name. See Fields.

<Name>

First, Middle, and Last names of the customer.

<Name Location="First" />

Location: Position of name: First, First2, Middle, Last, or Last2. For descriptions of First2 and Last2 names, see Multiple Names.

<Name Location="First2" />

<Name Location="Middle"/>

<Name Location="Last" />

<Name Location="Last2" />

<Salutation>

A formal prefix that comes before a person’s name. See Fields.

<Nickname>

A nickname that the customer has provided.

  • The elements below are updated by deactivating the old data and adding the new data, or using set to deactivate all existing addresses and setting the new one as primary.

  • No old data is required with a set.

  • The old data and the new data must be in separate <Address> blocks.

  • If PrimaryFlag is not included in new data, default = false.

  • If a new address is included without an old address, the address is just added.

  • If ValidFlag is true, address is marked as valid regardless of internal validation.

<Address PrimaryFlag=" "

PrimaryFlag: true = customer’s primary address, false = not the customer’s primary address. If this attribute is missing, the default is false. Only one primary address is permitted regardless of TypeCode.

Label=" "

Label: The label used for the address.

ContactPreferenceCode=" "

ContactPreferenceCode: Code indicating the customer contact preferences for the address.

TypeCode=" "

TypeCode: Indicates the type of telephone (e.g. HOME or BUSINESS).

UpdateType=" "

UpdateType: Old helps identify existing or old data. New specifies replacement data, Set specifies deactivate all existing addresses and set the included address as Primary.

ValidFlag=" "

ValidFlag: true sets the Valid Flag to true regardless of the results of Customer Engagement’s internal validation. See Address for Validation information.

<Country>

Country where the customer lives.

<AddressLine1>

First line of the address.

<AddressLine2>

Second line of the address.

<AddressLine3>

Third line of the address.

<AddressLine4>

Fourth line of the address.

<ApartmentNumber>

Apartment number.

<City>

City

<Territory>

State or province. Be consistent in use of abbreviation or full name.

<PostalCode>

Postal/Zip code.

<County>

County or parish.

  • The elements below are updated by deactivating the old data and adding the new data, or using set to deactivate all existing email addresses and setting the new one as primary.

  • No old data is required with a set.

  • The old data and the new data must be in separate <EMail> blocks.

  • If PrimaryFlag is not included in new data, default = false.

<EMail PrimaryFlag=" "

PrimaryFlag: true = customer’s primary email address, false = not the customer’s primary email address. If this attribute is missing, the default is false. Only one primary email is permitted regardless of TypeCode.

Label=" "

Label: The label used for the email.

ContactPreferenceCode=" "

ContactPreferenceCode: Code indicating the customer contact preferences for the email.

TypeCode=" ">

TypeCode: Indicates the type of the Email (e.g. HOME or BUSINESS).

UpdateType=" "

UpdateType: Old helps identify existing or old data. New specifies replacement data, Set specifies deactivate all existing emails and set the included email as Primary.

<EMailAddress>

Email address.

  • The elements below are updated by deactivating the old data and adding the new data, or using set to deactivate all existing phone numbers and setting the new one as primary.

  • No old data is required with a set.

  • No old data is copied to the new; therefore, everything you want included in the telephone must be entered in the new block.

  • The old data and the new data must be in separate <Telephone> blocks.

  • If PrimaryFlag is not included in new data, default = false.

<Telephone PrimaryFlag=" ">

PrimaryFlag: true = customer’s primary telephone, false = not the customer’s primary telephone. If this attribute is missing, the default is false. Only one primary phone is permitted regardless of TypeCode.

Label=" "

Label: The label used for the telephone number.

ContactPreferenceCode=" "

ContactPreferenceCode: Code indicating the customer contact preferences for the telephone.

TypeCode=" ">

TypeCode: Indicates the type of telephone (e.g. HOME or BUSINESS).

UpdateType=" "

UpdateType: Old helps identify existing or old data. New specifies replacement data, Set specifies deactivate all existing phone numbers and set the included phone number as Primary.

<PhoneNumber>

Telephone number.

<Extension>

Telephone extension.

The elements below are updated by overwriting the existing or old values.

<PersonalSummary>

<GenderType>

Gender. Must start with M, m, or 1 for male or F, f, W, w, or 0 for female. See Gender.

<BirthDate>

Date of birth (Format = YYYY-MM-DD). The use of any other format will result in the BirthDate not being written to the database.

<MaritalStatusCode>

Marital status.

<Ethnicity>

Ethnic background.

<LanguageCode>

The 2-letter ISO language code for the customer’s preferred language.

<Rent>

Indicates whether the customer is part of a rented customer list.

The elements below are updated by overwriting the existing or old values.

<SocioEconomicProfile>

<HighestEducationalLevelName>

Highest level of education. Must be SECONDARY, BACHELORS, GRADUATE, or PHD. This field is limited to 10 characters.

<AnnualIncomeAmount>

Amount the customer earns annually.

<NetWorth>

Value of customer’s assets.

  • The elements below are updated by deactivating the old data and adding the new data, or using set to deactivate all existing alternate keys and setting the new one as primary. You can also use an updateType of DELETE to delete an alternate ID.

  • No old data is required with a set.

  • Old data is used to help identify the correct customer.

  • The old data and the new data must be in separate <AlternateKey> blocks.

<AlternateKey TypeCode=" ">

TypeCode: The type of alternate key (e.g. EMAIL, PHONE, TWCUSTID, etc.).

UpdateType=" "

UpdateType: Old helps identify existing or old data. New specifies replacement data, DELETE deletes the current data, and Set is ignored.

<AlternateID>

Unique number/code for the specific type of alternate key.

Note: Information that maps to a Customer’s identity is not protected if stored in Alternate Keys. Oracle does not recommend using Alternate Keys to store personal data.

  • The elements below are updated by overwriting the existing or old values.

  • If there is more than one value for an Attribute, all values are overwritten by the new value in the request.

<CustomAttribute name=" ">

User-defined customer attributes.

name: The name of the attribute. Name must be defined in dtv_attribute_type database table (Note lowercase n).

<AttributeValue>

The value of the attribute; must be of the type defined for the attribute. If the attribute is a list, the value must match a value contained in the dtv_attribute_type_value table.

Information that maps to a Customer’s identity is not protected if stored in Customer Attributes. Oracle does not recommend using Customer Attributes to store personal data.

<CustomerNotes>

User-entered customer notes.

<CustomerNote

The text of the customer note. There is no maximum number of CustomerNotes for a request. A customer note sent to Customer Engagement will always be added, not updated. However, an AddOrUpdate or Update request will check for duplicate comments to prevent note duplication.

type=""

The type of note. The type is specified by the user and can have any value. All notes without a specified type will be given a note type of COMMENT.

createDate=" "

Date the note was created.

createUser=" "

ID for the user who created the note.

location=" ">

ID for the location where the note was created.

action=""

Indicates whether to ADD, UPDATE, or DELETE a customer note.

sequence=""

Indicates the sequence number of the note.

privateFlag=""

Indicates if the note content is private.

Note: Information that maps to a Customer’s identity is not protected if stored in Customer Notes. Oracle does not recommend using Customer Notes to store personal data.

Note:

<ActivitySummary> information cannot be updated. If <ActivitySummary> information is included in the request, the application will ignore it.

The following rules apply to old data and new data:

  • If only old data is included, the old data is marked as inactive.

  • If both old and new data is included in the request, the old data is marked as inactive and the new data is added to the database and marked as active.

  • If only new data is included in the request, the new data is added to the database and marked as active.

If the <LastUpdateInfo> section is updated, the old data is overwritten and not saved.

Example

An Update Customer Information request should appear similar to the example below. The CustomerID and/or AlternateID will vary according to each particular request.

If more than one customer is being updated, there should be multiple <Customer> blocks.

<?xml version="1.0" encoding="UTF-8"?>
<Customers>
  <Customer Action="Update">
    <!-- Customer to Update -->
    <CustomerID></CustomerID>
    <AlternateKey TypeCode="XSTORE_ID">
      <AlternateID><ALT_ID></AlternateID>
    </AlternateKey>
    <LastUpdateInfo>
      <UpdateUserID><USERID></UpdateUserID>
      <UpdateDate>2015-03-18</UpdateDate>
    </LastUpdateInfo>
    <!-- The following RetailStoreID updates SignUpLocation in 
        CST_Customer. -->
    <RetailStoreID><STORE_ID></RetailStoreID>
    <SignupDate>2006-07-13</SignupDate>
    <CustomerNumber></CustomerNumber>
    <CustomerReference></CustomerReference>
    <OrgName></OrgName>
    <CustOrgTypcode></CustOrgTypcode>
    <EmployeeID><USERID></EmployeeID>
    <!-- The following Affiliation updates Home_RTL_Loc_ID in 
         CST_Customer -->
    <Affiliation Action="Add">
      <RetailStoreID><STORE_ID></RetailStoreID>
    </Affiliation>
    <Prospect>true</Prospect>
    <BusinessName><NAME></BusinessName>
    <CustomerClass>BusinessClass</CustomerClass>
    <EntityInformation>
      <Individual>
        <Suffix>Sr.</Suffix>
        <Salutation>Mr.</Salutation>
        <NickName></NickName>
        <Name>
          <Name Location="Middle"></Name>
          <Name Location="Last"><LAST></Name>
          <Name Location="First"><FIRST></Name>
        </Name>
        <ContactInformation>
          <!-- Update Type = Old will deactivate the old address 
             listed below -->
          <Address UpdateType="Old" PrimaryFlag="true" 
                   TypeCode="HOME">
            <AddressLine1><ADDRESS></AddressLine1>
            <AddressLine2></AddressLine2>
            <AddressLine3></AddressLine3>
            <AddressLine4></AddressLine4>
            <ApartmentNumber></ApartmentNumber>
            <City>Doylestown</City>
            <Territory>PA</Territory>
            <PostalCode>18901</PostalCode>
            <County></County>
            <Country>US</Country>
          </Address>
          <!-- Update Type = New will add the new address listed 
             below -->
          <Address UpdateType="New" PrimaryFlag="true" 
                   TypeCode="HOME">
            <AddressLine1><ADDRESS></AddressLine1>
            <AddressLine2></AddressLine2>
            <AddressLine3></AddressLine3>
            <AddressLine4></AddressLine4>
            <ApartmentNumber></ApartmentNumber>
            <City>Solon</City>
            <Territory>OH</Territory>
            <PostalCode>44139</PostalCode>
            <County>Cuyahoga</County>
            <Country>US</Country>
          </Address>
          <!-- Update Type = Set will deactivate all emails 
               address and add the new one -->
          <EMail UpdateType="Set" PrimaryFlag="true" TypeCode="HOME">
            <EMailAddress>pnewman2@example.com</EMailAddress>
          </EMail>
          <!-- Update Type = New will add the new telephone 
               leaving all other telephones as active -->
          <Telephone UpdateType="New" PrimaryFlag="true" 
                     TypeCode="HOME">
            <PhoneNumber>8005550102</PhoneNumber>
            <Extension>100</Extension>
          </Telephone>
        </ContactInformation>
        <PersonalSummary>
          <GenderType>MALE</GenderType>
          <BirthDate><BIRTHDATE></BirthDate>
          <MaritalStatusCode>MARRIED</MaritalStatusCode>
          <Ethnicity></Ethnicity>
        </PersonalSummary>
        <SocioEconomicProfile>
          <HighestEducationalLevelName>BACHELORS
          </HighestEducationalLevelName>
          <AnnualIncomeAmount>123456</AnnualIncomeAmount>
          <NetWorth>1234567</NetWorth>
        </SocioEconomicProfile>
      </Individual>
    </EntityInformation>
    <PersonalPreferences>
      <ContactPreference ContactType="Mail" SubTypeCode="HOME"
       Permission="true">
      </ContactPreference>
      <ContactPreference ContactType="Email" SubTypeCode="HOME"
       Permission="true">
      </ContactPreference>
      <ContactPreference ContactType="Phone" SubTypeCode="HOME"
       Permission="true">
      </ContactPreference>
      <ContactPreference ContactType="Fax" SubTypeCode="FAX"
       Permission="true">
      </ContactPreference>
    </PersonalPreferences>
    <AlternateKey TypeCode="EMAIL" UpdateType="Old">
      <AlternateID><ALT_ID>/AlternateID>
    </AlternateKey>
    <AlternateKey TypeCode="EMAIL" UpdateType="New">
      <AlternateID><ALT_ID></AlternateID>
    </AlternateKey>
    <!-- Must have Custom Attribute types defined first -->
    <CustomAttribute name="JACKET SIZE">
      <AttributeValue>Large</AttributeValue>
    </CustomAttribute>
    <CustomAttribute name="NUMBER OF CHILDREN">
      <AttributeValue>8</AttributeValue>
    </CustomAttribute>
      <CustomerNotes>
       <CustomerNote action="UPDATE" createDate="2017-09-22"
         createUser="example" type="COMMENT" location="99901"
         sequence="326212" privateFlag="false">sample note content
        </CustomerNote>
     </CustomerNotes>
  </Customer>
</Customers>

Batch Processing Errors

The following table contains a list of errors that may occur and possible causes:

Error Cause
ALTERNATE_KEY_ TYPECODE_UNSPECIFIED A typecode was not specified for an alternate key to be added.
ALTERNATE_KEY_VALUE_UNSPECIFIED A value was not specified for an alternate key to be added
ATTRIBUTE_VALUE_TOO_LARGE Number of characters or numbers exceed field length.
CUSTOMER_NOT_FOUND No customers could be found based on the parameters provided.
CUSTOMER_NOTE_EMPTY Customer note parameters defined, but the customer note is blank
GENERAL_ERROR A general, non-specific error. If you cannot determine the cause of the problem, contact your Project Consultant.
INVALID_ATTRIBUTE_VALUE Invalid data based on attribute type. For example, characters included in a value for a numeric attribute.
INVALID_DATE_FORMAT The data in a date field is not valid date information
MULTIPLE_VALUES_ON_UNIQUE_ATTRIBUTE_TYPE The request includes multiple values for an attribute defined as unique.
NAME_POSITION_INVALID The location (for example, First, Last, First2, etc.) of the name element is not specified, or the location is not valid.
UNKNOWN_ATTRIBUTE_TYPE Unknown attribute type.
VALUE_NOT_IN_ENUMERATED_ ATTRIBUTE_TYPE_VALUES The value entered for an attribute is not among the possible enumerated values.

Batch File Response

A complete copy of the incoming request is placed in the /complete/[Fileset Name]/archived directory.

Each <Customer> block in the request that was not successfully processed is placed in a file with _failures appended to the original filename in the /complete/[Fileset Name]/failed directory.

You may be able to determine the reason for the failure by using the Batch Import Review pages (see Batch Import Review).

Delete Customer

The purpose of this action is to remove customer(s) from the client’s active customer database.

If the customer’s business address is the same as the home address, and it was created as a retail location in Customer Engagement, it can be deleted through the Remove Retail Location request.

A deleted customer is considered to not be in the system if the <CustomerID> or <AlternateID> in the request do not match those in the database, or if the customer is already inactive.

Fields

The elements in the table below are the elements that can be included in the request. The placement/use of these elements is shown in the sample request.

Not all of these elements have to be used in any one request.

XML Tag Description

<CustomerID>

Customer Engagement unique customer identification number.

<AlternateKey TypeCode=" ">

TypeCode: The type of alternate key (for example, EMAIL, PHONE, TWCUSTID, and so on) These values must be in the cst_alt_key_typcode database table.

<AlternateID>

Unique number/code for the specific type of alternate key.

If any fields other than the ones listed above are included in a request, they will be ignored.

Example

A delete request should appear similar to the example below. The search parameters in the body will vary according to each particular request.

If more than one customer is being deleted, there should be multiple <Customer> blocks.

Note:

When processing delete requests in a batch file, the customer parameters, <CustomerID> and <AlternateID>, can be all of one kind or mixed. 

<?xml version="1.0" encoding="UTF-8"?>
<Customers>
  <Customer Action="Delete">
    <AlternateKey TypeCode="XSTORE_ID">
      <AlternateID><ALT_ID></AlternateID>
    </AlternateKey>
  </Customer>
</Customers>

Batch Processing Errors

The following table contains a list of errors that may occur and possible causes:

Error Cause

CUSTOMER_NOT_FOUND

No customers could be found based on the parameters provided.

GENERAL_ERROR

A general, non-specific error. If you cannot determine the cause of the problem, contact your Project Consultant.

Batch File Response

A complete copy of the incoming request is placed in the /complete/[Fileset Name]/archived directory.

Each <Customer> block in the request that was not successfully processed is placed in a file with _failures appended to the original filename in the /complete/[Fileset Name]/failed directory.

You may be able to determine the reason for the failure by using the Batch Import Review pages (see Batch Import Review).

Add/Update Home Location

The purpose of this action is to add or update the Home Location for a customer. The Home Location is the retail location that the customer frequents most often. The home location is essentially a type of affiliation. A customer can have only one Home Location.

There are three ways to add or update a Home Location for a customer:

  • In an Add Customer request in conjunction with adding a new customer (see Add Customer).

    Note:

    Do not use an Add Customer request solely for the purpose of adding a Home Location. The Add Customer request will also create a new customer.

  • In an Update Customer request in conjunction with a customer update (see Update Customer Information).

  • In an Update Customer request without a customer update (see Examples).

The minimum data elements/attributes required for adding/updating a Home Location are:

  • Either a Customer ID or an Alternate ID

  • Retail Location ID

Fields

The elements in the following table are the elements that can be used when adding or updating a Home Location. The use of these elements is shown in the examples below.

XML Tag Description

<CustomerID>

Customer Engagement Customer ID.

<Affiliation Action="Add" orUpdateType="New">

There is essentially no difference between Action="Add" and UpdateType="New" in Customer Engagement.

<RetailStoreID>

[required] This is the customer’s home location.

<AlternateKey TypeCode=" ">

TypeCode: The type of alternate key (e.g. EMAIL, PHONE, TWCUSTID, and so on) The value must be in the cst_alt_key_typcode database table.

<AlternateID>

Unique ID for the specific type of alternate key.

Any additional data elements/attributes included in the request body, but which do not appear in the schema section of CRMProcessor.wsdl, are ignored.

Examples

Update Customer Request

A request to add a Home Location without updating customer information should appear similar to the example below. The information in the body of the request will vary according to each particular request.

If more than one home location is being updated and/or created, there should be multiple <Customer> blocks in the batch file. 

<?xml version="1.0" encoding="UTF-8"?>
<Customers>
  <Customer Action="Update">
    <CustomerID></CustomerID>
    <AlternateKey TypeCode="TWCUSTID">
      <AlternateID><ALT_ID></AlternateID>
    </AlternateKey>
    <Affiliation Action="Add">
      <RetailStoreID><STORE_ID></RetailStoreID>
    </Affiliation>
  </Customer>
</Customers>

See Example for an example of an Update Customer XML Request.

Note:

The line:

    <Affiliation Action="Add">

shown above can be replaced with the line:

    <Affiliation UpdateType="New">

Both of these attribute-value sets update the customer record in the same way.

Batch Processing Errors

The following table contains a list of errors that may occur and possible causes:

Error Cause

ACTIVATION_DATE_DOES_NOT_MEET_CARD_EXPIRATION_DATE

The attempt to activate the card is occurring prior to the eligibility start date for the card.

CUSTOMER_NOT_FOUND

No customers could be found based on the parameters provided.

GENERAL_ERROR

A general, non-specific error. If you cannot determine the cause of the problem, contact your Project Consultant.

Batch FIle Response

A complete copy of the incoming request is placed in the /complete/[Fileset Name]/archived directory.

Each <Customer> block in the request that was not successfully processed is placed in a file with _failures appended to the original filename in the /complete/[Fileset Name]/failed directory

You may be able to determine the reason for the failure by using the Batch Import Review pages (see Batch Import Review).

Card Customer Association

The purpose of the card/customer association request is to allow external systems to instruct the Customer Engagement Host system to link a known customer to a known card (and related accounts).

  • In addition to associating a card and a customer, the card and any related accounts are also activated.

  • An account activity record is created if a tender, loyalty, or award account is activated.

  • If the entitlement deal definition for the card program has “Issue only when associated to a customer” selected, an entitlement coupon is issued, provided this is the first customer associated with the card.

Tasks

For information about the tasks performed as part of the Card Customer Association process, see “Activate Instrument Request” in Chapter 9.An error is generated under the following conditions

An error is generated under the following conditions:

  • The card does not exist in the system.

  • The customer does not exist in the system.

  • An unknown error occurs in the Card Customer Association process.

Requirements/Restrictions

The minimum data elements required for a valid Card Customer Association request is a Customer ID or Alternate Customer ID/Alternate Key Type, and Card Number.

If an Alternate Customer ID is used, the Alternate Key Type Code must also be provided.

If both a Customer ID and Alternate Customer ID are provided, the Customer ID takes precedence over the Alternate Customer ID.

Fields

XML Tag Description

<Instrument>

<UserName>

The name of the person sending the request.

<InstrumentID>

This is the serial number of the card.

<CardNumber>

Card Number

<AuthenticationData>

PIN

<RTPTransaction>

<LocationID>

Retail location generating request.

<Customer>

<CustomerId>

Customer ID assigned by the Customer Engagement application.

<AlternateKey TypeCode=" ">

TypeCode: The type of alternate key (e.g. EMAIL, PHONE, TWCUSTID, and so on) The value must be in the cst_alt_key_typcode database table.

<AlternateID>

Unique ID for the specific type of alternate key.

If any fields other than the ones listed above are included in a request, they will be ignored.

Example

A Card Customer Association request should appear similar to the example below. The parameters will vary according to each particular request.

If more than one Card Customer Association is being performed, there should be multiple <Instrument> blocks.

<?xml version="1.0" encoding="UTF-8"?>
<ActivateInstrumentCustomerRequest>
  <Instrument>
    <UserName>WPL</UserName>
    <InstrumentID><INSTRUMENT_ID></InstrumentID>
    <AuthenticationData><AUTH_DATA></AuthenticationData>
    <CardNumber></CardNumber>
    <RTPTransaction>
      <LocationID><LOCATION_ID></LocationID>
    </RTPTransaction>
    <Customer>
      <CustomerID>23</CustomerID>
      <AlternateKey TypeCode="">
        <AlternateID></AlternateID>
      </AlternateKey>
    </Customer>
  </Instrument>
</ActivateInstrumentCustomerRequest>

Batch Processing Errors

The following table contains a list of errors that may occur and possible causes:

Error Cause

ACCOUNT_BLOCKED

The associated tender account is blocked. Note: You must first unblock the account using the Card/Account Admin GUI (see the Customer Engagement User Guide).

ACCOUNT_EXPIRED

An account has previously been activated (Activation Date not Null) and there is an Expiry Date for the account and the Expiry Date is less than the current date.

AWARD_PROGRAM_EXPIRED

The award account has never been activated (Activation date = null) and the award program Expiry Date is not null and it is less than the current date.

AWARD_PROGRAM_NOT_EFFECTIVE

The award account has never been activated (Activation date = null) and the award program Effective Date is not null and it is greater than the current date.

CARD_EXPIRED

There is an Expiration Date for the card and it is less than the current date.

CARD_NOT_FOUND

The card specified in the request could not be found.

CUSTOMER_NOT_FOUND

No customers could be found based on the parameters provided.

LYL_PROGRAM_EXPIRED

The loyalty account has never been activated before (Activation Date = null) and the loyalty program Expiry Date is not null and it is less than the current date.

LYL_PROGRAM_NOT_EFFECTIVE

The loyalty account has never been activated before (Activation Date = null) and the loyalty program Effective Date is not null and it is greater than the current date.

MIN_ACTIVATION_AMT_NOT_MET

The activation amount is less than the minimum activation amount for the Tender Program.

PROGRAM_EXPIRED

The tender account has never been activated (Activation Date = null) and the tender program Expiry Date is not null and it is less than the current date.

PROGRAM_INACTIVE

The program has been deactivated (inactive).

PROGRAM_NOT_EFFECTIVE

The tender account has never been activated before (Activation Date = null) and the tender program Effective Date is not null and it is greater than the current date.

Batch File Response

A complete copy of the incoming request is placed in the /complete/[Fileset Name]/archived directory.

Each <Instrument> block in the request that was not successfully processed is placed in a file with _failures appended to the original filename in the /complete/[Fileset Name]/failed directory.

You may be able to determine the reason for the failure by using the Batch Import Review pages (see Batch Import Review).

Customer Merge

Customer Merge is the process of taking two or more duplicate customer records and combining the information into a new single record in the database. Duplicate records are not removed from the database.

Caution:

Use caution when merging customer records. This process is not reversible.

Note:

This process assumes that the customer records to be merged are already known.

There are two types of records involved in the merge process:

  • Source - This is a duplicate record that has been selected to be the source of data for new single record.

  • Target - One or more records that have been identified as being the same person as the Source record.

The following System Configuration properties control rules for merging customers:

  • Customer Merge - Attributes: Enables you to override merge behavior by specifying one or more attributes that will take preference when merging.

  • Customer Merge - Contact Permissions: Controls whether to accept the contact permissions setting of the source customer, set all contact permissions to Yes, or set all contact permissions to No.

  • Customer Merge - Date of Birth: Controls whether to use the date of birth for the source customer, or select the first non-null date of birth while merging (best match).

  • Customer Merge - Email Address: Controls whether to use the email address(es) of the source customer, select the first non-null email address (best match), or retain all email addresses.

  • Customer Merge - Home Location: Controls whether to use the home location for the source customer, or select the first non-null home location (best match).

  • Customer Merge - Mail Address: Controls whether to use the mail address(es) of the source customer, select the first non-null mail address (best match), or retain all mail addresses.

  • Customer Merge - Phone Numbers: Controls whether to use the phone number(s) of the source customer, select the first non-null phone number (best match), or retain all phone numbers.

  • Customer Merge Override: Enables you to specify the preferred behavior when merging in different scenarios: if the customer is not found; if the customer has one or more cards; if the customer has made one or more transactions; if the customer has a promotion response; and if the source customer cannot be merged.

  • Duplicate Customer Merge Limit: Sets the maximum number of customer records that can be merged into a single customer record.

  • Duplicate Customer Rules: Defines the criteria for selecting source customer records, including recent activity dates and possession of cards, email address, phone number, address, or attributes.

Refer to the Customer Engagement Implementation Guide, or contact your Project Manager for more information on Customer Merge configuration.

Merge Logic

This section describes the new customer record that results from the merge process and where the information in the fields comes from. The following table lists information categories and where the information for the new record comes from.

Table 2-3 Merge Logic

Category Comes From ...

Customer ID

New

Home Location

Source

Personal Preferences

Source

Name

Source

Address(es)

Source

Email Address(es)

Source

Telephone Number(s)

Source

Personal Summary

Source

Socioeconomic Profile

Source

Alternate IDs

All Duplicate records

Customer Attributes

All Duplicate records

Transactions

All Duplicate records

Effective Date

Minimum of all Duplicate Records

Expiry Date

Maximum of all Duplicate Records

Create Date

Minimum of all Duplicate Records

First Transaction Date

Minimum of all Duplicate Records

Last Transaction Date

Maximum of all Duplicate Records

Total Values

Sum of all Duplicate Records

YTD Values

Sum of all Duplicate Records

Signup Date/Location

Minimum of duplicate records that have both or source if has both or minimum date of duplicate records and any location

Birthday

Source or any if source is empty

Update Date

Current Date

Promotion Response

Leaves the existing responses alone and keeps them associated with the original Customer IDs

Promotion Target

Adds new target Customer ID for future promotion processing

Promotion Totals

Keeps the original customer promotion totals associated with the original Customer IDs

Card Associations

All cards associated with new Customer ID

Requirements/Restrictions

The minimum data elements required for a valid Customer Merge request are the following.

  • One Merge Source (Customer ID or Alternate Customer ID/Alternate Key Type) and at least one Merge Target (Customer ID or Alternate Customer ID/Alternate Key Type)

    Or

  • Two or more Merge Targets (Customer ID or Alternate Customer ID/Alternate Key Type for each)

If both a Customer ID and Alternate Customer ID are provided, the Customer ID takes precedence over the Alternate Customer ID.

There can only be a single Merge Source record. If no Source customer is specified, Customer Engagement will choose a source based on the Duplicate Customer Rules configured for the organization.

Fields

The following table lists the XML tags.

Table 2-4 XML Tags

XML Tag Description

<Customer>

<MergeSource>

<CustomerID>

Customer ID assigned by the Customer Engagement application.

<AlternateKey

TypeCode=" ">

TypeCode describes the type of alternate customer ID (e.g. phone, email, etc.) The TypeCode must be in the cst_alt_key_typcode database table.

<AlternateID>

An alternate Customer ID related to the TypeCode typically assigned by organization.

<MergeTargetSet>

<MergeTarget>

<CustomerID>

Customer ID assigned by the Customer Engagement application.

<AlternateKey

TypeCode=" ">

TypeCode describes the type of alternate customer ID (e.g. phone, email, etc.) The TypeCode must be in the cst_alt_key_typcode database table.

<AlternateKey>

An alternate Customer ID related to the TypeCode typically assigned by organization.

Example

A Customer Merge should appear similar to the one shown below. The data included will vary according to each particular request.

If there is more than one set of Merge Targets in the batch file, there should be multiple <MergeTarget> blocks. If more than one merge request is being made in the same batch file, there should be multiple <Customer> blocks.

<?xml version="1.0" encoding="UTF8"?><Customers>  <Customer Action="Merge">    <!-- Merge customer A & B into C -->
    <!-- using different types of alternate keys -->    <!-- The Merge Source is one customer record, which must be -->    <!-- specified by a CustomerID or Alternate Key -->    <MergeSource>      <CustomerID></CustomerID>      <AlternateKey TypeCode="TWCUSTID">        <AlternateID><ALT_ID></AlternateID>      </AlternateKey>    </MergeSource>    <!-- The MergeTargetSet can contain more than one MergeTarget, -->    <!-- which must be specified by a CustomerID or AlternateKey -->    <MergeTargetSet>      <MergeTarget>        <CustomerID></CustomerID>        <AlternateKey TypeCode="TWCUSTID">          <AlternateID><ALT_ID></AlternateID>        </AlternateKey>      </MergeTarget>      <MergeTarget>        <CustomerID></CustomerID>        <AlternateKey TypeCode="TWCUSTID">          <AlternateID><ALT_ID></AlternateID>        </AlternateKey>      </MergeTarget>    </MergeTargetSet>  </Customer></Customers>

Batch Processing Errors

The following table contains a list of errors that may occur and possible causes.

Table 2-5 Customer Merge Errors

Error Cause

CUSTOMER_NOT_FOUND

No customers could be found, based on the parameters provided.

MERGE_CUSTOMER_CREATION_EXCEPTION

The Customer Merge could not be performed.

Batch File Response

A complete copy of the incoming request is placed in the/complete/[Fileset Name]/archived directory.

Each <Customer> block in the request that was not successfully processed is placed in a file with _failures appended to the original filename and saved in the /complete/[Fileset Name]/failed directory.

You may be able to determine the reason for the failure by using the Batch Import Review pages (see "Batch Import Review").