Relate Customer Integration

Purpose: Use the Relate customer integration to keep customer information in CWSerenade in sync with Relate when Relate is the system of record for customer information. This integration also keeps CWSerenade in sync with an additional system, such as your e-commerce site or your point-of-sale application, if that system also integrates with Relate as its system of record for customers.

When does CWSerenade communicate with Relate?

• Searching for a customer: When you search for an existing customer in a CWSerenade menu option, Relate returns a list of customers matching the search criteria. See Notes on Searching for a Customer on CWSerenade Screens for more information.

• Synchronizing customer information (add/update customer): Synchronization occurs when:

• You create a new customer in CWSerenade. CWSerenade sends a message indicating to create the new customer in Relate.

• You retrieve an existing customer record from Relate. When Relate sends the current customer information to CWSerenade, CWSerenade creates or updates its customer record based on the information received from Relate.

• You update an existing customer at a CWSerenade screen. CWSerenade sends an update message to Relate.

• You update an existing customer through the order API, in certain cases. See Customer Synchronization through the Order API for a discussion.

• You use a periodic function to synchronize CWSerenade customer records with Relate. CWSerenade sends its current customer information to Relate and stores the Relate ID in the Customer Sold To table. See Synchronizing Customer Information through a Periodic Function for more information.

How are synchronized customers linked? A pair of synchronized CWSerenade and Relate customer records are linked by matching customer numbers:

• CWSerenade : the Relate Id in the Customer Sold To table identifies the customer number in Relate

• Relate: the Serenade Alternate key in Relate identifies the customer number in CWSerenade. The RELATE_ALT_ID_SERENADE setting in Working with Customer Properties (PROP) defines the alternate key type for the CWSerenade customer number in Relate.

E-Commerce site: If your e-commerce site also uses Relate as the system of record for customers, then the e-commerce customer ID is also stored in Relate as an alternate key. In this situation, the e-commerce site might pass its customer ID in the CWOrderIn message to help CWSerenade identify the correct record when synchronizing customer information with Relate if the e-commerce site does not have the CWSerenade customer number. The e-commerce site does not pass the Relate ID to CWSerenade in the order API. See Customer Synchronization through the Order API for a discussion.

Setup for the Relate customer integration: Customer synchronization takes place if the Relate Customer Integration (L37) system control value is set to INTERACT. See Relate Integration Setup (Sales and Customer) for more information on required setup.

CWSerenade initiates contact: In the Relate customer integration, CWSerenade initiates all customer searches and add/update messages by sending these requests to Relate.

Relate version compatibility: The Relate customer integration in CWSerenade 4.5, as described below, is compatible with version 10.5 or higher of Relate.

In this topic:

• Relate Customer Integration: Typical Information Flows

• Customer Synchronization through the Order API

• When the Customer Registers or Logs in at the E-Commerce Site

• When the Customer Checks Out as a Guest at the E-Commerce Site or the E-Commerce Site Cannot Communicate with Relate

• When CWSerenade Cannot Communicate with Relate

• When the Customer Contacts the Call Center

• Additional Ways to Create or Update a Customer in CWSerenade and Relate

• Notes on Searching for a Customer on CWSerenade Screens

• Customer Data Mapping between CWSerenade and Relate

• Updating an Existing Customer

• Synchronizing Customer Information through a Periodic Function

• Relate Customer Integration: Notes and Troubleshooting

• Activities that do not Trigger Communication with Relate

• Deleting Certain Information for an Existing Customer

• Functions that are Inconsistent with the Relate Customer Integration

For more information: See:

• Relate Batch Customer and Sales Integration for more information on sending merchandise hierarchy, item, customer, sales and return information from CWSerenade to Relate using a batch process. This section also includes Relate Integration Setup (Sales and Customer).

• Relate Purchase History Integration for more information on reviewing completed sales and return transactions from Relate on the Display Purchase History Screen in CWSerenade.

• Relate Customer Wish List Integration for more information on how to review and modify a customer’s wish list from Relate using the Display Wish List Screen in CWSerenade.

• Relate Loyalty Integration for more information on using the Relate Loyalty integration with CWSerenade.

• The Relate Implementation Guide (Installer Version) for more information on the procedures and instructions required to install and configure the Relate application and database.

• The Relate Configuration Guide for more information on configuration settings for Relate that are defined using the Conflate tool.

• The Relate Batch Processing and Web Services Guide for more information on the Relate API interface.

• The Relate Database Dictionary for more information on the tables in the Relate database.

• The Relate User Guide for more information on using the Relate application.

Relate Customer Integration: Typical Information Flows

Overview: Through the customer integration with Relate, information about the customer flows between the e-commerce site, the point-of-sale (POS) system, Relate, and CWSerenade, so that the customer’s current name, address, and email address are synchronized across systems. Relate stores both the CWSerenade customer number and the e-commerce customer number as alternate keys. The Relate Customer Integration (L37) system control value must be set to INTERACT.

Orders also flow between systems, such as between the POS system and Locate, and the customer information included in an order can trigger customer creation or update across systems.

Customer Synchronization through the Order API

Communication between Relate, the e-commerce site, and CWSerenade through the Generic Order Interface (Order API) varies, depending on whether the customer registers and is logged in at the e-commerce site.

• Registered: If the customer registers or logs in at the e-commerce site, then the e-commerce site and Relate synchronize customer information in Relate before the e-commerce site sends the order to CWSerenade. In this situation, CWSerenade does not need to notify Relate to create the customer record, since the communication between the e-commerce site and Relate has already taken place; however, if the customer did not previously exist in all of the integrated systems or the customer information was not previously synchronized, CWSerenade might need to update Relate with its customer number, and record the Relate ID in the Customer Sold To table. The most likely scenarios are described below.

