JavaScript Extensibility API Reference Guide

Extensibility Packages

Introduction

While Extensibility Applications are a very useful feature for the Simphony POS, configuring an Extension Application in EMC can be complicated and error-prone. A customer must manually add all Extension Application content individually and configure the options for each. If the content is versioned the task becomes much more difficult.

The Extensibility Package feature was designed to make importing of Extension Application content easier. While there is a burden on the extensibility developer to create the package, importing the package into EMC is a trivial process.

It should be noted that there will usually be additional steps for the customer: Creation of site-specific configuration content, page buttons, extension data, etc. These functions are not available in Extensibility Packages.

Feature Overview

Package Highlights

  • Packages are available starting with Simphony 19.7.
  • Packages are simple .ZIP files with a published easy to implement format.
  • Packages work with SIM, C# assemblies, and JavaScript applications.
  • Packages work with Windows / Linux / Android
  • Packages work with OPS / Transaction Services / Extensibility services.
  • Packages can optionally be password encrypted using standard zip file encryption. The customer must supply the password when importing the package using EMC.
  • Packages can contain multiple versions of Extensibility Applications based on client version.
  • Packages are not limited to individual Extension Application content items. Entire web directories, libraries, custom html dialogs, and page controls can be packaged within a hierarchal directory structure.
  • Packages can have an optional readme file. This will be displayed in EMC and contain additional installation instructions, usage instructions, and contact information.
  • Extensibility Applications can read data from the package at runtime.

Package Limitations

  • Packages are only recognized by Simphony 19.7 or later POS clients.
  • Packages must be created manually by the author of the Extension Application, there is no automated tool for this.
  • Legacy C# Extension Application Service (EAS) assemblies cannot be part of a Package.

Typical Workflow

Extensibility Application Author

There will be two ways that a package can be created:

  1. Manual
    1. Create a local disk directory
    2. Create manifest.xml, a simple XML file which specifies minimal information about the package itself
    3. Create a directory for the actual Extensibility Application
    4. Place .isl / .dll / .js files in Extensibility Application directory
    5. Create a metadata.xml file for that Extensibility Application, indicating various options similar to what is configured in EMC (e.g. Main SIM Content)
    6. Zip up directory, deliver to customers
  2. Use EMC to create a package from an existing Extensibility Application
    1. See Can I create a package from an existing extensibility application in EMC? below.
    2. Modify to fit your application.
    3. Zip up directory, deliver to customers.

Customer

  1. Create Extensibility Application in EMC.
  2. Click ‘Import Package’ button, specify Application content name and location of package on disk.
  3. Complete any further custom configuration for Extensibility Application.

Package File Creation

Package creation is a manual process. There is no automated way to select a directory, click a button, and a valid package file now exists.

In each of these cases you will end up with a ZIP file that has a manifest.xml in the root directory. Please ensure this is true to validate the package format.

Using Windows archive creation

This method uses the built-in Windows “Send to | Compressed (zipped) folder)” feature.

  1. Select all the files in the root directory of the package (in which manifest.xml resides) on local disk.
  2. Right-click, select “send to”, then “Compressed folder”. Provide a ZIP file-name.
  3. The newly created file is now a valid package

Using 7-zip archive creation

This method uses the popular 7-zip program to create the package, optionally including a password to protect it.

  1. Select all the files in the root directory of the package (in which manifest.xml resides) on local disk.
  2. Right-click, select “7-zip”, then “Add to archive”
  3. Select destination directory and filename
  4. Optionally set password
  5. Click “OK”

Using a batch file

The following batch file can be used to create the package directory. The name of the package will be prompted.

  1. Open a command prompt in the parent directory of the package directory. In other words, a “dir” will reveal the target directory.
  2. Run the batch file
  3. Enter package directory name.
  4. Package should be created.
@echo off
setlocal


set ZipExe="C:\Program Files\7-Zip\7z.exe"
set /p packageDir="Enter package directory: "

if not exist %packageDir% (
       echo %packageDir% does not exist
       EXIT /B
)

set packageDirManifest=%packageDir%/manifest.xml
if not exist %packageDirManifest% (
       echo %packageDirManifest% does not exist
       EXIT /B
)

set PackageZip=%packageDir%.zip
if not exist %PackageZip% goto zipQDone
set /p AREYOUSURE=Package already exists, delete? (Y/[N])
if /i "%AREYOUSURE%" NEQ "Y" EXIT /B
del %PackageZip%
:zipQDone

