Introducing SuperOffice API's

Ratings

Introduction

It can sometimes be daunting for people new to SuperOffice programming to know where to begin. With several platforms, for both Customer Relationship Management (CRM) and Customer Service (CS), it can be difficult to understand which application programming interface (API) is appropriate for which platform. This article explores the different platforms and explains what SuperOffice API are available for each one, as well as provide links to the corresponding API documenation.

Internal Automation API versis External Integration API

The primary focus of this article is to discuss the API's that enable external integration with SuperOffice. This typically means 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 and are covered briefly.

Both SuperOffice CRM and SuperOffice Customer Service (CS) support different forms of scripting automation. SuperOffice CS, available in both on-site and online, supports scripting automation, and accounts for a majority of CS integrations. SuperOffice CRM on the other hand is available as four unique platforms, each of which have their own extensible characteristics:

  1. Windows client
  2. On-site web client
  3. On-line web client
  4. Mobile client: Pocket CRM

These first three CRM clients support many forms of integration, but the mobile client does not. The mobile client does support custom web panels that are configuable on each device, but that is all. Because the mobile client does not expose any external integration points, it will not be mentioned any further in this article

The sections below discuss the capabilities of both internal automation and external integrations. The differences between the two are that internal automation primarily deals with scripting languages while most external integrations use a compiled program using .NET, Java or Delphi.

Internal Automation APIs

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 tasks imaginable, but generally involve validating, tranforming and/or moving data. These types of routines are commonly discussed in the Developer Forums.

Figure One: Script automation options by platform.

As seen in Figure One, there are several scripting options available for each platform. The graph details which automation languages are supported by each platform.

SuperOffice CS leverages its' own scripting engine and language, known as ejScript. Primarily used to automate workflows around customer service scenarios involving tickets, mailings and templates, it's been extended to include classes and methods that mirror NetServer web service API's. The extented ejScript API allows the platform to access and manipulate CRM data previously only available to CRM.

SuperOffice CRM is slightly more complicated than SuperOffice CS. The Windows client hosts a scripting environment made possible by the MSScriptControl, a COM component that's built in and made available on every Windows operating system.

The SuperOffice web client relies exclusively on client-side javascript support. SuperOffice tests the web client against all major browsers and versions to ensure a fully functionaly client no matter what the browser policy in an organization. On-site installations support including and running integration javascript to support customer needs, but it is up to the organization to ensure it works in their environment. On-site web installations also supports server-side scripting by executing C# or VB.NET scripts on the application server.

The SuperOffice Windows client can load and execute both vbScript and JScript code. The scripting environment does enable some interaction with users by showing message boxes, or displaying input boxes. The Windows client has the most complete automation engine of all the SuperOffice products. It is, for example, the only client that out of the box exposes events that can invoke script routines when users open and close dialogs. This presents an opportunity to either eliminate or augment other integrations.

Although the on-site web client has the ability to detect when a user opens or closes a dialog, it requires custom javascript on the the web server. This type of functionality is normally implemented by larger customers or partners who specialize in CRM web client customizations and integrations.

Each platform has strengths and weaknesses that are dependent on the environment in which they are deployed. Figure Two highlights many of the strengths by platform.

Figure Two: Automation capabilities by on-site platform

For example, automation code in the CRM Windows client has complete access to all of the current users contextual identity values. The following code snippet demonstrates how to access the current companys' current identity value:

Dim contactId
contactId = CurrentContact.Identity

While the same is possible on the web client, it requires a round trip request to the web server using javascript, and is not considered an internal automation API.

var contact = AjaxMethodDispatcher.CallSync(
"SuperOffice.DCF.Web.AjaxMethods.SuperState.GetCurrent", "", "contact"
);

Internal automation API's are very useful for managing a 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, and let the user focus on the task at hand.

More information about scripting automation can be found in each client SDK documentation.

External Integration APIs

The term external API refers to all SuperOffice client products, SuperOffice COM API's, and the NetServer API landscape.

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 query objects to high-level business objects, to higher-level SOAP 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 API's. 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 it's ecosystem.

Where to get started really depends on your target SuperOffice platform and your preferred technology stack.

As seen in Figure Three, the list of available API's for integrations decrease the closer they are to on-line. That is just the nature of the respective environment and not limitations of the platforms or APIs.

Figure Three: Recommended API's for each platform.

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 together, 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 API's. It does not make sense, for example, to use the COM-based API in today's web service architectures. Although it sometimes can not be avoided, we generally discourage building integrations that leverage more than one of our API's in the same solution.

Although integrations in SuperOffice CRM Online can display visual elements, such as partner applications through a web panel, the web client in SuperOffice CRM online only supports service-orientated integrations today. Meaning that all data access routines must use the web services API's. Considering the SuperOffice web client relies exclusively on these API's, and has more functionality that the Windows user and administration clients, the capability of the web service API's should never be considered inferior. In fact, the web service API's should be given serious consideration for nearly all scenarios.

Integration Scenarios by Platform

To gain a better understanding what types of integrations are possible, the remainder of this article is going to take discuss each SuperOffice client and NetServer to help clarify which integration approach is best for your specific needs.

Window Client

A flagship CRM platform, the SuperOffice CRM client has been the leading SuperOffice CRM product since 1989. SuperOffice CRM was created to support the needs of the sales person by making his everyday life easier – and make it so user-friendly and elegant that the user would want to use it.

