Copy a Value to the Item Column

This use case shows you how to use a custom transaction line field and a client script to change the value of a standard column field, such as the Item column.

This project is available on the SuiteCloud Project Repository on Oracle Samples GitHub. It includes the complete project customization setup with custom objects, unit tests, package file configuration, and more.

Scenario

You are a store owner and you have employees who can recognize several digits of the UPC code for your core billing items. You would like to make those UPC codes available in a small drop down list for the employee to select from. You plan to enter your items by name in NetSuite. However, the item list is long and you want employees to select a UPC code instead of scrolling through a long list of item names. You can customize the invoice form for these employees to disable the Item column and add a custom transaction line field where they can select billing items using the UPC code.

Customization Details

The customization for this use case includes:

• A custom field (Billing Item) to select an item by UPC code

• A custom list (Billing Items) to store products with UPC codes

• An item record to test the implementation of UPC code selection

• A custom form to be used as a custom billing item invoice

• A client script triggered on the fieldChanged entry point

Steps in this tutorial to complete this customization:

• Before You Begin

• Step 1: Create the Custom Field, List, Record, and Form

• Step 2: Write the Script

• Step 3: Create the Script Record

• Step 4: Deploy the Script

• Step 5: Test the Solution

Note:

This tutorial best shows how a fieldChanged client script can work for various applications. You can also limit the number of items available on a transaction using a saved search and a custom transaction form. See Filtering the Items Dropdown List on Transactions.

Before You Begin

The following table lists features, permissions, and other requirements necessary for performing this tutorial and implementing the solution:

Required Features	The following features must be enabled in your account: Client SuiteScript – Lets you apply client scripts to records and forms. File Cabinet – Lets you store your script files in the NetSuite File Cabinet. A/R – Lets you create, edit and save invoices. For more information, see Enabling Features.
Required Permissions	You need a role with access to the following: Scripts – Edit access Script Deployments – Edit access Transaction Line Fields – Create access Transaction Forms – Create access Invoices – Create access For more information, see NetSuite Permissions Overview.
Other Requirements	None

Step 1: Create the Custom Field, List, Record, and Form

This customization uses a custom field called Billing Item to select an item by UPC code. This field displays as a column on transaction line items. For the custom field to find matching items, you'll create an item record with a matching UPC code.

This customization also uses a custom list called Billing Items, which provides values to the Billing Item field.

This customization also uses a custom invoice form so that users can use the custom field, list, and record. All standard forms in NetSuite remain the same. Every form you create from a standard form is a custom version of that form. For this tutorial, you'll customize the standard invoice form to add your new transaction line field as a column on the Items subtab.

To create the Billing Item transaction line field and Billing Items custom list:

1. Go to Customization > Lists, Records, Fields > Transaction Line Fields > New.

2. Enter or select values for fields as listed in the following table:

   Field	Value
   Label	Billing Item
   ID	_billingitem
   Description	This custom field is for the user to select an item that will be copied to the standard Item column.
   Type	List/Record
   List/Record	Select -New- to create a new list of UPC codes to choose from. For this tutorial, enter Billing Items in the Name field, and enter a single list value of 704875 in the Value field on the Values tab. To access this custom list later, go to Customization > Lists, Records, & Fields > Lists.
   Store Value	Checked
   Applies To Tab	Leave all values cleared. Checking boxes here adds the custom column to standard forms. For this tutorial, the field will be added to a custom form only.

3. Click Save.

To create the item record:

1. Go to Lists > Accounting > Items > New.

2. Select For Sale under Non-Inventory Item.

3. Enter or select values for fields as listed in the following table:

   Field	Value
   Item Name/Number	Bulk Shampoo
   UPC Code	704875, the code you entered for the Billing Item.

4. Click Save.

To customize the invoice form:

1. Go to Customization > Forms > Transaction Forms.

2. Click Customize next to Standard Product Invoice.

3. Enter or select values for fields as listed in the following table:

   Field	Value
   Name	Billing Item Invoice
   ID	_billingitem
   Form is Preferred	Check this box if you want this custom form to be the default invoice form for everyone. For this tutorial, you don't need to check this box.
   Sublist Fields tab > Billing Item	Your custom field, Billing Item, may be at the bottom of the list. Click the dot grid to the left of the field, and then move the field up to the top of the list, under the standard Item field. Note: Click the Show box to the right of the field name. If you don’t click the Show box, your custom field won't appear on your custom invoice form. This box isn't checked by default. Fields are listed top to bottom as they appear right to left on the invoice form.

