Client SuiteScript Developer s Guide

Transcription

1 Client SuiteScript Developer s Guide

2 Copyright NetSuite, Inc All rights reserved. January 18, 2007 This document is the property of NetSuite, Inc., and may not be reproduced in whole or in part without prior written approval of NetSuite, Inc. Trademarks NetSuite, NetERP and NetCRM are provided by NetSuite, Inc, and NetSuite is a trademark of NetSuite, Inc. Oracle is a registered trademark of Oracle Corporation. Other product names mentioned in this document may be trademarks, servicemarks, or tradenames of their respective companies and are hereby acknowledged.

3 Contents Chapter 1 Welcome In This Guide Roles & Permissions Chapter 2 Using Client SuiteScript General Guidelines Getting Started Enabling the Client SuiteScript Feature and Preferences Field Names (IDs) Attaching Client SuiteScripts to Forms Functions PageInit SaveRecord PostSourcing ValidateField FieldChanged Client SuiteScript API Using the Fire Field Changed Parameter Working with Line Items Chapter 3 Client SuiteScript Tutorial Customizing the Page Load Setup Create the Code Test the Code Validating Field Values Setup Create the Code Test the Code More Validation Triggering Events when a Field is Changed Setup Create the Code Test the Code Validating a Line Item Setup Create the Code Test the Code

4 Recalculating Field Totals Setup Create the Code Test the Code Prompting before Save Create the Code Test the Code Chapter 4 Code Names Code Names by Record Type Case Record Contact Record Customer Record Employee Record Event Record Partner Record Task Record Vendor Record Opportunity Record Code Names by Field Type Entity Fields CRM Fields Item Fields Transaction Fields Appendix: Tutorial Code

5 Chapter 1 Welcome In This Guide Welcome to NetSuite s Client SuiteScript feature. With Client SuiteScript you can write custom JavaScript code that performs validations and calculations on forms. You can use custom code in combination with custom fields, forms and records to completely tailor your business management system to your individual business needs. The purpose of this guide is to introduce you to NetSuite Client SuiteScript tools. It provides step-by-step instructions on how to create and implement Client SuiteScript for your forms as well as real-world examples for how companies use custom code to customize NetSuite accounts for their businesses. Client SuiteScript requires an understanding of JavaScript code and is intended to be used by customers with some advanced programming knowledge only. Note: When using Client SuiteScript, you will need to create custom fields, forms and records. For more information on the complete customization features available in your NetSuite account, refer to the Customization Guide. This guide contains the following chapters: Chapter 1 "Welcome": provides an overview of this guide. Describes which roles in your company can access Client SuiteScript. Chapter 2 "Using Client SuiteScript": introduces Client SuiteScript and its uses. Provides instructions for turning the feature on. Describes each function and possible API call that can be invoked. Chapter 3 "Client SuiteScript Tutorial": provides a detailed example of how to use Client SuiteScript to control the behavior of item discounts in a custom Cash Sale Transaction Form. Chapter 4 "Code Names": provides tables that detail standard field names that can be used in Client SuiteScript. "Appendix: Tutorial Code": provides the complete code for the example use case created in Chapter 3 "Client SuiteScript Tutorial". Roles & Permissions NetSuite provides many standard roles with predefined permissions. A role is a set of permissions that lets customers, vendors, partners and employees access specific areas of your data. Each role grants access at a certain level for each permission. Access to the Client SuiteScript feature is also controlled using roles and permissions. There are seven standard roles that have access to custom code as outlined in the following table. Refer to this table when assigning employees and vendors the task of implementing Client SuiteScript for the part of NetSuite they or their teams work with.

6 Welcome Roles & Permissions 2 Note: Depending on the product you subscribe to, all of these roles may NOT be available for you to use. Also, in addition to the following standard roles there may be custom roles created with Client SuiteScript permissions assigned to them. To create a custom role, an administrator must go to Setup > Users/Roles > Manage Roles. When customizing a role to add Client SuiteScript capabilities, you must also add permission for customizing entry forms and transaction forms. Roles Administrator Full Access Marketing Manager Marketing Administrator Sales Manager Sales Administrator Support Administrator Access Level FULL FULL FULL FULL FULL FULL FULL

