PunchOut/cXML configuration and data requirements

This is article two in a series of five articles:

  1. PunchOut/cXML Process and Design Overview
  2. PunchOut/cXML Configuration and Data Requirements - Current Article
  3. PunchOut Setup Request and Response
  4. PunchOut Order Message (that is Cart Information)
  5. Order Request (that is Purchase Order)

B2B Commerce configuration and data requirements

In order for the PunchOut/cXML integration to function fully, data needs to be populated within the Optimizely B2B 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 B2B Admin Console:

  • Create a role for PunchOut under Administration > Permissions > Roles. See Creating custom roles for more details.
  • Create a single B2B Website User for the Integration Partner
  • Create separate B2B 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 B2B Customer records to the B2B PunchOut/cXML Customer Users
  • Map cXML Ship To addressID values to B2B Ship To records

Create a single B2B website user for the integration partner

The B2B 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 B2B 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 B2B website users for each PunchOut/cXML customer

The B2B 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 B2B 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 B2B 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 B2B customer records to the B2B PunchOut/cXML customer users

Once a User is created for a PunchOut/cXML Customer, then at least one B2B Customer record needs to be assigned to the B2B PunchOut User. No Customer records should be assigned the Integration Partner User.

  1. Go to Admin Console > Administrators > Users
  2. Click Edit for the B2B PunchOut User.
  3. Select the Customers finger tab.
  4. Select the desired Customers and click Assign Customers.

The B2B Customer records assigned to the PunchOut/cXML Customer User determine the Bill To Customer within the B2B system to which the cXML message is attached. Therefore at least one of the B2B Customer records assigned to the User should be a Bill To level record.

Map cXML ship to addressID values to B2B ship to records

An addressID is a cXML data element that represents the buyer's Ship To location ID. B2B has the ability to map this addressID value to a specific Ship To record in the B2B 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 B2B Admin Console.

  1. Go to Admin Console > Administration > PunchOut > Punchout Customer Mapping (see Note below).
  2. From the top toolbar, click Add Punchout Customer User Profile Map.
  3. Using the User Profile drop-down menu, select the PunchOut Customer User that has been assigned to the PunchOut Role.
  4. 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.
  5. 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.

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. See the articles within the Application Dictionary section of the Help Center for more details.

Once the Address ID values are configured in B2B 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 B2B mapping table, this would trigger a processing error in B2B 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 B2B 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 B2B should use the PunchOut Customer Mapping table within B2B to map the Ship To addressID in the cXML to the given ERP Ship To record, or if B2B should simply treat the Ship To addressID in the cXML as the ERP Ship To Number.
    • Property Values:
      • True - B2B will assume the Ship To addressID value in the cXML matches to an B2B Ship To record
      • False (or <blank>) - B2B will use the PunchOut Customer Mapping table and Ship To addressID value in the cXML to determine which B2B Ship To record to attach to the order.

With the release of B2B 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_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 B2B 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 B2B that are not a part of the standard B2B mapping. These data elements will be mapped into B2B 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 B2B 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_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 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) - B2B will attach all the line item prices provided in the Order Request cXML onto the order
      • False - B2B will recalculate the item price for all order lines sent into the cXML

        With the release of B2B 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 B2B should accept the price sent in the cXML Order Request message or if B2B 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>) - B2B will attach all the line item prices provided in the Order Request cXML onto the order
      • False - B2B will recalculate the item price for all order lines sent into the cXML

        If the configuration for a User is set to reprice and a price sent in the cXML does not match the ISC-calculated price, B2B 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 B2B 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 B2B 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 B2B system. This setting will delete data from the following B2B 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)