pushd %packageDir%
%ZipExe% a  -bb0 -bd -mx5 -r ..\%PackageZip% .
popd

echo.
dir %PackageZip%
echo.
echo Package created.
popd

Package File Format

An extensibility package requires at a minimum:

  • manifest.xml
  • metadata.xml
  • Extensibility Application executables: .isl, .dll, .js

Furthermore, both metadata.xml and executables must be in a directory below the manifest.xml location.

manifest.xml

Simplest manifest.xml

<?xml version="1.0" encoding="utf-8" ?>
<Manifest>
  <ExtensibilityApplications>
    <ExtensibilityApplication Path="default" ClientMinimum="*" ClientMaximum="*"/>
  </ExtensibilityApplications>
</Manifest>

Notes:

  • The <ExtensibilityApplication> tag specifies an extensibility application’s POS version and the directory where it sits.
  • “default” is the directory name
  • One Extensibility Application that is targeted for all versions of Simphony POS
  • Extensibility Application exists in the ‘default’ directory.

With documentation

<?xml version="1.0" encoding="utf-8" ?>
<Manifest>
  <Documentation Path="doc/readme.txt" DisplayType="Text"/>
  
  <ExtensibilityApplications>
    <ExtensibilityApplication Path="default" ClientMinimum="*" ClientMaximum="*"/>
  </ExtensibilityApplications>
</Manifest>

Notes:

  • The <Documentation> tag specifies where the documentation file exists for this package.
  • The document file will be displayed in EMC when viewing the package.
  • The only supported format currently is a text file.
  • There are no limits to this text file.

With multiple extension applications

<?xml version="1.0" encoding="utf-8" ?>
<Manifest>
  <Documentation Path="doc/readme.txt" DisplayType="Text"/>
  
  <ExtensibilityApplications>
    <ExtensibilityApplication Path="app-older-dir" ClientMinimum="*" ClientMaximum="19.8"/>
    <ExtensibilityApplication Path="app-latest" ClientMinimum="19.9" ClientMaximum="*"/>
  </ExtensibilityApplications>
</Manifest>

Notes:

  • Two ext apps are specified
    • Simphony POS clients with version up to 19.8
    • Simphony POS clients with version 19.9 and higher
  • The <ExtensibilityApplication> tags are processed in sequence. When a POS scans the package, it will match with the first application that matches its version.
  • In general, the ClientVersion is most useful for extension applications with DLLs. SIM and JS applications can check the version at runtime rather than encoding it into the manifest.xml, but this is a choice for the author.

metadata.xml

It is easiest to begin with a sample ‘metadata.xml’ file.

<?xml version="1.0" encoding="utf-8" ?>
<Metadata>
  <ContentEntries>
    <ContentEntry FileName="ops-root.js" HostType="OPS"/>
    <ContentEntry FileName="ts-root.js" HostType="TransactionServices"/>
    <ContentEntry FileName="extsrvc-root.js" HostType="ExtensibilityService"/>    
  </ContentEntries>
</Metadata>

Each directory specified by the must have a metadata.xml file. Key aspects of this file:

  • Each entry in metadata.xml corresponds to a file in the directory specified in manifest.xml. However, not all files in the directory require an entry in metadata.xml. Libraries, bitmaps or other content should not be specified.
  • Content type is inferred from the file name extension - .sim, .isl, .js, and .dll are the only files that generally need to exist in this file.
  • File entries in metadata.xml should only specify executable files: SIM, DLL, and JS. Images, text files, strings, and other contents do not need to be in metadata.xml and are ignored.
  • The attributes for correspond to configuration options in EMC Extension Application content.
    • string FileName
    • string HostType - only valid for JavaScript based Extension Application
    • bool MainSIMContent - only valid for SIM based Extension Application
    • string ZoneableKey
    • string Description
    • string WriteToDiskFileName
    • bool DoNotLoadDLL
    • string FileNameOrigin
    • bool WriteDLLIntoHandlersDirectory - only valid for .Net DLL based Extension Application
    • bool LocalEAS - only valid for JavaScript based Extension Application using HostType ExtensibilityService, it is ignored for any other HostType. Enables Extension Application Service (EAS) for this Extension Application on a non-CAPS workstation (excl. any Android device, i.e. only for Windows and Linux based workstations). The default behavior for EAS is to execute only on a CAPS workstation.

metadata.xml (SIM example)

<?xml version="1.0" encoding="utf-8" ?>
<Metadata>
  <ContentEntries>
    <ContentEntry FileName="main.isl" MainSIMContent="true"/> 
    <ContentEntry FileName="common.isl" WriteToDiskFileName="common.isl"/> 
  </ContentEntries>
