SuperOffice API Overview

SuperOffice provides a comprehensive suite of APIs and integration capabilities that enable developers to build powerful solutions on top of the SuperOffice platform. This guide will help you understand the architecture, choose the right APIs for your needs, and get started with SuperOffice development.

What is NetServer?

NetServer is the heart of SuperOffice’s API ecosystem - a multi-tiered database access layer that bridges communications between client applications and the SuperOffice database. NetServer contains both low-level classes for managing data access in onsite domain environments as well as high-level web services for access from anywhere in the world.

NetServer enables developers to perform lookups, create, read, update and delete (CRUD) operations towards SuperOffice. Whether deploying a solution in an onsite domain environment or accessing SuperOffice via web services, NetServer exposes an array of application programming interfaces (APIs) that enable virtually unlimited access to the data in SuperOffice.

SuperOffice Sales, SuperOffice Service and SuperOffice Mobile are examples of clients that use NetServer. All applications listed in the SuperOffice Online AppStore do too.

NetServer Architecture and API Layers

At its core, NetServer contains database-independent abstractions, and has database-specific implementations that API consumers never have to think about. The only indication is during configuration when the target database server is set.

SuperOffice NetServer provides several persistence layers, each one allowing more fine-grain control the closer they get to the database. You can choose to work at the level that suits you best.

Domain-level APIs (NetServer Core)

The lowest layer of NetServer is only used by clients or an application server in an onsite domain environment. This level does the heavy lifting and is responsible for serializing all model-based instructions into SQL.

• SQL data objects (OSQL): low-level, high-performance, database-independent objectified SQL.
• Row and Rows: medium-level data table and row-level access.
• Entities: high-level business model classes that abstract multiple table joins.
• Archive providers and MDO Providers: provide read-only search capabilities.

Web service APIs

NetServer web service data access is provided by the following types of web service endpoints:

• RESTful: ASP.NET WebAPI with modern HTTP-based APIs
• SOAP: WCF-based IIS application for enterprise integrations

SuperOffice publishes web service proxies that can be used by clients to access the service endpoints.

An important aspect of NetServer web service development is its deployment flexibility. It’s capable of being embedded in a domain-centric client, or used by a web application across the internet.

At the highest level, encapsulated in the SuperOffice.Services namespace, is an agent pattern-derived API that in terms of deployment is quite flexible. Access and modification to data in the database, using service objects, will always be coded the same, whether the application and database are located on the same server, or operating in a distributed environment.

Read more about web services.

SuperOffice Extensibility Levels

There are several levels of SuperOffice extensibility, and these are commonly defined as configuration settings, workflow and scripting, external APIs, and internal APIs.

Configuration Level

The first level of extensibility is exposed inside the admin UI pages of SuperOffice. These are features commonly managed by system administrators and SuperOffice consultants and are used to tailor SuperOffice to individual customer needs.

Scripting Level

The scripting level pertains to a few different features that provide similar functionality, albeit by different means:

• CRMScript: A SuperOffice scripting dialect similar to JavaScript, managed inside the administrative pages
• NetServer scripting: An Application Server capability that is accessible onsite only

External APIs

External APIs provide complete data access for both SuperOffice clients and online applications. This level includes SuperOffice COM APIs and the NetServer API landscape.

Internal APIs

Internal APIs are the nearly limitless amount of customization capabilities that most onsite installations leverage to provide everything from custom pages and dialogs, document and sentry plugins, and so much more.

Online vs. Onsite Deployment

Since 2005, SuperOffice has heavily invested in building APIs that enable partners and customers to build integrations that encompass everything from the database schema changes up to modifying UI elements in the application interface.

With this breadth of customization capability in onsite installations, it’s sometimes hard for legacy partner applications to adapt to move their application to the cloud.

Online applications are much more strict, and only have a subset of extensible capabilities.

Onsite Installations

With onsite installation, there is one web server hosting SuperOffice sites, and the owners can do whatever they like with their installation.

Online Tenants

Online tenants, on the other hand, share application file sets. Therefore, any compiled assemblies that are exposed to one installation would inadvertently expose those same customizations across all shared tenants.

Security and hosting restrictions in Online force both standard and custom applications to adapt in ways that support the features and functions they can provide, and accept the limitations that restrict the things they can’t.

SuperOffice will continue to invest in research and development to deliver equivalent onsite customization capabilities to SuperOffice CRM Online. However, a timeline for this is not available. This policy decision is related to security reasons, and SuperOffice is not willing to compromise tenant security.

Programming with SuperOffice APIs

Configuration Requirements

Every solution that uses NetServer packages directly needs a SuperOffice section in the application configuration file. This only pertains to the following nuget packages:

• SuperOffice.NetServer.Core (onsite clients and plugin development)
• SuperOffice.NetServer.Services (SOAP proxy and utility classes)
• SuperOffice.WebApi (HTTP RPC proxy and utility classes)
• @SuperOffice/WebApi (NPM package for JavaScript/TypeScript applications)

Configuration requirements:

• Windows applications must add a SuperOffice section to the app.config file.
• ASP.NET web applications must add a SuperOffice section to the web.config file.

The SuperOffice section group contains configuration details pertaining to NetServer operations, such as database connection details, logging, document handling and security. Everything you need to know about the SuperOffice configuration options is defined in the NetServer configuration documentation.

Multi-Platform Support