7 Chapter 2 Using Client SuiteScript This section describes the event functions that can be modified and the API calls that can be used in Client SuiteScripts. These scripts are supported across NetSuite versions as long as the procedures and guidelines provided in this guide are adhered to. Note: NetSuite Client SuiteScript does NOT support JavaScript code using the Document Object Model (DOM) to interact with the objects on the web page. Currently, you can provide custom JavaScript functions to handle the following events: Initializing forms Entering or changing a value in a field (before and after it is entered) Entering or changing a value in a field that sources another field Selecting a line item Adding a line item (before and after it is entered) Saving a form Searching for another record Loading, saving or deleting a record Sending an If desired, functions that save or validate events can abort the action. General Guidelines Following are some general guidelines to follow when working with NetSuite Client SuiteScript. Important: During testing of Client SuiteScript, use Ctrl-Refresh to clear your cache and ensure that the latest scripts are being executed. Always thoroughly test your code before using on your live NetSuite data. If the same code is being used across multiple forms, ensure that you test any changes in the code for each form that the code is associated with. Ensure that you test your code for the roles that will be using the forms that the code is associated with. Keep in mind that form definitions may change for different roles such that certain fields may become available or unavailable for certain roles. Wherever data may be inconsistent, not available, or invalid for certain functions, ensure that you include proper error handling sequences in your script. For example, if your script requires a field value in order to validate another, ensure that the field value is available.

8 Using Client SuiteScript Getting Started 4 Getting Started Organize your code into reusable chunks. Many functions can be used in a variety of forms. Any reusable functions should be stored in a common library file and then called into specific event functions for the required forms as needed. Since name values can be changed, ensure that you use static ID values in your API calls where applicable. Although you can use any desired naming conventions for functions within your code, it is recommended that the top level functions include an indication of the corresponding NetSuite function. For example, if you are creating a Page Init function, you could name the function pageinit or formapageinit. If your code is already established, you could simply wrap it with a top level function that has the appropriate naming convention. As with any script, ensure that you thoroughly comment your code. This will not only help with debugging and development but will assist NetSuite support in locating problems if necessary. Before describing the nuances of creating javascript files for use with your NetSuite forms, review the information provided in this section so that you understand how the code will be implemented. Enabling the Client SuiteScript Feature and Preferences Before beginning with Client SuiteScript, you should enable the Client SuiteScript feature and enable the preference that causes NetSuite to display internal IDs. Enabling the Client SuiteScript Feature: Go to Setup > Company > Enable Features and check Client SuiteScript on the General tab. Once enabled, the Client SuiteScript feature provides a new folder in the file cabinet at Documents > Files > SuiteScripts. A custom code tab is also available in custom entry and transaction forms. Here you can define which scripts to associated with the current form. Displaying Internal IDs (nskeys): Go to Home > Set Preferences and check Show Internal IDs. When Show Internal IDs is checked, the internalid values for records are displayed in the Internal ID column of record lists. When referencing records in your custom code, always use the internal ID values since the internal IDs are constant but the records themselves may be renamed. For example, to determine if a selection in a drop down is specific value, without worrying if that value has been renamed, refer to the internal ID of the record not the text name. Note: The internal ID of a record and a field ID are two different things. Field IDs must be used when calling a field from any custom code API. Field IDs are displayed in the ID column of any lists of fields such as at Setup > Customization > CRM Fields. Record internal IDs are unique IDs associated with a record at creation time. Internal ID values should be used when referencing a specific field value.

9 Using Client SuiteScript Getting Started 5 Field Names (IDs) Field names (or IDs) must be used when calling a field from any SuiteScript API. Standard field names are provide in Chapter 4 "Code Names". Custom Field IDs are displayed in the ID column of any lists of fields. For example, to obtain the field ID for a specific custom CRM field, go to Setup > Customization > CRM Fields. Note: When creating custom fields, the custom field ID can be specified or you can accept the default ID assigned by NetSuite. To ensure that the field IDs make sense in the context of your business environment, it is recommended that you always define your own custom field IDs. This will also help to make your custom code more readable. For detailed information on creating custom fields and assigning custom field IDs refer to the Customization User Guide. Attaching Client SuiteScripts to Forms After you have created your Client SuiteScript scripts, you need to make the scripts available for custom forms and define which forms will use which functions. Important: SuiteScripts must have a.js extension. To attach your script files to a custom form: 1. Upload your scripts to your NetSuite file cabinet. Click Documents > Files > SuiteScripts, navigate to your script file, and click attach. Note: The SuiteScripts folder is provided for convenience; you can store the script files in any location. 2. Go to the desired custom form. Client SuiteScript can only be attached to custom Entry or Transaction forms. Click Setup > Customization > [Form]. Then click edit next to the desire custom form or click Customize next to an existing standard form in order to create a new custom form based on it. Note: For detailed information on creating custom forms, refer to the Customization User Guide.