Scenario	Can Occur When:	More Information:
Site has received CWSerenade customer number from Relate: The e-commerce site synchronizes customer information with Relate, where at that time there was a CWSerenade customer number as an alternate key.	The customer has previously placed an order in CWSerenade, either through the order API or through the call center, and CWSerenade has already synchronized the customer information with Relate. In this scenario, Relate provides the CWSerenade customer number to the e-commerce site, and the e-commerce site provides the CWSerenade customer number in the CWOrderIn message. CWSerenade updates its own customer record with current name and address information, but does not need to communicate with Relate, since the e-commerce site has already done so.	When the Customer Registers or Logs in at the E-Commerce Site
Site does not have CWSerenade customer number: The e-commerce site synchronizes customer information with Relate, and at that time there is no CWSerenade customer number in Relate as an alternate key.	A new customer registers on the e-commerce site and creates an order, and no previous communication has occurred between CWSerenade and Relate. In this scenario, the e-commerce site provides its own e-commerce ID in the CWOrderIn message, and CWSerenade needs to synchronize its customer information with the current information that is already in Relate and the e-commerce site, including assignment of the current Relate ID to the CWSerenade customer record.	When the Customer Registers or Logs in at the E-Commerce Site
E-Commerce site does not communicate with Relate	The customer checks out as a guest or the e-commerce site is unable to communicate with Relate for any reason before submitting the order to CWSerenade, even if the customer might already exist in either Relate or CWSerenade, or both. In this situation, CWSerenade notifies Relate to create or update the customer.	When the Customer Checks Out as a Guest at the E-Commerce Site or the E-Commerce Site Cannot Communicate with Relate

After CWSerenade ships the order, it uses the Relate Batch Customer and Sales Integration to communicate sales information to Relate.

The communication flows described below are:

• When the Customer Registers or Logs in at the E-Commerce Site

• When the Customer Checks Out as a Guest at the E-Commerce Site or the E-Commerce Site Cannot Communicate with Relate

• When CWSerenade Cannot Communicate with Relate

When the Customer Registers or Logs in at the E-Commerce Site

Registration (new account) or login (existing account): The registration or account login process involves communication between Relate and the e-commerce site. For example:

• When the customer logs into the e-commerce site or creates a new account, the e-commerce site:

• searches Relate for the customer

• if the customer does not exist in Relate, sends an add/update message to create the customer in Relate

• if the customer does exist in Relate, sends an add/update message to update the customer in Relate with any changes to the customer’s name or address

• Relate:

• creates the customer record if it does not exist, using the e-commerce site’s customer number as an alternate key; otherwise,

• updates the customer record if it already exists, including adding the e-commerce site’s customer number as an alternate key, and updating the current name and address if necessary

• acknowledges the e-commerce site’s request, including the e-commerce ID, the Relate ID, and the CWSerenade customer number if it already exists as an alternate key

Submitting the order for an existing CWSerenade customer: The e-commerce site should include the CWSerenade customer number, if it is available, in the CWOrderIn message. This could occur if:

• the customer has previously registered at the e-commerce site and used it to place an order; or,

• the customer has previously placed an order through the call center as well as registering through the e-commerce site, and CWSerenade and Relate have synchronized the customer records independently of the e-commerce site.

In this scenario:

• the customer record in Relate includes:

• the Relate ID

• the CWSerenade customer number as an alternate key

• the e-commerce ID as an alternate key

• the CWOrderIn message from the e-commerce site should include:

• the current customer name and address

• the CWSerenade customer_number

• the relate_cust_sync_success flag set to Y, indicating that the e-commerce site and Relate have been synchronized with current customer information

• the sold_to_address_update flag set to Y, indicating that CWSerenade should update the customer information from the message in the CWSerenade database

• CWSerenade updates the customer name and address using the information from the CWOrderIn message and does not communicate with Relate, since the e-commerce site has already communicated with Relate.

Exceptions:

• If the customer record with the specified number does not currently exist in CWSerenade (for example, as a result of a merge/purge), CWSerenade uses its standard matchcode search logic (see Customer Creation, Matching and Update Logic in the Order API) to attempt to find the customer in the Customer Sold To table, creates or updates the customer as needed, and sends the current customer information, including the CWSerenade customer number, to Relate.

• If the customer exists, but does not currently have a Relate ID, CWSerenade sends an update to Relate and then updates the customer with the Relate ID it receives in the response.

Note: MICROS recommends that the sold_to_address_update flag always be set to Y when the CWOrderIn message includes customer name and address information.

When it creates the order, CWSerenade sends the CWORDEROUT message, including the CWSerenade customer number, to the e-commerce site.

Note: If the e-commerce system submits multiple CWOrderIn messages for the same order (for example, if the payment information is sent after the initial message), it should include the CWSerenade customer number each time.

Submitting the order without a CWSerenade customer number: If the e-commerce site does not receive a CWSerenade customer number from Relate, it should include its own e-commerce ID instead. This situation could occur if:

• the customer has previously registered at the e-commerce site, which synchronized the customer information between Relate and the e-commerce site, but has not placed an order through the order API, and CWSerenade and Relate have not previously synchronized the customer records independently of the e-commerce site, or

• this is a new customer that has just registered at the e-commerce site, creating a new customer record in Relate.

In either case, the Relate customer record does not currently include the CWSerenade customer number as an alternate key.

In this scenario:

• the customer record in Relate includes:

• the Relate ID

• the e-commerce ID as an alternate key

• the CWOrderIn message from the e-commerce site should include:

• the current customer name and address

• the ecommerce_id

• the relate_cust_sync_success flag set to Y, indicating that the e-commerce site and Relate have been synchronized with current customer information

• the sold_to_address_update flag set to Y, indicating that CWSerenade should update the customer information from the message in the CWSerenade database

• To synchronize the customer records across the systems, CWSerenade:

• searches for the customer in CWSerenade using its standard matchcode search logic; see Customer Creation, Matching and Update Logic in the Order API

• if it finds a matching customer and that customer does not currently have a Relate ID:

• updates the customer with the information from the CWOrderIn message, temporarily saving the e-commerce ID

• sends an update to Relate indicating both the e-commerce ID and the CWSerenade customer number to add as an alternate key

• updates the customer with the Relate ID and deletes the e-commerce ID

• if it finds a matching customer in CWSerenade and that customer already has Relate ID, or it does not find a matching customer:

• creates a new customer in CWSerenade, temporarily saving the e-commerce ID on the customer record

• sends an update to Relate indicating both the e-commerce ID and the new CWSerenade customer number to add as an alternate key

• updates the new customer with the Relate ID and deletes the e-commerce ID

Note:

• CWSerenade temporarily retains the e-commerce ID on the customer record until the customer information between Relate and CWSerenade is synchronized; then it deletes the e-commerce ID.

