Title and Copyright Information

Oracle® MICROS Simphony

Simphony JavaScript Extensibility API Reference Guide

Release 19.9

September 2025

Introduction

JavaScript Extensibility will provide the same functionality around OpsContext and DataStore as SIM and .Net Extensibility provide today. It will provide the ability to subscribe to the same events that exist today. Transaction Services and Extension Application Service (EAS) will introduce a new API.
JavaScript Extensibility executes under Windows, Linux and Android and provides the same API (excl. platform specific limitations)
JavaScript Extensibility executes under OPS, Transaction Services and Kiosk and handles the appropriate events of the client.
Replacing / Updating JavaScript does not require any ServiceHost restart, subject to certain limitations.
Ability to debug JavaScript as much as technically feasible and without creating any security concerns is available
JavaScript Extensibility will utilize the existing HTML5 custom dialogs for any custom UI required with OPS. Any custom UI is handled as a modal dialog. Any new UI requirements, such as in-page html controls, will not be covered as part of the initial release.

Solution Overview

History of Simphony Extensibility

Before Simphony version 19.6 two different Extensibility features were available, these are part of the product almost since its initial release.

SIM (System Interface Module) which is an interpreter using a proprietary scripting language named Interface Script Language (ISL). No development environment is needed to produce a SIM script. SIM scripts are imported into the Simphony EMC. SIM scripts are not written out to the disk, they are only present in memory on the POS client. SIM permits to load and use .Net Framework assemblies as well as 3rd party assemblies. SIM scripts that are not making use of any assembly will reload without any restart of POS client. If any assembly is in use a restart is required to fully reload an update. SIM supports POS clients running Windows, Linux or Android.
.Net Extensibility which is a published interface/API that allows 3rd party to build assemblies and import those into Simphony EMC. A development environment is required, next to basic understanding on how to build .Net Extensibility. Extensibility assemblies are synced to the POS client DB. Writing them out to disk and loading an assembly will only happen after the POS client was restarted. .Net Extensibility also includes Extension Application Service, which allows message based functionality outside of POS operations. .Net Extensibility supports POS client running Windows or Linux

No published Simphony Extensibility was available for Simphony Transaction Services.

Introduction of Simphony JavaScript Extensibility

With Simphony version 19.6 a new Simphony JavaScript Extensibility API is introduced that includes the following features:

POS Client Extensibility
Extension Application Service (EAS)
Transaction Services Extensibility

POS Client

POS Client JavaScript Extensibility will reload without any client restart. POS Client JavaScript Extensibility can raise UI dialogs, incl. Custom HTML5 dialogs.

Transaction Services

Transaction Services JavaScript Extensibility will only reload after a client restart. Transaction Services JavaScript Extensibility can never raise UI dialogs.

Extension Application Service (EAS)

Different to .Net Extensibility, EAS JavaScript Extensibility will only run on the CAPS workstation. Functionality to run EAS JavaScript Extensibility on any other workstation is currently not planned. EAS JavaScript Extensibility will reload without any client restart. EAS JavaScript Extensibility can never raise UI dialogs.

Remarks around JavaScript

Simphony JavaScript Extensibility uses an engine to process the JavaScript provided. This is NOT a browser JavaScript environment. It does not run in CEF (Chromium Embedded Framework) that is utilized for i.e. Custom HTML5 dialogs. The JavaScript engine does not contain a DOM, Window or built-in browser objects like XmlHttpRequest. Any 3rd party library, like JQuery or React, that depends on a browser DOM or the presence of XmlHttpRequest will not load.

Simphony JavaScript Extensibility has no relation to any JavaScript being utilized within OPS Custom HTML5 dialogs, these are separate entities. OPS Custom HTML5 dialogs are using a dedicated Simphony JavaScript API named POSDialogAPI, without any relation to Simphony JavaScript Extensibility.

Simphony JavaScript Extensibility has no relation to any JavaScript being utilized within the HTML Kiosk, these are separate entities. HTML Kiosk is using a dedicated JavaScript API named SimphonyKioskAPI, without any relation to Simphony JavaScript Extensibility.

