Version: eXtendPS-SE 1.3.7 and above
Audience: Administrator, Developer

Overview

In some scenarios, you might receive charge items from a PromoStandards Purchase Order request that do not exist in your account. This article provides a method to address these cases by mapping the incoming charge items to a miscellaneous (default/common) charge item. This process allows for seamless creation of Sales Order records when unrecognized charge items are received in the service.

Configuration

Step 1: Create a Miscellaneous Charge Item

You need to create the miscellaneous charge item in your account that will be used for unrecognized charges. You can also use any existing item as the miscellaneous charge item.

Step 2: Modify the suite_promoapi_transformer.js File

You will need to add two snippets to the suite_promoapi_transformer.js file in your account.

Snippet 1:
var MISCELLANEOUS_CHARGE_ITEM = {
  chargeId: '4600',
  chargeName: 'Miscellaneous'
};

/**
 * @param {Object} requestPO
 * @param {Object} hookArgs
 * @prop  {Array}  hookArgs.chargeList
 * @prop  {Object} hookArgs.itemResultMap
 * @prop  {Object} hookArgs.cachedCharge
 * @prop  {Object} hookArgs.chargeIndex
 */
getMiscellaneousChargeItem: function(requestPO, hookArgs) {
  return MISCELLANEOUS_CHARGE_ITEM;
}
In this script, replace the chargeId and chargeName fields under the variable MISCELLANEOUS_CHARGE_ITEM with the internal ID and name of your miscellaneous item, respectively.

Next, add the following hook to be called before committing a charge item of the type 'Order' under the item sublist:
/**
 * A hook to be called before committing a charge item of type *Order* under item sublist
 *
 * @param {HookContext} hookContext
 * @param {Object}      hookArgs
 * @prop  {Object}      hookArgs.lineItem                  - A line item identified by **po.LineItemArray[lineIndex]**
 * @prop  {number}      hookArgs.lineIndex                 - Current index of line item being proccessed
 * @prop  {number}      hookArgs.lineNumber                - Line number in item sublist of current part
 * @prop  {Object}      hookArgs.itemSublistWrapper        - A wrapper for item sublist
 * @prop  {number}      hookArgs.chargeIndex               - Charge Array in **po.LineItemArray[lineIndex].Configuration.ChargeArray[]** is modifed and by plucking out
 *                                                           orders of type **Charge** thus keeping only deco charges in *ChargeArray*. This field specifies the original index
 *                                                           in **ChargeArray** before modification.
 * @prop  {Object}      hookArgs.currentChargeIndex        - This field specifies the index of charge order in **hookContext.cache.lineItemConfigCacheList[lineIndex].orderCharges**
 *
 */
orderChargeLineItemBeforeCommit: function (hookContext, hookArgs) {
  log.debug({ title: 'po_v100::orderChargeLineItemBeforeCommit', details: hookArgs });

  var itemSublistWrapper = hookArgs.itemSublistWrapper;
  var itemId = itemSublistWrapper.getValue({ fieldId: 'item' });
  var lineRate = itemSublistWrapper.getValue({ fieldId: 'rate' });
  var miscellaneousChargeId = MISCELLANEOUS_CHARGE_ITEM ? _.get(MISCELLANEOUS_CHARGE_ITEM, 'chargeId') : '';

  if (miscellaneousChargeId && (itemId === miscellaneousChargeId) && !lineRate) {
    itemSublistWrapper.setValue({ fieldId: 'rate', value: 0 });
  }
},
This script defaults the rate of your charge item to "0" if no rate is specified on your charge item record.

Step 3: Review the Sales Order Record

From now on, whenever a Purchase Order request is received that includes a charge item not present in your account, the miscellaneous charge line will be added to your Sales Order record in its place. You can then revisit your Sales Order record and update this item's rate & amount as per your requirement.