NetSuite 3.1 User Manual
System-to-System Developer’s Guide
Revision: 3.1
Date: December 16, 2003
PURPOSE
This document describes the extension of the smbXML (small and medium business eXtensible Markup
Language) integration functionality to support the bi-directional exchange of business data between NetSuite
products and third-party systems.
smbXML was developed to facilitate the exchange of business information between trusted, third-party, XML-
enabled, business applications and the NetSuite product family. smbXML was origin ally implemented as a user
initiated exchange of XML data via flat -file export and import. This was performed by selecting the file to import
through the standard NetSuite web -browser interface, and is referred to as smbXML UI Import.
System-to-System (s2s) integration enables trusted systems to add, update and query data in an integrated
NetSuite account in real-time, or in batch, without user intervention. Most often this is done in real-time, in
response to an event occurring in the integrated third-party system (e.g.: a purchase being made in a third -party
e-commerce application, that sends transaction, customer and item information to the NetSuite product regarding
the sale).
System-to-System integration supports the same records and actions as the smbXML UI Import capability,
available in the standard user interface.
System-to-System Developer’s Guide v3.0
TABLE OF CONTENTS
TABLE OF CONTENTS ......................................................................................................................................... 2
1 OVERVIEW .....................................................................................................................................................3
1.1 CUSTOMERS AND APPLICATION PROVIDERS ..................................................................................................3
1.2 DOCUMENT ROADMAP .................................................................................................................................3
2 IMPLEMENTATION OVERV IEW................................................................................................................. 4
2.1 SUPPORTED PLATFORMS AND NETSUITE DEVELOPMENT SUPPORT..................................................................4
2.2 ARCHITECTURE............................................................................................................................................4
2.2.1 Two-Way Secure Socket Layer (SSL) .....................................................................................................4
2.2.2 Additional Certificate Verification........................................................................................................ 4
2.2.3 Data Exchange Steps........................................................................................................................... 4
2.3 PRE-IMPLEMENTATION CHECKLIST...............................................................................................................5
2.3.1 Integration Partner will Provide NetSuite ............................................................................................. 5
2.3.2 NetSuite will Provide Integration Partner............................................................................................. 5
2.4 IMPLEMENTATION CYCLE.............................................................................................................................5
3 SETUP CLIENT CERTIFICATE.................................................................................................................... 8
3.1 JAVA PLATFORM..........................................................................................................................................8
3.2 MICROSOFT DEVELOPMENT PLATFORM....................................................................................................... 10
4 IMPLEMENTATION DETAILS................................................................................................................... 13
4.1 SMBXML .................................................................................................................................................. 13
4.1.1 Related Documentation ...................................................................................................................... 13
4.1.2 DTD Elements................................................................................................................................... 13
4.1.3 Many to One..................................................................................................................................... 14
4.2 URLS AND HOSTNAMES............................................................................................................................. 14
4.2.1 Post URL.......................................................................................................................................... 14
5 SINGLE SIGNON ACCOUNT MAPPING.................................................................................................... 15
5.1 DO I NEED SINGLE SIGNON?....................................................................................................................... 15
5.2 THE PROBLEM ........................................................................................................................................... 15
5.3 THE SOLUTION........................................................................................................................................... 15
5.4 FURTHER RESOURCES AND DOCUMENTATION............................................................................................. 15
6 USER INTERFACE OPTIONS...................................................................................................................... 16
APPENDIX A – REFERENCES............................................................................................................................ 17
APPENDIX B – JAVA CODE SAMPLE............................................................................................................... 18
APPENDIX C – MICROSOFT .NET C# CODE SAMPLE................................................................................... 19
Confidential Material 2 of 19
System-to-System Developer’s Guide v3.0
1 OVERVIEW
1.1 CUSTOMERS AND APPLICATION PROVIDERS
Generally, there are two types of integration partners, customers and application providers .
Customers are themselves users of a NetSuite product, and are interested in integrating their NetSuite
application data with that of an external, third-party, application’s data. An example would be a NetSuite customer
that ran an external, custom, e-commerce application, that feeds sales information (transactions, customers,
items, etc.) into their NetSuite account.
Application Providers are providers of applications and services to end-customers, who are themselves
customers of NetSuite. Application providers are interested in integrating their customers’ application data, stored
within the application provider’s datacenter, with their customers’ NetSuite data. An example would be a thirdparty Point-of-Sale (POS) provider, that wanted to transmit their customers’ sales information (transactions,
customer, items, etc.) into the NetSuite accounts of their end-customers. In this scenario, the application provider
acts as an agent on behalf of our mutual customer.
Throughout this document, customers and application providers will be called integration partners, collectively.
Before proceeding with this document, you should know whether you are a customer or an application provider.
For more explanation on the difference between customers and application providers, please refer to the
Customer v. Application Provider document available with the NetSuite Developer Program Technical
Documentation, or with your NetSuite Account Manager.
1.2 DOCUMENT ROADMAP
NetSuite’s System-to-System security model uses several technologies and methods to ensure secure
communication and enforce appropriate integration partner access to user data. The following sections will
describe:
• Implementation overview that includes platforms supported by NetSuite, the System- to-System architecture, an
implementation checklist, and an overview of the implementation cycle.
• Step-by- step instructions for the creation of a keystore containing the client certificate
• Overview of smbXML and the DTD elements specific to System- to-System data exchange
• Brief overview of the NetSuite Single Signon (SSO) technology used to map accounts between systems, and
enable application provider access to a user’s NetSuite data
• User interface options relevant to System-to-System integration
Confidential Material 3 of 19
System-to-System Developer’s Guide v3.0
2 IMPLEMENTATION OVERVIEW
2.1 SUPPORTED PLATFORMS AND NETSUITE DEVELOPMENT SUPPORT
While our integration technology to establish System-to-System connectivity is based on standards and can be
used from any development platform, NetSuite officially supports the following two development platforms.
• Java platform
• Microsoft .NET platform
If you’re using one of these platforms, NetSuite will be able to provide a command line driven test client that is
designed to test SSL connectivity to NetSuite, post smbXML documents to NetSuite, and to serve as an example
for the development of the integration partner’s application code. The tool includes the source code.
Currently, the primary development expertise of NetSuite Professional Services are with the above mentioned
platforms, and Professional Services ability to advise an d consult will be strongest for integration partners whose
implementation is in these platforms. If the client application to be implemented uses a different language or
platform, as long as this environment supports two -way SSL communications, there should not be any problems
in implementation since there are no NetSuite proprietary libraries that need to be used.
2.2 ARCHITECTURE
2.2.1 TWO-W AY SECURE SOCKET LAYER (SSL)
Put simply, System-to-System integration allows data (in the form of an smbXML document) to be posted to, or
queried from, NetSuite accounts via an HTTPS post.
NetSuite uses a Two-Way Secure Socket Layer authentication methodology, for System-to-System
communications, that ensures that both parties are who they claim to be. The client is required to validate
NetSuite’s server certificate, and to provide a client certificate in order to authenticate themselves to NetSuite.
NetSuite’s Two-Way Secure Socket Layer (SSL) uses industry standard 128-bit SSL encryption, as well as
certificate hash comparison. Server authentication takes place over an SSL connection initiated with NetSuite’s
key pair signed by a mutually trusted key signer (in this case RSA). The certificate-based client authentication
uses a client generated key pair, the public key of which is signed by and possessed by NetSuite. For details on
certificate-based SSL, please see Appendix A of this document.
Concisely, Two-Way SSL allows for the following:
• The Client verifies that the Server is who it claims to be.
• The Server verifies that the Client is who it claims to be.
2.2.2 ADDITIONAL C ERTIFICATE VERIFICATION
As a further check on authentication, once the XML request document is received, NetSuite performs secondary
validation of the client certificate by comparing a hash of the certificate to a previously stored hash, taken during
the signing phase.
This second validation of the certificate is performed to ensure that the certificate being presented matches
identically the certificate originally provided by the partner.
2.2.3 DATA EXCHANGE STEPS
1. integration partner system generates a valid smbXML document
Confidential Material 4 of 19
System-to-System Developer’s Guide v3.0
2. integration partner opens an HTTPS connection to the NetSuite smbXML server
3. during the SSL handshake
a. the integration partner verifies NetSuite’s identity by validating the NetSuite server certificate, signed by
RSA
b. the NetSuite server verifies the identity of the integration partner by requesting a client-side certificate,
signed by NetSuite
c. the smbXML server returns a symmetric key, encrypted using the integration partner’s public key, used
to establish SSL communication
d. SSL is established
4. partner system transmits smbXML document to NetSuite in the body of an HTTP Post
5. the smbXML server performs secondary validation of the certificate, by comparing a hash of the certificate
to a previously stored has h of the certificate
6. the smbXML server parses the smbXML document and determines whether the partner system has the
appropriate permissions to perform the requested action(s) in the account specified
7. the smbXML server processes the requests and returns the results in the body of an HTTP Response with:
e. any appropriate success or error messages
f. the results of any query requests
2.3 PRE-IMPLEMENTATION CHECKLIST
Prior to beginning development and testing of XML data transmission, NetSuite and the integration partner will
exchange certificates, public keys, URLs and partner IDs.
2.3.1 INTEGRATION PARTNER WILL PROVIDE NETSUITE
• certificate signing request (CSR) – signed by NetSuite, for establishing client authentication
• 1024-bit public key – for use in Single Signon (application providers only)
• company name – used as the partnerAccount, discussed below under DTD Elements (customers only)
2.3.2 NETSUITE WILL PROVIDE INTEGRATION PARTNER
• unique partner ID – used during System-to-System and Single Signon communication, discussed below under
DTD Elements and Single Signon
• signed client certificate – the signed client certificate signing request
• NetSuite signing certificate – the NetSuite certificate used to sign the client CSR
• RSA signing certificate – the public RSA certificate that signed our server certificate, discussed above under the
Architecture Overview, SSL handshake section
• post URL – the production post URL, used by the client to post smbXML documents to NetSuite
2.4 IMPLEMENTATION CYCLE
The following workflow details the implementation steps integration partners undertake, and the NetSuite
organizations responsible for each step.
Confidential Material 5 of 19
System-to-System Developer’s Guide v3.0
Following is a detailed list of steps:
1. Create a sample smbXML document .
o Ensure that it is valid against the current version of the smbXML DTD.
o Ensure that it can be imported into NetSuite using the smbXML UI Import (Transactions > Other > Import
XML Document).
Confidential Material 6 of 19
Loading...