• CWSerenade creates a new customer rather than using the existing, matching customer with the Relate ID because the existing customer is not correctly synchronized with Relate. If the customer records in CWSerenade and Relate were correctly synchronized, the CWOrderIn message would have included the CWSerenade customer number.

• MICROS recommends that the sold_to_address_update flag always be set to Y when the CWOrderIn message includes customer name and address information.

When it creates the order, CWSerenade sends the CWORDEROUT message, including the CWSerenade customer number, to the e-commerce site.

When the Customer Checks Out as a Guest at the E-Commerce Site or the E-Commerce Site Cannot Communicate with Relate

Unknown customer? If the e-commerce site has not synchronized the customer information with Relate, the CWOrderIn message does not include either the CWSerenade customer number or the e-commerce ID. This situation could occur if:

• the customer has opted to check out as a guest, or

• communication is down between the e-commerce site and Relate.

In either case, the e-commerce site cannot determine whether the customer record exists in either Relate or CWSerenade.

In this scenario:

• the CWOrderIn message from the e-commerce site should include:

• the current customer name and address

• the relate_cust_sync_success flag set to N, indicating that the e-commerce site and Relate have not been synchronized with current customer information

• the sold_to_address_update flag set to Y, indicating that CWSerenade should update the customer information from the message in the CWSerenade database

Note: In this scenario, the CWOrderIn message does not include either the CWSerenade customer number or the e-commerce ID.

• To synchronize the customer records across the systems, CWSerenade:

• searches for the customer in CWSerenade using its standard matchcode search logic; see Customer Creation, Matching and Update Logic in the Order API

• if it finds a matching customer and that customer does not currently have a Relate ID:

• updates the customer name and address with the information from the CWOrderIn message

• sends an update to Relate including the CWSerenade customer number to add as an alternate key and the current name and address information from the CWOrderIn message, and updates the CWSerenade customer with the Relate ID

• if it finds a matching customer and that customer already has a Relate ID

• updates the customer with the information from the CWOrderIn message

• sends an update to Relate, including the CWSerenade customer number and the current name and address information

• if there is no matching customer in CWSerenade:

• creates a new customer in CWSerenade using the information from the CWOrderIn message

• sends a message to search Relate based on the customer’s email address

• if Relate returns any matching customers, selects the first customer in the response that does not currently have a CWSerenade alternate key; sends an update to Relate, including the CWSerenade customer number to add as an alternate key and the current name and address information from the CWOrderIn message; and updates the CWSerenade customer with the Relate ID

• if Relate does not return any matching customers, creates a new customer in Relate and synchronizes the current customer name and address, CWSerenade customer number, and Relate ID between CWSerenade and Relate

Note: CWSerenade searches Relate for a customer using email address only if the relate_cust_sync_success flag is set to N.

Exception: If CWSerenade creates a new customer or selects an existing customer without a Relate ID, but Relate returns only customers that already have CWSerenade alternate keys in the search response, CWSerenade selects the first customer record returned in the search response and updates it with the current name and address information and the Relate ID.

Note: MICROS recommends that the sold_to_address_update flag always be set to Y when the CWOrderIn message includes customer name and address information.

When it creates the order, CWSerenade sends the CWORDEROUT message, including the CWSerenade customer number, to the e-commerce site.

When CWSerenade Cannot Communicate with Relate

If CWSerenade cannot communicate with Relate during order API processing, it selects the Synchronize with remote DB flag for the customer sold to record. The next time you run the SYNCRDB periodic function, it attempts to synchronize the CWSerenade customer record with Relate.

If an e-commerce ID was passed in the CWOrderIn message, this ID is stored in the Customer Sold To table until the record is synchronized.

See Synchronizing Customer Information through a Periodic Function for more information on the SYNCRDB periodic function.

What Does the relate_cust_sync_success flag Control?

The relate_cust_sync_success flag in the CWOrderIn message indicates whether the e-commerce site has successfully synchronized information about the customer with Relate. If this flag is set to Y:

• When the system searches CWSerenade for a customer using standard customer selection rules, if the selected customer already has a Relate ID, the system creates a new customer for the order, since the existing CWSerenade customer record is not consistent with the Relate customer record. The system then sends an update to Relate that includes the new customer number as well as the e-commerce ID, if available.

• When creating a new customer for the order, the system does not search Relate for a customer record based on email address; it only sends an update, as described above.

• The system does not send an update to Relate if the CWOrderIn message specifies a valid CWSerenade customer number, and the customer already has a Relate ID.

Otherwise, if this flag is set to N:

• When the system searches CWSerenade for a customer using standard customer selection rules, if the selected customer already has a Relate ID, the system uses this customer instead of creating a new customer for the order, and sends an update to Relate.

• The system searches Relate for a customer record based on the email address for the customer on the order when it creates a new customer because a customer does not match the name and address in the CWOrderIn message, or when it selects an existing customer that does not have a Relate ID or an e-commerce ID.

• The system always sends a create/update request to Relate that includes the customer’s name, address, and customer number.

When the Customer Contacts the Call Center

Overview: A customer can also create an order by contacting the call center. When the customer contacts the call center to place an order, request a catalog, create a customer membership outside of order entry, or update name and address information, the CSR needs to first search for the customer in order to keep the Relate and CWSerenade customer records in sync and prevent creating duplicate records. The process when a customer contacts the call center is:

• Search Relate first: When the CSR performs a search, CWSerenade first checks in Relate for any matches. Unlike the process used for the order API, the customer search can send various criteria to Relate. If the CSR selects a customer from the search results and enters any updates, CWSerenade syncs these updates with the Relate customer record.

• Search CWSerenade second: If the CSR’s search does not find any matches in the Relate database, CWSerenade checks for any matches in its Customer Sold To table. When the CSR selects and works with a CWSerenade record, CWSerenade sends the current information to Relate, creating the customer record there.

• Create customer if no match: If there are no matches in either database, then the CSR can create a new customer, and CWSerenade sends the new customer record to Relate.

Examples of these processes are provided below.

Searching Relate for the customer

When the customer contacts the call center to place an order, request a catalog, create a customer membership outside of order entry, or update name and address or other information:

Searching:

