• Back to Glue42 Enterprise Docs
Glue42 enterprise documentation

Reference Documentation

  • Back to Glue42 Enterprise Docs
Press/
  • Glue4Office
  • Bus
  • Connection
  • Excel
  • Interop
  • Logger
  • Metrics
  • Outlook
  • Shared Contexts
  • Word

Interop

1.6.5

The Interop API enables applications to:

  • offer functionality to other applications (JavaScript and native executables) by registering Interop methods
  • discover applications which offer methods
  • invoke (call) methods on the user's desktop and across the network
  • stream and subscribe for real-time data using the Streaming API.

We call applications which offer methods and streams Interop servers, and applications which consume them - Interop clients, and collectively - Interop instances.

Interop instances

Any running instance of an Interop application is identified by its Interop instance, which is a set of known key/value pairs uniquely identifying an application:

Environment and region are used to qualify an instance. Usually region is a geographical location and environment refers to the deployment model (development or production).

Key Example (Value) Description
application Client Portfolio Application name
region TICK42 e.g. EMEA, NA, APAC
environment TRAINING e.g. DEV, SIT, UAT, PROD
service null Optional namespace with a region and environment
machine Lambda User machine name
PID 2864 Process ID
user JSmith Currently logged on user

See also the Interop documentation for more details.

APIobject

Properties

Property Type Default Required Description
instance Instance

Instance of the current application.

Methods

  • createStream
  • invoke
  • invoke
  • methodAdded
  • methodRemoved
  • methods
  • methodsForInstance
  • register
  • registerAsync
  • serverAdded
  • serverMethodAdded
  • serverMethodRemoved
  • serverRemoved
  • servers
  • subscribe
  • unregister

createStreammethod

Signature

(methodDefinition: string | MethodDefinition, options?: StreamOptions, successCallback?: (args?: object) => void, errorCallback?: (error?: string | object) => void) => Promise<Stream>

Description

Creates a new Interop stream.

Parameters

Name Type Required Description
methodDefinition string | MethodDefinition

A unique string or a MethodDefinition for the stream to be registered.

options StreamOptions

The StreamOptions object allows you to pass several optional callbacks which let your application handle subscriptions in a more detailed manner.

successCallback (args?: object) => void

An optional handler to be called if the creation of the stream succeeds.

errorCallback (error?: string | object) => void

An optional handler to be called in case of an error when creating a stream.

Example

glue.interop
  .createStream({
    name: "MarketData.LastTrades",
    displayName: "Publishes last trades for a symbol",
    objectTypes: ["Symbol"],
    accepts: "String symbol",
    returns: "String symbol, Double lastTradePrice, Int lastTradeSize"
  })
  .then(stream =>
    setInterval(
      () =>
        stream.push({
          symbol: "GOOG",
          lastTradePrice: 700.91,
          lastTradeSize: 10500
        }),
      5000
    )
  )
  .catch(console.error);

invokemethod

Signature

(method: string | MethodDefinition, argumentObj?: object, target?: InstanceTarget, options?: InvokeOptions, success?: InvokeSuccessHandler<any>, error?: InvokeErrorHandler) => Promise<InvocationResult<any>>

Description

Invokes an Interop method with some arguments on target servers.

Parameters

Name Type Required Description
method string | MethodDefinition

The unique name or the MethodDefinition of the method to be invoked.

argumentObj object

A plain JavaScript object (or JSON) holding key/value pairs passed as named arguments to the handler of the registered Interop method.

target InstanceTarget

Specifies which servers to target. Can be one of: "best", "all", Instance, Instance[].

options InvokeOptions

An optional [InvokeOptions] object specifying the timeouts to discover a method and to wait for a method reply.

success InvokeSuccessHandler<any>

An InvokeSuccessHandler handler to be called if the invocation succeeds.

error InvokeErrorHandler

An InvokeErrorHandler handler to be called in case of error.

Example