10 Using Client SuiteScript Functions 6 3. In the custom code tab, select the script file and library script file to associate to the current form. The library script file should contain any commonly used functions whereas the script file should contain functions specific to the current form. 4. Enter the exact name of your function that correlates to each NetSuite function. When a Client SuiteScript script is called for a form function, the actions defined within the SuiteScript file, as well as any NetSuite actions, are performed for the given function. For example, if your form calls a custom PageInit function, the actions defined by that script, as well as any predefined NetSuite actions, are performed prior to the page loading. Functions NetSuite provides several standard functions that are automatically triggered with certain events as outlined in the following table. Function Parameters Returns Description PageInit Called when the page is first loaded. SaveRecord Boolean Called when the user requests the form to be saved. Returns false to reject the operation. ValidateField* line item type: String; field name: String Boolean Called when the user changes the value of a field. Returns false to reject the value. This script does NOT apply to dropdown select or check box fields. FieldChanged* line item type: String; field name: String Called when a new value for a field is accepted. PostSourcing type: String field name: String Called on the FieldChanged event after all slaved fields source. Line Init line item type: String Called when an existing line is selected in the item machine. The string value returned is always item.

11 Using Client SuiteScript Functions 7 Function Parameters Returns Description Validate Line line item type: String Boolean Called when a user requests the addition or edit of a line item. Returns false to reject the operation. Recalc line item type: String Called when a new or edited line has been accepted. *The ValidateField and FieldChanged scripts require a null line item for body form fields. PageInit The PageInit function is called when the form is first loaded. Some functions that can be performed on PageInit include the following: Populate field defaults Disable or enable fields Change field availability or values depending on the data available for the record Add flags to set initial values of fields Provide alerts where the data being loaded is inconsistent or corrupt Retrieve user login information and change field availability or values accordingly Validate that fields required for your custom code (but not necessarily required for the form) exist Examples Set Default Field Values for a Field function pageinit() // is fielda is either NULL or equal to "valuea" if ((nlapigetfieldvalue('fielda').length == 0) (nlapigetfieldtext('fielda') == "valuea")) // then set fielda to valueb nlapisetfieldtext('fielda', nlapigetfieldtext('valueb')); Disable a Field function pageinit() // On init, disable two optional Other fields: fielda and fieldb. nlapidisablefield('custrecord_other_fielda', true); nlapidisablefield('custrecord_other_fieldb', true); Display User Profile Information function pageinit() // On page init display the currently logged in User's profile information. // Set variables var username = nlapigetuser(); // entity id of the current user var userrole = nlapigetrole(); // id of the current user's role var userdept = nlapigetdepartment(); // id of the current user's department var userloc = nlapigetlocation(); // id of the current user's location

12 Using Client SuiteScript Functions 8 // Display information alert("current User Information" + "\n\n" + "Name: " + username + "\n" + "Role: " + userrole + "\n" + "Dept: " + userdept + "\n" + "Loc: " + userloc ); SaveRecord The SaveRecord function is called when the user requests the form to be saved. Returns false to reject the operation. Use the Save function to provide alerts to the user before committing the data. If it is necessary for the user to make changes before comitting the data, return false otherwise display the alert, return true and allow the user to commit the data. You can also use the SaveRecord function to: Enable fields that were disabled with other functions Redirect the user to a specified url Examples Requesting Additional Information function SaveRecord() // Check to see that fielda is populated. If not, block the save and warn with a popup. if (String(nlapiGetFieldValue('fieldA')).length == 0) alert("please provide a value for fielda"); return false; alert("are you sure you want to Save the record?"); return true; Redirect the User to Another Location function saverecord(type,name) window.open(' string]');void(0) return true;

13 Using Client SuiteScript Functions 9 PostSourcing (Transaction Forms Only) The PostSourcing function is called when a field is modified that sources information from another field. Event handlers for this function behave similar to event handlers for the Change Field function except that the function is called only after all sourcing is completed it waits for any slaved or cascaded field changes to complete before calling the user defined function. Therefore, the event handler is not triggered by field changes for a field that does not have any slaved fields. If there is at least one field sourced from a drop down (either a built-in sourcing or one created through customization) the post sourcing event is fired. Therefore, if you need to do something based on sourced values, you should do it in PostSourcing rather than from Field Changed. ValidateField The ValidateField function is called whenever the user changes the value of a field. This function returns false to reject the value. Note: This script does NOT apply to dropdown select or check box fields. Use the ValidateField function to validate field lengths, restrict field entries to a predefined format, restrict submitted values to a specified range, validate the submission against entries made in an associated field, Examples Validate Field Lengths function ValidateField(type, name) // if fielda is not greater than 5 characters, fail validation if (name == 'fielda') var fieldalength = String(nlapiGetFieldValue('fieldA')).length; if (fieldalength <= 6) alert("fielda must be at least 6 characters."); return false; // Always return true at this level, to continue validating other fields return true;

