Customer API Setup

Customer API Setup

Before you can use the Generic Customer API, you must complete the necessary setup.

• System Control Values used by the Customer API

System Control Values used by the Customer API

System Control Value	Description
Assign Alternate Customer # (I88)	Indicates whether the system should automatically assign an alternate customer number when creating a customer through the customer API or any other means. However, if there is a cst_interface_cust_nbr specified in the Add request, the system does not assign a different alternate customer number, but uses the specified number instead.
Default Customer for Customer API (I90)	Indicates the customer to use as a guideline to determine which fields can be cleared if they are not specified in a Change request.
Perform Address Standardization in Customer API (I99)	Indicates whether to use the QAS Address interface to standardize the customer’s address before processing an Add or Change request through the Customer API. See Using the QAS Address Interface for an overview and required setup.
Validate Prefix (I27)	If this system control value is selected, the system validates the prefix code included in the request against the Prefix table; see Working with Prefix Codes (WPFX).
Require Customer Class in OE, WCAT, and WCST (H85)	If this system control value is selected, a customer class must be included in an Add request (or use the default defined in the Default Customer Class in Order Entry (D63) system control value) or the system will place the message in error.
Bypass Customer API Edit (L93)	If this system control value is selected, customer API transactions bypass validation when creating or changing a customer with an original source code of XSTORE.
The following system control values provide default values to apply to an Inbound Customer Message (CWCustomerIn).
Default Country for Customer Address (B17) system control value	If an Add request does not include a country, the system defaults the country code from this system control value.
Default Customer Class in Order Entry (D63)	If an Add request does not include a customer class, the system defaults the customer class from this system control value.
Default Mail Name (D10)	• If an Add request does not include a mail name or it is invalid, the system defaults the mail name from this system control value. • If an Add request does not include a mail code or mail name, the system defaults the mail code from this system control value. • If a Change request does not include a mail name or it is invalid and a Default Customer for Customer API (I90) is not defined, the system defaults the mail name from this system control value.
Default Rent Name (D11)	• If an Add request does not include a rent name or it is invalid, the system defaults the rent name from this system control value. • If a Change request does not include a rent name or it is invalid and a Default Customer for Customer API (I90) is not defined, the system defaults the rent name from this system control value.
Default Associate Code (D09)	If an Add request does not include an associate flag, the system defaults the associate flag from this system control value.
Default Item History Tracking (B18)	If an Add request does not include an item history tracking setting, the system defaults the setting from this system control value; if this system control value is blank, the system sets item history tracking to blank.
Default Delivery Code for New Order Entry Customers (D13)	If an Add request does not include a delivery type, the system defaults the delivery code from: 1. The Zip/City/State record for the postal code in the cst_zip tag. 2. The Default Delivery Code for New Order Entry Customers (D13) system control value.
Default Opt In/Opt Out Flag (G97)	If an Add request does not include an email status, the system defaults the Opt in/out setting from this system control value.

Default Customer for Customer API

Use Creating and Updating Sold-to Customers (WCST) to configure the customer defined as the Default Customer for Customer API (I90). The default customer determines which fields can be cleared if they are not specified in a Change request.

For each field that is not provided in the Inbound Customer Message (CWCustomerIn), the Customer API checks the corresponding field for the default customer.

• If that field contains any data in the default customer record, then the Customer API does not clear the information in that field for the customer being updated. Example: The default customer has data in the home phone number field. The Customer API receives a change request through the CWCustomerIn message. No home phone number is specified in the CWCustomerIn message, and the specified customer currently has a home phone number on record. The Customer API does not clear (blank out) the customer’s home phone number.

• If that field does not contain data in the default customer record, then the Customer API clears that field when updating the customer. Example: The default customer does not have data in the home phone number field. The Customer API receives a change request through the CWCustomerIn message. No home phone number is specified in the CWCustomerIn message, and the specified customer currently has a home phone number on record. The Customer API clears (blanks out) the customer’s home phone number.