EMC Configuration

Each Host-Type / Environment (OPS, Transaction Services or Extension Application Service) must use its own “root script”, i.e. if support for OPS and STS is required, you need to have one root-script for OPS and one root-script for Transaction Services.

This is an administrative limitation that is enforced to ensure the correct script is loaded for the host-type in use. Nothing prevents you from keeping a root script to the bare minimum and implement any logic in a ‘common’ script (that can be used via import). On the other side if there is only OPS support required, nothing stops you from having all code reside in the single root-script.

Extension Application

Configuring Extension Application requires a privilege in the EMC Roles module. Please ensure that this was granted.

In EMC, select the Enterprise, property, revenue center, or zone, click Setup, and then click Extension Application.

Add a new record or edit an existing Extension Application record. This will present on overview of any Application Content that is available.

To insert a new JavaScript Application Content click on Insert Application Content. Provide a meaningful value for Zoneable Key and optionally a description. In the following form, set Content Type to 22 - Javascript and either enter your script or import this from a file.

Switch back to the General tab and set the Host Type to the correct value as shown in the table below.

Host Type	Description
OPS	Used for an Extension Application running within the POS Client
Transaction Services	Used for an Extension Application running within Transaction Services. Requires a service script next to the root script
Extensibility Service	Used for an Extension Application running as Extension Application Service. Requires a service script next to the root script. An Extension Application Service will only be executed on the CAPS workstation

Calling a JavaScript extensibility method via a Page button

globalThis is the shorthand way to expose a method to the global namespace of the JavaScript engine. Functions in general are private.

The button should be configured as Function | Sim Inquire. The button “Argument” should be:

extAppName:functionName[:arg1[:arg2[:arg3]]]

for example:

myExtApp:myFunction
myExtApp:myFunction:1
myExtApp:myFunction:1:localhost:tcp

In each case the arguments are pass in as strings.

globalThis examples

//---------------------------------------------------
// No arguments for the exposed method
//---------------------------------------------------
globalThis.myFunction= function ()
{
    //Your code
}
//---------------------------------------------------
// One argument for the exposed method
//---------------------------------------------------
globalThis.myFunction= function (a1)
{
    //Your code
}
//---------------------------------------------------
// Two arguments for the exposed method
//---------------------------------------------------
globalThis.myFunction= function (a1, a2)
{
    //Your code
}

Javascript API Object

The javascript engine has one object injected into its namespace: SimphonyExtensibilityAPI.

All API methods/properties are available on this object.
The API object is grouped into various namespaces; an API of APIs.
Each sub-API contains methods/properties specific to its area of interest.

Notes:

While many of these methods/properties are not available elsewhere, some are shortcuts to existing functionality. The shortcuts are provided when using existing functionality is syntactically cumbersome.
- “AllocateXYZ()” methods are useful as the script writer does not have to remember where the objects are available in the PosCore namespace.
- “DynamicEnum” methods return javascript-friendly enumerations.
It should be understood that this documentation is for the latest version of the API. It can be difficult to determine what is available in your version of software. Therefore, we have added a method on the API itself to provide every available method and property on that version. The SimphonyExtensibilityAPI.GetDocumentation() method provides a very compact representation of the API and can be useful when developing in many versions of software.

SimphonyExtensibilityAPI

Method / Property	Description
`string GetDocumentation( string format )`	This method returns a string which lists the objects/properties/methods of the API for that version of ServiceHost. The returned string can be saved to disk by the JS extensibility application using the System.IO.File.WriteAllText() method. The parameter specifies the format of the return string, currently ignored. The current implementation returns a C#-like API specification.

Logger

The Logger object defines properties/methods for logging to the ServiceHost EGateway log file. All logging is filtered through the “ExtApps” setting in wwwroot_LoadHandlers.txt. The “ExtApps” setting applies to all extension applications. One cannot raise a log level for a particular extension application.

