Disable Tax Fields

Note:

This customization is for accounts that use Legacy Tax, where SuiteTax feature is not enabled.

The script in this tutorial disables tax fields on U.S. sales transactions only. The script assumes that the Per Line Taxes on Transaction preference isn't enabled for U.S., and that the tax fields appear as transaction body fields on the Accounting subtab of the transaction record. For information about U.S. tax preferences, see Setting U.S. Tax Preferences.

This customization shows how to control who can edit tax fields on the following sales transactions: Cash Refund, Cash Sale, Credit Memo, Invoice, Sales Order, and Return Authorization.

Only users with the Administrator role and users with other specific roles have permission to edit tax fields. Sales transactions are created as usual, and taxes depend on how the customer and items are set up.

This customization uses a script parameter to determine which roles can edit tax fields. If the user is not logged in with an Administrator role or a role that is specified in the parameter, the script disables the tax fields. This occurs whether the sale is taxable or not.

The script in this tutorial disables the following tax fields for U.S. sales transactions:

Field Name	Field Type	Internal ID	Location
Taxable	Checkbox	istaxable	Accounting subtab > Tax information field group
Tax Item	Select	taxitem	Accounting subtab > Tax information field group
Tax Rate	Float	taxrate	Accounting subtab > Tax information field group

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.

Customization Details

The customization for this use case includes:

• A script parameter (Tax Allowlist) to specify which roles are allowed to modify the tax fields on the transaction record

• A client script triggered on the pageInit entry point

Steps in this tutorial to complete this customization:

• Before You Begin

• Step 1: Write the Script

• Step 2: Create the Script Record

• Step 3: Deploy the Script

• Step 4: Create and Set the Script Parameters

• Step 5: Test the Solution

Before You Begin

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

Required Features	Ensure the following features are 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. Multiple Currencies – Lets you select currencies on transactions and set exchange rates. For more information, see Enabling Features. Note: This tutorial deals with subsidiaries. You need a NetSuite OneWorld account, which automatically supports subsidiaries.
Required Permissions	You need a role with access to the following: Scripts – Edit access Script Deployments – Edit access Sales Orders – Edit access For more information, see NetSuite Permissions Overview.
Other Requirements	None

Step 1: Write the Script

This script checks a script parameter to determine if the user can edit tax fields on a U.S. sales transaction.

Script Summary

The following table summarizes the script:

Script: Disable Tax Fields
Script Type	SuiteScript 2.x Client Script Type
Modules Used	N/runtime Module 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 can if you want. This tutorial doesn't explicitly load this module. N/log Module – This module is available to all scripts as a global object. However, you should explicitly load this module to avoid conflicts with other objects that may be named ‘log’.
Entry Points	pageInit(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_disableTaxFields.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/runtime', 'N/log'], (runtime, log) => {
  function pageInit (scriptContext) {
    try {
      const objRecord = scriptContext.currentRecord;
      const stRecordType = objRecord.type;
      const stFuncName = '_DisableTaxField_' + stRecordType;
      if (scriptContext.mode !== 'copy') {
        const objContext = runtime.getCurrentScript();
        const stAllowList = objContext.getParameter({
          name: 'custscript_tax_allowlist'
        });
        const stUserRole = runtime.getCurrentUser().role;
        const arrExclusionRoleList = stAllowList.split(',');
        if (NSUtil.isEmpty(stAllowList)) {
          log.error({
            title: stFuncName,
            details: 'Script parameter is empty. Script will now exit'
          });
          return
        }
        const taxitem = objRecord.getField({
          fieldId: 'taxitem'
        });
        if (taxitem && !NSUtil.inArray(stUserRole, arrExclusionRoleList)) {
          const istaxable = objRecord.getField({
            fieldId: 'istaxable'
          });
          const taxrate = objRecord.getField({
            fieldId: 'taxrate'
          });
          istaxable.isDisabled = true;
          taxitem.isDisabled = true;
          taxrate.isDisabled = true;
        } 
      }
    } catch (error) {
      if (error !== undefined) {
        log.error({
          title: 'Process Error in pageInit',
          details: error
        });
        throw error;
      } 
    }
  }
  return {
    pageInit: pageInit
  };
});
const NSUtil = {
  isEmpty: function (stValue) {
    if ((stValue === '') || (stValue === null) || (stValue === undefined)) {
      return true;
    }
  },
  inArray: function (stValue, arrValue) {
    let bIsValueFound = false;
    for (let i = arrValue.length; i >= 0; i--) {
      if (stValue == arrValue[i]) {
        bIsValueFound = true
        break;
      }
    }
    return bIsValueFound;
  }
} 

            

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 functions

