OVERVIEW

Customer Integration is used to pass customer information (name, physical address, e-mail address, etc.) from an independent source directly into the customer database used in the Online Store and Order Management System. Popular uses include:

  • A specialty foods merchant creates a form whereby new visitors can sign up to be added to that merchant's mailing list. Visitors who complete the form are added to the customer database (thereby being available to the Order Management System's Mail Wizard) and are rewarded with a $10.00 off coupon redeemable in the Online Store.
  • A winery creates a Wine Club signup form, allowing visitors to join the club for a monthly fee. Those who complete the form are added to the customer database with a Customer Type of "Wine Club", entitling them to preferential pricing and allocations.
  • A special interest club creates a "members-only" section of its web site requiring a login. Visitors who successfully log in are permitted to visit the members-only BtoB Store without an additional login.

    METHODOLOGY

    Customer Integration is achieved via an HTTP POST (the Request POST) from the client's web site to the default page of the client's Online Store via the secure https protocol. The exact URL depends on which Online Store (BtoC or BtoB) is targeted.

    Note: Nexternal strongly recommends that you use the secure (https) protocol as shown above. If you are using a Secure Domain Alias (Settings/Site Options in the Order Management System), Nexternal recommends using the Domain Alias in your URLs, i.e. https://DomainAlias/default.aspx (BtoC) and https://DomainAlias/bus/default.aspx (BtoB).

    Customer Integration may be used to identify existing customers, to create new customers, or both. If integration is used to identify existing customers, one or more "Match" fields (starting with Match1) are required. These "Match" fields are then used to identify the customer, while any other fields specified are used to update the customer's information. If new customers are being created, all fields listed as Required for New Customers are required. If the integration fields provided are not sufficient to uniquely determine the existing customer, or to create a new customer, then the integration fails. (Any error in the data provided likewise causes the integration to fail.)

    MODES

    Customer Integration may be operated in any of seven possible modes:

    Reply-Only: Following the Request POST, an HTTP POST (the Reply POST) is sent back to a URL specified in the Request POST (the ReplyURL). The Reply POST contains the all of the data included in the Request POST, as well as the status of the integration attempt and reason for failure, if applicable. The ReplyURL must be a file that can accept an HTTP POST, and thus may not be a .htm (or .html) file. In this mode, it is inconsequential whether the Request POST is directed to the BtoC Store or the BtoB Store. Reply-Only is appropriate if you wish to keep the customer on your site regardless of the success or failure of the integration, and have the ability to read in the values of the Reply POST and take corresponding action.

    Redirect-Only: Similar to the Reply-Only mode, the customer is redirected to a URL specified in the Request POST (the ReplyURL). In this mode, no data is sent to the ReplyURL, and thus a .htm (or .html) file is permitted. It is inconsequential whether the Request POST is directed to the BtoC Store or the BtoB Store. Redirect-Only is appropriate if you wish to keep the customer on your site regardless of the success or failure of the integration, but lack the ability to read in the values of the Reply POST and take corresponding action.

    Proceed-Only: This is the default mode. Following the Request POST, the customer proceeds to the Online Store (either BtoC or BtoB, as appropriate). If the integration attempt is successful, the customer enters the store already logged in and never sees the store's login screen. If the integration attempt is unsuccessful, the customer must log in as usual. There is never a Reply POST in this mode. Proceed-Only is appropriate if you wish to send the customer into the Online Store regardless of the success or failure of the integration.

    Display-Only: Following a successful integration attempt (via the Request POST), the word "Success" is displayed on screen. Following an unsuccessful integration attempt, the Failure Reason is displayed on screen. Display-Only is appropriate for debugging purposes when developing your integration, if you lack the ability to read in the values of the Reply POST used in the Reply-Failure mode.

    Reply-Failure: Following a successful integration attempt (via the Request POST), the customer proceeds to the Online Store as in the Proceed-Only mode, and no Reply POST is sent. Following an unsuccessful integration attempt, a Reply POST is sent as in the Reply-Only mode. Reply-Failure is appropriate if you wish to send the customer into the Online Store only if the integration is successful, and have the ability to read in the values of the Reply POST and take corresponding action for an unsuccessful integration. Reply-Failure is also useful for debugging purposes when developing your integration.

    Redirect-Failure: Following a successful integration attempt (via the Request POST), the customer proceeds to the Online Store as in the Proceed-Only mode. Following an unsuccessful integration attempt, the customer is redirected to the ReplyURL as in the Redirect-Only mode. Redirect-Failure is appropriate if you wish to send the customer into the Online Store only if the integration is successful, but lack the ability to read in the values of the Reply POST and take corresponding action for an unsuccessful integration.

    Display-Failure: Following a successful integration attempt (via the Request POST), the customer proceeds to the Online Store as in the Proceed-Only mode. Following an unsuccessful integration attempt, the Failure Reason is displayed on screen as in the Display-Only mode. Display-Failure is appropriate for debugging purposes when developing your integration, if you lack the ability to read in the values of the Reply POST used in the Reply-Failure mode. Using Display-Failure in a live integration is not recommended.

    Note: If the customer lands on a page within the Online Store following an integration attempt, the body tag of that page includes the css class nextIntegrationSuccess or nextIntegrationFailure, as appropriate.

    REQUEST POST FIELDS

    Customer Fields
    Field Name Description Notes Data Type (Max Length) Required for New Customers
    LAST_NAME Customer's Last Name   Text (50) Yes
    FIRST_NAME Customer's First Name   Text (30) Yes
    EMAIL Customer's E-Mail Address   Text (50) Yes
    ADDRESS_LABEL Customer's Contact Address Label   Text (25) No
    COMPANY_NAME Customer's Company Name   Text (100) Conditional1
    ADDRESS1 Customer's Street Address, Line 1   Text (100) Yes
    ADDRESS2 Customer's Street Address, Line 2   Text (100) No
    CITY Customer's City   Text (50) Yes
    STATE Customer's State/Province
  • Use recognized 2 letter state/province abbreviations (refer to http://www.nexternal.com/documentation/statescountries.htm for a complete list), or leave blank (if State/Province does not apply)
  • Integrity must be maintined between STATE and COUNTRY
  • Text (2) Conditional2
    POSTAL_CODE Customer's Postal (Zip) Code   Text (20) Yes
    COUNTRY Customer's Country
  • Use recognized 2 letter country codes (refer to http://www.nexternal.com/documentation/statescountries.htm for a complete list)
  • Integrity must be maintained between STATE and COUNTRY
  • May not be a country denied access to the Online Store (Settings/Anti-Fraud and Security in the Order Management System)
  • Text (2) Yes
    ADDRESS_TYPE Contact Address Type
  • Use 1 for Business and 0 for Residential
  • Defaults to 0 (Residential) for new customers (if not specified)
  • Boolean No
    PHONE_NUM Customer's Phone Number Subject to a minimum number of digits if the Minimum Phone Digits feature is in use (Settings/Site Options in the Order Management System) Text (30) Yes
    PHONE_EXT Customer's Phone Extension   Text (30) No
    PRIMARY_SHIP Primary Ship To Address
  • Use 1 for Yes and 0 for No
  • Defaults to 0 (No) for new customers (if not specified)
  • Boolean No
    PRIMARY_BILL Primary Bill To Address
  • Use 1 for Yes and 0 for No
  • Defaults to 0 (No) for new customers (if not specified)
  • Boolean No
    DISCOUNT Customer Discount
  • Express as a decimal number between 0 and 1
  • Defaults to 0 for new customers (if not specified)
  • Must be blank if the Allow Customer Discount option (Customers/Integration in the OMS) is off
  • Float No
    ACTIVE Active Status
  • Use 1 for Yes and 0 for No
  • Defaults to 1 (Yes) for new customers (if not specified)
  • Must be blank if the Allow Active option (Customers/Integration in the OMS) is off
  • Boolean No
    MAILING_LIST Mailing List Status
  • Use 1 for Yes and 0 for No
  • Defaults to 1 (Yes) for new customers (if not specified)
  • Boolean No
    CUST_TYPE Customer Type
  • Must be a recognized Customer Type (Customers/Types in the OMS)
  • Defaults to the Default Type for new customers (if not specified)
  • Must be blank if the Allow Customer Type option (Customers/Integration in the OMS) is off
  • Text (20) No
    PASSWORD Customer's Password   Text (50) Conditional3
    PASSWORD_REMINDER Customer's Password Reminder (Hint)   Text (100) No
    CUSTOM_FIELD1 Custom Field #1 For type Yes/No, use 1 for Yes and 0 for No Conditional (50) Conditional4
    CUSTOM_FIELD2 Custom Field #2 For type Yes/No, use 1 for Yes and 0 for No Conditional (50) Conditional4
    CUSTOM_FIELD3 Custom Field #3 For type Yes/No, use 1 for Yes and 0 for No Conditional (50) Conditional4
    CUSTOM_FIELD4 Custom Field #4 For type Yes/No, use 1 for Yes and 0 for No Conditional (50) Conditional4
    CUSTOM_FIELD5 Custom Field #5 For type Yes/No, use 1 for Yes and 0 for No Conditional (50) Conditional4
    CUSTOM_FIELD6 Custom Field #6 For type Yes/No, use 1 for Yes and 0 for No Conditional (50) Conditional4
    CUSTOMER_NO Customer Number May be used for matching purposes only (will be ignored otherwise) Integer No
    1May be required, optional, or not in use, as set at Customers/Types in the Order Management System
    2Required if COUNTRY has associated STATE values -- otherwise must be left blank; please refer to http://www.nexternal.com/documentation/statescountries.htm
    3Required if the Require Password option is on (Customers/Password Preferences in the Order Management System); you may enable password auto-generation for Customer Integration at Customers/Password Preferences
    4Required if that Custom Field is required (Customers/Custom Fields in the Order Management System)

    Administrative Fields
    Field Name Description Notes
    Matchn nth field to be used for customer matching
  • n must be an integer starting with 1
  • Value must be the name of a Customer Field
  • If any Match field is included and the Require Password for Matching option (Customers/Integration in the OMS) is on, PASSWORD must be included as a match field
  • Mode Integration Mode
  • Allowed values are Reply-Only, Redirect-Only, Proceed-Only, Reply-Failure, Redirect-Failure, and Display-Failure
  • Defaults to Proceed-Only if not specified
  • ReplyURL URL to which the Reply POST is directed for Reply-Only and Reply-Failure modes; or to which the customer is redirected for Redirect-Only and Redirect-Failure modes
  • Must be a full URL beginning with http:// or https:// (preferred)
  • Required for Reply-Only, Redirect-Only, Reply-Failure, and Redirect-Failure modes; not relevant for Proceed-Only and Display-Failure modes


  • Example:

    <form name="Customer" method="post" action="https://www.nexternal.com/fairway/default.aspx">
    <input type="hidden" name="LAST_NAME" value="Woods">
    <input type="hidden" name="FIRST_NAME" value="Tiger">
    <input type="hidden" name="EMAIL" value="demo@demo.com">
    <input type="hidden" name="ADDRESS_LABEL" value="Home">
    <input type="hidden" name="ADDRESS1" value="956 18th St.">
    <input type="hidden" name="CITY" value="La Jolla">
    <input type="hidden" name="STATE" value="CA">
    <input type="hidden" name="POSTAL_CODE" value="92037">
    <input type="hidden" name="COUNTRY" value="US">
    <input type="hidden" name="ADDRESS_TYPE" value="0">
    <input type="hidden" name="PHONE_NUM" value="760-730-9015">
    <input type="hidden" name="PHONE_EXT" value="882">
    <input type="hidden" name="PRIMARY_SHIP" value="0">
    <input type="hidden" name="PRIMARY_BILL" value="0">
    <input type="hidden" name="PASSWORD" value="demo">
    <input type="hidden" name="MAILING_LIST" value="1">
    <input type="hidden" name="Match1" value="EMAIL">
    <input type="hidden" name="Match2" value="PASSWORD">
    <input type="hidden" name="Mode" value="Proceed-Only">
    <input type="submit" value="Shop Online">
    </form>

    Warning Field names are case sensitive.

    REPLY POST FIELDS (Reply-Only and Reply-Failure modes only)

    Field Name Description Notes
    (Same as Request POST) (Same as Request POST) Every field included in the Request POST is also included in the Reply POST, even if that field is not needed for Customer Integration
    Status Integration Status Value is either Success or Failure
    Action Action Taken
  • Successful Integration: Value is either Create (if a new customer was created) or Update (if a new customer was updated)
  • Failed Integration: Value is blank
  • FailureReason Reason for Failed Integration
  • Successful Integration: Value is blank
  • Failed Integration: Value is a textual description of the first error found