Request-Level Preferences
Certain SOAP web services preferences can be set at the request level. When you use this approach, the request-level preferences override any company-wide preferences that might have been set.
Preferences available at the request level are part of the Preferences complex type. This type is defined in the platform messages XSD file. You can also view the Preferences complex type on the SOAP Schema Browser’s Preferences reference page.
Note that all of these preferences take boolean values.
The available preferences are:
When setting a preference value, you must use camelCase style capitalization for the preference type name. If you do not, the system does not return an error, but your settings are ignored.
disableMandatoryCustomFieldValidation
This preference affects the handling of custom fields that are configured in the UI to be mandatory. If you set this preference to true, the fields are not treated as required during SOAP web services requests. If the preference is set to false, the fields are required. In these cases, if you fail to provide the required value, the system returns a USER_ERROR, with instructions to provide a value for the field.
When deciding whether to enable this preference, consider whether the data being provided comes from a system that has equivalent fields to the custom field.
This preference can also be set at the company-wide level. It displays in the UI as Disable Mandatory Custom Field Validation. If you do not set this value at the request level, NetSuite uses the company-wide preference.
disableSystemNotesForCustomFields
System notes are system-generated records that track changes to a record, including changes to specific field values. This preference lets you disable the creation of system notes for changes to custom fields. Depending on your integration, using this preference may increase performance.
This preference is available at the request level only.
In NetSuite, logging system notes can also be controlled by checking the Log System Notes on Update Only box under Setup > Company > Preferences > General Preferences. The SOAP web services preference does not override the UI preference when the UI preference is set to true. This means that if you set the Log System Notes on Update Only preference in the UI to true, while the disableSystemNotesForCustomFields SOAP web services preference to false, only updates will be logged for custom fields. For more information about the UI preference, see Setting General Account Preferences.
System notes are important for maintaining a complete audit trail. Therefore, if a custom field contains sensitive information that is critical for audit purposes, you should carefully consider whether or not to enable this preference. For more details about system notes, see Auditing Data Changes using Searches.
ignoreReadOnlyFields
This preference affects the way the system behaves when you mistakenly submit a value for a read-only field. If you set this preference to true, the system ignores these mistakes.
You should set this preference to true in the following situations:
-
If you are getting a record, making a change to it, and then submitting it.
-
If you are initializing a record.
In these situations, if you set the preference to true, you do not have to take the time to remove values for read-only fields. Otherwise, if values for these fields exist, the system returns an error reading INSUFFICIENT_PERMISSION.
This preference is available at the request level only.
runServerSuiteScriptAndWorkflowTriggers
By using the runServerSuiteScriptAndTriggerWorkflows preference, you can control SuiteScript and trigger workflows per request. If you do not include this preference in a request, the company preference set on the SOAP Web Services Preferences page is used. If you include this preference in the request, it overrides the company preference set in the UI.
The preference is set in the request in the following way:
<runServerSuiteScriptAndTriggerWorkflows>true</runServerSuiteScriptAndTriggerWorkflows>
The value of the preference is set corresponding to the value from the request. If the preference is not included in the request, the UI preference is used. If the preference is included in the request, it overwrites the company preference set in the UI. This preference can be set on the UI using the Run SuiteScript and Workflow Triggers check box.
If you disable this option, you do both of the following:
-
Disable server SuiteScripts that otherwise would have been triggered by SOAP web services requests.
-
Disable workflows that otherwise would have been triggered by SOAP web services requests.
Also see Basic Search Behavior with User Event Scripts and Workflows about the effects of this preference.
If you are bringing historical data into NetSuite, consider disabling this option to increase speed of operations and block executions of additional logic performed automatically by executed scripts and workflows. If you are syncing live data or running a partner application (for example, Outlook Sync) you should use the default option, Server. In other words, you should consider enabling server SuiteScript to ensure that your business logic runs for your integrated application. However, note that doing so may have a negative performance impact.
To ensure that your business logic is fully executed, always use the default option to run SuiteScript and Server Triggers. Additionally, changing the default option can potentially break your working integration. You are discouraged from doing so unless you are an advanced SOAP web services user.
The Control SuiteScript and Workflow Triggers in Web Services Request permission is related to the preference for disabling scripts and workflow triggers per request. This permission is a Setup type permission. A user must have the Full level of this permission to set the new SOAP header preference for disabling scripts and workflow triggers per request. If a user with insufficient permissions sends a request with this preference set, the request fails with the following error:
<platformFaults:code>INSUFFICIENT_PERMISSION</platformFaults:code>
<platformFaults:message>You do not have permission to control SuiteScript and Workflow Triggers in Web Services Request.</platformFaults:message>
The global preference applies to requests sent by users who do not have permission to set a request-level preference.
warningAsError
When this preference is enabled, warning messages generated by NetSuite are treated as errors that cause an exception, resulting in rejection of the request. For more information on the difference between errors and warnings, see SOAP Web Services Warnings, Errors, and Faults.
This preference can also be set at the company-wide level. It displays in the UI as Treat Warnings as Errors. If you do not set this value at the request level, NetSuite uses the company-wide preference.
bodyFieldsOnly
The bodyFieldsOnly preference is boolean. You use it to specify whether or not sublist values are returned in search results. In other words, if you set this value to true, only body fields are returned. If you set it to false, sublist values are also returned.
Leaving this preference set to its default value, which is true, can significantly improve performance. If the preference is set to false, a basic search triggers user event scripts and workflows.
Note that in an advanced search, this preference is ignored.
The bodyFieldsOnly request-level preference affects the way computed fields such as total values and formulas on forms are processed. As a result, for example, if the values of custom fields are calculated using formulas, the search might return incorrect results. If the calculated values of formulas are incorrect or incorrect total values are returned, set the bodyFieldsOnly preference to false to make sure the correct values are returned.
pageSize
The pageSize preference takes an integer. You use this preference to specify the number of records returned on a single page of search results.
When you set a value for pageSize, the following limits apply.
|
Search Type |
Minimum |
Maximum |
|---|---|---|
|
Synchronous |
5 |
1,000 |
|
Asynchronous |
5 |
2,000 |
If you enter an invalid number, the system may return an error code reading WS_INVALID_SEARCH_PAGE_SIZE.
If you do not set a value for this preference in your search, the system uses the value that has been set for the entire system. For more details, see Search Page Size.
returnSearchColumns
The returnSearchColumns preference is relevant when you are using an advanced search to execute an existing saved search. In these cases, you might want the search to return full records, as opposed to columns. To accomplish this, you would set the preference to false.
The default value for the preference is true. Note that if you set this preference to true and you do not specify search return columns, the system returns an error. Similarly, if you are not executing a saved search and you set the preference to false, the system returns an error.
For more information on advanced searches, see Advanced Searches in SOAP Web Services.