glue.interop
  .invoke("Sum", { a: 37, b: 5 }) // everything else is optional
  .then(successResult => {
    console.log(`37 + 5 = ${successResult.returned.answer}`);
  })
  .catch(err => {
    console.error(`Failed to execute Sum ${err.message}`);
  });

invokemethod

Signature

(method: string | MethodDefinition, argumentObj?: object, target?: InstanceTarget, options?: InvokeOptions, success?: InvokeSuccessHandler<any>, error?: InvokeErrorHandler) => Promise<InvocationResult<any>>

Parameters

Name Type Required Description
method string | MethodDefinition
argumentObj object
target InstanceTarget
options InvokeOptions
success InvokeSuccessHandler<T>
error InvokeErrorHandler

methodAddedmethod

Signature

(callback: (method: MethodDefinition) => void) => UnsubscribeFunction

Description

Subscribes to the event which fires when a method is added for the first time by any application.

Parameters

Name Type Required Description
callback (method: MethodDefinition) => void

A handler to be called when the event fires.

methodRemovedmethod

Signature

(callback: (method: MethodDefinition) => void) => UnsubscribeFunction

Description

Subscribes to the event which fires when a method is removed from the last application offering it.

Parameters

Name Type Required Description
callback (method: MethodDefinition) => void

A handler to be called when the event fires.

methodsmethod

Signature

(filter?: MethodFilter) => MethodDefinition[]

Description

Returns all methods that match the passed filter. If no filter is specified, returns all methods.

Parameters

Name Type Required Description
filter MethodFilter

An object describing a filter matching one or more Interop methods.

methodsForInstancemethod

Signature

(server: Instance) => MethodDefinition[]

Description

Returns all Interop methods registered by a server.

Parameters

Name Type Required Description
server Instance

An Interop Instance identifying an application.

registermethod

Signature

(name: string | MethodDefinition, handler: (args: object, caller: Instance) => void | object) => Promise<void>

Description

Registers a new Interop method.

Parameters

Name Type Required Description
name string | MethodDefinition

A unique string or a MethodDefinition for the method to be registered.

handler (args: object, caller: Instance) => void | object

The JavaScript function that will be called when the method is invoked.

Example

glue.interop.register(
  {
    name: "Sum", // required - method name
    accepts: "int a, int b", // optional - parameters signature
    returns: "int answer" // optional - result signature
  },
  args => {
    // required - handler function
    return { answer: args.a + args.b };
  }
);

registerAsyncmethod

Signature

(name: string | MethodDefinition, handler: (args: object, caller: Instance, successCallback: (args?: object) => void, errorCallback: (error?: string | object) => void) => void) => Promise<void>

Description

Registers a new async Interop method. Async methods can delay returning the result from the method invocation.

Parameters

Name Type Required Description
name string | MethodDefinition

A unique string or a MethodDefinition for the method to be registered.

handler (args: object, caller: Instance, successCallback: (args?: object) => void, errorCallback: (error?: string | object) => void) => void

The JavaScript function that will be called when the method is invoked. Accepts two extra arguments - a success and an error callbacks. To return a result, you must call the success callback, or the error callback for errors.

serverAddedmethod

Signature

(callback: (server: Instance) => void) => UnsubscribeFunction

Description

Subscribes to the event which fires when an application offering methods is discovered.

Parameters

Name Type Required Description
callback (server: Instance) => void

A handler to be called when the event fires.

serverMethodAddedmethod

Signature

(callback: (info: { server: Instance; method: MethodDefinition; }) => void) => UnsubscribeFunction

Description

Subscribes to the event which fires when an application starts offering a method. This will be called every time a server starts offering the method, whereas methodAdded() will be called only the first time the method is registered.

Parameters

Name Type Required Description
callback (info: { server: Instance; method: MethodDefinition; }) => void

serverMethodRemovedmethod

Signature

(callback: (info: { server: Instance; method: MethodDefinition; }) => void) => UnsubscribeFunction

Description

Subscribes for the event which fires when a server stops offering a method. This will be called every time a server stops offering the method, whereas methodRemoved() will be called only when the method is removed from the last application offering it.

Parameters

