Offline Package Management API

Titania Delivery portal themes can use various Freemarker directives and/or Javascript APIs to request, list, download, and delete offline packages.

Freemarker Directives

The following Titania Delivery tags are available for managing packages in the portal.

<@td.offlinePackages>

Analogous to HARPPortal.listPackages(), this directive lists the packages requested by the current user and stores them in a variable.

@var: The variable to hold the list.
@startPage: The page number to return.
@limit: The max number of results to return. Must be a positive integer n where 0 < n <= 2147483647.
@anonymous: Whether to return the list of anonymous packages or those for the current user. The default is 'false'.

<@td.offlinePackageDownloadUrl>

Retrieves the download URL for an offline package, either inline in the page or in a variable.

@package: The package whose URL to load. Either this or the @key attribute must be specified.
@key: The key of the package whose URL to load. Either this or @package must be specified.
@var: The variable in which to store the URL. If not specified, the URL is output to the page.

Javascript APIs

The HARPPortal Javascript library will have new methods for managing offline packages.

requestPackage(request: PackageRequest, [anonymous: boolean]): Promise<PackageInfo>: Requests a package be created using the info in the given request. The package will be private to the currently-authenticated user unless anonymous is true. This will send an HTTP POST request to the new URL endpoint /portals/rpc/{portalPath}/offline/request containing the JSON representation of the PackageRequest object.

getPackageStatus(key: string): Promise<PackageStatus>

Requests the status of the given package key. The result will be one of "QUEUED", "WORKING", "FINISHED", or "FAILED".

getPackageInfo(key: string): Promise<PackageInfo>

Retrieves details about the given package.

getPackageDownloadUrl(key: string): string

Retrieves the URL from which the finished package can be downloaded.

getPackageHashUrl(key: string[, format: string = 'sha512']):
                        string

Retrieves the URL of the SHA-512 checksum of the finished package. The optional format parameter can be one of the following:

sha512: The hex representation of the checksum, followed by the filename. This is the default.
binary: The raw binary bits of the digital checksum.
hex: A hex-encoded string of the checksum.
base64: A base64-enoded string of the checksum.

getPackageSignatureUrl(key: string[, format: string = 'binary']):
                        string

Retrieves the URL of the digital signature for the finished package, if available. The optional format attribute can be one of the following:

binary: The raw binary bits of the digital signature. This is the default behavior.
hex: A hex-encoded string of the signature.
base64: A base64-enoded string of the signature.

deletePackage(key: string): Promise<boolean>

Deletes the package with the given key.

listPackages(anonymous: boolean): Promise<PackageInfo[]>

Lists the currently-authenticated user's packages. If not logged in, or anonymous is set to true, packages created by anonymous users are listed. Otherwise, only packages created by the currently-authenticated user are listed.

Javascript Data Structures

The data structures used by these methods are defined as follows, using TypeScript syntax.

class PackageRequest {
  packager: string;
  parameters: {[key: string]: any};
  documents?: PackageRequestDocument[];
  search?: string;
  includeContextualizedTopics?: boolean; // true by default
  ignoreCache?: boolean; // false by default
  signContents?: boolean; // false by default
  signaturePathPrefix?: string;
  signaturePathSuffix?: string;
  signatureAlgorithm?: string;
  makeXmlSignatures?: boolean;
}

class PackageRequestDocument {
  projectKey: string;
  itemKey: string;
  contextKey?: string;
  refId?: string?;
}

class PackageInfo {
  key: string;
  portalKey: string;
  packager: string;
  createdBy: string;
  createDate: number; // Epich timestamp
  documents: PackageDocument[];
  params: {[key: string]: any};
  status: PackageStatus;
  statusMessage: string;
  filename: string;
  mimeType: string;
  scriptOutput: string;
  hash: string; // Hex string of the SHA-512 hash
  signature: string; // Hex string of the digital signature, if any
}

enum PackageStatus {
  QUEUED, WORKING, FINISHED, FAILED
}

`PackageRequest` Properties