4. Click Save.

For more information about creating custom fields, lists, and forms, see the following help topics:

• Creating a Custom Field

• Creating a Custom List

• Creating Custom Entry and Transaction Forms

• Creating Custom Transaction Line Fields

Step 2: Write the Script

This script copies the value from the custom Billing Item field to the standard Item field when you select or change the Billing Item field.

Script Summary

The following table summarizes the script:

Script: Copy Value to Item
Script Type	SuiteScript 2.x Client Script Type
Modules Used	N/currentRecord Module – This module is available to all scripts as a provided context object. You don't need to explicitly load this module as a dependency in your define or require statement, however, you may if you want. This tutorial does not explicitly load this module. N/search Module
Entry Points	fieldChanged(scriptContext)

For more information about script types and entry points, see SuiteScript 2.x Script Types.

The Complete Script

This tutorial includes the complete script along with individual steps you can follow to build the script in logical sections. The complete script is provided below so that you can copy it, paste it into your text editor, and save it as a .js file (for example, cs_copyValueToItem.js).

If you would rather create your script step by step, follow the steps in Build the Script.

Note:

This tutorial script uses the define function, which is required for an entry point script (a script you attach to a script record and deploy). If you want to copy the script into the SuiteScript Debugger and test it, you must use the require function. For more information, see SuiteScript Debugger.

Important:

This sample uses SuiteScript 2.1. For more information, see SuiteScript 2.1.

              /**
 * @NApiVersion 2.1
 * @NScriptType ClientScript
 * @NModuleScope SameAccount
 */

define(['N/search'], (search) => {
  function fieldChanged (context) {
    try {
      const recInvoice = context.currentRecord;
      const stCurrField = context.fieldId;
      const stCurrSublist = context.sublistId;
      // Get UPC code of billing item
      if (stCurrSublist === 'item' && stCurrField === 'custcol_billingitem') {
        const billingitem = recInvoice.getCurrentSublistText({
          sublistId: 'item',
          fieldId: 'custcol_billingitem'
        });
        // Search for Item with Billing Item's UPC code
        const itemSearch = search.create({
          type: 'noninventoryitem',
          filters: [
            ['upccode', 'is', billingitem]
          ],
          columns: [
            'upccode', 'itemid'
          ]
        }).run();
        // Set the UPC code text to the invoice
        const result = itemSearch.getRange(0, 1);
        const itemName = result[0].getValue(itemSearch.columns[1]);
        recInvoice.setCurrentSublistText({
          sublistId: 'item',
          fieldId: 'item',
          text: itemName
        });
      }
    } catch (e) {
      alert(e);
    }
  }
  return {
    fieldChanged: fieldChanged
  };
}); 

            

Build the Script

You can write the script using a step-by-step approach that includes the following:

• Start with required opening lines

• Create the entry point function

• Get the field and sublist that changed

• Create a search to find the Billing Item UPC Code

• Set the UPC Code Text to the Invoice

• Create the return statement

• Save your script file

Note:

The code snippets included below don't include indentation. Refer to The Complete Script for suggested formatting.

Start with required opening lines

You need a JSDoc comments and a define function at the top of the script file. The JSDoc comments in this script indicate that it's a SuiteScript 2.1 client script. The script doesn't use any SuiteScript modules except for the globally available N/currentRecord module, which you don't need to include in the define statement.

Start a new script file using any text editor and add the following JSDoc comments and define function at the top of the file:

Note:

This tutorial script uses the define function, which is required for an entry point script (a script you attach to a script record and deploy). If you want to copy the script into the SuiteScript Debugger and test it, you must use the require function. For more information, see SuiteScript Debugger.

                /**
 * @NApiVersion 2.1
 * @NScriptType ClientScript
 * @NModuleScope SameAccount
 */

define([], function() {
}); 

              

Create the entry point function

This script is triggered on the fieldChanged entry point when the value for the custom Billing Item line field on the Item subtab changes. A try-catch block logs errors that might occur when the script runs. Most of the script code goes in the try block.