• The CSR enters the search criteria at the Customer Scan Screen.

• There is at least one customer record in Relate that matches the search criteria.

• The Results tab at the Customer Scan screen displays the names, home addresses, email addresses, and primary phone numbers of any customers in the Relate database matching the search criteria. The Results tab displays the error message Maximum search results exceeded, please refine your search if the number of matching records exceeds the Customer Lookup Limit setting in Relate Conflate. In this situation, you need to make your search criteria more specific to make sure that you can find the customer record you are looking for.

Selecting a customer from the Relate search results:

• If the CSR selects a record from the Results tab:

• CWSerenade requests information on the complete customer record from Relate.

• Relate sends the customer information, including the alternate key, if any, that maps to the CWSerenade customer number.

• If the alternate key identifies an existing customer in the Customer Sold To table, CWSerenade updates the customer record with the current information from Relate.

• If there is not an alternate key that identifies an existing customer in CWSerenade, CWSerenade creates a new customer record.

Searching CWSerenade for the customer

Searching:

• The CSR enters the search criteria at the Customer Scan Screen.

• There are no records in Relate that match the search criteria, but there is at least one match in the CWSerenade Customer Sold To table.

• The Results tab at the Customer Scan screen displays the names, home addresses, email addresses, and primary phone numbers of any customers in CWSerenade’s Customer Sold To table that match the search criteria.

Selecting a customer from the CWSerenade search results:

• If the CSR selects a record from the Results tab:

• CWSerenade retrieves the current information from its Customer Sold To table.

• When the CSR updates or accepts the customer information, CWSerenade sends an add/update message to Relate.

• Relate creates the customer record, assigning the CWSerenade customer number as an alternate key, and sends the Relate customer number to CWSerenade.

• CWSerenade updates the Customer Sold To record with the Relate Id.

 

Creating a new customer

Searching:

• The CSR enters the search criteria at the Customer Scan Screen.

• There are no records matching the search criteria in either Relate or CWSerenade.

• The Results tab at the Customer Scan screen does not display any records.

Creating the customer:

• When the CSR enters the information on the new customer:

• CWSerenade creates the customer record in its Customer Sold To table.

• CWSerenade sends an add/update message to Relate.

• Relate creates the customer record, assigning the CWSerenade customer number as an alternate key, and sends the Relate customer number to CWSerenade.

• CWSerenade updates the Customer Sold To record with the Relate Id.

 

Notes on Searching for a Customer on CWSerenade Screens

Since the Relate customer integration is based on Relate acting as the system of record for customer information, searching on CWSerenade screens always looks to Relate first for the customer unless the menu option is related to existing orders.

Customer Scan screen availability: CWSerenade provides the Customer Scan Screen to search for a customer in order entry, customer maintenance, customer membership creation, and catalog requests if the Relate Customer Integration (L37) system control value is set to INTERACT. When you search using this screen, the system first calls Relate when searching for customers, and checks the CWSerenade Customer Sold To table only if Relate does not return any records that match your search criteria.

You cannot use the Customer Scan Screen when searching for a customer in regular or streamlined order inquiry, order maintenance, or return authorizations, because these options are related to existing orders for the customer in CWSerenade. In these options, if you scan on a field related to customer name or address, you advance to a subsequent scan screen that displays customer records from the CWSerenade database.

Note: If the CSR creates a new customer without first searching, this indicates to create the customer in Relate regardless of whether any duplicate customers exist there.To avoid creating duplicate customers in Relate, it is important to search first.

For more information: See the Customer Scan Screen for more information on searching for customers at CWSerenade screens.

Additional Ways to Create or Update a Customer in CWSerenade and Relate

In addition to order entry, you can search for, create, or update a customer through the additional options listed below. If the Relate Customer Integration (L37) system control value is set to INTERACT:

Option	Description	For more information, see:
Interactive catalog requests (WCAT)	When you select Customer at the Create Catalog Request Screen to search for an existing customer, you advance to the Customer Scan Screen. Otherwise, if you create a new customer to receive the catalog, CWSerenade sends the customer information to Relate and the customer records are linked by customer numbers so that they stay synchronized.	Entering Catalog Requests (WCAT)
Catalog request interface (WCRU)	When you create a customer through the catalog request interface, the new customer information is also created in Relate.	Working with the Catalog Request Interface (WCRU)
Customer maintenance (WCST)	When you select the Work with Customers option, you advance to the Customer Scan Screen. When you: • search for or retrieve an existing customer, the information is provided by Relate if the customer record exists there • create a new customer or update customer name, address, email, phone, or preferences, the customer information is sent to Relate so that the records are synchronized	Work with Customers (WCST)
Work with Customer Memberships (WWCM)	When you prompt on the Customer # field at the Create Customer Membership Window, you advance to the Customer Scan Screen. If you: • search for or retrieve an existing customer, the information is provided by Relate if the customer record exists there • create a new customer or update customer name, address, email, phone, or preferences, the customer information is sent to Relate so that the records are synchronized	Working with Customer Memberships (WWCM)
Customer API	When you receive the Inbound Customer Message (CWCustomerIn) to create a new customer or update customer name, address, email, phone, or preferences, the customer information is sent to Relate so that the records are synchronized. Note: Resubmitting a customer API request through Working with Customer API (WCAI) is not currently implemented.	Generic Customer API
Order Broker integration (retail pickup and delivery orders)	When you: • create a retail pickup or delivery order for a new customer, the customer information is sent to Relate so that the records are synchronized • update an existing customer through a retail pickup or delivery order, the updated customer information is sent to Relate for synchronization if the Sold to Email Update for Orders Brokered to Serenade (K96) or Sold to Address Update for Orders Brokered to Serenade (K97) system control values are selected	Retail Pickup or Delivery Orders
Creating or selecting an order recipient	When you: • search for or retrieve an existing customer as an order recipient, the information is provided by Relate if the customer record exists there • create a new customer as an order recipient, or update customer name, address, email, phone, or preferences for the recipient, the customer information is sent to Relate so that the records are synchronized Note: Only sold-to and recipient customers are synchronized with Relate. Order ship-tos, permanent ship-tos, and individual customers are not included in the integration with Relate.	Adding a Recipient Order in Order Entry
Order maintenance	When you: update the customer name, address, email, phone, or preferences for the customer placing or receiving the order (recipient customer but not a permanent ship-to, order ship-to, or individual), the updated customer information is sent to Relate. This update occurs regardless of whether the customer was previously synchronized with Relate.	Work with Order Screen in Order Maintenance

