2. PunchOut cXML Configuration and data requirements
This is article two in a series of five articles:
- PunchOut/cXML process and design
- PunchOut/cXML configuration and data requirements
- PunchOut setup request and response
- PunchOut order Message (that is Cart information)
- Order request (that is Purchase Order)
{user["product-name"]} configuration and data requirements
For the PunchOut/cXML integration to function fully, data needs to be populated within the Optimizely {user["product-name"]} database and various configurations set within the Admin Console. The sections below outline these data elements and their use within the PunchOut/cXML process.
Product and pricing data
The Product table within {user["product-name"]} should be populated with the data listed below to correctly identify order lines sent in the Order Request Message cXML and to set data on the PunchOut Order Message (that is cart). While not all of the following data elements are necessarily required, they are used by this integration.
Product ERP #
- DB Table & Field: Product.ERPNumber
Product Title/Short Description
- DB Table & Field: Product.ShortDescription
Customer Part #
- DB Table & Field: CustomerProduct.Name
- In Conjunction with DB Table & Field. Customer.ERPNumber
Manufacturer Name
- DB Table & Field: Vendor.Name
Manufacturer Part Number
- DB Table & Field: Product.ManufacturerItem
UPC
- DB Table & Field: Product.UPCCode
Unit of Measure
- DB Table & Field: Product.UnitOfMeasure & ProductUnitOfMeasure.UnitOfMeasure
UNSPSC
- DB Table & Field: Product.Unspsc
It is also assumed that pricing is shown on the site so that it can be sent in with the PunchOut Order Message (that is cart) and potentially used for processing Order Request Messages (that is Purchase Orders)
Customer data
The Customer table should be populated with the Bill To and Ship To level records in order to preset the session for PunchOut users - essentially logging users into the site with a Bill To & Ship To already set for the session. The Customer data is also used to attach the ERP Bill To & Ship To onto a given order before submission to the ERP.
The following Customer data is used by the integration:
- Bill To ERP #
- DB Table & Field: Customer.ERPNumber
- DB Table & Field (ISC v4.1+): Customer.IsBillTo = 1 (that is 'True')
- Ship To ERP # (in conjunction with Bill To ERP #)
- DB Table & Field: Customer.ERPSequence (In Conjunction with Customer.ERPNumber)
- DB Table & Field (ISC v4.1+): Customer.IsShipTo = 1 (that is 'True')
- DB Table & Field: Customer.ShipCode (matches to a valid ShipVia code)
PunchOut/cXML users and address ID mapping
There are also setup steps required to enable the site to accept and process cXML documents. This involves the following tasks that are executed via the ISC Admin Console:
- Create a single {user["product-name"]} Website User for the Integration Partner
- Create separate {user["product-name"]} Website Users for each PunchOut/cXML Customer
- Logic for how Bill To and Ship To are dynamically assigned to a given PunchOut/cXML message
- Assign ISC Customer records to the {user["product-name"]} PunchOut/cXML Customer Users
- Map cXML Ship To addressID values to {user["product-name"]} Ship To records
Create a single {user["product-name"]} website user for the integration partner
The {user["product-name"]}Website User's username, password, and email are agreed upon by both the integration Partner and Client. Assign the role of PunchOut to this User.
The Username and Password of the manually-created {user["product-name"]} Website User record need to match the data sent in the PunchOut cXML (that is <Header><Sender><Credential><Identity> = Username & <Header><Sender><Credential><SharedSecret> = Password).
Create separate {user["product-name"]} website users for each PunchOut/cXML customer
The {user["product-name"]} User's username and email are agreed upon by both the integration Partner and Client. Assign the role of PunchOut to this User.
A single {user["product-name"]} PunchOut User record will need to be created for each unique PunchOut Customer, but NOT separate ones for each individual at a given Customer.
The recommended format for the Username is [Customer]PunchOut. For example, ACMEPunchOut, ApplePunchOut, and so on. This is recommended to help identify all PunchOut Users within the Admin Console.
Logic for how bill to and ship to are dynamically assigned to a given PunchOut/cXML message
The following diagram illustrates the logic for dynamically assigning a Bill To and Ship To to a given PunchOut/cXML message. The diagram references settings and configurations that are explained further in this article.
The Customer to User assignment is critical for PunchOut Customers to automate setting the Bill To/Ship To Customer into the site session when they PunchOut to the site. Without being able to determine a specific Bill To/Ship To combination from processing the cXML document, the site will display the Bill To/Ship To Customer drop-down boxes.
When sending Order Request messages, it is also important to have these {user["product-name"]} Customer records attached to the PunchOut/cXML Customer User in order to determine order processing rules that should be applied (such as pricing, product restrictions, and so on).
Assign {user["product-name"]} customer records to the ISC PunchOut/cXML customer users
Once a User is created for a PunchOut/cXML Customer, then at least one {user["product-name"]} Customer record needs to be assigned to the {user["product-name"]} PunchOut User. No Customer records should be assigned the Integration Partner User.
The Customer records assigned to the PunchOut/cXML Customer User determine the Bill To Customer within the {user["product-name"]} system to which the cXML message is attached. Therefore at least one of the Customer records assigned to the User should be a Bill To level record.
Map cXML ship to addressID values to {user["product-name"]} ship to records
An addressID is a cXML data element that represents the buyer's Ship To location ID. {user["product-name"]} has the ability to map this addressID value to a specific Ship To record in the {user["product-name"]} database. Typically these Ship To addressID values are not in the seller's ERP, which makes the mapping necessary. These values are typically obtained from the PunchOut/cXML Customer's procurement system administrator.
For PunchOut/cXML Customers that will be sending specific Ship To addressID values in the cXML, the site Admin needs to set up these mappings in the PunchOut Customer Mapping section of the {user["product-name"]} Admin Console.
- Go to Admin Console > Administration > Permissions > Punchout Customer Mapping (see Note below).
- From the top toolbar, click Add Punchout Customer User Profile Map.
- Using User Profile, select the PunchOut Customer User that has been assigned to the PunchOut Role.
- Using Customer, select the Customer to which you will assign an Address ID. Typically the Address ID is assigned to a Ship To record.
- For Address ID, enter the PunchOut Customer's address ID value for the address record. This value needs to be obtained from the PunchOut Customer's procurement software administrator.
The PunchOut Customer Mapping page within the Admin Console is not exposed by default. There are two options to expose this page:
- A User assigned the "ISC_System" or "ISC_Admin" role can click Debug on the Primary Toolbar and select Master Edit Mode from the menu. This will expose any hidden screens and fields.
- From the Application Dictionary, under the Administration section, make the PunchOut Customer Mapping page visible to proper Roles.
Once the Address ID values are configured and populated in the PunchOut Setup Request, this mapping data can automatically log PunchOut users into the site under the given Bill To/Ship To Customer. Should a Customer not provide this information in the Setup Request, the user may be prompted to select their Ship To when they first go to the site.
Should a Customer not provide an Address ID in the Order Request or if there was not a match between the value in the cXML and the {user["product-name"]} mapping table, this would trigger a processing error in {user["product-name"]} and the order would not be submitted into the client's ERP.
Configuration of PunchOut/cXML processing behaviors
{user["product-name"]} has the ability to configure certain behaviors around cXML/PunchOut processing. The following section outlines these behaviors, how they are configured, and the effect they have on data processing:
Use {user["product-name"]} address ID mapping table or accept address ID as seller's ERP ship to
- User Custom Property: Punchout_UseProvidedShipToId
- This Custom Property can be added to a PunchOut/cXML Customer User. It is used to determine if ISC should use the PunchOut Customer Mapping table within {user["product-name"]} to map the Ship To addressID in the cXML to the given ERP Ship To record, or if {user["product-name"]} should simply treat the Ship To addressID in the cXML as the ERP Ship To Number.
- Property Values:
- True - {user["product-name"]} will assume the Ship To addressID value in the cXML matches to an ISC Ship To record
- False (or<blank>) - {user["product-name"]} will use the PunchOut Customer Mapping table and Ship To addressID value in the cXML to determine which Ship To record to attach to the order.
Configure required and custom order header fields
- Application Setting: Punchout_OrderRequiredFieldsOrder Required Fields
- This global setting will determine the OrderRequestHeader cXML fields that are required to be populated to consider an order complete. If a field is defined as required but not populated, then {user["product-name"]} will issue an error on processing the cXML.
- Setting Value:
- Comma-separated list of cXML OrderRequestHeader fields that are deemed as required for the order to be accepted; they can be base cXML data elements or extensible fields where the cXML element attribute is the value included in the list.
- <blank> (default) - no fields are required
- Application Setting: Punchout_OrderCustomPropertyFieldsOrder Custom Property Fields
- This global setting will allow users to map OrderRequestHeader cXML fields into {user["product-name"]} that are not a part of the standard mapping. These data elements will be mapped into {user["product-name"]} as a Customer Order Custom Properties to use during the order submission process.
- Setting Value:
- Comma-separated list of cXML OrderRequestHeader fields that will be mapped into an {user["product-name"]} Customer Order Custom Property; they can be base cXML data elements or extensible fields where the cXML element attribute is the value included in the list.
- <blank> (default) - no custom field mapping
Accept prices provided in cXML vs. recalculate in {user["product-name"]}:
- User Custom Property: Punchout_AcceptPriceProvided
- This Custom Property can be added to a PunchOut/cXML Customer User. It is used to determine if {user["product-name"]} should accept the price sent in the cXML Order Request message or if {user["product-name"]} should reprice all of line items. This setting will apply to all Order Request messages received under the given User. If this setting exists and is populated, it will override the Punchout_DefaultAcceptPriceProvided Application Setting outlined below.
- Property Values:
- True (or<blank>) – {user["product-name"]} will attach all the line item prices provided in the Order Request cXML onto the order
- False – {user["product-name"]} will recalculate the item price for all order lines sent into the cXML
- Application Setting – Punchout_DefaultAcceptPriceProvidedAccept Pricing as Provided
- This global setting will determine the default/fallback behavior if the price sent in the cXML should be accepted and submitted directly into the ERP as provided or if it should be repriced using {user["product-name"]}. If a PunchOut/cXML Customer User does not have the Punchout_AcceptPriceProvided custom property set, then this Application setting will take effect.
- Setting Values
- True (default) – {user["product-name"]} will attach all the line item prices provided in the Order Request cXML onto the order
- False – {user["product-name"]} will recalculate the item price for all order lines sent into the cXML
Note If the configuration for a User is set to reprice and a price sent in the cXML does not match the {user["product-name"]}-calculated price, {user["product-name"]} will attach an Order Line Custom Property called "Unit Price Submitted" to the given Order Line.
Item not found
- Application Setting – Punchout_NotOnFileProductNamePunchOut Default Product
- This setting determines the {user["product-name"]} Product record that is attached to an Order Line where the Product could not be determined (such as no part # match) from the cXML. The value populated in this setting needs to match the Product.Name and Product.ERPNumber fields for a single {user["product-name"]} Product record.
- Setting Value
- String value that matches to the Product.Name and Product.ERPNumber
Nightly routine to cleanup PunchOut data
- Application Setting – PunchoutOrderRetentionDaysPuncOut Order Retention Days
- This global setting will determine the number of days-worth of PunchOut data/logs that are kept within the {user["product-name"]} system. This setting will delete data from the following {user["product-name"]} tables where the Modify date is older than the setting value:
- PunchoutOrderRequest
- PunchoutOrderRequestExstrinsic
- PunchoutOrderRequestItemOut
- PunchoutOrderRequestMessage
- PunchoutSession
- PunchoutSessionAccess
- PunchoutSessionExtrinsic
- PunchoutSessionItemIn
- PunchoutSetupRequest
- Setting Value
- Integer representing number of days to keep; 30 (Default)