AgileApps Support Wiki Pre Release

Package Data

From AgileApps Support Wiki

Package Data is data that is included in an application Package.

Motivation

When you add an object to a package, the object definition is included--structure (tables) and behaviors (methods to add and update entries, for example), but not object data. In general, that is highly desirable functionality. It means that you can package up a running, tested application, and know that neither proprietary data nor test data has been inadvertently included in the package.

At times, though, it is also desirable to include object data. For example:

  • A table of country codes
  • A table of state abbreviations
  • A table that maps zip codes to cities and states

Package data satisfies that need.

Mechanism

With the Package Data mechanism, a developer defines a single class that adds selected data to the package when publishing, and that makes a local copy of that data when a subscriber installs the package.

In addition, that class lets publishers select a subset of the data to publish--so different subsets of data can be published with different versions of the package.

The class also handles upgrades. So when a new version of the package is published, the developer can choose to upgrade the data in as efficient a manner as necessary (important for very large data sets).

Operation

The initial step is to Create a Data Handler class that:

  1. Makes data elements selectable in the packaging GUI.
  2. Adds selected data to the package, when publishing.
  3. Extracts the data when a subscriber installs the package.
    For example: see the ZipMapDataHandler class in Create a Data Handler.

Next, make the Data Handler selectable.

Develop > Configuration

Lock-tiny.gif

Users that have the Developer Tools permission can configure package data. 

To make a data-handler class selectable from the GUI when creating a package:

  1. Click New Package Data Item
  2. Provide Item Name.
    For example: "ZipMapData"
    (In upcoming releases, this field is targeted for use in the Translation Workbench.)
  3. Provide Item Label.
    For example: "Zip Map Data"
  4. Select a Data Handler class.
    For example: ZipMapDataHandler

Notepad.png

Note: A Data Handler class is one that has been programmed to implement the PackageItemType interface. A class is able to act as data handler if and only if it satisfies the requirements of that interface.

To publish a package with package data:

  1. Select the Package Data item for inclusion in the package.
    For example: Zip Map Data
  2. Select the specific data items to include. (Or click All to take them all.)
  3. Add any other items to be included in the package
  4. Publish the package.

A tenant then subscribes to the package to install it. When a package is upgraded by the publisher, or deleted by the tenant, the Data Handler class takes care of the details.