14 Using Client SuiteScript Client SuiteScript API 10 FieldChanged The FieldChanged function is called when a new value for a field is accepted. Use the FieldChanged function to provide the user with additional information based on user input, disable or enable fields based on user input. Examples Requesting Additional Information function FieldChanged(type, name) // Prompt for additional information, based on values already selected. if (name == 'fielda') && (nlapigetfieldtext('fielda') == "Other") alert("please provide additional information about fielda in the text field below."); Client SuiteScript API This section describes the API calls that your Client SuiteScript can invoke to retrieve and modify information on forms. These API calls can only be invoked when an event triggers the custom code functions that have been assigned to the current form. Each call acts on standard or custom fields defined for the current form. For a complete list of standard fields available on standard NetSuite forms, see Code Names on page 27. NetSuite is committed to maintaining these field names across versions. In rare cases where field names must be changed, the name changes will be documented in the release notes for that version of the software. Important: You can NOT modify the values of the following standard fields with Client SuiteScript. Amount Applied Unapplied Total Exchange Rate Shipping Cost Last Modified Date Creation Date Return on Investment Opening Balance

15 Using Client SuiteScript Client SuiteScript API 11 Function Parameters Description nlapigetfieldvalue field name: String Retrieves the value of the given field. nlapisetfieldvalue field name: String; value: String; firefieldchanged: Boolean Sets the value of the given field. See also Using the Fire Field Changed Parameter on page 13 nlapigetcurrentlineitemvalue nlapisetcurrentlineitemvalue nlapigetlineitemvalue nlapisetlineitemvalue line item type: String; field name: String line item type: String; field name: String; value: String firefieldchanged: Boolean line item type: String; field name: String; line index: Integer line item type: String; field name: String; line index: Integer; value: String Retrieves the value of the given line-item field before it has been added to the form. Typically used in validate line functions. Sets the value of the given line-item field before it has been added to the form. Typically used in validate line functions. See also Using the Fire Field Changed Parameter on page 13 Retrieves the value of the given field on the line item at the given index. Note: You cannot set default line item values when the line is not in edit mode. Sets the value of the given field on the line item at the given index. Currently, you can use this only to write to description or custom fields. To write to other fields, use the method described at Example: Adding Line Items to a Transaction on page 14. nlapigetcurrentlineitemindex line item type: String Retrieves the current index of the line being added or edited. If adding, the function should nlapigetlineitemcount(type)+1. nlapigetlineitemcount line item type: String Retrieves the total number of line items for the given type. nlapiformatcurrency amount: Float Formats a floating point value according to the prevailing currency conventions. nlapistringtodate string: Date Converts a JavaScript string to a Date according to date formatting conventions. nlapidatetostring date: Date Converts a JavaScript Date to a string according to date formatting conventions. nlapiadddays date: Date; days: Integer Adds a set number of days to a JavaScript date, returning the modified object. nlapiaddmonths date: Date; months: Integer Adds a set number of months to a JavaScript date, returning the modified object. nlapigetfieldtext field name: String Gets the text value of the given selection field. Important: nlapigetfieldtext can NOT be used on hidden fields.

16 Using Client SuiteScript Client SuiteScript API 12 Function Parameters Description nlapigetcurrentlineitemtext nlapigetlineitemtext nlapisetfieldtext nlapisetcurrentlineitemtext nlapidisablefield nlapidisablelineitemfield line item type: String; field name: String firefieldchanged: Boolean line item type: String; field name: String; line index: Integer field name: String; text value: String firefieldchanged: Boolean line item type: String; field name: String; text value: String field name: String; value: Boolean line item type: String; field name: String; value: Boolean Gets the text value of the given line-item selection field in the form before it has been added. Typically used in validate line functions. See also Using the Fire Field Changed Parameter on page 13 Gets the text value of the given selection field on the line item at the given index. Sets the value of the given selection field to the value with the given text. See also Using the Fire Field Changed Parameter on page 13 Sets the value of the given line-item selection field to the value with the given text. Sets the given field to disabled or enabled based on the value (true or false). Sets the given line item field of the given type to disabled or enabled based on the value (true or false). nlapiencrypt Clear Text: String Returns an encrypted string for the given input string. nlapigetuser N/A Returns the entity ID of the current user. nlapigetrole N/A Returns the ID of the current user s role. nlapigetdepartment N/A Returns the ID of the current user s department. nlapigetlocation N/A Returns the ID of the current user s location. nlapiselectlineitem line item type: String line item number: String Selects an existing line number of a machine. Line number must be between 1 and nlapigetlineitemcount. nlapicommitlineitem line item type: String Commits the current line of a machine type. This is the equivalent of clicking Done for a line item in the UI. nlapiinsertlineitem line item type: String Inserts a line above the current line of machine. nlapiremovelineitem line item type: String Removes the current line of a machine. nlapicancellineitem line item type: String Cancels any edits to the current line of a machine and reselects the line. nlapiselectnewlineitem line item type: String Synonym for nlapicancellineitem. nlapiislineitemchanged line item type: String Returns true if the currently selected line of machine has been edited. nlapiloadrecord type: record type id: internalid Loads an existing record.

