2. PunchOut cXML Configuration and data requirements

This is article two in a series of five articles:

1. PunchOut/cXML process and design
2. PunchOut/cXML configuration and data requirements
3. PunchOut setup request and response
4. PunchOut order Message (that is Cart information)
5. Order request (that is Purchase Order)

Configured Commerce configuration and data requirements

For the PunchOut/cXML integration to function fully, data needs to be populated within the Optimizely Configured Commerce 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 Configured Commerce 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 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 ISC 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 CommerceWebsite 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 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.

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 in order to determine order processing rules that should be applied (such as pricing, product restrictions, and so on).

Assign Configured Commerce customer records to the ISC 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.

The 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 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 has the ability to 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.

1. Go to Admin Console > Administration > Permissions > Punchout Customer Mapping (see Note below).
2. From the top toolbar, click Add Punchout Customer User Profile Map.
3. Using User Profile, select the PunchOut Customer User that has been assigned to the PunchOut Role.
4. Using Customer, select the Customer to which you will assign an Address ID. Typically the Address ID is assigned to a Ship To record.
5. 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:

1. 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.
2. 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 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

Configured Commerce 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 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 ISC 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 an ISC 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 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 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_OrderCustomPropertyFieldsOrder 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 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 an 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 Configured Commerce:

• 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

• 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 Configured Commerce. 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

  If the configuration for a User is set to reprice and a price sent in the cXML does not match the Configured Commerce-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_NotOnFileProductNamePunchOut 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 – PunchoutOrderRetentionDaysPuncOut 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)