NOTE: This is being designed as a replacement for netsuite-rest-client.
Brought to you by the NetSuite Liberation Front
Contributing to rest_suite
Getting Up and Running
- Install node.js and npm
General Contribution Process
- Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
- Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
- Fork the project
- Start a feature/bugfix branch and commit atomically
- Commit and push until you are happy with your contribution
- Be sure to test your code and make sure that all tests pass before submitting a pullrequest.
Copyright (c) 2012 Acumen Brands, Inc. See LICENSE.txt for further details.
Generally, each individual script is to be uploaded to NetSuite as a single endpoint with a single function being exposed. These functions are documented throughout the project and should be relatively easy to ferret out.
Uploading to NetSuite
The process of deployment is a somewhat involved manual process at the moment. It is possible to wrap all files into a zip and automate the process via a manifest, but this has not yet been implemented. Many files contain multiple classes that would normally exist in their own files specifically for this reason. The deploy process is painful enough as it is.
In the NetSuite web interface, go to the documents dropdown and select:
Upload all .js files in lib here. Now go to Setup -> Customization -> Scripts -> New.
Create a new Script record using each operation file. List netsuite_toolkit.js as an included library on each.
The script record also assigns each HTTP function to a provided function name. In each Script,
reference the appropriate post handler function in the "POST" text box. The function names should
be provided without parentheses:
deletePostHandler() just becomes
From each Script record, generate a Script Deployment with an appropriate role/employee/account access for the credentials your client will be using. NetSuite calculates these permissions inclusively, so if one criteria out of any of them matches your credentials, it will provide access.
The Script Deployment will list the endpoint URL to which you will send requests with the JSON body for the script's parameters.
The Script Deployment records will list endpoint URLs that you POST your JSON objects to. Simply build the JSON object and include it as the request body. The authentication header must include your account credentials assigned to the following variables in a string assigned to 'authorization' in your request header.
"NLAuth nlauth_account=<business account id>,nlauth_email=<login email>,nlauth_signature=<password>,nlauth_role=<role_id>"
We've added some handy tools in
jspec to perform most of the mundane tasks associated with the project.
Here's a quick reference:
./jspecSet up your environment and run all tests
./jspec --docGenerate HTML documentation in
./jspec --resetGlear out installed node modules
./jspec --monoRun tests without color
./jspec --debugFire up a node debugger with jasmine
HTML formatted documentation can be found in
doc. This has been generated with JSDoc3 and
includes documentation provided by NetSuite for SuiteScript v2010.1 for easy reference. Documentation
is re-generated for each tagged release. If you'd like to generate docs on the fly, simply run
- Generally, anywhere you see
idmentioed, it can safely be assumed to be
- Each script has one endpoint and only one endpoint. This is due to the nature of NetSuite's RESTlet interface.
- Furthermore, each endpoint should respond to a POST request
- All actions for a given endpoint are taken based on the request body of the POST
Basic Input Reference
This is a basic overview of the JSON object payload for each request. A '+' next to a row indicates an array; a '-' indicates a key in a hash.
Initialize returns a blank record of the given type with all mandatory keys pre-populated with null or default values. This does not expose non-mandatory fields in the returned hash, those must be filled in manually client-side.
Load will request a given record from the Netsuite database by internalid. It will return the requested record will all mandatory and populated schema. Non-mandatory and custom fields with blank values will not be populated in the returned hash.
+ single record action - id - record_type
Delete will destroy records in Netsuite's database. If successful, the id of the removed record will be returned. Otherwise, an exception will be raised.
+ single record action - id - record_type
Upsert requests a new records be written to the database or an existing record be altered. If an internalid is present id the 'id' field, then it will attempt to update a record loaded using the type and id, otherwise throwing an exception if it does not exists. If no id is present, it will attempt to create a new record using the values given.
+ single record action - id - record_type + literals + sublists - name + line_items + create_or_update - match_field - literals + excise - match_field (unique field to search against) - value
Transform initializes a new transaction from another transaction record in a workflow. In this case sublist items can be filtered (altered somewhat or removed if need be) but cannot be added if they do not exist on the original transaction. A record is is mandatory for transform.
+ single record action - id - source_type - result_type + literals + sublists - name + line_items + create_or_update - match_field - literals + excise - match_field (unique field to search against) - value
Saved search will request the results of an already created saved search from Netsuite. Results must be sorted by internalid of the records returned in order to properly paginate the results. This is a limitation of the SuiteScript environment that we have not yet found a workaround for.
- record_type - search_id - lower_bound - batch_size
Search allows you to build a search on the fly. As with saved searches, results generally should be filtered by internalid, however with ad-hoc search this is not mandatory. If another criteria could reasonably be used to sort, the sort boolean is exposed for the client to use. If multiple result columns have this set to true, only the last column in the list will be processed. A column to sort by internalid is always added, so if no sort is provided the search will always be sorted by internalid.
Formula filtering is also exposed and is a required alternative to explicit string matching in RESTlet operation to avoid hitting the execution limit. It produces a SQL function that results in 1 or 0. In the event a formula search is used, the name of the filter must be 'formulanumeric', the value must be 'IS', and the value will be 1 or 0.
For the formula:
- name: The field on which the script is filtering
- values: An array of possible values, the comparison is
- comparison: A valid SQL comparison or equality operator
- join: 'AND' or 'OR' to join all comparisons of 'field' to a single value
- record_type - batch_size - lower_bound + search_filters - name - operator - value - formula (optional) - field + values - comparison - join + search_columns - name - join - sort (boolean)