Add the following function definition and initial try-catch block statements at the top of the define function:

                function fieldChanged(context) {
    try {
    } catch(e) {
        alert(e.name + ': ' + e.message);
    }
} 

              

Get the field and sublist that changed

You only need to set the standard Item line field when someone changes the custom Billing Item field. You need to get the current field and sublist IDs to determine which field was changed.

Add the following code into the try block:

                const recInvoice = context.currentRecord;
const stCurrField = context.fieldId;
const stCurrSublist = context.sublistId;
if (stCurrSublist === 'item' && stCurrField === 'custcol_billingitem') {
} 

              

Create a search to find the Billing Item UPC Code

Create and run a saved search to find the Billing Item by its UPC Code.

Add the following code into the try block:

                const itemSearch = search.create({
          type: 'noninventoryitem',
          filters: [
            ['upccode', 'is', billingitem]
          ],
          columns: [
            'upccode', 'itemid'
          ]
        }).run(); 

              

Set the UPC Code Text to the Invoice

Use the results from the saved search to set the UPC code text values on the invoice.

Add the following code in the if statement in the try block:

                const result = itemSearch.getRange(0, 1);
        const itemName = result[0].getValue(itemSearch.columns[1]);
        recInvoice.setCurrentSublistText({
          sublistId: 'item',
          fieldId: 'item',
          text: itemName
        }); 

              

Create the return statement

This script associates the fieldChanged function with the fieldChanged client entry point.

Add the following code immediately above the closing }); in your script:

                return {
    fieldChanged: fieldChanged
}; 

              

Save your script file

You need to save your script file so you can load it to the NetSuite File Cabinet. Before you save, you may want to adjust the indentation to improve the readability of the script. Refer to The Complete Script for suggested formatting.

When you are happy with your script, save it as a .js file (for example, cs_copyValueToItem.js).

Step 3: Create the Script Record

Now that you’ve completed the script, you can upload the file to the File Cabinet and create a script record for it.

For more information about creating script records, see Creating a Script Record.

To create the script record:

1. Upload your script to the NetSuite File Cabinet.

2. Go to Customization > Scripting > Scripts > New.

3. Select your script from the Script File list and click Create Script Record. The Script page is displayed.

4. On the Script page, enter the following values:

   Field	Value
   Name	Copy Value to Item
   ID	_cs_copy_value_to_item NetSuite prefixes the ID with customscript.
   Description	This script copies the value entered into a custom Billing Item field into the standard Item field.

5. Set any other fields on the script record as required.

6. Click Save and Deploy. The Script Deployment page appears. Continue with Step 4: Deploy the Script.

Step 4: Deploy the Script

After you create the script record, you can create a script deployment record for it. A script deployment record determines how, when, and for whom the script runs.

For more information about script deployment records, see Script Deployment.

To deploy the script:

1. Complete the steps in Step 3: Create the Script Record.

2. On the Script Deployment page, enter the following values:

   Field	Value
   Applies To	Invoice
   ID	_cs_copy_value_to_item NetSuite prefixes the ID with customdeploy.
   Status	Testing The Testing status lets the script owner test the script without affecting other users in the account.
   Log Level	Debug The Debug level writes all log.debug statements and errors to the Execution Log tab of the script deployment record.
   Audience > Roles	Check Select All

3. Click Save.

Step 5: Test the Solution

After you create the script record and deploy your script, you can test. Select a value in the custom Billing Item field (on your custom form) and verify that it is copied to the standard Item field.

To test your solution:

1. Go to Transactions > Sales > Create Invoices to create a new invoice.

2. In the Custom Form field, select your custom Billing Item Invoice form.

3. In the Customer field, select any customer to test with.

4. On the Items tab, in the Billing Item field, select 704875. The script copies 704875 to the standard Item field. Because 704875 is in the UPC Code field on the Bulk Shampoo item record, the system automatically selects Bulk Shampoo in the standard Item field.

Related Topics

• SuiteCloud Customization Tutorials
• Add Custom Button to Execute a Suitelet
• Calculate Commission on Sales Orders
• Disable Tax Fields
• Hide a Column in a Sublist
• Populate Item Substitution
• Set a Default Posting Period in a Custom Field
• Set Purchase Order Exchange Rate
• Set the Item Amount to Zero for Marketing Orders
• Set Default Values in a Sublist
• Track Customer Deposit Balances
• Validate Order on Entry

General Notices