PunchOut/cXML configuration and data requirements
This is article two in a series of five articles:
- PunchOut/cXML Configuration and Data Requirements - Current Article
Configured Commerce configuration and data requirements
In order for the PunchOut/cXML integration to function fully, data needs to be populated within the Optimizely Configured Commerce (ISC) 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 ISC, 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
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)
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)
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 Configured Commerce Admin Console:
- Create a role for PunchOut under Administration > Permissions > Roles. See Create custom roles for more details.
- Create a single Configured Commerce Website User for the Integration Partner
- Create separate Configured Commerce 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 Configured Commerce Customer records to the Configured Commerce PunchOut/cXML Customer Users
- Map cXML Ship To addressID values to Configured Commerce Ship To records
Create a single Configured Commerce website user for the integration partner
The Configured Commerce 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 PunchOut role is the only role that the User should have.
The Username and Password of the manually-created Configured Commerce 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 Configured Commerce website users for each PunchOut/cXML customer
The Configured Commerce User's username and email are agreed upon by both the integration Partner and Client. Assign the role of PunchOut to this User. The PunchOut role is the only role that the User should have.
A single Configured Commerce 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 Configured Commerce Customer records attached to the PunchOut/cXML Customer User to determine order processing rules that should be applied (such as pricing, product restrictions, and so on).
Assign Configured Commerce customer records to the Configured Commerce PunchOut/cXML customer users
Once a User is created for a PunchOut/cXML Customer, then at least one Configured Commerce Customer record needs to be assigned to the Configured Commerce PunchOut User. No Customer records should be assigned the Integration Partner User.
- Go to Admin Console > Administrators > Users
- Click Edit for the Configured Commerce PunchOut User.
- Select the Customers finger tab.
- Select the desired Customers and click Assign Customers.
The Configured Commerce Customer records assigned to the PunchOut/cXML Customer User determine the Bill To Customer within the Configured Commerce system to which the cXML message is attached. Therefore at least one of the Configured Commerce Customer records assigned to the User should be a Bill To level record.
Map cXML ship to addressID values to Configured Commerce ship to records
An addressID is a cXML data element that represents the buyer's Ship To location ID. Configured Commerce can map this addressID value to a specific Ship To record in the Configured Commerce 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 Configured Commerce Admin Console.
- Go to Admin Console > Administration > PunchOut > Punchout Customer Mapping (see Note below).
- From the top toolbar, click Add Punchout Customer User Profile Map.
- Using the User Profile drop-down menu, select the PunchOut Customer User that has been assigned to the PunchOut Role.
- Using the Customer drop-down menu, select the Customer to which you will assign an Address ID. Typically the Address ID is assigned to a Ship To record.
- For the Address ID field, 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.
Note
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. See the articles within the Application Dictionary section of the Help Center for more details.
Once the Address ID values are configured in Configured Commerce 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 Configured Commerce mapping table, this would trigger a processing error in Configured Commerce and the order would not be submitted into the client's ERP.
Configuration of PunchOut/cXML processing behaviors
ISC has the ability to configure certain behaviors around cXML/PunchOut processing. The following section outlines these behaviors, how they are configured within ISC, and the effect they have on data processing:
Use Configured Commerce 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 Configured Commerce should use the PunchOut Customer Mapping table within Configured Commerce to map the Ship To addressID in the cXML to the given ERP Ship To record, or if Configured Commerce should simply treat the Ship To addressID in the cXML as the ERP Ship To Number.
- Property Values:
- True - Configured Commerce will assume the Ship To addressID value in the cXML matches to a Ship To record
- False (or <blank>) - Configured Commerce will use the PunchOut Customer Mapping table and Ship To addressID value in the cXML to determine which Configured Commerce Ship To record to attach to the order.
Note
With the release of Configured Commerce 4.5, we removed PunchOut_UseProvidedShipToId as a custom property for PunchOut and added it to the UserProfile table with a new name of PunchoutUseProvidedShipToId.
Configure required and custom order header fields
- Application Setting: Punchout_OrderRequiredFields — Order 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 Configured Commerce 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_OrderCustomPropertyFields — Order Custom Property Fields
- This global setting will allow users to map OrderRequestHeader cXML fields into Configured Commerce that are not a part of the standard Configured Commerce mapping. These data elements will be mapped into Configured Commerce 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 a Configured Commerce 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 ISC:
- Application Setting: Punchout_DefaultAcceptPriceProvided — Accept 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 ISC. 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) - Configured Commerce will attach all the line item prices provided in the Order Request cXML onto the order
- False - Configured Commerce will recalculate the item price for all order lines sent into the cXML
Note
With the release of Configured Commerce 4.5, we removed PunchOut_AcceptPriceProvided as a custom property for PunchOut and added it to the UserProfile table with a new name of PunchoutAcceptPriceProvided.
- User Custom Property: Punchout_AcceptPriceProvided
- This Custom Property can be added to a PunchOut/cXML Customer User. It is used to determine if Configured Commerce should accept the price sent in the cXML Order Request message or if Configured Commerce 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>) - Configured Commerce will attach all the line item prices provided in the Order Request cXML onto the order
- False - Configured Commerce 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 ISC-calculated price, Configured Commerce will attach an Order Line Custom Property called "Unit Price Submitted" to the given Order Line.
Item not found
- Application Setting: Punchout_NotOnFileProductName — PunchOut Default Product
- This setting determines the Configured Commerce 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 Configured Commerce Product record.
- Setting Value:
- String value that matches to the Product.Name and Product.ERPNumber
Nightly routine to cleanup PunchOut data
- Application Setting: PunchoutOrderRetentionDays — PuncOut Order Retention Days
- This global setting will determine the number of days-worth of PunchOut data/logs that are kept within the Configured Commerce system. This setting will delete data from the following Configured Commerce 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)