Chapter 12   Customizing


This chapter provides information and guidelines on customizing some of the iPlanet BuyerXpert features for your operation.

This chapter contains the following sections:

• About Administering Customizations

• Invoice Matching

• Supplier Performance

About Administering Customizations

---

An administrator is generally concerned with the following aspects of customization:

• Doing customizations that do not require programming skills, such as:
  • Modifying system elements, such as login, session timeout parameters, application server parameters, database parameters, and error message text

  • Modifying look and feel of the graphical interface

  • Creating AIFs

• Verifying customizations that do require programming skills and thus, have been written by a developer, such as:
  • Adding new fields to a data object

  • Modifying look and feel of the graphical interface

  • Adding new fields to the inbound/outbound file for ECXpert

  • Creating new reports; modifying existing reports

• Implementing customizations to production.

As the administrator, you are responsible for verifying that developer-level customizations have been tested on a staging system (testing can be done by the developer or you), and for implementing the customization to the iPlanet BuyerXpert production system

Setting Up Interface to an API

If an application program interface (API) has been written for your iPlanet BuyerXpert system, you need to establish an interface to the API. A typical situation for creating an API related to product data is when your organization has an existing enterprise resource planning (ERP) database and you want the accounting and/or commodity codes that already exist in your ERP to be validated when line items are added to a requisition. Without an API, iPlanet BuyerXpert has no way of interfacing with your ERP system.

Testing and Implementing Customizations

After any customization work is completed, you need to test the results and the impact of the customizations on iPlanet BuyerXpert. Even if you or the developer has already done some testing in the staging environment, you need to verify the testing. While the developer is responsible for creating customizations that work, you are responsible for the operation of iPlanet BuyerXpert, so it is very important that you are careful about anything that impacts your production system.

To test customizations in the staging environment:

1. Load customization files to the staging system.

2. Test the behavior of the files

3. Verify success.

4. Get requester sign-off, if applicable.

After you are satisfied that the customizations work correctly in the iPlanet BuyerXpert staging environment, you are ready to implement them to production.

When a customization is ready for testing (or for implementation, if the developer has done the staging testing), the following information should be provided by the person who did the customization:

• Location—where the files are located

• Documentation—Readme file and any other documentation that explains the customization and how to use it

• Testing done—description of what testing has been done in the development or staging environment

• Impact areas—description of what iPlanet BuyerXpert areas are impacted by this customization

• Requester sign-off—verification by the requester that the customization is what was requested

To implement developer customizations to production, follow these guidelines:

1. Schedule implementation.

2. Load customization files to the production system.

3. Test behavior of the customization.

4. Verify success.

5. Notify users.

6. Archive source files.

Invoice Matching

---

Configuring Invoice Matching

Invoices are received as XML documents and entered into BuyerXpert using a script. This script can be launched by a custom service of ECXpert. Invoice documents can be received from suppliers in any format (EDI X12, Edifact, RosettaNet XML, and so on) and in any Internet protocol (http(s), SMTP, FTP, and so on). ECXpert then takes care of translating the document to the XML format needed by BuyerXpert, and enters the file into BuyerXpert using the import script.

Invoice Matching Formats

The XML format of the BuyerXpert invoice is OBI-like. Currently there is no official OBI specification for the invoice document, so special user fields have been allocated. These fields allow for custom dates/strings/amounts going into and out of iPlanet BuyerXpert.

If the BuyerXpert invoice XML format meets the customer needs, minimal work is required to set up ECXpert to receive the XML and forward it to BuyerXpert. If the customer decides to use a different XML format, a Mercator map needs to be created for ECXpert that transforms the customers XML format to the XML format expected by BuyerXpert.

If customers want to create their own invoices, they must set up a web form to enter the invoice data. After this, a servlet or CGI script could be launched which would take this invoice data, create the invoice XML document, and send it to ECXpert for processing.

Roles Related to Invoice Matching

Basically there are two groups that the invoice can be forwarded to (meaning that the invoice is added to their task list): reviewers and adjusters.

Reviewers can view invoices and re-submit invoices, for example, after they know goods have been received. Adjusters can edit invoices and resubmit invoices, for example, if the invoices are being entered by hand in another system and there was an error, or if the invoice needs to be changed.

In addition, adjusters, if the appropriate business rule is enabled for them, can decide to pay anyway, even if invoice matching has failed. In the pay anyway situation, the invoice is allowed to bypass invoice matching and a payment voucher is generated.