packager: The packager to execute. This will be the name of the folder beneath the packagers folder in the portal theme containing the packager.ftl entry point.
parameters: A map of parameters that control various aspects of package generation, accessible from within the packager execution via the parameters variable.
documents: The documents to include.
search: A search string; the results of the search will be packaged.
Note: If neither search nor documents are specified, all documents in the portal will be packaged. If both are specified, search takes precedence.
includeContextualizedTopics: When packaging compound documents, like DITA maps or chunked non-DITA XML files, the search or documents need only specify the root documents and set this to true to capture the root document and all of its component topics.
ignoreCache: Generated package contents are typically cached to improve performance for subsequent re-generation of the package; setting this to true skips that caching.
signContents: Whether to automatically generate and store side-files containing digital signatures of each file in the package. If set to true, one or both of signaturePathPrefix and signaturePathSuffix must be specified or no signatures will be added to the package. This is false by default.
signaturePathPrefix: A string to prepend to the paths for digital signature side files, commonly used to put signatures in their own root-level folder in the package. For instance, set to /signatures/ to create a mirror of the package folder structure beneath the signatures folder for digital signatures. This is blank by default.
signaturePathSuffix: A string to append to file paths for digital signature side files. This is .signature by default, meaning signature files will be in the same folder as the file they're signing, with a .signature extension.
signatureAlgorithm: The signature algorithm to use to generate digital signatures of the package itself and its contents. Must be one of the following values:

SHA512withRSA (default)

SHA384withRSA

SHA256withRSA

SHA224withRSA

SHA1withRSA
makeXmlSignatures: If set to true, the packager will build up an XML document that contains digital signatures for each file in the package. This document is available via the package.signaturesXmlDoc variable and can be inserted into the package using Freemarker code like this:
<@package.generate dest="META-INF/signatures.xml"> ${package.signaturesXmlDoc.@@markup} </@package.generate>

Sample Javascript Code for Requesting a Package

For example:

HARPPortal.requestPackage({
  packager: 'WebHelp',
  parameters: {
    title: 'My Fancy WebHelp Package'
  },
  documents: [
    'harp://blahblahblah',
    {projectKey: 'abc', itemKey: '123'}
  ]

}).then(checkStatus);

function checkStatus(info) {
  switch(info.status) {
    case 'QUEUED':
    case 'WORKING':
      console.log('Current status is ' + info.status + '. Checking again in 5 seconds.');
      setTimeout(function() {
        HARPPortal.getPackageInfo(info.key).then(checkStatus);
      }, 5000);
      return;

    case 'FAILED':
      alert('Packager failed.\n' + info.scriptOutput);
      return;

    case 'FINISHED':
      if (confirm('Package completed. Download?')) {
        window.open(HARPPortal.getPackageDownloadUrl(info.key));
      }
      return;
  }
}

JSON HTTP Endpoints for Package Management

POST /portals/rpc/portalPath/offline/request[?anonymous=true]

Requests the creation of a portal. The response will be a JSON document describing the package. The result is a PackageInfo document. Use the anonymous query parameter to request a public package not associated with the current user.

DELETE /portals/rpc/portalPath/offline/packageKey

POST /portals/rpc/portalPath/package/packageKey/delete

Deletes the specified package.

GET /portals/rpc/portalPath/offline/packageKey/status

Requests the status of the given packager. The return value will be a JSON string containing one of the following values:

"QUEUED"
"WORKING"
"FINISHED"
"FAILED"

GET /portals/rpc/portalPath/offline/packageKey/info

Returns a PackageInfo document describing the package. Some fields will not be present for some statuses.

GET /portals/rpc/portalPath/offline/packageKey/download

Downloads the package, if it is in the FINISHED state. Otherwise callers will receive a JSON document containing a "error" or "message" keys describing the reason for the refusal.

GET /portals/rpc/portalPath/offline/list[?anonymous=true]

Lists the PackageInfo objects created by the currently-authenticated user. use the anonymous query parameter to request anonymous packages even if logged in.

GET
                        /portals/rpc/portalPath/offline/packageKey/hash

Retrieves the SHA-512 checksum of the package. This parameter takes an optional format URL parameter which can have one of the following values:

sha512: The hex representation of the checksum, followed by the filename. This is the default.
binary: The raw binary bits of the digital checksum.
hex: A hex-encoded string of the checksum.
base64: A base64-enoded string of the checksum.

GET
                        /portals/rpc/portalPath/offline/packageKey/signature

Retrieves the digital signature of the package, if any. This endpoint takes an optional format URL parameter which can have one of the following values:

binary: The raw binary bits of the digital signature. This is the default behavior.
hex: A hex-encoded string of the signature.
base64: A base64-enoded string of the signature.

Titania Delivery Developer's Guide