• Complete the pageInit function

• 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 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.x (2.0 or 2.1) client script. The script uses two SuiteScript modules specified in the define statement:

• N/runtime – provides access to runtime information, including script parameters

• N/log – lets you log execution details

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(['N/runtime', 'N/log'], (runtime, log) => {
}); 

              

Create the entry point functions

This script is triggered on the pageInit entry point when a sales transaction is created or edited. Sales transactions include cash refunds, cash sales, cash memos, invoices, sales orders, and return authorizations. A try-catch block logs any errors that might occur during script execution in the entry point function. Most of the script code goes in one of the try blocks.

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

                function pageInit(scriptContext) {
    try {
    } catch(error) {
        if (error !== undefined) {
            log.error({
                title: 'Process Error in pageInit,
                details: error
            });
            throw error;
        } 
    }
} 

              

Complete the pageInit function

Add the following code at the top of the try block of the pageInit function:

                const objRecord = scriptContext.currentRecord;
const stRecordType = objRecord.type;
const stFuncName = 'pageInit_DisableTaxFields_' + stRecordType; 

              

If the transaction is in create or edit mode, we want to get the script parameter and user role information.

Add the following code into the try block of the pageInit function:

                if (scriptContext.mode !== 'copy') {
   const objContext = runtime.getCurrentScript()
   const stAllowList = objContext.getParameter({
      name: 'custscript_tax_allowlist'
    });
   const stUserRole = runtime.getCurrentUser().role;
   const arrExclusionRoleList = stAllowList.split(','); 

              

If the script parameter allow list parameter is empty, we need to log an error.

Add the following code within the try block of the pageInit function:

                if (NSUtil.isEmpty(stAllowList)) {
    log.error({
       title: stFuncName,
       details: 'Script parameter is empty. Script will now exit'
     });
  return
} 

              

We'll disable fields according to the U.S. subsidiary of the customer on the transaction record. To do this, we'll check if the tax item field exists when a customer is selected. If the tax item field exists and the user role doesn't match the allow list parameter, we'll disable the Taxable, Tax Item, and Tax Rate fields.

Add the following code into the try block of the pageInit function:

                const taxitem = objRecord.getField({
   fieldId: 'taxitem'
});
if (taxitem && !NSUtil.inArray(stUserRole, arrExclusionRoleList)) {
    const istaxable = objRecord.getField({
       fieldId: 'istaxable'
    });
    const taxrate = objRecord.getField({
       fieldId: 'taxrate'
     });
     istaxable.isDisabled = true;
     taxitem.isDisabled = true;
     taxrate.isDisabled = true;
} 

              

The pageInit function should now be complete.

Create the return statement

This script associates the pageInit function to the pageInit entry point.

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

                return {
    pageInit: pageInit
}; 

              

Add the utility functions

A utility function checks the script parameters and compares them to the user’s role and the subsidiary of the transaction.

Add the following code at the end of your script following the end of the define function.

                const NSUtil = {
    isEmpty : function(stValue) {
        if ((stValue === '') || (stValue === null) || (stValue === undefined)) { 
            return true;
        } 
    },
    inArray : function(stValue, arrValue) {
        let bIsValueFound = false;
        for (let i = arrValue.length; i >= 0; i--) {
            if (stValue == arrValue[i]) {
                bIsValueFound = true;
                break;
            }
        }
        return bIsValueFound;
    }
} 

              

Save your script file

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

When you're happy with your script, save it as a .js file (for example, cs_disableTaxFields.js).

Step 2: Create the Script Record

Now that you’ve completed the script, you can upload it 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 appears.

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

   Field	Value
   Name	Disable Tax Fields
   ID	_cs_disable_tax_fields NetSuite prefixes the ID with customscript.
   Description	This script disables tax fields on a transaction record. It also ensures that only users with an Administrator role or one of the roles specified in the script parameter can edit tax fields.

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

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

Step 3: 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 this tutorial, we'll create multiple deployments, one for each of the following sales transactions:

• Cash Refund

• Cash Sale

• Credit Memo

• Invoice

• Sales Order

• Return Authorization

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

Cash Refund

Follow this procedure to deploy the script on cash refund transactions.

To deploy the script on cash refund transactions:

1. Go to Customization > Scripting > Scripts and click Deployments for the script record you created in Step 2: Create the Script Record).