Failed invoices display in a separate section of the reviewers' and adjusters' approval task lists, with links to the failed invoices.

The following sections discuss configuring the invoice matching feature for your iPlanet BuyerXpert environment:

• Implementing Invoice Matching

• Testing Invoice Matching

Implementing Invoice Matching

The Process Manager application that has to be deployed for invoice matching can be found at: $IASROOT/buyer/sample_data/srm/InvoiceMatching.zip

To implement iPlanet BuyerXpert invoice matching, follow these steps:

1. Deploy the Process Manager application:
   1. Run Process builder.

      $IASROOT/builder/Builder.sh&

   2. Select Import, you are asked to specify the path of a zip file. The zip file is located here:

      $IASROOT/buyer/sample_data/srm/InvoiceMatching.zip

   3. Click Deploy.

   4. Select the cluster you have created for Process Manager.

      When prompted for authentication, use the login ID and password you have entered for your Process Manager application (for example admin/admin).

   5. Click OK. You should see the Successful Deployment screen.

   6. In your browser go to the process express:

      http://ibiza.mcom.com:11002/Express.npm

   7. Click the New Process tab and verify that you can see the name of the application you just deployed (InvoiceMatching.zip).

2. Set the rules.
   1. Log into the iPlanet BuyerXpert Admin interface.

   2. Click the organization (for example BuyerCompany) and go the invoice matching rules.

   3. Set the following rules:
      • Invoice Matching algorithm—Set to 2-way or 3-way.

        In the default behavior (without customization), if the value of this rule is set to 3-way, the matching is done between the Ordered, Received and the Invoiced quantities.

        If the rule is not set, or the rule is set to any other value, (the Received quantity is not considered), the matching is done only between the Ordered and the Invoiced quantities.

      • Allowed to Pay Invoice—Set to all. (To be set more specifically later.)

      • Payment Voucher Currency—Leave this empty. In this case, the payment voucher has the same currency as the invoice currency.

      • Invoicing User—Set this to anything, for example, admin. This is just a dummy user whose environment is used to initiate the invoice matching process.

3. Create the user groups in iPlanet BuyerXpert:
   1. Log into the iPlanet BuyerXpert Admin interface.

   2. Create the following user groups under BuyerCompany:
      • IMAG (Invoice Matching Accounting Group)

      • IMPG (Invoice Matching Purchasing Group)

      • IMSAG (Invoice Matching System Administration Group)

   3. Add the same user to each of these groups, for example, admin. You can use any user name, since this is user is for testing purposes only.

4. Update the $IASROOT/buyer/buyer/config/xdoc/xdocinfo.ntv file:
   1. Update the following settings:

      "xdoc_dir" Str "/d/10/buyerfiles",
      ....
      "submit_payment_voucher_to_ecx_script" Str\\ "submitPaymentVoucherToECX.sh",
      "payment_voucher_receiver" Str "BuyerCompany",
      "payment_voucher_sender" Str "seller",
      "payment_voucher_document" Str "paymentvoucher",

   2. Restart the iPlanet Application Server.

Testing Invoice Matching

To test invoice matching after configuring, use the following XML file (call it, for example, oneitem.xml):

<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE BXXMLInvoice SYSTEM 'file:/h/buster/export2/ias6/buyer/sample_data/xdoc/Dtds/BXXM LInvoice.dtd'>