Method / Property	Description
`Log( string text )`	logs a single line of text to the ServiceHost egateway log. Equivalent to LogAlways().
`Log( int logLevel‚ string text )`	logs a single line of text to the ServiceHost egateway log with respect to the ExtApps setting. For example, if the ExtApps setting is 2, then the line will be written to the log if the logLevel parameter is 0-2.
`LogAlways( string text )`	always logs a single line of text to the ServiceHost egateway log
`LogLightFlow( string text )`	logs a single line of text to the ServiceHost egateway log when the ExtApps setting is 1 or higher.
`LogGeneralFlow( string text )`	logs a single line of text to the ServiceHost egateway log when the ExtApps setting is 2 or higher.
`LogDetailFlow( string text )`	logs a single line of text to the ServiceHost egateway log when the ExtApps setting is 3 or higher.
`LogBufferDumps( string text )`	logs a single line of text to the ServiceHost egateway log when the ExtApps setting is 4 or higher.
`LogError( string text )`	always logs a single line of text to the ServiceHost egateway log with the “error” indication.
`LogWarn( string text )`	always logs a single line of text to the ServiceHost egateway log with the “warning” indication.
`LogInfo( string text )`	always logs a single line of text to the ServiceHost egateway log with the “info” indication.
`LogDebug( string text )`	always logs a single line of text to the ServiceHost egateway log with the “debug” indication.
`LogException( string text‚ Exception ex )`	always logs a single line of text to the ServiceHost egateway log. The exception must be provided.
`string Prefix`	string which identifies the current running context. This includes the ext app name, script name, engine type (root, worker,…), engine ID. This is useful for console.log() functions. Every Logger.Log() message contains this prefix.
`int WsLogVerbosity`	This property corresponds to the “log verbosity” setting in the workstation entry for this ServiceHost. It is configured in EMC.

Instance

The Instance object provides data specific to that specific javascript engine instance of the script that accesses it.

Method / Property	Description
`string EngineType`	the engine type: “Root”, “Worker”, “Service”
`long EngineID`	unique ID for the currently running engine, similar to a thread id. Engine IDs are unique throughout the lifetime of the ServiceHost application. Engine IDs can be used to send messages from one engine to another, as well as identifying log statements for a particular engine
`string EngineName`	The user-supplied name of the worker engine. This is set the WorkerParameters object when creating a worker. If an engine name is not supplied one will be generated automatically.
`ApiWorkerParameters WorkerParameters`	The worker parameters object supplied when creating the worker engine. This is valid only for worker engines and is null otherwise. The ‘argument’ property for the worker can be access from this object.
`ApiServiceParameters ServiceParameters`	The service parameters object supplied when specifying

Runtime

The Runtime object supplies properties/methods that pertain to the javascript extensibility environment.

Method / Property	Description
`ApiWorkerParameters AllocateWorkerParameters()`	This method should be used by a script to allocate parameters required for creating a worker engine.
`CreateWorker( ApiWorkerParameters parms )`	Creates a worker engine. The engine will start running soon after this method call. The engine will run on a separate thread and will have access to the parameters used to create it.
`ApiServiceParameters AllocateServiceParameters()`	method to allocate a ServiceParameters object, used by transaction services and extension application services to define the service script.
`ApiServiceParameters SetService( ApiServiceParameters serviceParameters )`	method to set the service script for transaction services and Extension Application Service
`HostType`	enumeration of the host type of the ext app: OPS, TransactionServices, ExtensibilityService
`string ApplicationName`	the name of the extensibility application for that script
`int ServiceHostID`	the current ServiceHostID of the workstation
`bool ShutdownPending`	true if a shutdown is pending. Worker engines can use this to detect if a service host shutdown is pending OR the ext app is being destroyed.

ApiWorkerParameters

Method / Property	Description
`string ContentName`	The extension application content zoneable key for the worker script. This field must be set by the script.
`string Argument`	Optional string argument to be passed to a worker.
`string Name`	Optional name for a worker engine.
`long ParentEngineID`	The engine ID of the engine that created the worker. This ID can be used to send messages back to a parent engine.

ApiServiceParameters

