1.0 - Understanding the Required Customer Data Formats - Vantage Customer Experience

Vantage Customer Experience User Guide

prodname
Vantage Customer Experience
vrm_release
1.0
category
User Guide
featnum
B035-3800-099K

The customer data that Vantage CX requests from the third-party application must be returned to Vantage CX in XML or JSON format. Vantage CX generates attributes for the third-party profile based on the XSD or JSON sample data you supply. When setting up third-party profiles, you must be aware of the format and contents of the data before selecting the attributes to generate.

The XSD and the JSON sample data file shown in the following sections are equivalent; the potential attributes are identical. The names of the attribute categories differ, because they are based on a combination of the third-party profile name and the elements in the XSD or JSON sample data file:

XML Schema Definition (XSD)

An XSD is a known standard for describing XML data, so that is the document type that you provide for XML data.

All elements must be defined in a single XSD.

The following shows a sample XSD.

<?xml version="1.0" encoding="ISO-8859-1" ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">

<xs:element name="shiporder">
  <xs:complexType>
    <xs:sequence>
      <xs:element name="orderperson" type="xs:string"/>
      <xs:element name="contactnumbers" type="xs:string" maxOccurs="unbounded"/>
      <xs:element name="item" maxOccurs="unbounded">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="title" type="xs:string"/>
            <xs:element name="quantity" type="xs:positiveInteger"/>
            <xs:element name="price" type="xs:decimal"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>
</xs:element>
			
</xs:schema>

For this example, if the third-party profile name is My TPP XSD, then the simple attribute category name will be My_TPP_XSD. The complex attribute category name will be shiporder_item.

Vantage CX supports primitive XSD types (such as string and date) when making the list of potential attributes. Vantage CX also supports arrays (multiple values for an attribute) and complex arrays (complex attributes). The format of any inferred/unmapped attributes is always assumed to be string.

Vantage CX generates potential attributes for leaf elements that have any of the following primitive XSD types—elements with other types are skipped:
  • date
  • time
  • integer
  • nonPositiveInteger
  • positiveInteger
  • negativeInteger
  • long
  • int
  • short
  • nonNegativeInteger
  • unsignedLong
  • unsignedInt
  • unsignedShort
  • decimal
  • double
  • float
  • string
  • normalizedString
  • boolean
Vantage CX does not support creating potential attributes from attributes on elements.

An element with maxOccurs set to unbounded becomes a complex attribute category when that complex element contains other elements. The following example creates a complex attribute category named item with the attributes title, quantity, and price:

  <xs:element name="item" maxOccurs="unbounded">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="title" type="xs:string"/>
        <xs:element name="quantity" type="xs:positiveInteger"/>
        <xs:element name="price" type="xs:decimal"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

JSON Sample Data File

There is not an equivalent standard file like an XSD for JSON data. Vantage CX refers to a JSON sample data file to determine the format of the attribute data. One easy way to get the JSON sample data file is to make a call to the URL for the third-party application to pull the data for a single customer, then use that as the JSON sample data file after you remove any headers or other information not needed for the sample.

The following shows a JSON sample data file.

{
  "orderperson": "Tom Sawyer",
  "contactnumbers": [
    "999-123-4567",
    "855-444-3333"
  ],
  "item": [
    {
        "title": "paintbrush",
        "quantity": 1,
        "price": 5.00
    },
    {
        "title": "whitewash",
        "quantity": 3,
        "price": 25.00
    }
  ]
} 

For this example, if the third-party profile name is My TPP JSON, the simple attribute category name will be My_TPP_JSON. The complex attribute category name will be My_TPP_JSON_item.

The usual JSON formats apply. Here are some examples of sample data:

  • String

    A string with any text or numbers surrounded by quotation marks.

      "orderperson": "Tom Sawyer"
    
    In this example, the attribute created from orderperson might never have the value Tom Sawyer, but the value of the attribute will always be treated as a string.

    Quotation marks within strings need to be escaped with a \.

      "quotes": "\"This is a quotation.\""
    
  • Numeric value
      "timezone": -5
  • Boolean (true/false)
      "verified": true
    
  • Date/time
      "valid_date1": "2014-01-07T18:55:24+0000"
    
      "valid_time1": "18:55:24+0000"
    

    The JSON sample data expects date/time data to follow ISO 8601 (for example, 2014-04-01 or 2014-04-01T20:17:35+00:00 are two simple examples that adhere to ISO 8601). If the date/time is in any other format, Vantage CX interprets the date/time as a string.

  • Array with objects inside it (complex attribute category). Like the XSD example shown previously, the following JSON sample data creates a complex attribute category with the attributes title, quantity, and price.
      "item": [
            {
              "title": "paintbrush",
               "quantity": 1,
               "price": 5.00
            },
            {
               "title": "whitewash",
               "quantity": 3,
               "price": 25.00
            }
         ]
    
    This sample shows two groups of sample attribute data for item, but only the first group is required. Vantage CX ignores the second.