</Metadata>

metadata.xml (.Net DLL example)

<?xml version="1.0" encoding="utf-8" ?>
<Metadata>
  <ContentEntries>
    <ContentEntry FileName="mylibrary.dll"/>
  </ContentEntries>
</Metadata>

Visual Representation

The diagrams more clearly demonstrate the package file structure.

There are only two hardcoded names in a package: manifest.xml and metadata.xml.

All other files’/directories’ names are encoded in these files.

Simplest package
Simplest package.


A full Javascript extensibility package
A full Javascript extensibility package


Javascript package with page controls, custom dialogs, etc
Javascript package with page controls, custom dialogs, etc

This image shows:

  • A ‘translation’ directory with hardcoded transaction files.
  • A page control directory with multiple page control ‘applications’
  • A custom dialog directory with multiple dialogs

Multiple Simphony POS client versions
Multiple Simphony POS client versions

AppContent

A new object was introduced in 19.7 to easily read content from a package or from the database. Each application type references AppContent in a different way:

  • SIM: @AppContent.
  • .Net Extensibility: OpsExtensibilityApplication.AppContent
  • JavaScript Extensibility: SimphonyExtensibilityAPI.Environment.AppContent

AppContent provides access to any extension application content, whether from the database or from the package. The object provides:

  • State information
  • Methods to read content from the package
  • Methods to read content from the database

General notes about reading content from a package:

  • The ReadPackage* methods will throw an exception if not executing from a package.
  • The ReadDatastore* methods are shortcuts to the standard datastore client methods for reading content.
  • The DefaultRvcID property is useful when running from transaction services or extensibility services. An extension application should be aware that an OPS workstation may change revenue centers and decide whether DefaultRvcID is applicable. (if there is no rvc-level content then DefaultRvcID is sufficient).
  • RootPath is the selected directory for the <ExtensionApplication> chosen from manifest.xml. In the samples provided, it will be “default”.
  • Applications can read content from virtual directories in the zip file. In the samples provided the applications read “data/file.txt”. Any directory structure is allowed
  • Use the forward slash for all directory access.

AppContent Definition

The class definition for AppContent is:

namespace Micros.PosCore.Extensibility.Package
{
    public class AppContent
    {
        // true if extension application executing in the context of a package
        public bool IsPackage { get; }

        // the default revenue center for the context of this extension application
        public int DefaultRvcID { get; }

        // the path of the package <ExtensionApplication> being executed, if in a package
        public string RootPath { get; }

        // read from package as a string
        public string ReadPackageText( string path )

        // read from package as a byte array
        public byte[] ReadPackageBytes( string path )

        // read list of file names for a directory in a package
        public string[] ReadPackageDirectory( string directory )

        // read from database as a string
        public string ReadDatastoreText( int revCtrID, string zoneableKey );

        // read from database as a string using the default rvc
        public string ReadDatastoreText( string zoneableKey );

        // read from database as a byte array
        public byte[] ReadDatastoreBytes( int revCtrID, string zoneableKey );

        // read from database as a byte array using the default rvc
        public byte[] ReadDatastoreBytes( string zoneableKey );
    }
}

Samples

Read content from a package

JavaScript Extensibility

const _api = SimphonyExtensibilityAPI;
const _appContent = _api_.Environment.AppContent;
function OnInitEvent(sender, args)
{
    let text = _appContent.ReadPackageText('data/file.txt');
    _api.Environment.Context.ShowMessage(`OnInitEvent: file.txt [${text}]`);
}

SIM

event init
    var text:a = @AppContent.ReadPackageText("data/file.txt")
    InfoMessage "message from main, file.txt [", text, "]"
endevent

.Net Extensibility

private EventProcessingInstruction App_OpsInitEvent( object sender, OpsInitEventArgs args )
{
    var text = this.AppContent.ReadPackageText( "data/file.txt" );
    OpsContext.ShowMessage( $"App_OpsInitEvent: file.txt [{text}]" );
    return EventProcessingInstruction.Continue;
}

Register package directory for page control source

Page control source can be read directly from the package. The html source does not have to be zipped up, it just needs to be in a directory. JavaScript Extensibility

const _api = SimphonyExtensibilityAPI;
const _pos = _api.Common.LoadPOS();
function registerPageControls()
{
    // allocate parameters
    let resourceParms = new _pos.Micros.PosCore.Extensibility.UserInterface.PageControlPackageDirectoryResourceParameters();

    // directory within the package. assume index.html is the start page
    resourceParms.DirectoryName = "pagectl/sample";

    // register
    _api.Environment.Context.RegisterPageControlResource(_api.Runtime.ApplicationName, "Sample", resourceParms);
}

