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)

InsiteCommerce configuration and data requirements

In order for the PunchOut/cXML integration to function fully, data needs to be populated within the InsiteCommerce (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

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 ISC Website User for the Integration Partner
  • Create separate ISC 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 ISC PunchOut/cXML Customer Users
  • Map cXML Ship To addressID values to ISC Ship To records

Create a single ISC website user for the integration partner

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

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

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

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

Map cXML ship to addressID values to ISC ship to records

An addressID is a cXML data element that represents the buyer's Ship To location ID. ISC has the ability to map this addressID value to a specific Ship To record in the ISC 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 ISC 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. See the articles within the Application Dictionary section of the Help Center for more details.

Once the Address ID values are configured in ISC 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 ISC mapping table, this would trigger a processing error in ISC 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 ISC 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 ISC to map the Ship To addressID in the cXML to the given ERP Ship To record, or if ISC should simply treat the Ship To addressID in the cXML as the ERP Ship To Number.
    • Property Values:
      • True - ISC will assume the Ship To addressID value in the cXML matches to an ISC Ship To record
      • False (or <blank>) - ISC will use the PunchOut Customer Mapping table and Ship To addressID value in the cXML to determine which ISC 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 ISC 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 ISC that are not a part of the standard ISC mapping. These data elements will be mapped into ISC 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 ISC 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:

  • User Custom Property: Punchout_AcceptPriceProvided
    • This Custom Property can be added to a PunchOut/cXML Customer User. It is used to determine if ISC should accept the price sent in the cXML Order Request message or if ISC 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>) - ISC will attach all the line item prices provided in the Order Request cXML onto the order
      • False - ISC 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 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) - ISC will attach all the line item prices provided in the Order Request cXML onto the order
      • False - ISC 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, ISC 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 ISC 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 ISC 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 ISC system. This setting will delete data from the following ISC 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)