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 and include 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 your NetSuite account, however, the item list is long and you want to allow these employees to select a UPC code rather than to have to scroll through a long list of item names. You can customize the invoice form used by these employees to disable the Item column and add a custom transaction line field where your employees can select billing items using the UPC code instead.

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 is best for demonstrating how a fieldChanged client script might 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 – This feature allows you to apply client scripts to records and forms. File Cabinet – This feature allows you to store your script files in the NetSuite File Cabinet. A/R - This feature allows you to create, edit and save invoices. For more information, see Enabling Features.
Required Permissions	You will 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. The Billing Item field is used to select an item by UPC code. This field displays as a column on the line items of transactions. And, for the custom field to find matching items, you will create an item record with a matching UPC code.

This customization also uses a custom list. The Billing Items list is used to source values to the Billing Item field.

This customization also uses a custom invoice form. This form will let users use the custom field, list, and record. All standard forms in NetSuite remain standard. Every form you create from the standard form is a custom version of that form. For this tutorial, you will 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; this is 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’d like this custom form to be the default invoice form for all users. In this tutorial, it is not necessary 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 to select the line for dragging and dropping, and 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 will not be displayed on your custom invoice form. This checkbox is not automatically checked. 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 stored in the custom Billing Item field to the standard Item field when the Billing Item field value is selected or changed.

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 do not 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 and paste it into your text editor and save the script as a .js file (for example, cs_copyValueToItem.js).

If you would rather create your script by adding code in logical sections, 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). You must use the require function if you want to copy the script into the SuiteScript Debugger and test it. 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 do not account for indentation. Refer to The Complete Script for suggested indentation.

Start with required opening lines

JSDoc comments and a define function are required at the top of the script file. The JSDoc comments in this script indicate that it is a SuiteScript 2.1 client script. The script does not use any SuiteScript modules other than the globally available N/currentRecord module which does not need to be included in the define statement.

Start a new script file using any text editor and place 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). You must use the require function if you want to copy the script into the SuiteScript Debugger and test it. 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 is changed. A try-catch block is used to log any errors that might occur during script execution. Most of the script code will be placed 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 the employee changes the custom Billing Item field. You need to get the current field and sublist ids to determine what field the employee changed.

Add the following code inside 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 help find the Billing Item by its UPC Code.

Add the following code inside 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 created to set the UPC code text values to the invoice.

Add the following code inside 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 your script file, you may want to adjust the indentation so that the script is readable. Refer to The Complete Script for suggested indentation.

When you are happy with how your script file reads, 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 script 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 prepends ‘customscript’ to this ID.
   Description	This script copies the value entered into a custom Billing Item field into the standard Item field.

5. Optionally set any other fields on the script record as desired.

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 for your script, 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 prepends 'customdeploy' to this ID.
   Status	Testing The Testing status allows the script owner to test the script without affecting other users in the account.
   Log Level	Debug The Debug level will write all log.debug statements in the script to the Execution Log tab of the script deployment record as well as all errors.
   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 your solution by selecting a value in the custom Billing Item field (on your custom form) and verifying that is gets 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 the value 704875 to the standard Item field. Because 704875 is the value entered 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