2. Click New Deployment.

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

   Field	Value
   Applies To	Cash Refund
   ID	_cs_disable_tax_fields_cr NetSuite prefixes the ID with custdeploy.
   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 subtab of the script deployment record.
   Audience > Internal Roles	Check Select All
   Audience > External Roles	Select all external roles.

4. Click Save.

Cash Sale

Follow this procedure to deploy the script on cash sale transactions.

To deploy the script on cash sale transactions:

1. Go to Customization > Scripting > Scripts and click Deployments for the script record you created in Step 2: Create the Script Record).

2. Click New Deployment.

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

   Field	Value
   Applies To	Cash Sale
   ID	_cs_disable_tax_fields_cs NetSuite prefixes the ID with custdeploy.
   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 subtab of the script deployment record.
   Audience > Internal Roles	Check Select All
   Audience > External Roles	Select all external roles.

4. Click Save.

Credit Memo

Follow this procedure to deploy the script on credit memo transactions.

To deploy the script on credit memo transactions:

1. Go to Customization > Scripting > Scripts and click Deployments for the script record you created in Step 2: Create the Script Record).

2. Click New Deployment.

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

   Field	Value
   Applies To	Credit Memo
   ID	_cs_disable_tax_fields_cm NetSuite prefixes the ID with custdeploy.
   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 in the script to the Execution Log subtab of the script deployment record.
   Audience > Internal Roles	Check Select All
   Audience > External Roles	Select all external roles.

4. Click Save.

Invoice

Follow this procedure to deploy the script on invoice transactions.

To deploy the script on invoice transactions:

1. Go to Customization > Scripting > Scripts and click Deployments for the script record you created in Step 2: Create the Script Record).

2. Click New Deployment.

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

   Field	Value
   Applies To	Invoice
   ID	_cs_disable_tax_fields_in NetSuite prefixes the ID with custdeploy.
   Status	Testing The Testing status let 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 subtab of the script deployment record.
   Audience > Internal Roles	Check Select All
   Audience > External Roles	Select all external roles.

4. Click Save.

Sales Order

Follow this procedure to deploy the script on sales order transactions.

To deploy the script on sales order transactions:

1. Go to Customization > Scripting > Scripts and click Deployments for the script record you created in Step 2: Create the Script Record).

2. Click New Deployment.

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

   Field	Value
   Applies To	Sales Order
   ID	_cs_disable_tax_fields_so NetSuite prefixes the ID with custdeploy.
   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 subtab of the script deployment record.
   Audience > Internal Roles	Check Select All
   Audience > External Roles	Select all external roles.

4. Click Save.

Return Authorization

Follow this procedure to deploy the script on return authorization transactions.

To deploy the script on return authorization transactions:

1. Go to Customization > Scripting > Scripts and click Deployments for the script record you created in Step 2: Create the Script Record).

2. Click New Deployment.

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

   Field	Value
   Applies To	Return Authorization
   ID	_cs_disable_tax_fields_ra NetSuite prefixes the ID with custdeploy.
   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 subtab of the script deployment record.
   Audience > Internal Roles	Check Select All
   Audience > External Roles	Select all external roles.