Customer Data Mapping between CWSerenade and Relate

Overview: The table below lists the fields that are mapped between CWSerenade and Relate in the customer integration.

Note:

• When CWSerenade creates or updates a customer, it puts alphanumeric information in all uppercase. If the customer name and address in Relate is not all uppercase, this indicates that CWSerenade has not created or updated the customer. The exception is the email address, which can be upper and lower case in both Relate and CWSerenade.

• Not all mapped fields are the same length in both systems. When CWSerenade imports information from Relate, it truncates certain fields as indicated in the table below, and updates the corresponding fields in Relate with the truncated information.

Reviewing the customer in Relate: Use the Customer Lookup / Edit option in Relate to search for, review, or update a customer.

Which tables? Customer records are stored in:

• CWSerenade : the Customer Sold To table, except where noted below.

• Relate: the CST_CUSTOMER table.

For more information: See the Information that is not mapped for a listing of some of the fields that are not mapped as part of the Relate customer integration.

CWSerenade Field	Relate Field	Comments
Customer numbers
Displaying in Relate: • CWSerenade customer number: select Alternate Key. • Relate ID: labeled the Customer Id.
Customer number	Alternate key SERENADE_ID	Indicates the Alt Key Type of the alternate key in Relate that maps to the CWSerenade customer number. This field is available for display in Relate by selecting Alternate Key in the Customer Lookup /Edit option. Relate automatically creates this entry for a customer when you send the customer to Relate interactively or through the Relate Add or Update Customer Message if it does not already exist based on the RELATE_ALT_ID_SERENADE setting in the Relate Properties file. In this situation, Relates also adds a row to the CST_ALT_KEY_TYPCODE table in the Relate database if it does not already exist.
Relate id	Customer ID	Note: The Relate id: • is not displayed on any screen in CWSerenade • is an alphanumeric field in the CWSerenade Customer Sold To table
Name Displaying in Relate: Under Customer.
Prefix	Prefix	Truncated in CWSerenade to 3 positions. Any trailing spaces are removed.
First name	First name	Truncated in CWSerenade to 15 positions. Any trailing spaces are removed.
Middle initial	Middle name	Truncated in CWSerenade to 1 position. Any trailing spaces are removed.
Last name	Last name	Truncated in CWSerenade to 25 positions. Any trailing spaces are removed.
Suffix	Suffix	Truncated in CWSerenade to 3 positions. Any trailing spaces are removed.
Company	Business Name	Truncated in CWSerenade to 30 positions. Any trailing spaces are removed.
Customer-level information and permissions The customer-level permissions in Relate are informational only. Displaying in Relate: Included under the Customer option. See above.
Retail Store ID	Signup Store	The value defined in the Default Location for Sales Download (K69) system control value.
	Home Store
