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.
There will be two ways that a package can be created:
manifest.xml, a simple XML file which specifies
minimal information about the package itselfmetadata.xml file for that Extensibility
Application, indicating various options similar to what is configured in
EMC (e.g. Main SIM Content)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.
This method uses the built-in Windows “Send to | Compressed (zipped) folder)” feature.
manifest.xml resides) on local disk.This method uses the popular 7-zip program to create the package, optionally including a password to protect it.
manifest.xml resides) on local disk.The following batch file can be used to create the package directory. The name of the package will be prompted.
@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.
popdAn extensibility package requires at a minimum:
manifest.xmlmetadata.xmlFurthermore, both metadata.xml and executables must be
in a directory below the manifest.xml location.
<?xml version="1.0" encoding="utf-8" ?>
<Manifest>
<ExtensibilityApplications>
<ExtensibilityApplication Path="default" ClientMinimum="*" ClientMaximum="*"/>
</ExtensibilityApplications>
</Manifest>Notes:
<ExtensibilityApplication> tag specifies an
extensibility application’s POS version and the directory where it
sits.<?xml version="1.0" encoding="utf-8" ?>
<Manifest>
<Documentation Path="doc/readme.txt" DisplayType="Text"/>
<ExtensibilityApplications>
<ExtensibilityApplication Path="default" ClientMinimum="*" ClientMaximum="*"/>
</ExtensibilityApplications>
</Manifest>Notes:
<Documentation> tag specifies where the
documentation file exists for this package.<?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:
<ExtensibilityApplication> tags are processed
in sequence. When a POS scans the package, it will match with the first
application that matches its version.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
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.string FileNamestring HostType - only valid for JavaScript based
Extension Applicationbool MainSIMContent - only valid for SIM based
Extension Applicationstring ZoneableKeystring Descriptionstring WriteToDiskFileNamebool DoNotLoadDLLstring FileNameOriginbool WriteDLLIntoHandlersDirectory - only valid for
.Net DLL based Extension Applicationbool 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.<?xml version="1.0" encoding="utf-8" ?>
<Metadata>
<ContentEntries>
<ContentEntry FileName="main.isl" MainSIMContent="true"/>
<ContentEntry FileName="common.isl" WriteToDiskFileName="common.isl"/>
</ContentEntries>
</Metadata><?xml version="1.0" encoding="utf-8" ?>
<Metadata>
<ContentEntries>
<ContentEntry FileName="mylibrary.dll"/>
</ContentEntries>
</Metadata>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.
This image shows:
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:
@AppContent.OpsExtensibilityApplication.AppContentSimphonyExtensibilityAPI.Environment.AppContentAppContent provides access to any extension application content, whether from the database or from the package. The object provides:
General notes about reading content from a package:
ReadPackage* methods will throw an exception if not
executing from a package.ReadDatastore* methods are shortcuts to the
standard datastore client methods for reading content.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).<ExtensionApplication> chosen from manifest.xml. In
the samples provided, it will be “default”.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 );
}
}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;
}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);
}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.
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.
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
metadata.xml.Exporting a package: 1. Click “Export To 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:
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.The SIM scripts can remain the same. However,
metadata.xml must be configured properly for deal with
include files.
JavaScript import statements are relatively trivial to use.
Notes:
import 'common/mathlib.js'.Since the number and structure of files in the package are unlimited, there are a number of advantages to packages.
Implementation of ext packages was intentionally limited to:
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:
If an Extensibility developer has a legacy .Net Extensibility Service that they wish to include in a package, the simplest answer is to:
LocalEAS to true if needed (Simphony 19.10 or
later)