4. Click Save.

To verify that you have six deployments:

1. Go to Customization > Scripting > Scripts and click Deployments for the script record you created in Step 2: Create the Script Record).

2. Verify all six script deployments are listed:

   • custdeploy_cs_disable_tax_fields_cr

   • custdeploy_cs_disable_tax_fields_cs

   • custdeploy_cs_disable_tax_fields_cm

   • custdeploy_cs_disable_tax_fields_in

   • custdeploy_cs_disable_tax_fields_so

   • custdeploy_cs_disable_tax_fields_ra

Step 4: Create and Set the Script Parameters

This script uses a script parameter to specify which roles can edit tax fields on a transaction record.

For more information about creating and setting script parameters, see Creating Script Parameters (Custom Fields).

To create the script parameters:

1. Go to Customization > Scripting > Scripts.

2. Find your script in the list and click Edit next to the script name.

3. On the Script page, click the Parameters subtab and click New Parameter. The Script Field page appears.

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

   Label	ID	Type	Description	Preference
   Tax Allowlist	_tax_allowlist NetSuite prefixes the ID with custscript, so the script uses custscript_tax_allowlist.	Free-Form Text	This parameter determines which roles can edit tax fields on sales transactions.	Leave blank.

5. To save the script record with the updated script parameter, click Save.

After you create the script parameters, you must set the value for each parameter on each script deployment record you created in Step 3.

To set the script parameter:

1. Go to Customization > Scripts > Script Deployments.

2. For each script deployment:

   1. Click Edit next to the deployment ID.

   2. Click the Parameters subtab.

   3. Enter the value for the script parameter on each script deployment record:

      Deployment Record	Tax Allowlist script parameter
      custdeploy_cs_disable_tax_fields_cr	3 (this is the internal ID of the Administrator role) Add the internal IDs of other roles that can edit tax fields on sales transactions. Separate each ID with a comma, for example, 3,1,1001
      custdeploy _cs_disable_tax_fields_cs
      custdeploy _cs_disable_tax_fields_cm
      custdeploy _cs_disable_tax_fields_in
      custdeploy _cs_disable_tax_fields_so
      custdeploy _cs_disable_tax_fields_ra

3. Click Save. Repeat these steps for each script deployment record.

For more information about creating script parameters, see Creating Script Parameters (Custom Fields).

Step 5: Test the Solution

After you create the script record and deploy your script, you can test it for two main cases:

• Create a sales transaction with a role that's allowed to edit tax fields

• Create a sales transaction with any other role that has Edit access to sales transactions

To test the solution for a role that is allowed to edit tax fields:

1. Log in with a role specified in the script parameter.

2. Go to Transaction > Sales > Enter Sales Orders to create a new sales order.

3. In the Customer field, select a U.S. customer.

4. On the Items subtab, select an item.

5. On the Accounting subtab, ensure that the following tax fields are editable and set values for these fields:

   • Taxable

   • Tax Item

   • Tax Rate

6. Click Save.

7. Edit the sales order that you created in the previous step. Verify that the tax fields are still editable in edit mode.

To test the solution for a role that is not allowed to edit tax fields:

1. Log in with a role that isn't specified in the script parameter. Make sure that the role has permission to edit sales transactions.

2. Go to Transaction > Sales > Enter Sales Orders to create a new sales order.

3. In the Customer field, select a U.S. customer.

4. On the Items subtab, select an item.

5. On the Accounting subtab, ensure that the following tax fields aren't editable:

   • Taxable

   • Tax Item

   • Tax Rate

6. If the subsidiary or customer has default tax values set up, you should be able to save the sales order. Click Save.

7. Edit the sales order that you created in the previous step. Verify that tax fields are still editable in edit mode.

Related Topics

• SuiteCloud Customization Tutorials
• Add Custom Button to Execute a Suitelet
• Calculate Commission on Sales Orders
• Copy a Value to the Item Column
• 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