N/A	Source	Contact Center defaults when a new customer is sent to Relate.
Mail flag	Mail contact permission flag	CWSerenade to Relate: Y defaults if the Mail flag is selected; otherwise leave blank. Relate does not send this setting to CWSerenade.
Opt in/out setting for primary email address	Email contact permission flag	CWSerenade to Relate: Y defaults if the Email status setting for the primary email address is O1; otherwise leave blank (N). Relate does not send this setting to CWSerenade.
Day or Evening phone number	Phone contact permission flag	CWSerenade to Relate: Y defaults if a Day or Evening phone number exists; otherwise leave blank. Relate does not send this setting to CWSerenade.
Do not fax	Fax contact permission flag	CWSerenade to Relate: Y defaults if the Third Phone Number Type (L53) system control value is set to FAX and the Do Not Fax field for the customer in CWSerenade is unselected; otherwise leave blank. Relate does not send this setting to CWSerenade.
Rent	Rent contact permission flag	The setting of the Default Rent Name (D11) system control value always overrides any other setting in both CWSerenade and Relate once the customers are synchronized; however, if the Default Rent Name (D11) system control value is blank, the setting for the customer applies.
Default Male/Female Profile Code (C74)	Gender	CWSerenade to Relate: The default value defined for the profile code in the Default Male/Female Profile Code (C74) system control value. Note: Mapped only if a value is defined in the Default Male/Female Profile Code (C74) system control value, the value to pass is M or F, and the Send Profile Data to Relate (L51) system control value is selected. Relate to CWSerenade: The M or F value defined for the Gender field. If a value other than M or F is passed from Relate, CWSerenade uses the default value defined for the profile code in the Default Male/Female Profile Code (C74) system control value.
Birth Month and Birth Date	Birth date	CWSerenade to Relate: The month and date defined in the Birth month and Birth date fields for the customer. The year passed to Relate defaults to 1900; however this year is not used if a birth year has already been defined in Relate. Note: If you remove the Birth month and Birth date from the customer in CWSerenade, the Birth date defined in Relate is retained. Relate to CWSerenade: The date defined in the Birth date field, including the actual month, day, and year defined.
Address Important: Only the customer’s HOME address in Relate is mapped to CWSerenade. If more than one HOME address exists in Relate, the system uses the primary HOME address. This information is required in order for CWSerenade to create the customer record correctly. Relate automatically creates an Address type of HOME when it receives a customer from CWSerenade interactively or through the Relate Add or Update Customer Message. In this situation, Relates also adds a row to the CST_ADDR_TYPCODE table for ADDRESS_TYPECODE HOME in the Relate database if it does not already exist. No address validation in Relate: Unlike CWSerenade, Relate does not require an address for a customer, and does not validate that the address includes certain required components; for example, no address lines are required. To prevent problems in CWSerenade, it is important that any other means you use to create customers in Relate, such as through your e-commerce site, always creates a home address when you use the Relate customer integration. If a home address does not exist in Relate, Relate displays the customer in CWSerenade without an address. Also, if certain fields for the home address are not defined in Relate, these fields will be blank when you display the customer in CWSerenade. However, when you update the customer’s address in CWSerenade so that is passes validation, the system will also update the customer’s home address in Relate Displaying in Relate: Select Address.
N/A	Primary	Set to Yes in Relate.
Street	Address line 1	Truncated in CWSerenade to 32 positions. Any trailing spaces are removed.
Apt/Suite	Apartment	Truncated in CWSerenade to 32 positions. If deleted in CWSerenade, also deleted in Relate. Any trailing spaces are removed.
Address (lines 2-4)	Address lines 2-4	Truncated in CWSerenade to 32 positions. Stored in the Customer Sold To Extended table. If deleted in CWSerenade, also deleted in Relate. Any trailing spaces are removed.
City	City	Truncated in CWSerenade to 25 positions. Any trailing spaces are removed.
State	State	Truncated in CWSerenade to 2 positions and validated against the states in the Country table. Any trailing spaces are removed.
Postal code	Postal code	Truncated in CWSerenade to 10 positions and validated against the SCF table. Any trailing spaces are removed.
Country	Country	Must be a 2-position country code; validated in CWSerenade against the Country table. Note: MICROS recommends that you use the two-position ISO country code; for example, use US instead of USA. Any trailing spaces are removed.
Mail	Contact permission/opt in setting (address level)	CWSerenade to Relate updates: • Y in CWSerenade = Y in Relate • N in CWSerenade = N in Relate Relate to CWSerenade updates: • Y or any setting starting with Y in Relate = Y in CWSerenade • N or any setting starting with N in Relate = N in CWSerenade Note: The mail permission setting in Relate must consist of or start with the letters Y or N; otherwise, synchronizing the customer with CWSerenade results in an error when validating the customer in CWSerenade because the only valid settings in CWSerenade are Y and N.
Phone numbers The phone numbers in CWSerenade map to the soft-coded Telephone types based on the Relate Properties. Relate automatically creates the Telephone type codes of HOME, BUSINESS, and FAX or MOBILE when it receives a customer from CWSerenade interactively or through the Relate Add or Update Customer Message. In this situation, Relates also adds rows to the CST_PHONE_TYPCODE table for types of WORK, HOME, and FAX or MOBILE in the Relate database if they do not already exist. Note: Phone number extensions are not mapped between Relate and CWSerenade. Phone numbers in CWSerenade are stored in the Customer Sold To Phone # table. Any formatting is removed from the phone number before sending to Relate. Removing a phone number: If you delete a phone number in either Relate or CWSerenade, the system deletes the associated phone number in the other system. Displaying in Relate: Select Phone. Optionally, highlight a phone number to open the Phone Detail window.
Day	varies	The RELATE_DAY_PHONE_LABEL setting in the Relate Properties file indicates the Telephone Type in Relate that maps to the daytime phone number in CWSerenade; this setting should be set to BUSINESS. Any trailing spaces are removed from the phone number. Primary? If there is a daytime phone number, this phone number in Relate is flagged as Primary by default after synchronizing customer information with CWSerenade.
Eve	varies	The RELATE_EVE_PHONE_LABEL setting in the Relate Properties file indicates the Telephone Type in Relate that maps to the evening phone number in CWSerenade; this setting should be set to HOME. Any trailing spaces are removed from the phone number. Primary? If there is no daytime phone number, then the evening phone number in Relate is flagged as Primary by default after synchronizing customer information with CWSerenade. Also, if you delete the daytime phone number in CWSerenade, then the evening phone number is flagged as Primary in Relate.
Mbl or Fax	varies	The RELATE_FAX_PHONE_LABEL setting in the Relate Properties file indicates the Telephone Type in Relate that maps to the third phone number in CWSerenade; this setting should be set to FAX or MOBILE. Any trailing spaces are removed from the phone number. Note: The Third Phone Number Type (L53) system control value controls whether the third phone number is labeled as the mobile or fax number in CWSerenade. Primary? If there is no daytime or evening phone number, then the fax/mobile phone number in Relate is flagged as Primary by default after synchronizing customer information with CWSerenade. Also, if you delete the daytime and evening phone number in CWSerenade, then the fax/mobile phone number is flagged as Primary in Relate.
N/A	Contact permission/opt in setting (phone-level)	For the day and evening phone numbers: Y defaults if a corresponding phone number is defined; otherwise N defaults. If the Third Phone Number Type (L53) system control value is set to FAX: • N defaults if the Do Not Fax field is selected for the customer. • Y defaults if the Do Not Fax field is unselected for the customer. If the Third Phone Number Type (L53) system control value is set to MOBILE: Y defaults if a mobile phone number is defined; otherwise, N defaults.
Email address In CWSerenade, the primary email address is stored in both the Customer Sold To table and the Customer Sold To Email table. Additional, non-primary email addresses are stored only in the Customer Sold To Email table. Only the HOME email address that is flagged as primary in Relate is eligible to be included in the integration. Relate automatically creates an Email type of HOME when it receives a customer from CWSerenade interactively or through the Relate Add or Update Customer Message. In this situation, Relates also adds a row to the CST_EMAIL_TYPCODE table for EMAIL_TYPECODE HOME in the Relate database if it does not already exist. Displaying in Relate: Select Email. Optionally, highlight the email address to open the Email Detail window.
N/A	Primary	Set to Yes in Relate.
Email address	Email type: HOME	Only the HOME email address that is flagged a primary is eligible to be included in the integration. If the customer has any other email type in Relate, but not a HOME email type, the email address(es) are not passed to CWSerenade. Any trailing spaces are removed.
Opt in/opt out	Contact permission/opt in setting (email level)	CWSerenade to Relate updates: • O1 in CWSerenade = Y in Relate • O2, O3, or O4 in CWSerenade = N in Relate Relate to CWSerenade updates: • Y in Relate = O1 in CWSerenade • N in Relate = O2 in CWSerenade • any other value in Relate = no change in CWSerenade
Format	Format preference	• H in CWSerenade = HTML in Relate • T or blank in CWSerenade = TEXT in Relate
Profile data In CWSerenade, profile data is stored in the Customer Profile table. Included in the integration? The Send Profile Data to Relate (L51) system control value controls whether to include demographic profile data when synchronizing customer information. Required setup: You need to complete the setup described under CWSerenade Customer Profile > Relate Attribute Definition in order to synchronize the information between the systems. Examples are provided below. Displaying in Relate: Select Attributes.
Profile description	Attribute name	Use the Setting Up Customer Profiles (WPFL) option in CWSerenade to set up the type of demographic information you are capturing, and also use the Attribute Definition screen in Relate to create a corresponding attribute definition for each CWSerenade profile code. Example: To capture marital status, you can set up: • CWSerenade : a profile category with a description of MARITAL STATUS • Relate: an attribute name of MARITAL STATUS and a description of MARITAL STATUS with a data type of Character Note: The default value defined for the profile code in the Default Male/Female Profile Code (C74) system control value maps to Relate’s gender if the value to pass is M or F.
Profile data description	Attribute value	Use the Setting Up Customer Profiles (WPFL) option in CWSerenade to set up each valid profile data value that you can capture. It is not necessary to set up valid data in Relate; Relate stores the data as a text string. Example: In the Setting Up Customer Profiles (WPFL) option in CWSerenade, set up profile data options such as: • Code = M • Description = MARRIED Relate stores an attribute value of MARRIED.
Additional information
user ID	Create user	For new customers, set to SERENADE-USERID, where USERID is the user ID of the person who performed the customer create, if the customer record originated in CWSerenade.
user ID	Update user	Set to SERENADE-USERID, where USERID is the user ID of the person who performed the customer update, if the customer record was most recently updated by CWSerenade.
N/A	Create date	The date when the customer record was created in Relate.
N/A	Update date	The most recent date when the customer record was changed. Activities in CWSerenade that change the Update date include: • selecting the customer for an order as the sold-to or order recipient • viewing the customer in customer maintenance • selecting the customer for a catalog request • selecting the customer for a customer membership in Working with Customer Memberships (WWCM) The above activities change the Update date in Relate, even if there is no change to the information about the customer or if you reject the order in order entry. Note: Creating an order for the customer through the order API changes the Update date in Relate if the sold_to_address_update flag in the CWOrderIn message is selected and no customer_number is passed, even if there is no change to the customer’s name and address information.
RELATE_ SECURITY_USER_ID	Security ID	The Relate user ID with security group permission defined in the RELATE_SECURITY_ USER_ID setting in the Relate Properties file. Note: This value does not display on any screen in Relate.