<BXXMLInvoice version="1.0" xml:language="1.0" revision="1">
<Envelope>
<Sender>
<NamingAuthority>only text</NamingAuthority>
<PartnerName>only text</PartnerName>
<Password>only text</Password>
</Sender>
<Receiver>
<NamingAuthority>only text</NamingAuthority>
<PartnerName>only text</PartnerName>
</Receiver>
<TransmissionDateTime>only text</TransmissionDateTime>
<EnvelopeID>only text</EnvelopeID>
</Envelope>
<Invoice>
<InvoiceHeader>
<InvoiceNumber>Invoice_01</InvoiceNumber>
<InvoiceDate>Jan 22, 2001 11:00 AM</InvoiceDate>
<InvoiceDescription>Some Description</InvoiceDescription>
<BuyingParty>
<Organization>
<Name>BuyerCompany</Name>
<Address>
<AddressLine1></AddressLine1>
<City></City>
<StateOrProvince></StateOrProvince>
<PostalCode></PostalCode>
<CountryCode></CountryCode>
</Address>
</Organization>
<ContactInfo>
<Contact>
<FirstName>nancy</FirstName>
<EMail>nancy</EMail>
</Contact>
</ContactInfo>
</BuyingParty>
<SellingParty>
<Organization>
<Name>tech</Name>
<Address>
<AddressLine1></AddressLine1>
<City></City>
<StateOrProvince></StateOrProvince>
<PostalCode></PostalCode>
<CountryCode></CountryCode>
</Address>
</Organization>
<ContactInfo>
<Contact>
<FirstName></FirstName>
<EMail></EMail>
</Contact>
</ContactInfo>
</SellingParty>
<CurrencyCode> USD </CurrencyCode>
<OrderTotal>460.16</OrderTotal>
<Tax>
<TaxJurisdictionCode>group_tax</TaxJurisdictionCode>
<TaxAmount>-0.84</TaxAmount>
</Tax>
<ShippingCost>17.55</ShippingCost>
<AllowanceOrCharge>
<Allowance>
<AllowanceType>group_dcap</AllowanceType>
<Amount>-4.24</Amount>
<Description></Description>
</Allowance>
</AllowanceOrCharge>
</InvoiceHeader>
<InvoiceDetail>
<LineItemInvoice>
<LineItemNumber> 1 </LineItemNumber>
<QuantityOrdered>
<Quantity>1</Quantity>
<UnitOfMeasure CodeValue="code">EA</UnitOfMeasure>
</QuantityOrdered>
<Part>
<PartNumber>
<SellerPartNumber>7432152</SellerPartNumber>
</PartNumber>
<ItemDescription>
<Description>pencil</Description>
</ItemDescription>
<URL></URL>
</Part>
<InvoiceLineItemNumber> 1 </InvoiceLineItemNumber>
<NetQuantity>
<Quantity>1</Quantity>
<UnitOfMeasure CodeValue="code">EA</UnitOfMeasure>
</NetQuantity>
<PurchaseOrderRef>
<OrderNumber>xyz0000000001abc</OrderNumber>
<OrderDate> 10/10/2000 </OrderDate>
</PurchaseOrderRef>
<Cost>
<ItemPrice>321.00</ItemPrice>
<ExtendedPrice>321.00</ExtendedPrice>
<ShippingCost>70.71</ShippingCost>
<Tax>
<TaxJurisdictionCode>total_line_tax</TaxJurisdictionCode>
<TaxAmount>63.46</TaxAmount>
</Tax>
<AllowanceOrCharge>
<Allowance>
<AllowanceType>line_dcap</AllowanceType>
<Amount>-7.48</Amount>
<Description></Description>
</Allowance>
</AllowanceOrCharge>
</Cost>
<ContractNumber> Contract123 </ContractNumber>
</LineItemInvoice>
</InvoiceDetail>
<InvoiceSummary>
<TotalLineItems>0</TotalLineItems>
<TotalAmount>0</TotalAmount>
</InvoiceSummary>
</Invoice>
</BXXMLInvoice>

---

Note	The sample XML file is set up for product 745150.

---

After configuring the invoice matching application, test it as follows:

1. Create a cart with one of these items and submit it.

2. Approve the requisition. Its status should be Pending Receipt.

3. Go to the URL location:

   http://<host>:<port>/NASApp/buyer/ReadInTest

4. Use the sample XML file above (called oneitem.xml).

   This is the successful match, so you do not see anything in the interface.

5. At the end of the KJS log, you should see the following line:

   "performAP complete: true"

6. Edit the oneitem.xml file.

7. Change the OrderTotal from 460.16 to 470.16. The invoice is now inconsistent with the line items.

8. Submit the XML file. This causes Relational Check to fail and an editable invoice be sent to the IMAG group.

9. Edit the oneitem.xml file again.

10. Change the ItemPrice and ExtendedPrice from 321.00 to 331.00. The invoice is now consistent with itself, but inconsistent with the order, which is for only 460.16.

11. Submit the XML file. This causes Relational Check to pass, the invoice matching to fail, and a non-editable invoice to be sent to the IMPG group.

12. Log into the iPlanet BuyerXpert Admin interface.

13. You should see a Need to approve message. Click Approve.

14. You should see two invoices, one for Action View and one for Action Adjust. Normally these would go to two different groups; they appear in both groups for convenience.

15. Click the Adjust invoice.

16. Change the Order Total from 470.16 to 460.16 and resubmit. The invoice passes both the Relational Check and invoice matching. The same message appears in the KJS log.

17. Return to the task list.

18. Select View Invoice.

19. Click Reassign.