Name Type Required Description
callback (info: { server: Instance; method: MethodDefinition; }) => void

A handler to be called when the event fires.

serverRemovedmethod

Signature

(callback: (server: Instance) => void) => UnsubscribeFunction

Description

Subscribes to the event which fires when an app offering methods stops offering them or exits.

Parameters

Name Type Required Description
callback (server: Instance) => void

A handler to be called when the event fires.

serversmethod

Signature

(filter?: MethodFilter) => Instance[]

Description

Returns all Interop aware applications. Optionally, the list can be filtered to return only servers providing specific Interop method(s) by passing a methodFilter.

Parameters

Name Type Required Description
filter MethodFilter

An object describing a filter matching one or more Interop methods.

subscribemethod

Signature

(methodDefinition: string | MethodDefinition, parameters?: SubscriptionParams) => Promise<Subscription>

Description

Subscribes to an Interop stream.

Parameters

Name Type Required Description
methodDefinition string | MethodDefinition

The unique name or the MethodDefinition of the stream to subscribe to.

parameters SubscriptionParams

An optional SubscriptionParams object with parameters.

Example

glue.interop
  .subscribe("MarketData.LastTrades", {
    arguments: { symbol: "GOOG" },
    target: "all"
  })
  .then(subscription => {
    // use subscription
  })
  .catch(error => {
    // subscription rejected or failed
  });

unregistermethod

Signature

(definition: string | MethodDefinition) => void

Description

Unregisters an Interop method.

Parameters

Name Type Required Description
definition string | MethodDefinition

The unique name or the MethodDefinition of the method to be unregistered.

Instanceobject

Description

Each Interop application is identified by its Interop instance, which is a set of known key/value pairs.

Properties

Property Type Default Required Description
api string

API version

application string

Unique application name.

applicationName string

Application name

environment string

Environment in which the application is running.

instance string

(Glue42 Desktop 3.0 only) Unique string identifying the application.

isLocal boolean

(Glue42 Desktop 3.0 only) A flag indicating whether the instance is running on a local machine or not. Taken into account when a Gateway mesh is present - local instances are preferred when invoking methods.

machine string

Name of the machine the instance is running on.

peerId string

(Glue42 Desktop 3.0 only) Gateway peer ID of the instance.

pid number

Process ID of the instance.

region string

Region in which the application is running.

service string

Service string of the application.

user string

Name of the user who has started the instance.

windowId string

(Glue42 Desktop 3.0 only) Window ID of the instance. Only set if running in a Glue42 window.

Methods

  • getMethods
  • getStreams

getMethodsmethod

Signature

() => MethodDefinition[]

Description

Returns all methods registered by that instance.

getStreamsmethod

Signature

() => MethodDefinition[]

Description

Returns all streams registered by that instance.

InvocationResultobject

Description

Extends InvocationResultCore. Results from a method invocation.

Properties

Property Type Default Required Description
all_errors any[]

An array of error objects.

all_return_values InvocationResultCore<T>[]

An array of invocation results.

called_with any

Arguments of the invocation.

executed_by Instance

Instance of the application that executed the method.

message string

Message from the application that executed the method.

method MethodDefinition

Method definition of the method that was invoked.

returned T

Returned object.

status number

Status sent by the application that executed the method.

InvocationResultCoreobject

Description

Result from a method invocation.

Properties

Property Type Default Required Description
called_with any

Arguments of the invocation.

executed_by Instance

Instance of the application that executed the method.

message string

Message from the application that executed the method.

method MethodDefinition

Method definition of the method that was invoked.

returned T

Returned object.

status number

Status sent by the application that executed the method.

InvokeOptionsobject

Description

Method invocation options.

Properties

Property Type Default Required Description
methodResponseTimeoutMs number 10000

Timeout to wait for a method reply.

waitTimeoutMs number 3000

Timeout to discover the method, if not immediately available.

MethodDefinitionobject

Description

An object describing an Interop method registered by an application.

Properties

Property Type Default Required Description
accepts string

Signature describing the parameters that the method expects.