All types of technology platforms, including Java, PHP, Python, Ruby, and many more can integrate with NetServer web services. Any technology stack that supports web services can connect to and exchange data with SuperOffice NetServer. SuperOffice supplies .NET proxy assemblies only. All other technology platforms must generate their own proxies, or use raw SOAP/XML, to access the web services.

NetServer Extensibility

NetServer has several extensibility points. Some extensibility points show up in clients, such as the Document Plug-in, while others like the Sentry Plug-in do not. Webhooks are supported at both the low and high levels of NetServer.

SuperOffice Platforms and Clients

SuperOffice Service (CS) supports scripting automation and extensive UI customizations and accounts for the majority of integrations.

SuperOffice CRM is available as the Online Web client, the Onsite Web client, and the Windows client, each of which has its own extensibility characteristics.

The mobile clients SuperOffice Mobile and Pocket CRM support custom web panels that are configurable on each device. They expose few external integration points.

API Compatibility Matrix

The list of available APIs for integrations decreases the closer they are to online. That is just the nature of the respective environment and not the limitations of the platforms or APIs.

• From NetServer Core, Web supports NetServer script events only.
• Using NetServer web services, the configuration must be set to Local Mode for Windows and Local or Remote mode for Web.

There are virtually no limitations as to which API you leverage when building an integration that targets just the Windows client. If, however, your requirements include both the Windows client and the Web client, the available API options decrease. This is not necessarily a bad thing though. Sometimes it just makes technological sense to build an integration using only one of the available APIs. For example, it doesn’t make sense to use the COM-based API in today’s web service architectures.

SuperOffice CRM Online relies exclusively on the service-orientated APIs for data-access, and yet it has more functionality than the other clients.

Recommended APIs for each platform

The list of available APIs for integrations decreases the closer they are to online. That is just the nature of the respective environment and not the limitations of the platforms or APIs.

• From NetServer Core, Web supports NetServer script events only.
• Using NetServer web services, the configuration must be set to Local Mode for Windows and Local or Remote mode for Web.

There are virtually no limitations as to which API you leverage when building an integration that targets just the Windows client. If, however, your requirements include both the Windows client and the Web client, the available API options decrease. This is not necessarily a bad thing though. Sometimes it just makes technological sense to build an integration using only one of the available APIs. For example, it doesn’t make sense to use the COM-based API in today’s web service architectures.

SuperOffice CRM Online relies exclusively on the service-orientated APIs for data-access, and yet it has more functionality than the other clients.

Automation vs. integration

The APIs that enable external integration with SuperOffice typically mean applications that are compiled into executables and run in their own process. However, there are also important internal integration points in SuperOffice that are just as important.

The difference between the two is that automation primarily deals with scripting languages while most integrations use a compiled program using .NET, Java, or Delphi.

Automation allows an application to execute code when an event occurs inside the client. These events occur when an action takes place such as when a dialog is opened, or a person is created.

While automation code is usually defined by customer requirements, consultants often create routines that assist with common tasks. Automation code can perform just about any task imaginable, but generally involve validating, transforming, and/or moving data. These types of routines are commonly discussed in the developer forums.

Internal automation APIs are very useful for managing predetermined routines based on customers' requirements and providing user interaction within the application. They can make complex multiple-step tasks easier by programmatically automating the mundane details letting the user focus on the task at hand.

NetServer, although used as an umbrella term that encapsulates a variety of data access capabilities, is just as much if not more extensible than the SuperOffice clients. With constructs such as low-level database objects to high-level business objects, to higher-level web services and web service proxy libraries, NetServer is itself an extensible SuperOffice product.

SuperOffice has several partners and 3rd party vendors who have built tightly-coupled integrations with SuperOffice using external APIs. The different types of integrations built range from tiny edge-case security plugins to integrations with completely new document management systems. There are even complete enterprise resource planning systems that leverage SuperOffice CRM as the heart of its ecosystem.

Comprehensive Integration Guide

The following table compares some of the most common extensibility points and defines which capabilities are possible in both environments.

Each platform has strengths and weaknesses that are dependent on the environment in which it is deployed.

Summary and Next Steps

Whether constructing a small internal automation routine or building a complex integration, SuperOffice has many integration options. Once you get past the problem of knowing with which SuperOffice platforms you are integrating, it becomes a matter of just choosing the right API for your solution.

NetServer provides a robust, flexible foundation for all SuperOffice integrations. From low-level OSQL operations to high-level web services, you can choose the approach that best fits your technical requirements and deployment environment.

Key Takeaways

• NetServer is the core of SuperOffice’s API ecosystem, providing multiple layers of abstraction
• Web services are the preferred integration point for nearly all scenarios
• Online deployments have security restrictions that limit certain customization capabilities
• Choose your API level based on your needs: configuration, scripting, external APIs, or internal APIs

Getting Help

With the understanding that each SuperOffice platform provides a lot of integrations points, and knowing that any problem can have multiple solutions, it’s important to consider all options before you decide which approach to take.

Assistance and guidance are available:

• Use the developer forums to ask for recommendations
• Submit integration questions directly to SuperOffice at sdk@SuperOffice.com
• Read more about each platform API in the SDK documentation

Related Documentation

• NetServer Core APIs - Low-level data access
• Web Services - RESTful and SOAP APIs
• Authentication Overview - Security and access patterns
• Configuration Guide - Setting up NetServer
• Automation Overview - Scripting and workflow automation