17 Using Client SuiteScript Client SuiteScript API 13 Function Parameters Description nlapisaverecord type: record type Saves the current record. id: internalid nlapicreaterecord type: record type Creates a new record instance. nlapisearchrecord nlapideleterecord nlapisend Using the Fire Field Changed Parameter When creating scripts that provide the ability to watch a field for a change, and then write back to the field that just changed, a risk of creating a unending loop exists as follows: 1. The Client SuiteScript code watches for fielda to change. 2. fielda changes. 3. The Client SuiteScript writes to fielda, causing the Field Changed event to fire, returning the code to step 2, and this loop repeats indefinitely. To prevent this looping behavior, you can set the optional firefieldchanged parameter in your custom code. The firefieldchanged parameter is available for all write functions. If set to True, the parameter causes any field changed events to fire as normal. This is the default setting. If set to False, field changed events are NOT fired. Using the new parameter, we can modify the above example to: 1. Custom code watches for fielda to change. 2. fielda changes. type: record type searchid: saved search ID type: record type id: internalid author: author internalid (must be an employee record) recipient: recipient internalid subject: subject body: body copy[ ] : array of s to copy blindcopy[ ]: array of s to blind copy 3. Client SuiteScript writes to fielda using firefieldchanged = false, so the Field Changed event does not fire. The following API calls can set the firefieldchanged parameter. Allows you to search for other records in the system. Permanently deletes a record from the database. Generates and sends an .

18 Using Client SuiteScript Client SuiteScript API 14 Note: The set line item text and value functions are NOT affected, as these do not currently call field changed after firing. nlapisetfieldvalue(field, value, firefieldchanged) nlapisetfieldtext(field, text, firefieldchanged) nlapisetcurrentlineitemvalue(type, field, value, firefieldchanged) nlapisetcurrentlineitemtext(type, field, text, firefieldchanged) Note: The firefieldchanged parameter is provided for convenience. To prevent this loop, you could also include code that either checks to ensure that you are not writing the same value to the field or that tracks whether you just wrote to the field. Working with Line Items NetSuite provides several functions that can be used to manipulate line items in a machine. You can use these functions to update multiple line items in a machine when a body field is changed or to automate the population of item machine fields when certain conditions exit in the form. Line item functions include: nlapiselectlineitem nlapicommitlineitem nlapiinsertlineitem nlapiremovelineitem nlapicancellineitem nlapiselectnewlineitem nlapiislineitemchanged Important: Once the code associated with a line item function is initiated, mouse events will NOT be responded to until the code is complete. This includes extended delays such as when an alert or prompt is thrown while the line is being manipulated by the code. Example: Adding Line Items to a Transaction In order to add a line item to a transaction using custom code, you need to insert the line item and then commit the item in the same script. If you set the item field via nlapisetcurrentlineitemvalue, you can't call nlapicommitlineitem until the server call for the item information has completed. The only way to know that the server call is complete is to create a postsourcing function that sets a flag. For example, suppose that you want to insert a shipping line when a user clicks a button. You could attach a function such as insertshippingrate() to that button, which adds an item named Shipping, sets its rate, and then commits the line. function insertshippingrate() nlapiselectnewlineitem('item'); /* important so that we know that we were called from insertshippingrate(). */ nlapisetcurrentlineitemvalue('item', 'custcolinsertshippingrate', 'T'); nlapisetcurrentlineitemtext('item', 'item', 'Shipping');

19 Using Client SuiteScript Client SuiteScript API 15 function dopostsourcing(type, fldname) if ( type == 'item' && fldname == 'item' && nlapigetcurrentlineitemvalue ('item', 'custcolinsertshippingrate') == 'T' ) nlapisetcurrentlineitemvalue('item', 'custcolinsertshippingrate', 'F'); nlapisetcurrentlineitemvalue('item', 'rate', '7.50'); nlapicommitlineitem('item');

20 Chapter 3 Client SuiteScript Tutorial This tutorial provides a detailed example of how to use Client SuiteScript to control the behavior of item discounts in a custom Cash Sale Transaction Form. It is intended for use with NetSuite s sample company, Wolfe Electronics. You can access Wolfe Electronics by signing up for a Test Drive on the NetSuite Web Site. However, instructions are included to implement the example in an account without Wolfe Electronics data if you wish. We will start by describing the code to be used when the page first loads, then move on to field changed, validation and page save code. For each section, you may need to create custom elements as described in the Setup sections. If you are familiar with creating custom items, lists and fields, simply refer to the table provided for the required parameters for each element. Otherwise, refer to the Customization User Guide or the online help for detailed instructions. These fields must exist in your NetSuite account prior to using this example. If the items and fields do not exist, you will receive an error when attempting to use your custom cash sale. Note: Before beginning this tutorial, ensure that you have enabled the Client SuiteScript feature as described in Enabling the Client SuiteScript Feature and Preferences on page 4. Customizing the Page Load In the Page Init example, we will cause a 5% transaction discount to be automatically applied to the cash sale price of an item whenever our custom Cash Sale Transaction form is loaded. Setup Before creating a script that applies a discount, we must first create a discount item in NetSuite and then use this discount item in our custom code. Element Parameters Purpose Discount Item Item Name/Number: In-store Discount Income Account: 4000 Sales Rate: 5% Apply Before Sales Tax: No Create the Code Next we will create a javascript file called customcashsales.js and enter the following code. This code sets the discount item field to the value created in Setup. function samplepageinit() nlapisetfieldvalue('discountitem', 144); Defines the discount item that you will refer to in your custom code. To create, go to Lists > Accounting > Items > New > Discount.