20. Return to the task list. The invoice now appears in Adjust Action. Select the invoice.

21. Change the total amount to 460.16.

22. Change the product amount to 321.00 and resubmit. This causes the invoice to pass.

23. Return to the task list where there are no more tasks.

Customizing Invoice Matching

The invoice matching functionality of iPlanet BuyerXpert allows a developer to customize your site to do the following:

• Receive an invoice into iPlanet BuyerXpert via an XML document

• Run the invoice through an invoice matching algorithm, which may be customized

• Present a user interface to modify the invoice if the matching algorithm fails

• On success, generate a payment voucher XML document from iPlanet BuyerXpert.

The invoice matching algorithm is implemented in iPlanet Process Manager with JavaScript. The Process Manager interface exposes data from the invoice header, invoice lines, and associated order lines, including receiving information. This allows for customization of the invoice matching routine if the delivered algorithm does not meet your requirements.

The following sections discuss customizing the invoice matching feature:

• Delivered Algorithm

• Access to iPlanet BuyerXpert Data

• Functions to Retrieve Invoice Header Values

• Functions to Retrieve Invoice Line Values

• Functions to Retrieve PO Line Values

• Utility Methods

In addition, samples of invoice matching XML files are contained in Appendix D "Example Invoice Matching Files."

Delivered Algorithm

iPlanet BuyerXpert is delivered with a Process Manager process for invoice matching which may be useful to your operation as it is. If not, this delivered algorithm can be customized. The invoice matching algorithm is divided into two phases:

• Phase 1 does validation on the invoice itself, that is, determining whether the invoice total matches the total of the lines.

• Phase 2 matches the invoice lines against the associated order lines, that is, the price on the order compares correctly to the price on the invoice.

The source contains pseudo-code documentation of the functionality of the delivered algorithm, which is accessed using the Process Builder tool.

Access to iPlanet BuyerXpert Data

Access to the iPlanet BuyerXpert data is provided using the invoice object to access invoice header, invoice line, and associated order line data. To get the invoice object, use the following code in your Process Manager JavaScript (you see this in the sample code):

   var pi = getProcessInstance();

   var invoice = pi.getData("invoice");

The following methods of the invoice object show how to access invoice header, invoice line, and associated purchase order line data respectively:

// Get invoice total from the invoice header
var invoiceTotal = invoice.getDec("order_total");

// Get the total number of invoice lines
// Invoice lines are accessed sequentially starting with a zero index invoice.getTotalLines();

// Get invoice line total from the invoice line "i"
invoiceLineTotal = invoiceLineTotal.add(invoice.getLineDec(i, "line_total"));

// Get the unit price for the PO line associated with invoice line "i" var unitPrice = invoice.getPOLineDec(i, "net_price");

The following sections document the methods and data available for accessing invoice header, invoice line, and associated order line data. In addition, there are some utility methods available.

Functions to Retrieve Invoice Header Values

• getStr(String name) get a String value

• getInt(String name) get an int value

• getLong(String name) get a long value

• getBool(String name) get a boolean value

• getFloat(String name) get a float value

• getDec(String name) get a BigDecimal value
  

  Table 12-1    Available Invoice Header Values 
  
  

  Name	Type	Description
  inv_number	String	Invoice number
  inv_date	Date	Invoice date (from the invoice)
  inv_desc	String	Invoice description
  buying_company_name	String	Name of buying company
  selling_company_name	String	Name of selling company
  currency_code	String	Currency code
  order_total	BigDecimal	Total invoice amount
  group_freight	BigDecimal	Total group freight
  group_dcap	BigDecimal	Total group DCAP
  group_tax	BigDecimal	Total group tax
  invoice_url	String	Invoice URL provided
  other_date1	Date	For custom-use date1
  other_date2	Date	For custom-use date2
  other1	String	For custom-use string1
  other2	String	For custom-use string2
  other3	String	For custom-use string3
  other4	String	For custom-use string4
  other5	String	For custom-use string5
  other_amount1	BigDecimal	For custom-use currency amount1
  other_amount2	BigDecimal	For custom-use currency amount2
  other_amount3	BigDecimal	For custom-use currency amount3

Functions to Retrieve Invoice Line Values

• getLineStr(int lineNumber, String name) get a String value

• getLineLong(int lineNumber, String name) get a long value

• getLineInt(int lineNumber, String name) get an int value

• getLineFloat(int lineNumber, String name) get a float value

• getLineDouble(int lineNumber, String name) get a double value