Information that is not mapped

• From CWSerenade:

• PO Box

• Delivery code: From the Default Delivery Code for New Order Entry Customers (D13), but you can override this default. Not related to the Address type in Relate, although only addresses with a type of HOME are used as part of the integration.

• Class: From the Default Customer Class in Order Entry (D63), but you can override this default.

• Alternate customer number: However, if a third system, such as the e-commerce site, synchronizes with Relate, then its customer number might also be stored in Relate as an additional alternate key. Also, select the Enable Xstore Alt Key Creation setting in Relate Conflate configuration if the integration to Relate includes CWSerenade and XStore. Selecting this field will assign an XSTORE_ID to the customer if one does not already exist.

• From Relate:

• County: If the county is populated in Relate, this information is cleared when the customer record is synched with CWSerenade.

• Address type: Only the address with a type of HOME is used as part of the integration. If the customer record in Relate does not have a HOME address, then the address you enter for the customer in CWSerenade is created as the HOME address in Relate.

• Email address: Only the email address with a type of HOME is used as part of the integration.

• Class: The Default Customer Class in Order Entry (D63) defaults in CWSerenade.

Updating an Existing Customer

Overview: In general, the integration keeps existing CWSerenade and Relate customer records synchronized when you update customer information through either system. A few things to note are listed below.

Deleting customer information through screens in CWSerenade:

• If you delete address lines 2-4 or apartment in CWSerenade, these address lines are also deleted in Relate.

• Deleting other data in CWSerenade does not delete the corresponding fields in Relate; as a result, this data is repopulated when the customer information is resynchronized. This occurs if you delete the customer’s prefix, middle initial, suffix, company name, phone numbers, and primary email address in CWSerenade.

Deleting customer information through Relate: Deleting prefix, first name, middle initial, suffix, last name or business name, address lines 2-4, apartment, phone number extensions, or email address in Relate deletes the corresponding fields in CWSerenade. However, deleting phone numbers in Relate does not delete the phone numbers in CWSerenade; as a result, the phone numbers are repopulated in Relate when the customer information is resynchronized.

Phone number extensions: If you add an extension to an existing phone number:

• if you add the extension in CWSerenade, the extension is not added to Relate.

• if you add the extension in Relate, the extension is not added to CWSerenade and is removed when the customer information is resynchronized.

For more information: See Customer Synchronization through the Order API.

Synchronizing Customer Information through a Periodic Function

Overview: The SYNCRDB periodic function (Program Name = PFR0105) sends current customer information to Relate. You can use this periodic function:

• if communication has failed for any reason during normal operations, so that customer information was not synchronized interactively

• to initially export customer information from CWSerenade to Relate

Synchronization trigger: If the Synchronize with remote DB flag in the Customer Sold To table is set to Y, the SYNCRDB periodic function attempts to synchronize the customer record with Relate. CWSerenade sets this flag to Y automatically when communication with Relate fails. To initially export existing customer information to Relate, you can use a SQL statement to set this flag to Y for all customer records if you do not use the conversion periodic function.

Synchronization updates: The SYNCRDB periodic function:

• sends current customer information from CWSerenade to Relate, including creating an alternate key in Relate using the CWSerenade customer number; see Customer Data Mapping between CWSerenade and Relate for details

• populates the Relate Id field in the Customer Sold To table if the field is currently blank

• clears the Synchronize with remote DB flag for the Customer Sold To record

• clears the E-commerce ID for the Customer Sold To record if the order API has saved this information to use when synchronizing the customer; see Relate Customer Integration: Typical Information Flows for more information

The periodic function does not retrieve information from the Relate customer record to update the CWSerenade customer record, with the exception of populating the Relate Id.

Note: The periodic function synchronizes customer records only if the Relate Customer Integration (L37) system control value is set to INTERACT.

Information used for matching: The SYNCRDB periodic function uses the following information to match customer records between CWSerenade and Relate:

• Relate Id: Relate customer number = Relate Id in the CWSerenade Customer Sold To table

• Customer number: Relate alternate key record whose Alt Key Type matches the RELATE_ALT_ID_SERENADE setting in Working with Customer Properties (PROP) = the CWSerenade customer number