FAQ

How do I determine where extension application content should be stored

A package is immutable. It cannot be changed by the customer. If there is site-specific configuration required for the Extension Application then it should be a separate Extension Application content entry.

The Extensibility Application can read the configuration directly from the datastore using the datastore client object OR the AppContent object.

Separate content entry

If your content is static (that is, it never changes) then it should remain in the package. An example of this is translation files.

If your content can be modified by the customer then it should be configured as a separate content entry.

Can I create a package from an existing extensibility application in EMC?

EMC provides a very limited feature to export an existing Extensibility Application to a local directory. This directory will contain the start of an extensibility package.

This directory is not intended to be complete. It is assumed that the developer will now modify the contents of that directory to make it a valid package.

Some of the limitations of the export package facility

  • It is not intended to be complete.
  • Only files that can be exported will be exported. For example, an encrypted SIM script cannot be exported, but it will be specified in the metadata.xml.
  • It does not modify any JS/SIM code to make them package-aware.

Exporting a package: 1. Click “Export To Package”.

Export To Package

  1. Read warning.

Read warning

  1. Select destination directory.

Select destination directory

  1. Directory has been written.

Directory has been written

How are SIM include statements specified in a package

SIM include statements are rather straightforward. A sample metadata.xml file for SIM includes would look like:

<?xml version="1.0" encoding="utf-8" ?>
<Metadata>
  <ContentEntries>
    <ContentEntry FileName="main.isl" MainSIMContent="true"/> 
    <ContentEntry FileName="common.isl" WriteToDiskFileName="common.isl"/> 
  </ContentEntries>
</Metadata>

Notes:

  • All SIM include files must be specified in metadata.xml.
  • WriteToDiskFileName is the name of the file in the “include” statement.
  • FileName is the name of the file in the package. It cannot be in a directory, it must be in the root directory specified in the current <ExtensionApplication> entry.
  • It is recommended that both these entries match.

What has to be done to convert an existing SIM application to a package

The SIM scripts can remain the same. However, metadata.xml must be configured properly for deal with include files.

How are JavaScript import statements specified in a package

JavaScript import statements are relatively trivial to use.

Notes:

  • Do not include imported files in metadata.xml.
  • The file name in the import statement is the filename in the package.
  • JS files can be in directories, e.g. import 'common/mathlib.js'.
  • Package root scripts cannot import files from the datastore.

What are technical advantages of using packages

Since the number and structure of files in the package are unlimited, there are a number of advantages to packages.

  • Writing modular Extensibility Applications in SIM and JavaScript is difficult to configure in EMC today. If your SIM application has 10 library SIM scripts, then a total of 11 SIM content entries must be created. This is tedious. With packages there is no penalty for breaking up a script application into multiple files. A 20,000 line SIM script can easily be broken up into 10 different files and included separately in the main script.
  • Custom dialog and page control html applications can be included in the package and read out of the package when instantiated/registered. There is no need for individual zip files of the web apps, just a directory to contain them all.
  • Versioning is much simpler. Configuring content version in EMC can easily become too complex to maintain. A package maintains multiple versions in isolated directories.
  • Content entries have a limit of 10mb. The zip compression can easily shrink a package to 5% of its original size, allowing the developer to include more files.
  • The zip format allows directories, which allows partitioning of all functional components in the package, rather than the flat structure of extension application content.

Legacy Extensibility Services and Packages

Implementation of ext packages was intentionally limited to:

  • OPS: sim, c#, js
  • Transaction Services: js
  • Extension Application Services (EAS): js

It was never intended for legacy .Net Extensibility Services to be supported via a package.

Extension Application Services in general are given 2 bits of functionality:

  • ability to receive messages from multiple external sources
  • ability to query the database directly via a DbConnection

If an Extensibility developer has a legacy .Net Extensibility Service that they wish to include in a package, the simplest answer is to:

  1. create a JavaScript Extension Application package for Extension Application Services
  2. include the legacy .Net dll in the package
  3. set LocalEAS to true if needed (Simphony 19.10 or later)
  4. The JavaScript Extension Application is just a wrapper around the .Net Extensibility Application, it can call “into” the .Net dll for each received message.
  5. The JavaScript Extension Application can pass the DataStore object to the .Net Extensibility Application.