Last updated on June 10, 2015

Extensions Framework

Introduction

The purpose of developing an extension is to provide extended or specific workflow functionality that the Appspace Core or add-on extensions do not provide. The framework enables developers to extend the capability of Appspace by integrating with external systems. Extensions could also be developed to create workflows tailored to specific business requirements.

Prerequisites

To develop custom extensions, developers must satisfy the following requirements.

  • Appspace 5 – Developers require at minimum Appspace Version 5 to access the Appspace Graph API and install custom extensions.
  • Enterprise Licensing – The Appspace 5 instance must have an Enterprise License to enable custom extensions.
  • Extension Manager Advanced – The Appspace 5 instance must have the advanced extension manager add-on extension installed.

Extension Components

An extension is technically a web application that is hosted within the Appspace Core framework. An extension has the following components:

Web Application – The core of an extension is the web application that provides the functionality of the extension. The web application can be developed in any web technology that supports constructing, sending, and receiving HTTP messages. These include popular server side languages such as ASP.Net, PHP, JSP, and Ruby. The web application will provide a user interface and utilize the Appspace Graph API to provide its functionality.

Note

Extensions can also be developed in client side technologies such as Javascript and Flash Action Script. However do note that client side technologies typically have cross-domain policies imposed. To use these technologies make sure that the required cross-domain exclusions are handled on the respective Appspace instances.

Extensions are hosted on the Appsace instance under the IIS 7.0 web server. Therefore developers must ensure that the required IIS ISAPI extension or CGI is enabled on the web server. It is recommended to use more performance-optimized handlers such as FastCGI to handle non .Net technologies such as PHP and Perl.

Manifest File – An XML file (named “extensions.config”) that defines the operation of the extension. The structure of the file is as follows:

  • Name – The formal name of the extension. This name is displayed in the Appspace Toolbar and also the Extension Manager interfaces.
  • Guid – A globally unique 32-hexadecimal digit identifier, to uniquely identify the extension.
  • Application Name – A unique name for the web application that will be created on the Appspace web server.
  • Release Notes – Textual notes that describe the features for the version of the extension.
  • Description – A textual explanation of the functionality of the extension.
  • Version – Version number of the extension to denote its current revision.
  • Default Page – The relative path (from the root of the web application) to the start up page that will be called when the extension first runs.
  • Embedded – Value of True or False to indicate if the Extension is displayed as an IFrame (true) within the Appspace Core Framework or if it runs fullscreen (false).
  • Roles – Developers can define the access level to the extension by creating an access control list. The Roles are based on pre-defined roles in Appspace (such as Account Owner, Portal Administrator, Network Administrator, etc.). Developers can also define custom Roles exclusive to the extension. Appspace administrators will then need to apply these custom roles to respective users to provide visibility to the extension.
  • Widgets – Developers can define a widget that is displayed on the Appspace Core Dashboard when a user logs in. Typically widgets provide summary information related to the data managed by the extension. Developers can control the visibility of a widget by defining the roles on the widget similar to how roles can be defined at the extension level.
  • Installation Events – Developers can define a collection of relative URI’s within the web application to call during pre-installation, post-installation, and rollback events. These handlers can be used to configure specific settings of the extension on installation, and to perform specific tasks (such as cleanup on rollback or post-installation).

Extension Manifest XML File

The following is an example extension manifest file.

Extension Parameters

The Appspace Core Framework will pass in the following parameters to an extensions’ default page on loading the extension:

  • Parameter key: t
  • Value Type: 32 digit hexadecimal number
  • Description: The security token of the current logged in user. Extensions will use this to make API calls to the Appspace Graph.

The parameters are passed in as query string arguments to the extension’s default page. Extension authors are required to parse the query string arguments and utilize the values to invoke the Appspace Graph API methods.

The following is an example of how the Appspace Core Framework calls an extension.

Packaging An Extension

Extension should be archived as a .zip archive with the following structure.