The Windows client exposes many hooks that make it easy for vendors to create seamless experience with their applications. Integrations have full-duplex type communications, providing integrations the ability to receive notifications when users perform actions, immediately process the data concerned, and even switch the users context and show important relevant information related to that action.

There are several articles about using the integration points listed below in the Developer club articles section, SuperOffice Windows.

Integration Points:

  1. COM API
  2. Automation Engine (vbScript and JScript scripts)
  3. Event Subscriptions (internal scripts and external COM subscriptions)
  4. Web Panels
  5. Buttons to launch external applications
  6. Document Plugin (NetServer based since version 8)
  7. Sentry Plugin (COM)
  8. Email Plugin (COM)

Related SDK:

Web Client (On-Site)

Available since 2007, the SuperOffice web client has enjoyed a wide-spread adoption by many on-site customer installations. The product has several advantages over the Windows client. For example, customers can install SuperOffice on a web server that is accessible both near and far without having to pay extra license fees for disconnected functionality such as Travel, or incure the extra maintenance costs for maintaining Travel Gateway and the processing of .up and .dwn files.

SuperOffice CRM web also enjoys many integration capabilities. I would go so far as to say that it is the most extensible CRM platforms available today! With the ability to modify and adapt the users experience, manipulate the data processing and logic, nearly every component in the SuperOffice CRM web stack is overridable and extensible for complementary functionality or control.

Integration Points:

  1. Add controls to existing pages
  2. Add custom dialogs
  3. Override default functionality and inject custom logic into:
    1. DataHandlers (create, update, delete of page data)
    2. Archive Providers (read-only search providers)
    3. Most buttons
  4. Add custom views (tabs or preview pane options)
  5. Add web panels

Related SDK

Web Client (Online)

Both SuperOffice on-site installations and CRM Online applications use the same NetServer web service API's. The only difference between the two environments is how integrations are authenticated. While on-site integrations have a more direct approach, supplying credentials, CRM Online integrations must use SuperOffice federated authentication.

Federated authentication is a way SuperOffice can provided a single sign-in experience for multi-tenant users, and applications that serve multi-tenant installations.

The SuperOffice CRM Online environment hosts an app store with several partner integrations. These integrations are comprised of Business to Consumer (B2C) applications. Most applications expose functionality inside SuperOffice by adding web panels in relevant areas, while others add a button that opens a web page to the application. All application vendors have their own cloud platforms to manage customers and tenant users.

You can find out more information about CRM Online integration points by reading the CRM Online SDK pages.

Integration Points (Online):

  1. Custom Lists
  2. Custom List Items
  3. User-defined Fields
  4. Web Panels
  5. Custom buttons (navigator and button bar)
  6. Access to Web Services

Related SDK:

Customer Service

There are several articles available in both the Technical and Developer clubs that explain in detail many of the internal automation integrations points provided by SuperOffice CS. There are not, however, too many external integration points to discuss. The ones that do exist are primarily the CS legacy SOAP services. It must be said that these services have not evolved for quite some time, and do not appear to be on any road map. That said, there are a few major installations that do leverage these endpoints, and therefore they are not likely to fade away any time soon either. Similar to the Windows client COM API's, these API's are in the future not likely to change.

There are no prebuilt SuperOffice proxies available for these API's. You must use a proxy generator appropriate for your target technology platform, or use raw SOAP requests, to use these services.

Integrations Points

  1. SOAP Services (Not available in Online) (available at http://<domain>/scripts/SOAP.exe?action=<endpoint>
    1. Available action parameters:
      1. customer
      2. ticket
      3. admin

Related SDK:

NetServer Architecture

All SuperOffice clients, in one form or another, depend on NetServer for database access. While each client has its own extensibility points, NetServer also has extensibility points. Some of NetServer extensibility options surface to the clients, such as the Document Plug-in.

As a multi-tiered database access layer that bridges communications between clients and the SuperOffice database, NetServer uses database-independent database access code, as well as high-level web services for both the SuperOffice web and PocketCRM clients.

Figure Four: NetServer conceptual overview.

The lowest layer of NetServer, the domain-level development API's, are generally used by a client or application server. This layer does the heavy lifting and is responsible for marshalling all the model-based data into raw SQL.

Listed below are the different aspects of NetServer core API's.

  1. OSQL: Low-level high performance database-independent objectified SQL.
  2. Rows and Rows: Medium-level data table and data row level access
  3. Entities: High-level business model classes that abstract multiple table joins.

The highest level of NetServer data access is the service-orientated architecture and consists of:

  1. Web service endpoints based on WCF: IIS application used by SuperOffice web and PocketCRM.
  2. Web service proxies: Service agent pattern .NET assemblies 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 fat client application, as well as a fat client deployed with NetServer service proxies for data access across the internet.

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

Integration Points (Low Level):

  1. Document Plugin.
  2. Sentry Plugin.
  3. Add or override archive providers.
  4. Add or override resources providers.
  5. Multiple levels of database access.

Related SDK:

Conclusion

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.

With the understanding that each SuperOffice platform provides a lot of integrations points, and knowing that any one problem can have multiple solutions, it's important to consider all options before you decide which approach to take. There is assistance and guidance is available. Please use the developer forums to ask for recommendations, or you may submit integration questions directly to SuperOffice at sdk@superoffice.com.

Read more about each platform API in the SDK documentation.

Post Comment To the top