• getLineDec(int lineNumber, String name) get a BigDecimal value
  

  Table 12-2    Available Invoice Line Values 
  
  

  Name	Type	Description
  inv_line	long	Invoice line number
  order_code	String	Order code
  line_item_number	int	Order line item number
  product_code	String	Product code
  product_description	String	Product description
  contract_number	String	Contract number
  quantity_uom	String	Unit of measure for quantity
  net_quantity	long	Quantity
  unit_price	BigDecimal	Unit price
  line_total	BigDecimal	Total for line
  total_tax	BigDecimal	Total tax for line
  freight_amount	BigDecimal	Total freight for line
  dcap_on_amount	BigDecimal	Total DCAP for line
  other_amount1	BigDecimal	For custom-use currency amount 1
  other_amount2	BigDecimal	For custom-use currency amount 2
  other_amount3	BigDecimal	For custom-use currency amount 3
  other_amount4	BigDecimal	For custom-use currency amount 4
  other_amount5	BigDecimal	For custom-use currency amount 5
  other_amount6	BigDecimal	For custom-use currency amount 6
  other_date1	Date	For custom-use date1
  other_date2	Date	For custom-use date2
  other1	String	For custom-use string1
  other2	String	For custom-use string2
  other3	String	For custom-use string3
  already_invoiced	long	Quantity already invoiced

Functions to Retrieve PO Line Values

There are purchase order lines associated with a particular invoice line. The lineNumber is the invoice line number.

• getPOLineStr(int lineNumber, String name) get a String value

• getPOLineLong(int lineNumber, String name) get a long value

• getPOLineInt(int lineNumber, String name) get an int value

• getPOLineFloat(int lineNumber, String name) get a float value

• getPOLineDouble(int lineNumber, String name) get a double value

• getPOLineDec(int lineNumber, String name) get a BigDecimal value
  

  Table 12-3    Available Purchase Order Line Values 
  
  

  Name	Type	Description
  seller_company_name	String	Name of the selling company
  line_number	int	Order line number
  allow_partial_ship	boolean	Whether partial shipment is allowed
  product_code	String	Product code
  commodity_code	String	Commodity code
  product_description	String	Product description
  inventory_identifier	String	Inventory identifier
  external_product_code	String	External product code
  external_product_description	String	External product description
  order_code	String	Order code
  quantity_uom	String	Unit of measure
  quantity_requested	String	Quantity requested
  quantity_sold	long	Quantity sold
  quantity_shipped	long	Quantity shipped
  quantity_received	long	Quantity received
  total_tax	BigDecimal	Total tax
  net_price	BigDecimal	Net price per unit
  net_total	BigDecimal	Net total price
  net_tax	BigDecimal	Net tax
  total_tax	BigDecimal	Total tax
  line_total	BigDecimal	Total of line
  is_off_catalog	boolean	Off catalog flag
  base_total	BigDecimal	Base total
  gross_total	BigDecimal	Gross total
  catalog_code	String	Code from the catalog
  is_price_overridden	boolean	Whether price was over-ridden
  line_currency_code	String	Currency code
  matching_algorithm	String	Matching algorithm as set by rule

Utility Methods

Most of the utility methods are accessed using the iPlanet BuyerXpert EJB. Obtain access to the iPlanet BuyerXpert EJB through the process instance handle, as follows:

var handle = pi.getData("handle");

var home = ejbLookup("ejb/com/iplanet/buyer/BuyerEJB");

var buyer = home.create();

The following utilities are provided using the iPlanet BuyerXpert EJB:

// Clear the processing errors list

// This should be called at the beginning of each phase of checking a case

// See the usage in the sample invoice matching process buyer.clearIMErrors(handle);

// Add an error condition to the processing errors list

// This routine is called whenever your invoice matching processing detects an error condition

// handle: The case handle as obtained above

// invoice_line_index: the zero-based index of the invoice line items

// Use -1 if the error is not associated with a particular invoice line

// code: Currently unused. Pass a zero value.

// description: Free text description of the error. This text is presented to the user.

// field: The name of the field with which the error is associated (optional)

//

// Error messages are displayed to the end user in the problem invoice UI

// Errors associated with a particular invoice line index will be displayed with that line

// Other errors are displayed with the invoice header

//

buyer.createIMError(handle, invoice_line_index, code, description, field);

// Check for valid currency code

buyer.isValidCurrency(handle, currencyCode)

// Check for valid UOM code

buyer.isValidUOM(handle, uomCode)

// Notify BuyerXpert group via problem invoice task list