• E-commerce ID: Relate alternate key record whose Alt Key Type matches the RELATE_ALT_ID_WEB setting in Working with Customer Properties (PROP) = the e-commerce site’s customer number. From the ecommerce_id passed in the CWOrderIn message, and saved as the E-commerce ID in the Customer Sold To table only if the order API was unable to synchronize the CWSerenade and Relate customer records

• Primary email address: an email address for the customer in Relate = the customer’s primary email address in CWSerenade

Matching rules: The SYNCRDB periodic function uses the following rules:

• If a Relate Id or an e-commerce ID is specified in the Customer Sold To table and the Synchronize with remote DB flag is set to Y, CWSerenade sends the current CWSerenade customer number, e-commerce ID (if any), and customer name and address, including phone numbers and the primary email address.

Relate returns its Relate customer number; if this number is different from the current Relate Id in the Customer Sold To table, CWSerenade updates the Relate Id. The current Relate Id might be different if, for example, a merge/purge took place in Relate.

• If no Relate Id or e-commerce ID is specified in the Customer Sold To table, and the Synchronize with remote DB flag is set to Y, CWSerenade first searches Relate based on primary email address. If Relate returns:

• any matching customers, CWSerenade synchronizes the customer with the first customer returned that is not already assigned a CWSerenade alternate key; if all matching customers already have CWSerenade alternate keys, it selects the first customer returned in the response

• no matching customers, CWSerenade sends an add/update message to create a new customer in Relate

Troubleshooting: The SYNCRDB function always creates a new customer in Relate if the CWSerenade customer does not have an email address, e-commerce ID, or valid Relate Id. The function does not match customers based on name, address, or phone number.

Relate Customer Integration: Notes and Troubleshooting

Things to note:

• Must search before creating a customer at CWSerenade screens: Because the Relate customer integration is based on using Relate as the system of record for customers, you need to use the Customer Scan Screen to search for a customer and make sure that the record does not already exist before creating a new record to avoid the possibility of creating a duplicate. Creating the customer without searching first indicates that you want the customer created, regardless of any existing duplicates.

• Relate ID: The Relate customer ID is stored in the CWSerenade Customer Sold To table, but is not displayed on any screens in CWSerenade and is not used to search Relate for a matching customer.

• Logging: The information passed between CWSerenade and Relate is written to the CWSerenade Trace Log if its logging level is set to DEBUG or ALL.

• If communication fails: If for any reason the communication fails between CWSerenade and Relate and the synchronization cannot be completed, the Synchronize with remote DB flag in the Customer Sold To table is set to Y. You can use the SYNCRDB periodic function to synchronize the customer records; see Synchronizing Customer Information through a Periodic Function for more information.

• Customer Lookup Limit: The Results tab at the Customer Scan Screen displays the error message Maximum search results exceeded, please refine your search if the number of matching records exceeds the Customer Lookup Limit setting in Relate Conflate. In this situation, you need to make your search criteria more specific to make sure that you can find the customer record you are looking for.

Additional data from Relate not passed to CWSerenade: Not all customer information in Relate is sent to CWSerenade. See the Customer Data Mapping between CWSerenade and Relate for details on the information that is mapped.

Additional data in CWSerenade not passed to Relate: Not all customer information in CWSerenade is passed to Relate. For example, permanent ship-to addresses, individual names and emails, bill-to accounts, and contract pricing information are not passed. See the Customer Data Mapping between CWSerenade and Relate for details on the information that is mapped.

Email addresses never deleted from Relate: Even if you change or delete a customer’s email address, this information is not visible on the screen but is retained in the Relate database. For this reason, searching on the deleted or overwritten email address still finds the customer, and customer matching logic described under Customer Synchronization through the Order API uses the deleted or overwritten email address as it would use a current email address.

Phone number extension: Phone number extensions are not passed between Relate and CWSerenade.

Relate customer changed to uppercase by synchronization: When a Relate customer record is updated from the corresponding CWSerenade customer record, the alphanumeric characters in Relate change to all uppercase. This occurs because CWSerenade stores customer information in all uppercase. The exception is the email address, which is stored in upper and lowercase in both systems.

Company/business name: When you use the Relate customer integration, you cannot search for customer by name if the customer has a company/business name but not a last name.

No address validation in Relate: Unlike CWSerenade, Relate does not require an address for a customer, and does not validate that the address includes certain required components; for example, no address lines are required.

Setup information: See Relate Integration Setup (Sales and Customer) for information on the required setup for integration with Relate.

Activities that do not Trigger Communication with Relate

Functions that do not request or update customer information from Relate include:

• generating backorder cards

• generating soldout notifications

• generating return or shipment confirmations

• pick slip generation

• membership order generation

• reviewing an order in order inquiry, including displaying the customer

• maintaining an order, unless you change information about the customer

• billing an order

• creating an order for the customer through the ChannelAdvisor integration

Deleting Certain Information for an Existing Customer

Certain information deleted in CWSerenade is not deleted in Relate, and becomes repopulated in CWSerenade after resynchronization. The information that persists in this process is:

• name fields, including the company/business name

• email address

Example: You delete the customer’s middle initial in CWSerenade, but this does not delete this field in Relate. The next time the Relate and CWSerenade customer records are resynchronized, the middle initial is repopulated in CWSerenade.

Address fields: If you delete additional address fields in CWSerenade, such as the second through fourth address lines and the apartment/suite, this information is also deleted in Relate and does not reappear after resynchronization.

Email and phone: If you change the email address and phone numbers in CWSerenade, the previous information persists in the Relate database, although it is no longer displayed on the screen and does not repopulate the CWSerenade customer record at resynchronization. However, if you search for a customer using the previous email address or phone number as a search criterion, the customer is eligible to be included in the search results.

Functions that are Inconsistent with the Relate Customer Integration

Customer search API: The generic customer inquiry (search) API does not support searching Relate for customers. This API searches across CWSerenade customer records only.

Mass customer updates: Updates using NCOA or similar options in CWSerenade are not recommended if you use the Relate customer integration.

Cannot delete a customer if using the Relate customer integration: If the Relate Customer Integration (L37) system control value is set to INTERACT, you cannot delete a customer in CWSerenade customer maintenance.