Request-Level Preferences
Some SOAP web services preferences can be set at the request level. Request-level preferences override company-wide settings.
Request-level preferences 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 impacts mandatory custom fields in the UI. Setting this to true makes mandatory custom fields optional in SOAP requests. Setting this to false makes mandatory custom fields required. Omitting required values returns a USER_ERROR with instructions to provide a value for the field.
When deciding whether to enable this preference, consider if the provided data comes from a system that equivalent fields to the custom field.
This preference can also be set company-wide. It displays in the UI as Disable Mandatory Custom Field Validation. If not set 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 system notes for custom field changes. Using this preference may improve performance, depending on your integration.
This preference is available at the request level only.
In NetSuite, you can control logging system notes by checking the Log System Notes on Update Only box under Setup > Company > Preferences > General Preferences. The SOAP preference does not override the UI preference when it's set to true. This means that if the UI preference is true and the SOAP preference is false, only updates are 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 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 submit a value for a read-only field by mistake. 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.
Setting the preference to true saves time by not requiring you to remove values for read-only fields. Otherwise, existing values in read-only fields return an INSUFFICIENT_PERMISSION error.
This preference is available at the request level only.
runServerSuiteScriptAndWorkflowTriggers
The runServerSuiteScriptAndTriggerWorkflows preference control sSuiteScript and trigger workflows per request. Omitting this preference uses the company-wide setting on SOAP Web Services Preference page. Including this preference overrides the company-wide UI setting.
You can set the preference in the request like this:
<runServerSuiteScriptAndTriggerWorkflows>true</runServerSuiteScriptAndTriggerWorkflows>
The preference value is set based on the request value. IIf not included, the UI preference is used. Including the preference overwrites the company-wide UI setting. This preference can be set on the UI using the Run SuiteScript and Workflow Triggers box.
Disabling this option has two effects:
-
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.
To learn more about the effect of this preference, see Basic Search Behavior with User Event Scripts and Workflows.
When importing historical data into NetSuite, consider disabling this option for faster processing and block executions of additional logic performed automatically by executed scripts and workflows. For live data sync or partner apps like Outlook Sync, use the default option, Server. In other words, consider enabling server SuiteScript to run your business logic for integrated apps. Note that enabling server SuiteScript may negatively affect performance
To ensure that your business logic is fully executed, always use the default option, Server. Additionally, changing the default option can potentially break your working integration. Avoid this unless you're an advanced SOAP web services user.
The Control SuiteScript and Workflow Triggers in Web Services Request relates to disabling scripts and workflow triggers per request. It's a Setup type permission. Users need the Full level of this permission to set the new SOAP header preference for disabling scripts and workflow triggers per request. If a user sends the request with insufficient permissions, 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 users without request-level preference permission.
warningAsError
Enabling this preference treats warning messages generated by NetSuite as errors that cause an exeption, rejecting the request. For more information about the difference between errors and warnings, see SOAP Web Services Warnings, Errors, and Faults.
This preference can also be set company-wide. It displays in the UI as Treat Warnings as Errors. If not set at the request level, NetSuite uses the company-wide preference.
bodyFieldsOnly
The bodyFieldsOnly preference is boolean. This preference determines if sublist values are returned in search results. Setting it to true returns only body fields. Setting it to false returns both body fields and sublist values.
Leaving it at its default value (true) can improve performance. Setting it to false triggers user event scripts and workflows for basic searches.
This preference is ignored for advanced searches.
The bodyFieldsOnly request-level preference affects the how computed fields such as total values and formulas on forms are processed. This can lead to incorrect search results for custom fields with formula-calculated values. To get correct values, set bodyFieldsOnly to false if formulas or totals are incorrect.
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 |
Entering an invalid number may return a WS_INVALID_SEARCH_PAGE_SIZE error.
If not set, the system uses the default system value. For more details, see Search Page Size.
returnSearchColumns
This preference applies when using an advanced search with to execute an existing saved search. You might want to return full records instead of columns. Set the preference to false to return full records.
The default value for the preference is true. Setting it to true without specifying search return columns returns an error. Similarly, setting it to false without a saved search also returns an error.
For more information about advanced searches, see Advanced Searches in SOAP Web Services.