// group_name is the name of an existing BuyerXpert group

buyer.notifyIMGroup(handle.toString(), group_name);

// Change the status of the invoice matching case

// "VALIDATION_EXCEPTION"

// "PENDING_APPROVAL

buyer.changeIMCaseState(handle.toString(), status);

The following utilities are provided using the invoice object:

// Create a BigDecimal variable with an initial value

var decZero = invoice.resetDec(0.0);

Custom-Use Fields

The custom-use fields may be included in the input invoice XML file. (See the invoice DTD for the names of the fields.) They are also accessible in the invoice user interface and the Invoice Matching Process Manager Process JavaScript. This section documents the names and the types for the fields.

Use in Invoice User Interface
The custom-use fields can be displayed and edited in the invoice user interface by modifying the following templates:

• InvoiceView.jsp—The display of the invoice header and line information. Shows edit buttons in edit mode.

• InvoiceEditHeader.js—The invoice header edit screen.

• Invoice AddEditLine.jsp—The screen for adding a new line or editing a line.

The templates are in two locations. You should make sure your modifications are applied to the templates in both locations:

• ias_root/ias/APPS/modules/buyer/com/iplanet/buyer/templates/en/US/srm/im

• ias_root/buyer/buyer/templates/en/US/srm/im

You see sections for existing fields in each of the templates. You should copy a section that begins with a <TR> tag and end with a </TR> tag, then change the label and data retrieval for your new field. Be sure that the data access method matches the type of the field you are using. The following fields are available:

Header	OTHER_DATE1	Date
	OTHER_DATE2	Date
	OTHER1	String
	OTHER2	String
	OTHER3	String
	OTHER4	String
	OTHER5	String
	OTHER_AMOUNT1	BigDecimal
	OTHER_AMOUNT2	BigDecimal
	OTHER_AMOUNT3	BigDecimal
Line	OTHER_DATE1	Date
	OTHER_DATE2	Date
	OTHER1	String
	OTHER2	String
	OTHER3	String
	OTHER4	String
	OTHER5	String
	OTHER_AMOUNT1	BigDecimal
	OTHER_AMOUNT2	BigDecimal
	OTHER_AMOUNT3	BigDecimal
	OTHER_AMOUNT4	BigDecimal
	OTHER_AMOUNT5	BigDecimal
	OTHER_AMOUNT6	BigDecimal

Use in Process Manager Process JavaScript
Similarly, these fields can be accessed in the process manager Java Script. To access invoice header fields, use the following methods on the JavaScript invoice object:

• Date invoice.getDate("name");

• String invoice.getStr("name");

• BigDecimal invoice.getDec("name");

To access invoice line fields, use the following methods on the JavaScript invoice object:

• Date invoice.getLineDate(line_index, "name");

• String invoice.getLineStr(line_index, "name");

• BigDecimal invoice.getLineDec(line_index, "name");

The field names for the header and line, respectively are:

• other_date1, other_date2, other1, other2, other3, other4, other5, other_amount1, other_amount2, other_amount3.

• other_date1, other_date2, other1, other2, other3, other_amount1, other_amount2, other_amount3, other_amount4, other_amount5, other_amount6

Supplier Performance

---

The seller performance feature of iPlanet BuyerXpert allows a user to capture quality data during the receiving process. This data is meant to be a measure of the quality of a supplier's performance.

Customizing the supplier performance feature involves customizing the amount and type of quality data that a user is required, or allowed, to enter while receiving items against a purchase order.

Customizing the supplier performance feature involves the tasks described in the following sections:

• Creating a Template (JSP Template)

• Deploying the Template

• Setting the Templates Selection Rule

• Configuring Mail Settings

• Javadoc for Supplier Performance

Creating a Template (JSP Template)

Creating a template requires knowledge of the following:

• Java Server Page and Servlet programming

• JSP programming in the iPlanet BuyerXpert framework

• iPlanet BuyerXpert data and object repository and how it works

• APIs provided by the VendorPerformance servlet

The following sample templates are provided to aid in developing custom templates:

• SampleMultiPart.jsp contains all the user interface fields supported for quality data entry purposes.

• SampleDaysLate.jsp which has only two fields on it.

Data that is entered as quality data is stored in the database in a table called quality_entry_data as described in Table 12-4.

Table 12-4    Quality Data Table 

