1. Integration projects are the Bermuda Triangle of the Implementation world. Some believe plugging two
systems together should be something very simple and so sail ahead, only to capsize violently. For most
the complexity and danger is recognized, though that alone does not make the navigation any easier.
The secret to a successful Integration remains elusive, though success in integration typically means a
boon of considerable magnitude in operational efficiency and competitive advantage.
This document aims to provide some answers regarding some of the basic decision points in terms of
Web Services Design. This document is intended for non-technical Decision Makers and/or Sales people
In order to guide the basic direction of an Integration project.
Your Single Point Of Success
A PREMIER NETSUITE PARTNER
NetSuite Integration:
Restlets vs Web Services
Introduction
What Is an Integration and Why Is It so Hard?
The word integration is essentially defined as “making two things become one whole”. In computer science, what we’re going to
mean by Integration is taking two wholly apart systems (in our case, of course, one of those systems is going to be NetSuite) and
making it so they can exchange information.
Some classic example would be NetSuite and an external Web Site. Users navigate the Web Site, making use of its rich UI to find the
products they want and checkout. Information might flow from the Web Store to NetSuite in the form of completed orders, and from
NetSuite to the Web Store in the form of inventory counts. Another example might be integrating NetSuite with a software licensing
key management server. The CRM and order management occurs within NetSuite, but when a software product is purchased,
NetSuite must query an external server to register a new user and obtain a software key.
There are as many examples as there are businesses. Integrations can be required to support legacy or home-grown systems or to
plug into more complete “best-of-breed” alternative applications.
In any case, whatever systems are involved, an Integration project is always going to be complex and more difficult than, say, a
script of similar amount of functionality points coded entirely in NetSuite. The reasons for this are that, in an Integration project,
you are dealing with the idiosyncrasies of two systems rather than one, you are dealing with two data structure paradigms and on
top of that are adding a moving part in the middle (your middleware, more on this later).
The idiosyncrasies of systems can’t be helped. No system is going to be perfect. In our case, we are intimately familiar with
NetSuite, which is often the largest and most complex system involved in the integration, and so this, to as much a degree as ever
possible, helps de-risk that aspect. There will still remain the other system to deal with. I do not believe I have ever met Integrators
who were experts in BOTH systems they were integrating.
written by Olivier Gagnon
2. Conflicting data structures will then be the number one concern to address in all projects, because it can be addressed. The success
of any Integration project will largely depend in the mapping activity. This crucial activity will be where the data from the source
system will be mapped to the resulting data in the target system. In many cases, a transformation will be required between the two.
The last bit of challenge – the moving part in the middle – often referred to as the connector - is what we are about to look more
closely at.
The Basic Building Blocks
What Are Web Services
Web Services technology refers to interfaces open to manipulation by commands sent via HTTP Requests. Since that last
sentence was loaded with technical terms, let’s decompose that a little.
An interface refers to the ability for something or someone external to give commands to the software in question. More
specifically, in our case, we will be referring to Application Programming Interfaces, or APIs, which specifically refer to interfaces
accessible by programming/scripted commands. Fundamentally, the interface dictates what will be possible and what will not. If a
system does not have an interface that allows you to, say, delete a Contact, than it will simply not be possible to delete a Contact.
An HTTP Request is a very specific technology, but essentially, it is what allows the Internet to exists, so it is rather widespread.
HTTP Requests are how our browsers request web pages. It is an encoded command sent over “the internet” from a source to a
destination. Further details would require us to get into the definition of the internet and how it works, which is out of scope for
this document.
Thus, Web Services are commands that an application can send to another application over the internet. Web Services requests will
contain information packages, which will be encoded in a certain language, such as SOAP, XML, JSON or a number of other fancy
acronyms. This typically doesn’t really matter, as all package-definition markups are simple and converting one to the other is not
a big deal.
However, Web Services say nothing about what is going to send those commands and deal with the information received. Deciding
in a basic architecture to perform these command exchanges is the focus of the next part.
Middleware-Based Solution
A Middleware is a connector. It is the thing that sits between two systems and orchestrates communication. Because
Middleware is its own thing, sitting by itself outside of either system, it thus brings its own complexities and advantages.
IMAGE ILLUSTRATING THE MIDDLEWARE CONCEPT:
THE MIDDLEWARE SITS BETWEEN THE SYSTEMS AND CONTROLS INFORMATION BACK AND FORTH.
NetSuite
Other System
Middleware
3. ROBUST
FLEXIBLE
SCALABLE
Since Web Services are built from the ground up, essentially full-on software application in their own right, the developer can
chose to build them with as much robustness as desired. Multiple threading, error-handling and error-logging, temporary holding
databases, etc. Web Services apps can be coded with utmost robustness, allowing them to survive data errors, system errors and
even complete system interruption with minimal fuss. Data sent but unprocessed can be memorized and tried again at a later time.
No data or data transmission need ever be lost, ensuring up to 100% data reliability.
Because the Middleware is coded as you desire, you can chose to code out however best suits your needs. It can be made Statefull
or Stateless (meaning it can memorize the state of transient data or not, as you wish), its own interfaces can accept various
manners of commands and it can pass and receive information in whatever programming language you desire.
The Middleware can be coded to queue up requests and even use parallel processing if the target system supports it (NetSuite as
a target system does, subject to extra costs). This allows Web Services to be able to scale up to handle large volumes of data. The
ultimate input limit will be dictated by the source system, but the Middleware can go right up to the very limit.
Disadvantages
EXPENSIVE
REQUIRES HOSTING
While Middleware does allow you to build a solution that is robust, flexible and scalable, well, you do need to build all of that from
scratch, which directly translates to Middleware solutions being pretty expensive, since there is a lot of work involved. There are
many specialized tools to speed up Middleware development and deployment, but fundamentally, because of the wide range of
possibilities, it’ll always be expensive to build a middleware.
There are many off-the-shelf solutions for middleware orchestration (ex: Dell Boomi) but while using these will speed up the
delivery timeline and bring many other advantages, they are also expensive in their own right.
A significant disadvantage of Middleware is that they must be hosted somewhere. The client is responsible for setting up and
maintaining a hosted environment (this can be rented cloud space), but the burden of maintaining that space becomes part of the
maintenance cost of the Middleware.
Advantages
BI-DIRECTIONAL
A Middleware, by virtue of being independent from either systems involved in the integration, is able to orchestrate communication
to and from either system. This may seem like an obvious trait, but when we compare versus other solution types, we will see it
gets more complicated.
4. ILLUSTRATION OF DIRECT SUITESCRIPT-BASED INTEGRATION. RESTLETS ALLOW INCOMING COMMUNICATIONS AND SUITESCRIPTS
MAKING HTTP REQUESTS ALLOW OUTGOING COMMUNICATION. BOTH ASSUME THE OTHER SYSTEM HAS SIMILAR CAPABILITIES
Advantages
EASY TO DEVELOP
EASY TO DEPLOY
Entirely written in JavaScript and using the same NetSuite APIs as any other SuiteScript functionality, RESTlets and scripts are
quicker to code that Middleware apps. They have direct access to NetSuite records and fields and JavaScript is a comparatively rapid
language to code with.
Hosted and run by NetSuite itself, a finished RESTlet or script can be made operational in a matter of minutes.
Other System NetSuite
RESTlet
Suitescript
w/ HTTP
Request
Direct Suitescript-Based Solution
What are RESTlets and Scripts
NetSuite allows quite a bit of custom functionality to be built into the system. While NetSuite exposed a lot of functionality via Web
Services for other systems to command it, it also allows wholly custom interfaces to be built via RESTlets. This form of SuiteScript
allows users to code new interfaces into NetSuite, either providing entirely custom ways or reading or writing into NetSuite. Instead
of an external system having to chain a dozen Web Services command to achieve something, a single RESTlet can be coded,
NetSuite allows quite a bit of custom functionality to be built into the system. While NetSuite exposed a lot of functionality via Web
Services for other systems to command it, it also allows wholly custom interfaces to be built via RESTlets. This form of SuiteScript
allows users to code new interfaces into NetSuite, either providing entirely custom ways or reading or writing into NetSuite. Instead
of an external system having to chain a dozen Web Services command to achieve something, a single RESTlet can be coded,
allowing an external system to simply do a single request, with the RESTlet than firing its tailor-made code to do exactly what the
integration requires.
NetSuite is thus able to provide simplified interfaces to external system, greatly lowering the need for a developer to “learn”
NetSuite. In additional, NetSuite is able to launch commands to other systems without the use of Middleware. It is very important
to note, however, the opposite – the ability of external systems to launch commands to NetSuite without the use of Middleware - is
not necessarily true, depending entirely on the other system’s code.
Similarly, rather than relying on a large Middleware solution, NetSuite is able to use SuiteScript to fire off HTTP Request
commands one at a time to access a remote system’s Web Services and thus remotely command that system.
5. Interfaces
Ability To Host Code
Do both systems have web-enabled interfaces? We know that NetSuite does, but what about the other system? What kind of entry
points do we have? This is discovered by analysis of the documentation. Any system that is enabled to Web Services will typically
have clear documentation regarding this, detailing each of the APIs offered, what they do and how to use them.
If the target system is not Web Services enabled, then direct communication via SuiteScript is unlikely. A Middleware may be able
to help, by essentially coding a module that locally digs into the program and translates local signals into Web Services signals. If
that sounded complex, it’s because it is.
Other alternatives may include some sort of outputting capability, such as exporting files. These basic capabilities can still perhaps
be leveraged as part of a Middleware-driven process.
So, in summary: if the system is not Web Services enabled, direct SuiteScript calls are out, but Middleware may still be viable.
Does the other system have the ability to host and execute custom coded commands? Many systems are Web Services enabled, as
per the above point, without necessarily allowing any commands to be fired out of the system. This may dictate the type of solution
possible, depending on requirements. This aspect is twinned with the concept of Direction of Communication.
Design Considerations
Now that we have seen the two basic architectural choices available to us, how do we chose the method best suited to for each
project? There are some primary questions that must be considered that, above all else, may guide or even dictate our choice.
EASY TO MANAGE
Existing as just another script In NetSuite, managing scripted solutions is easy. Scripts benefit from the testing infrastructure
NetSuite provides, such as Sandboxes and Release Preview environments. They will be familiar to NetSuite Administrators, using
the same language and technology they are already familiar with
Disadvantages
LIMITED
NO ROBUST ERROR HANDLING
NOT REALLY STATEFULL
While their “closeness” to NetSuite and their reliance of the SuiteScript APIs makes them quick and easy to setup, they are also
limited by this. Scripted solutions cannot easily or at all make use of architectural solution blocs like external databases, FTP
servers, etc. Simplicity means faster but also more limited.
A particular form of limitation, and a particularly important one when dealing with Integrations, is a more limited ability to handle
errors. NetSuite error-handling and logging options aren’t totally awful, but a Middleware app will have more error-handling,
logging and reporting options than a scripted solution.
It’s possible to log some information about the state of transient data in NetSuite, but not as readily as a Middleware app can