description string

Description of what the method does. Useful for documentation purposes and for UI clients.

displayName string

The actual name of the method, used in UI applications.

getServers () => Instance[]

Returns all servers that provide the method.

name string

The name of the method. Must be unique.

objectTypes string[]

The entities this method is meant to work with.

returns string

Signature describing the properties of the object the method returns.

supportsStreaming boolean

If true, the method is a stream.

version number

Method version.

MethodFilterobject

Description

An object describing a filter matching one or more Interop methods.

Properties

Property Type Default Required Description
accepts string

Signature describing the parameters that the method expects.

description string

Description of what the method does. Useful for documentation purposes and for UI clients.

displayName string

The actual name of the method, used in UI applications.

name string

The name of the method. Must be unique.

objectTypes string[]

The entities this method is meant to work with.

returns string

Signature describing the properties of the object the method returns.

OnClosedInfoobject

Description

Addition information around subscription being closed

Properties

Property Type Default Required Description
message string
requestArguments object
server Instance
stream { info: MethodDefinition; }

Streamobject

Description

Object describing an Interop stream.

Properties

Property Type Default Required Description
definition MethodDefinition

Stream definition object.

name string

Name of the stream.

Methods

  • branches
  • branches
  • branches
  • close
  • push
  • subscriptions

branchesmethod

Signature

() => StreamBranch[]

Description

Returns the list of available stream branches. If key is specified, returns the corresponding stream branch or null.

branchesmethod

Signature

() => StreamBranch[]

Parameters

Name Type Required Description
key string

branchesmethod

Signature

() => StreamBranch[]

Parameters

Name Type Required Description
key string

closemethod

Signature

() => void

Description

Closes the stream. This will close all subscriptions.

pushmethod

Signature

(data: object, branches?: string | string[]) => void

Description

Push data to the stream. If a branches argument is passed, the data will be sent to the specified stream branch(es) only.

Parameters

Name Type Required Description
data object

Data to push.

branches string | string[]

To which branch(es) to push data.

subscriptionsmethod

Signature

() => StreamSubscription[]

Description

Returns a list of active subscriptions to the stream.

StreamBranchobject

Description

A stream branch created by the application.

Properties

Property Type Default Required Description
key string

Branch key.

Methods

  • close
  • push
  • subscriptions

closemethod

Signature

() => void

Description

Closes the stream branch.

pushmethod

Signature

(data: object) => void

Description

Pushes data to this branch only.

Parameters

Name Type Required Description
data object

Data to push.

subscriptionsmethod

Signature

() => StreamSubscription[]

Description

All subscriptions to that branch.

StreamDataobject

Description

Stream data received by the subscriber.

Properties

Property Type Default Required Description
data any

Data from the stream.

message string

Message from the publisher of the stream.

private boolean

If true, the data was sent to this application only.

requestArguments object

Arguments used when the subscription was made.

server Instance

Instance of the application publishing the stream.

StreamOptionsobject

Description

Optional handlers that can be supplied when creating streams.

Properties

Property Type Default Required Description
subscriptionAddedHandler (request: StreamSubscription) => void

Subscribes to the event which fires when a stream subscription is added.

subscriptionRemovedHandler (request: StreamSubscription) => void

Subscribes to the event which fires when a stream subscription is removed.

subscriptionRequestHandler (request: SubscriptionRequest) => void

Subscribes for subscription requests. These can be accepted, rejected or accepted on a custom branch. If this handler is attached, each request should be explicitly accepted.

StreamSubscriptionobject

Description

An object describing a subscription to an Interop stream.

Properties

Property Type Default Required Description
arguments any

Arguments used when the subscription was made.

branchKey string

The key of the stream branch to which the subscription was made.

instance Instance

Instance of the subscriber.

stream Stream

The stream to which the subscription was made.

Methods

  • close
  • push

closemethod

Signature

() => void

Description

Closes the subscription. This will not close the stream.

pushmethod

Signature

(data: object) => void

Description

Pushes data to this subscription only.

Parameters