Name	Null?	Type
ID	NOT NULL	NUMBER(19)
NAME	NOT NULL	VARCHAR2(80)
LINE_ITEM_ID	NOT NULL	NUMBER(19)
DATA_TYPE	NOT NULL	NUMBER(10)
STRING_DATA		VARCHAR2(1024)
NUMERICAL_DATA		NUMBER(19)
DECIMAL_DATA		NUMBER
SELLER_HANDLE	NOT NULL	VARCHAR2(80)
OWNER_HANDLE	NOT NULL	VARCHAR2(80)

The important fields to note are STRING_DATA, NUMERICAL_DATA, and DECIMAL_DATA, one of which stores the actual data. DATA_TYPE identifies which of these fields contains the data.

Each data field on the JSP has one row in the quality data table. With these fields in the database, the datatypes listed in Table 12-5 are supported for the user interface.

Table 12-5    User Interface Datatypes 

Name	Description
QualityTextLine	Text box 25 columns wide Data stored in STRING_DATA DATA_TYPE = 10
QualityTextBlock	Text box 40 columns wide and 5 rows Data stored in STRING_DATA DATA_TYPE = 11
QualityFactorLong	Drop-down list containing long values Data stored in NUMERICAL_DATA DATA_TYPE = 20
QualityFactorDouble	Drop-down list containing decimal values Data stored in DECIMAL_DATA DATA_TYPE = 21
QualityFactorString	Drop-down list containing String values Data stored in STRING_DATA DATA_TYPE = 22
QualityMailList	Drop-down list allowing user to choose email targets Data stored in STRING_DATA DATA_TYPE = 30

The user interface datatypes are Data and Object Repository (DOR) entries and can be found in the following file:

$APPS/com/iplanet/buyer/config/srm/repository.ntv

Minimum JSP Requirements

Every JSP should have the following lines at the beginning of the JSP:

<%@ include file="/com/iplanet/buyer/templates/bx_prolog.jsp"%>

<%@ include file="/com/iplanet/buyer/templates/bx_format.jsp"%>

In addition, the following line should be at the end of the JSP:

<%@ include file="/com/iplanet/buyer/templates/bx_epilog.jsp"%>

---

Note	You can use the SampleDaysLate.jsp or SampleMultiPart.jsp as a template for creating your own custom JSPs.

---

Creating an HTML FORM

In the iPlanet BuyerXpert framework, create an HTML FORM as follows:

   <% fc = oc.getForm

   (VendorPerformance.VENDOR_PERFORMANCE_FORM,

   "buyer/VendorPerformance"); %>

   <%= fc.beginForm ("METHOD=post") %>

This is equivalent to the <FORM ...> tag in HTML.

---

Note	You should not change the FORM name or the name of the Servlet which is going to handle this form.

---

A hidden field containing the primary key of the line item has to be added to each FORM. To add this field:

   <%

      String id = oc.getStr(SRMServletConstants.OBJECT_ID);

      pc = fc.getPC("Hidden", SRMServletConstants.OBJECT_ID);

      pc.setValue(id);

   %>

   <%= pc.getHtml() %>

The FORM should be terminated as follows:

   <%= fc.endForm() %>

This is equivalent to the </FORM> tag in HTML.

Putting a Submit Button on the HTML FORM

Each button you put on a JSP is a DOR entry defined in the following file:

   $APPS/com/iplanet/buyer/config/srm/repository.ntv

The buttons which are available to you are:

• Save Quality Data—Used to submit the FORM. Instructs the Servlet to save data edited by the user. The label on this button is Save.

• Done Quality Data—Used to configure the Servlet to ignore user edits. The label on this button is Done Editing.

Example
To add a button:

<% pc = fc.getPC( "SaveQualityData", SRMServletConstants.ACTION); %>

<% pc.setHtmlAttrs("border=0"); %>

<%= pc.getHtml() %>

Adding One of the UI Elements to a JSP

To create and place one of the above user interface elements on a JSP, you need to use the FormContext objects getPCHtml() method and a static method in VendorPerformance servlet.

Code samples for the user interface elements:

• <%= fc.getPCHtml("QualityTextLine",
  VendorPerformance.createTextLineName("<NAME>")) %>

• <%= fc.getPCHtml("QualityTextBlock",
  VendorPerformance.createTextBlockName("<NAME>")) %>

• <%= fc.getPCHtml("QualityFactorLong",
  VendorPerformance.createQualityFactorLongName("<NAME>")) %>

• <%= fc.getPCHtml("QualityFactorDouble",
  VendorPerformance.createQualityFactorDoubleName("<NAME>")) %>

