NetServer archive providers

• 5 minutes to read

How to use archive providers for simple to complex data sources.

From low-level Objectified-SQL to higher-level business Entities, SuperOffice integrations have several ways to access to SuperOffice data. Complete access to the database through web services, however, is subject to all kinds of security threats and therefore is not a simple problem to solve. Archive providers were later introduced as a means to execute complex queries through web services in a secure and easy-to-use manner. This section describes what they are and how to use them.

Terminology

An archive provider is a mechanism that delivers data in a form suitable for display or processing as a two-dimensional sheet, much like a spreadsheet. There are several terms used throughout the code that need to be precisely defined:

A row is one row of data, typically displayed as one line. Data is delivered one row at a time to the client.
Each row consists of one or more columns, where each column has a (predictable) name, and several kinds of content (display value, raw value, tooltip, ...)
Each row also has a name, called an entity. The entity name is a string and can be thought of as defining a row type. A provider will always define at least one entity.
The combination of entity and primary key (a 32-bit integer) uniquely identifies a row in the result from a provider

What is an archive provider

Fundamentally, an archive provider is similar to a database view. They each have a unique name, expose a fixed set of selectable fields, and mask their join logic. Underneath the hood lies a dynamic system that, based on the requested fields, creates absolute necessary joins only. This of course increases query performance and throughput.

An archive provider is determined by 3 main properties:

Archive Name
Available Entities
Available Columns

Entities add a dimension that database views do not possess. They act as an additional filtering capability. For example, not all, but several archive providers return rows that are of multiple types. This means that a single query can return rows of details that represent several different types of rows like appointment, sale, and document. On providers that support multiple entities, it is possible to tell the provider to only return one or two types of rows and ignore the rest.

Executing complex queries requires a way to specify criteria, and archive providers do this with archive restrictions.

From situations that depend on constructing light-weight data models to performing complex aggregate queries, archive providers are an attractive tool in your tool-belt. They are easy to use data sources and work well for executing a wide variety of queries.

An archive list is the UI elements or GUI controls representing columns and restrictions (while the provider is the data source). They are not MDO lists, hence they never have any history.

Why use an archive provider?

The functionality of an archive provider is basically searching on associate, contact, or project and retrieving any combination of a large number of available columns, arbitrarily sorted.

Available archive providers

There is a long list of archive providers that give access to virtually the entire database.

The Find providers are some of the most common:

FindAppointment Archive Provider
FindContact Archive Provider
FindDocument Archive Provider
FindProject Archive Provider
FindSale Archive Provider
FindSelection Archive Provider

The reference section has a complete list of archive providers.

Namespace is SuperOffice.CRM.ArchiveLists.

Getting started

Deep dive

Example

The example below shows how we can read the name+department as one field, and the postal address city as a separate field. Unlike an entity, the archive will not load categories or email addresses unless they are requested.

using SuperOffice;
using SuperOffice.CRM.ArchiveLists;
using SuperOffice.Util;
using(SoSession newSession = SoSession.Authenticate("SAL0", ""))
{
  IArchiveProvider contactArchive = ArchiveProviderFactory.CreateFindContactProvider();

  //Set the columns that needs to be returned
  contactArchive.SetDesiredColumns("contactId", "nameDepartment", "address/city");

  //set the paging properties of the provider.
  contactArchive.SetPagingInfo(10, 0);

  //An array of restrictions with an implicit and in between them.
  contactArchive.SetRestriction(new ArchiveRestrictionInfo("contactId", "=", "1234"));

  //Display the retrieved data in another list box
  foreach (ArchiveRow row in contactArchive.GetRows())
  {
    foreach (KeyValuePair<string, ArchiveColumnData> column in row.ColumnData)
    {
      resultsListbox.Items.Add(column.Value.ToString());
    }
    resultsListbox.Items.Add(" --- ");
  }
}