Name Type Required Description
data object

Data to push.

Subscriptionobject

Description

Stream subscription made by an application.

Properties

Property Type Default Required Description
requestArguments object

Arguments used to make the subscription.

serverInstance Instance
servers Instance[]

Instances of the applications providing the stream, that we have subscribed to

stream MethodDefinition

Stream definition.

Methods

  • close
  • onClosed
  • onConnected
  • onData
  • onFailed

closemethod

Signature

() => void

Description

Closes the subscription.

onClosedmethod

Signature

(callback: (info: OnClosedInfo) => void) => void

Parameters

Name Type Required Description
callback (info: OnClosedInfo) => void

onConnectedmethod

Signature

(callback: (server: Instance, reconnect: boolean) => void) => void

Parameters

Name Type Required Description
callback (server: Instance, reconnect: boolean) => void

onDatamethod

Signature

(callback: (data: StreamData) => void) => void

Parameters

Name Type Required Description
callback (data: StreamData) => void

onFailedmethod

Signature

(callback: (err: any) => void) => void

Parameters

Name Type Required Description
callback (err: any) => void

SubscriptionParamsobject

Description

Optional object with parameters passed to subscribe() when subscribing to a stream.

Properties

Property Type Default Required Description
arguments object

A plain JavaScript object (or JSON) holding key/value pairs passed as named arguments to the handler of the registered Interop stream.

methodResponseTimeout number 30000

Timeout to wait for a stream reply.

onClosed () => void

Subscribe for the event which fires when the subscription is closed.

onConnected (server: Instance, reconnect: boolean) => void
onData (data: StreamData) => void

Subscribe for the event which fires when new data is received.

target InstanceTarget

Specifies which servers to target. Can be one of: "best", "all", Instance, Instance[].

waitTimeoutMs number 30000

Timeout to discover the stream, if not immediately available.

SubscriptionRequestobject

Description

A subscription request object handled by the server that has created the stream. It can be accepted or rejected.

Properties

Property Type Default Required Description
arguments object

Arguments passed with the subscription request.

instance Instance

Instance of the application that wants to subscribe to the stream.

Methods

  • accept
  • acceptOnBranch
  • reject

acceptmethod

Signature

() => void

Description

Accepts the subscription request.

acceptOnBranchmethod

Signature

(branchKey: string) => void

Description

Accepts the request on a stream branch.

Parameters

Name Type Required Description
branchKey string

Key of the branch on which to accept the request.

rejectmethod

Signature

(reason?: string) => void

Description

Rejects the request.

Parameters

Name Type Required Description
reason string

Reason for rejecting the request.

InstanceTargetenumeration

Description

Which Interop server(s) to target when invoking Interop methods or subscribing to Interop streams.

  • "best"
  • "all"
  • "skipMine"
  • Instance
  • Instance[]

InvokeErrorHandlerfunction

Signature

(error: { method: MethodDefinition; called_with: object; executed_by: Instance; message: string; status: number; returned: object; }) => void

Description

Handler to be called in case of method invocation error.

Parameters

Name Type Required Description
error { method: MethodDefinition; called_with: object; executed_by: Instance; message: string; status: number; returned: object; }

An error object.

InvokeSuccessHandlerfunction

Signature

(result: InvocationResult<T>) => void

Description

Handler to be called if the method invocation succeeds.

Parameters

Name Type Required Description
result InvocationResult<T>

Result from the method invocation.

  • © 2023 Glue42
  • Home
  • Privacy policy
  • Contact Sales
  • Glue42.com
  • Tick42.com
  • Overview
  • API
  • Instance
  • InvocationResult
  • InvocationResultCore
  • InvokeOptions
  • MethodDefinition
  • MethodFilter
  • OnClosedInfo
  • Stream
  • StreamBranch
  • StreamData
  • StreamOptions
  • StreamSubscription
  • Subscription
  • SubscriptionParams
  • SubscriptionRequest
  • InstanceTarget
  • InvokeErrorHandler
  • InvokeSuccessHandler
Navigate
Go