• <%= fc.getPCHtml("QualityFactorString",
  VendorPerformance.createQualityFactorStrName("<NAME>")) %>

• <%= fc.getPCHtml("QualityMailList",
  VendorPerformance.createMailActionName("<NAME>")) %>

Where <NAME> is a string that gets stored in QUALITY_ENTRY_DATA.NAME

Constructing the email List for an email Field in the JSP

The entities to whom emails are sent can be computed in the JSP itself giving you the flexibility of customizing the email recipients.

QualityMailList DOR entry:

   "QualityMailList" NTV {

      "extends" Str "Listbox",

      "codecategory" Str "QualityMailList",

      "rows" Int "1"

},

The following CodeCategory setting can be found in the $APPS/com/iplanet/buyer/config/srm/codes.ntv file:

   "QualityMailList" NTV {

      "0" Str "-none at this time-",

      "1" Str "Send E-Mail to Manager",

      "2" Str "Send E-Mail to group('s)",

      "3" Str "Send E-Mail to individual('s)",

   },

The DOR name (QualityMailList) happens to be the same as the CodeCategory name (QualityMailList). However, this need not be the case. The DOR name can be different from the CodeCategory name.

---

Note	You cannot add entries to the QualityMailList code category.

---

As a result of the above DOR entry and CodeCategory entry, the user sees a drop-down list containing the four choices listed in the CodeCategory entry. Now you have the task of creating an email address (or a list of email addresses) corresponding to each of the three email actions the user is able to select. The following code snippet is code that you can change to suit your customization needs.

Example
SampleMultiPart.jsp

<%

// set up actual groups to mail,

String name = "Mail";

// note manager does not need a name list

// The Managers email address is computed automatically

// The manager of the organizational unit to which the current user

// belongs will be the one to receive an email.

// Add any UserGroup that you wish to receive email

// You may add/delete UserGroups

String[] groups = { "CatalogBrowsers","CatalogManagers"};

// Add the user ids of individual users

// You may add/delete users

String[] indivuduals = { "admin", "kevin"};

// NTV used to pass information to the Servlet

CXNTVList passDataList = new CXNTVList();

passDataList.setNTVList(VendorPerformance.createMailGroupListName(n ame),
   VendorPerformance.createMailList(groups));

passDataList.setNTVList(VendorPerformance.createMailIndividualListN ame(name),
   VendorPerformance.createMailList(indivuduals));

%>

<% // passData() can be called only once per Form %>

<%= fc.passData(passDataList) %>

---

Note	The code snippet above is code that you can change to suit your customization needs. The rest of the code should not be changed.

---

Deploying the Template

To deploy your templates, copy them to the following directories:

$APPS/buyer/com/iplanet/buyer/templates/en/US/srm/vendorperf $APPS/com/iplanet/buyer/templates/en/US/srm/vendorperf

Where:

$APPS refers to the APPS subdirectory under your iPlanet Application Server installation.

The en/US directory is the locale-specific subdirectory that contains templates for the en/US locale. If you support other locales, you can put the localized versions of these templates into the respective directories.

The srm/vendorperf directory is the recommended subdirectory where you should put the template, but you can choose a different subdirectory. You need to know this sub-directory when you set the QUALITY_ENTRY_FORM policy.

Setting the Templates Selection Rule

You can create and deploy as many templates as you want. However, this is not sufficient to ensure that the user sees the proper template while receiving items. To control which user sees which template, and under what conditions, you must set the QUALITY_ENTRY_FORM business rule, using the Import utility. Instructions for using the Import utility are contained in Chapter 7 "Importing/Exporting Data."

Rule Synopsis

• Name—QUALITY_ENTRY_FORM
  Specify the name of the template along with the path relative to the locale sub-directory.

• Roles—USER_CREATED_FOR, PRODUCT, SELLER_COMPANY

• Value—srm/vendorperf/CustomizedTemplate.jsp
  Specify the template you have created as the rule value.

Configuring Mail Settings

You can configure mail settings by editing the srmInfo.ntv file, which is located in the following directory:

   $APPS/com/iplanet/buyer/config/srm

This file has an NTV which looks like this:

"SRMMailSetting" NTV {

   "smtphost"               Str "<smtp_mailserver_hostname>",

   "subject"               Str "<subject line for email notifications sent on Quality data updates>",

      "cc"         Str "<email addresses, seperated by commas, to be copied on email notifications>",

}

Javadoc for Supplier Performance

Refer to the Class VendorPerformance Javadoc for details on the servlet.