Method / Property	Description
`string ContentName`	The extension application content zoneable key for the service script. This field must be set by the script.

Eventing

Method / Property	Description
`bool SubscribeToEvent( string eventID‚ object method )`	subscribe to extensibility event, equivalent to similar method in C#/SIM
`bool UnSubscribeFromEvent( string eventID‚ object method )`	unsubscribe from extensibility event, equivalent to similar method in C#/SIM
`PostMessage( long engineID‚ string message )`	post message to a different engine in the same ext application/host type context. An OPS engine cannot send a message to a transaction services engine.
`PostMessageToRoot( string message )`	shortcut for PostMessage() to the root engine of the currently running ext app
`object GetNextEvent( int timeoutMS )`	worker engines can receive events, this method is used to pull the next event from the event queue associated with that engine
`WaitForHtmlDialog( ExtensibilityHtmlDialogParameters parms‚ object method )`	similar to the WaitForHtmlDialog in SIM
`Continue`	shortcut to EventProcessingInstruction.Continue
`AbortEvent`	shortcut to EventProcessingInstruction.AbortEvent
`AbortEventMonitorProcessingAndContinueEvent`	shortcut to EventProcessingInstruction.AbortEventMonitorProcessingAndContinueEvent

Common

Method / Property	Description
`SleepMS( int milliseconds )`	shortcut to System.Threading.Thread.Sleep( milliseconds )
`AllocateByteList()`	shortcut to allocate a generic byte list
`AllocateStringList()`	shortcut to allocate a generic string list
`object AllocatePosPrinterData()`	shortcut to allocate PosPrinterData without parameters
`object AllocatePosPrinterData( TextAttribute textAtt‚` `TextAlignment textAlign‚ TextSize textSize )`	shortcut to allocate PosPrinterData with parameters
`ExtensibilityDataInfo AllocateExtensibilityDataInfo( string name‚` `string dataName‚ string textData )`	use this to allocate extensibility data based on string
`ExtensibilityDataInfo AllocateExtensibilityDataInfo( string name‚` `string dataName‚ Byte[] binData )`	use this to allocate extensibility data based on Byte array
`object LoadCommonNetAsssembles( String[] assemblies )`	load common .net assemblies and return reference (mscorlib, System, System.Core)
`object LoadPosCore()`	load PosCore assembly and return reference
`object LoadPosCommonClasses()`	load PosCommonClasses assembly and return reference
`object LoadOps()`	load Ops assembly and return reference
`string ReadConfigurationValue( string key‚ string dflt )`	read a configuration value from web.config.txt
`int ReadConfigurationValue( string key‚ int dflt )`	read a configuration value from web.config.txt and convert to an integer

Context (any Host-Type)

Method / Property	Description
`string MapRootPath( string fileName )`	Get application root path based on file-name provided
`string PropertyNumber`	Property number as configured in EMC
`long PropHierStrucID`	internal Hierarchy Structure ID for this Property
`int PropertyID`	internal Property ID
`string PropertyName`	Property name as configured in EMC
`string WorkstationName`	Workstation name as configured in EMC
`int WorkstationNumber`	Workstation number as configured in EMC
`int WorkstationID`	internal Workstation ID
`string HostName`	Host-name of the device
`int OrganizationId`	internal Organization ID
`int LocationId`	internal Location ID
`int CurrentLangId`	internal, current Language ID
`int CurrentLangObjNum`	current Language object number
`Networking Networking`	Networking object
`int ServiceHostID`	internal ServiceHost ID
`string EGatewayURL`	URL of the EGateway resource
`string Version`	Version string of Simphony
`string IPaddress`	IP address of the device
`ApiOperatingSystem OperatingSystem`	see ApiOperatingSystem members below

ApiOperatingSystem

Method / Property	Description
`bool IsWin32`	True when running under Windows
`bool IsNotWin32`	True for both Android and Linux
`bool IsAndroid`	True when running under Android
`bool IsLinux`	True when running under Linux

JavaScript Extensibility POS Transactions

Simphony JavaScript Extensibility