21 Client SuiteScript Tutorial Customizing the Page Load refers to the nskey value of In-Store Discount item created in the preceeding section. You can determine the discount item ID by navigating to the item, and inspecting the id= parameter of the URL or, if you have enabled the display of Internal IDs, the value is displayed in the nskey column. Test the Code Next we will upload the javascript file to NetSuite and apply the code to our custom Cash Sale Transaction form. To upload the javascript file to NetSuite: 1. Go to Documents > Files > File Cabinet. 2. Select the folder you want to add your file to. 3. At the bottom of the page, select Computer in the Attach From field. 4. Click Browse next to the File field and select the customcashsale.js file you just created. 5. Click Add This File. To apply the custom code to a transaction form: 1. Go to Setup > Customization > Transaction Forms. 2. Click Customize next to Standard Cash Sale. 3. In the Name field, enter Custom Code Sample. Leave all standard settings the same. 4. Click the Custom Code subtab. 5. In the Script File field, browse to the customcashsale.js file you uploaded to your file cabinet.

22 Client SuiteScript Tutorial Validating Field Values In the Page Init Function field, enter samplepageinit. 7. Click Save. You can now go to Transactions > Sales > Enter Cash Sales to test your custom code. Select the Custom Code Sample form in the Custom Form field on the Cash Sale page. Notice that the Discount is automatically set to In-Store Discount with the rate at -5%. This cash sale will have the 5% discount applied to it. Validating Field Values Of course, in some cases, there may be customer discounts already assigned for certain customers, in which case we wouldn t want to automatically assign the lower 5% discount we will want to consider the customer discount instead. In this section we will create a validation script to ensure that this is the behavior. Setup Before creating our code, we will need to setup several customers with custom discounts. The following table lists all of the elements you will need to create in order to do this.

23 Client SuiteScript Tutorial Validating Field Values 19 Element Parameters Purpose 5 Discount Items Item Name/Number: 10%* Income Account: 4000 Sales Rate: 10%* Apply Before Sales Tax: No Defines the discount items that you will be able to set for any customers. To create, go to Lists > Accounting > Items > New > Discount. Custom List Entity Field Transaction Body Field Customer Records And four additional discount items with the Item Name/Number and Rate fields to 15%, 20%, 25% and 30% respectively Name: Customer Discounts Values: 10%, 15%, 20%, 25%, 30% Description: Customer Discount ID: _customer_discount Type: List/Record List/Record: Customer Discounts Applies To: Customer:Job Subtab: General Description: Cust. Discount ID: _cust_discount Type: List/Record List/Record: Customer Discounts Applies To: Sale Subtab: Main Display Type: Disabled Source LIst: Entity Source From: Customer Discount Set a discount to various customers. Defines the selection list of discount items. To create, go to Setup > Customization > Lists > New. Sources the list just created. To create, go to Setup > Customization > Entity Fields > New. To create, go to Setup > Customization > Transaction Body Fields > New. Create the Code In this section we will add the validation code to the customcashsales.js file created for the Page Init function. Note: When applying custom code, you can select up to two javascript files to associate with a given custom form. One file should contain all of the code specific to the current form. The other, library file, should contain any code that may be used across multiple forms. For the purposes of this tutorial, we will include all of the custom code in a single file customcashsales.js. Retrieving the Customer Discount First, we ll need to create a function that determines whether a customer discount rate has been set. The following code uses nlapigetfieldtext to retrieve the value of the custom transaction body field we created custbody_cust_discount. If it exists, we convert the value to a negative number to ensure that the total is decreased by the specified amount and the value is then returned.

