ReadPurchaseOrder user exit
The ReadPurchaseOrder user exit is available so a developer can code an alternative method of retrieving purchase order details, such as a web service. This user exit returns an instance of PurchaseOrder along with the header data and PO lines.
To activate the user exit, select the Read PO Header Via User Exit setting in Settings > Invoice Processing > Capture Profiles > PO Number Settings > PO Number Validation tab, for the required profile ID. If you also want to use this user exit to retrieve purchase order line item details, select the Read PO Lines Via User Exit setting.
It is not possible to mix and match a custom read of the purchase order header and a standard read of the line item data. If the user exit reads the purchase order header, that user exit must also read the line items. The bool includeLineData user exit parameter is set to TRUE if the profile is configured to read line items. It notifies the developer that the line item data needs read. If line items are not needed, but are retrieved anyway, they are ignored by Kofax AP Agility.
The user exit is called when a purchase order number is validated on both the server side and in the Validation activity. The user exit is also called during document export. This is in order to retrieve the current purchase order details for line pairing. During validation only header data is requested, so includeLineData is set to False. During line pairing the full data is required, so it is called with includeLineData = true.
The key of the purchase order retrieved is passed to the function using the IPOKey poKey import parameter. The IPOKey poKey has the following structure:
|
Structure Element |
Type |
Description |
|---|---|---|
|
PONUMBER |
String |
The formatted purchase order number that is queried. |
|
COMPANYCODE |
String |
The invoice company code. This value is only populated if the company code forms part of the key that identifies a unique purchase order. |
|
POEXTENSION |
String |
Contains the JDE PO document type or the PeopleSoft business unit. It depends on whether the profile is configured for JD Edwards or PeopleSoft PO types respectively. |
Within the user exit, the developer uses the details provided by the IPOKey poKey structure to query the external system. If the profile ID is also required then it is available in the ProfileID component of the organization structure, which is also passed into the user exit.
If the capture profile is configured to use a purchase order data partition, the partition ID for the profile is also passed into the user exit via the POPartition component of the organization structure. This is done in tandem with checking that the profile is set up to use partitions for the purchase order data. For example,
if(projectContext.Settings.GetBooleanSetting("PON","UsePOPartition", false))If a technical error occurs when preforming a purchase order data source lookup, the poReadError setting should contain an appropriate message. If this value is not blank, a purchase order is displayed in the Validation activity and the error is displayed. During export, if the poReadError has a message specified, the export fails and the document is sent back to the Kofax TotalAgility Work Queue with the EXPORT FAILED Activity Name. This error is later written to the export instance log file and displayed to the user against the invoice number field.
If the lookup to the external data source is successful, but the purchase order cannot be found, the poNotFound import parameter should be True. This ensures that the document is displayed in the Validation activity with an appropriate error message. However, if this occurs during import, the export does not entirely fail.
It is not recommended to set an error in poReadError if the purchase order does not exist in the data source.
If the profile ID is configured to look for multiple purchase orders, documents can get stuck during document export. The poReadError message should be reserved for the exclusive handline of technical configuration or connectivity issues.
If the purchase order header can be read but the purchase order line items cannot be extracted, then the poNotFound setting may can be set to TRUE if a document needs to remain in the Validation activity until the line items become available. If the flat is set to False, then the purchase order number is accepted during validation, but it is not possible to carry out line pairing during document export. This does not however, cause document export to completely fail.
If multiple records are returned for the purchase order header lookup, indicating that duplicate purchase orders exist in the external data source, the duplicatePO parameter should be TRUE. Doing so will activate the standard purchase order duplicate handling, but only if the Skip Duplicate PO Check setting is cleared in the Settings > Invoice Processing > Capture Profiles > PO Number Settings > PO Number Validation.
Once data is successfully retrieved, the components of the POHeader structure and the POLineItems array are populated. The following table defines the structure of the purchase order header (POHeader) and explains what components are mandatory and those that are optional. It also provides hints for populating each component.
|
Structure Element |
Mandatory? |
Type |
Description |
|---|---|---|---|
|
DOCTYPE |
No |
String |
The purchase order document type. It is populated if the POType field is set as the SERVICE. |
|
COMPANYCODE |
No |
String |
The purchase order company code. This needs populated if the profile configuration is set to default a company code based on the purchase order number lookup. |
|
VENDORID |
Yes |
String |
The PO order-from vendor. If this field is not populated, then Kofax AP Agility raises a configuration error. Hence, the purchase order number field is set to invalid and the document is sent to the Validation activity. If this issue occurs during export, export fails and the document is sent back to the Kofax TotalAgility Work Queue with the EXPORT FAILED Activity Name |
|
SITEID |
Yes, if the document profile uses a site ID. |
String |
The site ID for the purchase order vendor. If the field is not populated and a site ID is needed, Kofax AP Agility raises a configuration error. Hence, the purchase order number field is set to invalid and the document sent to the Validation activity. If this occurs during export, export fails and the document is sent back to the Kofax TotalAgility Work Queue with the EXPORT FAILED Activity Name |
|
CURR |
|
String |
The purchase order currency. This component is populated if the configuration profile of the document is set to default a currency of the purchase order. This field is also required before line pairing occurs. |
|
RELEASEFLAG |
|
String |
The purchase order release flag. If purchase orders in the downstream ERP system are configured so that invoices are not processed until the purchase order is released, and the purchase order is currently not released, then this field is populated with a value. Under all other circumstances, it is left blank. Populating this field with a value notifies the Validation activity user that the PO has not been released. During export, line pairing is not performed. |
|
DOCCOND |
|
String |
The ID of the group of SAP ECC condition records that belong to the purchase order. |
|
DOCCOND |
|
String |
The remit-to vendor ID. If both the order-from and a remit-to vendor are present on the purchase order, the remit-to vendor takes priority and is displayed to the Validation activity user and exported. |
|
STAUS |
|
String |
The purchase order document status. |
|
EXRATE |
|
String |
The exchange rate between the purchase order currency and the local currency of the purchase order company code. This is a factor that is multiplied against the purchase order totals in order to convert from the purchase order currency to the company code currency. For example, if the purchase order document currency is CNY and the company code currency is GBP, then, assuming that 1 GBP = 10 CNY, the exchange rate is be set to 0.1. It is not mandatory to populate this field, but if the purchase order currency differs from the company code currency and the invoice is presented in the company code currency, then line pairing cannot be performed. |
The following table describes the structure of the purchase order line items array (poLineItems). It also explains which of the components are mandatory and which are optional. In addition, the table provides hints for populating each component.
Although all but one of the fields are optional, it is recommended to populate as many relevant fields as possible in order to maximize the success of line pairing. The relevant fields that fall into this category are:
-
MATERIALNO
-
DESCRIPTION
-
POQUANTITY
-
UOM
-
UNITPRICE
-
PUOM
-
PRICEUNIT
-
TOTAL
-
TOTALQUANTITYDELIVERED
-
TOTALVALUEDELIVERED
-
TOTALQUANTITYINVOICED
-
TOTALVALUEINVOICED
|
Structure Element |
Mandatory? |
Type |
Description |
|---|---|---|---|
|
LINENO |
Yes |
String |
The purchase order line item number. This identifies a unique purchase order line item from a purchase order. Kofax AP Agility raises a configuration error if the field is left empty. As a result, the purchase order number field is set to invalid and the document sent to the Validation activity. If this occurs during export, export fails and the document is sent back to the Kofax TotalAgility Work Queue with the EXPORT FAILED Activity Name |
|
MATERIALNO |
No |
String |
The purchase order line item material number. |
|
MATERIALGROUP |
No |
String |
The purchase order line item material group. |
|
DESCRIPTION |
No |
String |
The purchase order line item description. |
|
POQUANTITY |
No |
|
The line item order quantity. |
|
UOM |
No |
String |
The purchase order line item quantity unit of measure. |
|
UNITPRICE |
No |
Double |
The line item unit price. |
|
PUOM |
No |
String |
The purchase order line item price unit of measure. |
|
PRICEUNIT |
No |
String |
The purchase order line item price unit. If this value is not populated, Kofax AP Agility input a default value of 1. |
|
TOTAL |
No |
Double |
The line item order total. |
|
TAXCODE |
No |
String |
The purchase order line item tax code. For the best results, populate this field when the automatic tax determination feature is being used. |
|
TAXJURCODE |
No |
String |
The purchase order line item tax jurisdiction code that represents the ID of the tax office relevant to the location where the purchase order item is used. Tax jurisdiction codes are typically used in the US or countries where sales/use tax rates are set in law at the provincial level, as opposed to a fixed rate set at the national level, such as VAT within the EU. If relevant for the downstream ERP system, It is recommended to populate this field. |
|
TOTALQUANTITYDELIVERED |
No |
Double |
The total quantity already delivered for a purchase order line item. |
|
TOTALVALUEDELIVERED |
No |
Double |
The total value of the goods already delivered for a purchase order line item. |
|
TOTALQUANTITYINVOICED |
No |
Double |
The total quantity that is already invoiced for a purchase order line item. |
|
TOTALVALUEINVOICED |
No |
Double |
The total value of the goods already invoiced for the purchase order line item. |
|
ITEMCATEGORY |
No |
|
The purchase order line item category. This is populated if a document profile is configured to determine whether the POType is SERVICE. This is based on purchase order line item categories. |
|
PLANT |
No |
String |
The ID of the purchase order line item plant (i.e. where the goods are to be delivered). This should be populated if the automatic tax determination feature is activated as it specifies the ship-to state/country for the purchase order line item. |
|
CARGECODE |
No |
String |
The purchase order line item charge code. |
|
CHARGECODEID |
No |
String |
The purchase order line item charge code ID. |
|
ERS |
No |
Boolean |
This flag is set to TRUE if the purchase order line item is marked for ERS (Evaluated Receipt Settlement). If the Stop ERS PO setting is selected in the Settings > Invoice Processing > Capture Profiles > PO Number Settings > PO Number Validation for the document profile, the invoice is rejected and sent to the Validation activity. For ERS purchase orders, no paper invoice is expected as it is processed electronically as part of an EDI-type transaction. |
|
GRIV |
No |
Boolean |
A SAP ECC-specific flag that is set to TRUE if the purchase order line item is set up for goods receipt based invoice verification. |
|
SRIV |
No |
Boolean |
A SAP ECC-specific flag that is set to TRUE if the purchase order line item is set up for service based invoice verification. |
|
MULTIPLEACCOUNTASSIGNMENT |
No |
String |
indicates whether a purchase order line item is set up with a multiple account assignment. This should be left blank if no multiple account assignment exists. |
|
ACCOUNTASSIGNMENTCATEGORY |
No |
String |
The purchase order line item account assignment category. It is populated if the automatic tax determination feature is used and the default tax code is configured based on purchase order line item account assignment category. |
A suggested overview of the process flow in a script is as follows:
-
Connect to the purchase order header data source and then query using the key provided in POKey.
-
If a connection or configuration issue occurs, set the readError parameter to an appropriate error message and exit.
-
If the purchase order does not exist in the data source, set the duplicatePO setting to TRUE and exit.
-
If multiple purchase order headers are extracted, set the duplicatePO to TRUE, and exit.
-
Populate the POHeader.
-
If the readPOLines parameter is set to "False," exit at this point.
-
Connect to the purchase order line item data source and then query using the key provided in POKey.
-
If a connection or configuration error occurs, set the poReadError value to an appropriate error message and then exit.
-
If no line item data exists for the purchase order, the poNotFound flag is set to True. This is optional depending on project requirements.
-
Loop through the line items extracted and then copy the data into the POLineItems array.
-
Exit the subroutine.
If a custom validation is also required within the user exit, but the user may still accept the purchase order, then a new stop can be inserted between steps three and four above. This step passes as readError error message, but only if both export and projectContext.ProjectData.IsVerifier are False.
if(!export && !projectContext.ProjectData.IsVerifier) { poReadError = "Custom...";}