SpreadSheetSpace SDK developer guide

The goal of this SDK Documentation is to help developers to arrange a gateway between applicative ICT packages they developed and operate and SpreadSheetSpace collaborative world for real time data manipulation.

The SDK is available for Java and .Net C # environments. To use SDK enable the "Sync" option for the used profile (i.e. the developer account) from the user preferences on SpreadSheetSpace server's web interface. If this option is not available contact your system administrator.

Background

SpreadSheetSpace's replicator of tabular data is very useful to link together spreadsheets and ingest external data into them. The "dynamic" circulation of data among spreadsheet users currently happens in an uncontrolled way, leading to errors and inefficiencies:

  • Inconsistent cross-spreadsheet links due to uncontrolled delete, rename or replace operations of spreadsheet files potentially leads to data loss;
  • Proliferation of many copies of data due to spreadsheet circulation by email or other means leads to data replication, lack of control on spreadsheet versions, and potential usage of non up-to-date data;
  • Uncontrolled concurrent access to shared spreadsheets for manual data update leads both to high update latency and to uncontrolled changes in spreadsheet data;
  • Manual copy/paste operations to support data propagation from one spreadsheet to another may lead to mistyping errors and violations of cell formats.

So the effort will be directed to add quality to a spreadsheet composition platform. The basic idea is to guarantee the data flow embedded into separate worksheets by linking cell ranges belonging to different spreadsheets in such a way to come up with a distributed spreadsheet. While such behavior is already supported in private file spaces, the envisioned component extends the operating principle and the functionality to a networked environment in a secure controlled way.

A View has a source and more target end points following a publish/subscribe paradigm.

The SpreadSheetSpace's SDK enables to create and manage "Views" when the source isn't a spreadsheet user but an ICT element that's wrapped or interfaced by a coded daemon. The model may be used to enrich legacy environments (i.e. SAP) with the analytics capabilities as well as to interface industrial equipments or connect open data sources.

Concepts to Understand

The key element of SpreadSheetSpace environment is the "View". A SpreadSheetSpace View is the tabular representation of the data replicated between spreadsheets. This is composed of two parts: template and data. The template represents a formatting of the table that you can see on Excel after importing the view. The data is a value matrix, the actual information content of the view.

The view path pass through a relay node that's responsible for the right delivery and finalise the end-to-end 1:m channel.

When a synchronization link is required SpreadSheetSpace end point build up the View (open the link); next it may decide to propagate data updates in a manual or automatic way. SpreadSheetSpace implements an end-to-end encryption to ensure the confidentiality of exchanged data. Each user's client at the first run generates a pair of keys and sends the public key to the SpreadSheetSpace server. Every time a view is created, it is encrypted if all its recipients have a key published on the SpreadSheetSpace server.

Upon a "view" is up and running, synchronization messages and related management requests are sent though the channel to keep the relation alive.

SpreadSheetSpace SDK must follow the same steps in order create a view between any custom written code and one or more Excel spreadsheets.

SpreadSheetSpace SDK allows the creation of a little stub, scheduled at system manager convenience, able to capture dynamic data from the applicative landscape, organize them in a tabular format and pass them to the SpreadSheetSpace environment using a one to many view paradigma.

The structure of that stub appears as follows:

Key data structures into stub are: the one containing exchanged data (i.e. a table of data captured from application scope); and the one containing the view header identifier used for every SDK call.

SpreadSheetSpace SDK API Initialization

SDK API provides the system calls required to accomplish the steps of this process.

Init SDK

SpreadSheetSpace SDK initialization is the first operation to be performed by whoever wants to integrate his software with SpreadSheetSpace.

  • Sdk:
    SpreadSheetSpace SDK constructor. Call it to initialize the SDK. You can verify the result examining the returned State object. See the documentation of "State" for further details.

After SDK initialization you are enabled to call the following actions by verb. The call format, as stated in the SDK API reference, is: sdk."verb"(params);

SpreadSheetSpace SDK API actions to create and modify view

Create

Methods in this section are used to create a SpreadSheetSpace view. A SpreadSheetSpace view can be created in different ways:

  • Through the Excel client
  • Through the SpreadSheetSpace web site interface
  • Through the SDK libraries provided by SpreadSheetSpace

To create a SpreadSheetSpace view from the web interface or SDK, you must enable the "Sync" option from the user preferences. If this option is not available contact your system administrator.

The API are:

  • createPrivateView:
    Create a SpreadSheetSpace View and send it to a specific set of recipients.
Synchronize

Methods in this section are used to update an existing SpreadSheetSpace view. The updates have a progressive sequence number that must be respected to ensure data consistency.

  • updateView:
    Update data and template of an existing SpreadSheetSpace View. See the documentation of "createPrivateView" to learn how to create a View.
Management

Methods in this section are used to manage existing views, to retrieve info, modify parameters and delete your existing views.

  • addRecipients:
    Add recipient(s) to an existing view.
  • removeRecipients:
    Remove recipient(s) from an existing view.
  • deleteView:
    Delete an owned existing SpreadSheetSpace View.
  • deleteViews:
    Delete all owned SpreadSheetSpace Views.
  • getAddressBook:
    Retrieve your address book list from your SpreadSheetSpace account.
  • getOwnedView:
    Retrieve your owned views list.
  • getInboxView:
    Retrieve your inbox views list.

SpreadSheetSpace SDK API actions to subscribe a view

Read

Methods in this section are used for reading existing SpreadSheetSpace view data. If the view is encrypted this can only be read by users who previously generated the pair of SpreadSheetSpace keys.

  • generateKey:
    Generate your personal public and private keys. This function will also automatically send the public key to the SpreadSheetSpace server. You will have to manually store your private key.
  • getValuesView:
    Retrieve values from an existing SpreadSheetSpace view.