24 Client SuiteScript Tutorial Validating Field Values 20 function calccustomerdiscountrate() if(!isnan(parsefloat(nlapigetfieldtext('custbody_cust_discount'))) ) return ((parsefloat(nlapigetfieldtext('custbody_cust_discount'))) * -1); else return 0; Determining Which Discount to Use Next, we ll want to make sure that the Page Init function does not cause the discount to be set to 5% if a customer already has a pre-defined higher discount rate. 1. Create a new function. function samplevalidatefield(type, name) 2. Set the variables var usecustomerdiscount = true; var instore_discount = -5; var cust_discount = calccustomerdiscountrate(); 3. Determine if In-Store discount is higher than the customer discount and return an alert that allows you to choose whether to accept the higher value. if ( instore_discount <= cust_discount ) usecustomerdiscount = false; if( usecustomerdiscount ) alert("custbody_cust_discount: '" + nlapigetfieldtext('custbody_cust_discount') + "'"); nlapisetfieldtext('discountitem', nlapigetfieldtext('custbody_cust_discount')); else nlapisetfieldtext('discountitem', "In-store Discount"); 4. Close the function. Test the Code Now upload the modified customcashsale.js file to the file cabinet and then assign the samplevalidatefield function for the Validate Field function on the Custom Code Sample form.

25 Client SuiteScript Tutorial Triggering Events when a Field is Changed 21 Now when we enter a cash sale using the Custom Code Sample form, if a customer is selected that has a pre-defined discount higher than the In-store discount set by the Page Init function, then the In-store discount is NOT used. More Validation This is a very simple case. In reality, we d need to add some further validation to ensure that the field types are in the correct format and we may want to check for other discount restrictions, etc. The complete code included in the appendix, Appendix: Tutorial Code includes javascript validation for the following: If the transaction discount is changed to a rate greater than $50 or 30%, a box pops up asking for confirmation of manager approval for the discount. The user can choose to keep the current discount or abort the discount. If the discount is aborted, a message is displayed to notify the user that the discount level is not approved and it will be reset. If more than 20 of any one item is added to the transactions, a box pops up asking if you are sure you want to add the item. The user can choose to add the items or return to the item list without adding the items. Triggering Events when a Field is Changed In the Field Changed example, we will cause a popup box display that indicates if a customer has had order problems in the past and reminds the user to verify all items before submitting the order. Setup This script requires the creation of custom entity and transaction body fields.

26 Client SuiteScript Tutorial Triggering Events when a Field is Changed 22 Element Parameters Purpose Entity Field Description: Past Order Problems Subtab: General ID: _had_order_problems Applies To: Customer:Job To create, go to Setup > Customization > Entity Field > New. Transaction Body Field Create the Code In this section we will add the field changed code to the customcashsales.js file. 1. First, we will set this code to fire on any change to the transaction body field created during Setup. function samplefieldchanged(type, name) if (name == 'custbody_had_order_problems') Remember, the custbody_had_order_problems is sourced from the entity field selected. Therefore, this code will be executed each time a new customer is selected in the form. Since the custbody_had_order_problems field is locked, it can NOT be edited directly. 2. Next, we ll check the value of the checkbox field and if set to T, display an alert. if ( (nlapigetfieldvalue('custbody_had_order_problems') == 'T') && (nlapigetfieldtext('entity')) ) alert("this customer has had order problems previously. Be sure to verify all items with the customer before submitting the order."); return true; 3. Finally, we will close the function without causing any additional change. return true; Test the Code Description: Past Order Problems Type: Check Box Source List: Entity Subtab: Main Display Type: Locked ID: _had_order_problems Applies To: Sale To create, go to Setup > Customization > Transaction Body Field > New. Upload the modified customcashsale.js file to the file cabinet and then assign the samplefieldchanged function for the Field Change Validation function on the Custom Code Sample form.

27 Client SuiteScript Tutorial Validating a Line Item 23 Now when we enter a cash sale using the Custom Code Sample form, if a customer is selected where Past Order Problems checkbox is enabled, an alert is displayed. Validating a Line Item In the Validate Line example, we will include validation that prevents the addition of a service line item without a service employee being chosen for that line. Setup This script requires the creation of a custom entity and custom transaction column field. Element Parameters Purpose Entity Field Description: Service Rep Type: Check Box Subtab: Human Resources Applies To: Employee Transaction Column Field Employee Records Create the Code Description: Service Rep Type: List/Record List/Record: Employee ID: _service_rep Applies To: Sale Item Filter Using: Service Rep Is Checked: True Assign various employees as service reps. Provides a checkbox on employee records where you can define an employee as a service rep. To create, go to Setup > Customization >Entity Field > New. To create, go to Setup > Customization > Transaction Column Field > New. Again, we will modify the customcashsale.js file to add the following code. The code simply checks the value of the custcol_service_rep custom field whenever a custcol_service_item item is selected. If the value is T, then an alert is displayed and the event is aborted. The user is forced to first select a service rep before entering any line items. function samplevalidateline(type)

28 Client SuiteScript Tutorial Recalculating Field Totals 24 if ( (nlapigetcurrentlineitemvalue('item', 'custcol_service_item') == 'T') && (!nlapigetcurrentlineitemtext('item', 'custcol_service_rep')) ) alert("you must choose a Service Rep for this service item."); return false; return true; Test the Code Upload the modified customcashsale.js file to the file cabinet and then assign the samplevalidateline function for the Validate Line function on the Custom Code Sample form. Now when we enter a cash sale using the Custom Code Sample form, if a service line item is selected when a sales rep has not been assigned, the user is forced to return and select a sales rep for the customer before selecting any service items. Recalculating Field Totals In the Recalc example, we will determine if items added to the cash sale are service items. If the item is a service, the sales price is added to the service bookings field. Setup This script requires the creation of a custom item field, transaction column field and transaction body field.