Note: It does not matter what the data is in the corresponding field for the default customer record; the process simply checks to see whether there is any data.

Important: While defining a default customer is not required for the Generic Customer API, MICROS recommends you create it to avoid errors when processing a Change CWCustomerIn request.

For more information: See the Default Customer for Customer API (I90) for a discussion.

Message Log used by the Customer API

CWSerenade writes the Inbound Customer Message (CWCustomerIn) to the CWSerenade MQ Message Log if its Logging Level is set to INFO or lower.

When you are use Customer API integration with Xstore, the system writes the messages to the Customer API Log if its Logging Level is set to INFO or lower.

CWCustomer or CWMessageIn Web Service

You can use the CWCustomer web service or the CWMessageIn web service to process CWCustomerIn XML messages received from an external system and to send the CWCustomerOut XML message back to the external system. With either web service the type in the Inbound Customer Message (CWCustomerIn) must be CWCustomerIn.

Web service authentication? The Require_Auth field in the Webservice table defines whether the web service requires basic web service authentication. See Working with Web Service Authentication (WWSA) for an overview.

• CWCustomer Web Service

• CWMessageIn Web Service

CWCustomer Web Service

The CWCustomer web service allows an external system to post the CWCustomerIn XML message directly to CWSerenade and receive responses without the need of the CUSTOMR_IN job in Working with Integration Layer Processes (IJCT) or any queues.

If you are using the CWCustomerIn RESTful web service: You POST inbound CWCustomerIn messages to the web service’s URI, or endpoint, of the RESTful service. The individual URL for the CWCustomerIn RESTful service uses the following format: http://server:port/SerenadeSeam/sxrs/application/CWCustomerIn, where server:port identifies the application server where the RESTful service is located and CWCustomerIn is the name of the web service to call.

If you are using the CWCustomerIn SOAP-based web service: The endpoint specified in the CWCustomerIn.wsdl file is where you need to post messages in order for the CWCustomerIn web service to process them. The endpoint is typically set to http://server:port/CWDirectCPService/services/CWCustomerIn, where server:port identifies the application server where the wsdl is located and CWCustomerIn is the name of the web service to call.

The CWCustomerIn SOAP-based web service requires that inbound messages be embedded in SOAP envelope tags. A sample XML message embedded in a SOAP envelope is presented below.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:dom="http://dom.w3c.org">

<soapenv:Header />

<soapenv:Body>

<dom:performAction type="xsd:string">

<![CDATA[

</CustEmails>

</CustSoldTo>

</Message>

]]>

</dom:performAction>

</soapenv:Body>

</soapenv:Envelope>

CWMessageIn Web Service

You can use the CWMessageIn Web Service to route messages for the Generic Customer API if you prefer to use a single endpoint for all messages rather than using the separate endpoint specified for the CWCustomerIn message.

The CUSTOMR_IN integration layer process can remain inactive and a queue is not required if the target is CUSTCRT_IN in the XML message.

If you are using the CWMessageIn RESTful web service: You POST inbound CWMessageIn messages to the web service’s URI, or endpoint, of the RESTful service. The individual URL for the CWMessageIn RESTful service uses the following format: http://server:port/SerenadeSeam/sxrs/application/CWMessageIn, where server:port identifies the application server where the RESTful service is located and CWMessageIn is the name of the web service to call.

If you are using the CWMessageIn SOAP-based web service: The endpoint specified in the CWMessageIn.wsdl file is where you need to post messages in order for the CWMessageIn web service to process them. The endpoint is typically set to http://server:port/CWDirectCPService/services/CWMessageIn, where server:port identifies the application server where the wsdl is located and CWMessageIn is the name of the web service to call.

The CWMessageIn SOAP-based web service requires that inbound messages be embedded in SOAP envelope tags. A sample XML message embedded in a SOAP envelope is presented below.