29 Client SuiteScript Tutorial Recalculating Field Totals 25 Element Parameters Purpose Item Field Description: Service Item Type: Check Box Subtab: Basic ID: _service_item Applies To: Service Default Checked: True To create, go to Setup > Customization > Item Field > New. Transaction Body Field Item Records Create the Code Again, we will modify the customcashsale.js file to add the following code. function samplerecalc(type) var total = 0; for ( i = 1; i <= nlapigetlineitemcount('item'); i++) var item_amount = parsefloat(nlapigetlineitemvalue('item', 'amount', i)); if (nlapigetlineitemvalue('item', 'custcol_service_item', i) == 'T') total += item_amount; nlapisetfieldvalue('custbody_service_bookings', nlapiformatcurrency(total)); Test the Code Description: Service Bookings Type: Currency Subtab: Main Display Type: Locked ID: _service_bookings Applies To: Sale Designate various existing items as service items. To create, go to Setup > Customization > Transaction Body Field > New. Any new service items created are automatically marked as service items.. Upload the modified customcashsale.js file to the file cabinet and then assign the samplerecalc function for the Validate Line function on the Custom Code Sample form.

30 Client SuiteScript Tutorial Prompting before Save 26 Now when we save a cash sale using the Custom Code Sample form, any service items amounts are added to the service bookings field. Prompting before Save In the Save example, we will cause a pop-up box to display when a record is saved that prompts the user with Are you sure you want to save this record? The code will execute the save if the user clicks OK and abort the save if the user clicks Cancel. Note: No record customization (setup) is required for this script to work properly. Create the Code Again, we will modify the customcashsale.js file to add the following code. This simple script returns a dialog box prompting the user to confirm the save. function samplesaverecord() return confirm("are you sure you want to save this record?"); Test the Code Upload the modified customcashsale.js file to the file cabinet and then assign the samplesaverecord function for the Save Record function on the Custom Code Sample form. Now when we save a cash sale using the Custom Code Sample form, a confirmation prompt is returned.

31 Chapter 4 Code Names The tables in this chapter detail standard field names that can be used in custom code. You can reference the table with names listed by record type or by field type. Note: When referenced in Client SuiteScript, field names are case sensitive. Also, the Field Name column in the following tables refers the standard field name NetSuite uses to define the given field. This name may differ in your account if the name has been customized. Code Names by Record Type: Case Record Contact Record Customer Record Employee Record Event Record Partner Record Task Record Vendor Record Opportunity Record Code Names by Field Type: Entity Fields CRM Fields Item Fields Transaction Fields You can also find the Custom Code ID for any standard or custom field in NetSuite by viewing the page source of any form that displays the desired field. To find any Client SuiteScript ID for a Field in NetSuite: 1. Display the form that contains the standard or custom field ID you need in edit mode. You can display a form in edit mode by editing an existing record or creating a new record. For example, to find the Client SuiteScript ID for a field on an Opportunity form, display the list of Opportunities and click Edit next to an Opportunity record. 2. Copy the Field name. Highlight the field text and press CTRL + C. 3. Right click in the form and select View Source (or View Page Source).

32 Code Names by Record Type Find the Field name in the source. Press CTRL + F (Find) and then CTRL + V (Paste) and hit Return. 5. Examine the Anchor tag for that Field. The anchor tag contains the Custom Code ID for the field. For example: To find the Custom Code ID for the Win/Loss Reason field in an Opportunity form, navigate to the opportunity form (in edit mode), and find the Win/Loss Reason field in the page source. The anchor tag is as follows: <A class='smalltextnolink' tabindex=-1 title="what's this?" href='javascript:void("help")' style='cursor:help'onclick="return nlfieldhelp(19,'tran_opprtnty','winlossreason', this)" onkeypress="event.cancelbubble = true; return true;" onmouseover="this.classname='smalltextul'; return true;" onmouseout="this.classname='smalltextnolink'; ">Win/Loss Reason</A> Therefore, the Custom Code ID for the Win/Loss Reason field is winlossreason. Code Names by Record Type Case Record Code Name Field Name Location assigned Assigned main casenumber Case Number main category Category main company Company main contact Contact main createddate Creation Date main customform Custom Form main main employees Employees main form reply main escalationmessage Escalation Message escalation helpdesk Help Desk main inbound Inbound main incomingmessage Incoming Message main internalonly Internal Only main isinactive Inactive main issue Issue main item Item main