Internal communication Interface Service

This service enables Solution-to-Solution communication (e.g. link application and connector) by exposing the solution as a service. From this service, you can define 'operations' that can be called by subscribing solutions. Other solutions can then subscribe to this interface and use the defined operations as they would with any other service. Event triggers are also supported to send notifications to one or all subscribers.

Operations

• Interface.getSubscriber() - Get subscribers details
• Interface.listSubscribers() - List subscribers
• Interface.setSubscriber() - Set subscribers details
• Interface.trigger() - Send an event to the service subscribers.
• Interface.triggerOne() - Send an event to the given service subscriber.

Events

• subscriberAdded - New subscription
• subscriberRemoved - Subscription removal
• subscriberUpdated - Subscription update
• CustomEvent - Interface operation handler

---

Configuration parameters

Please note that bold arguments are required, while italic arguments are optional.

Name	Type	Description
default_script_key	^(?![0-9])[a-zA-Z0-9]{2,63}$	The default script key of the exposed solution service. This key can be used as alias from subscribers scripting logic instead of the id. Default to name (trimmed from special characters) or solution_id values.
name	string	Custom name used for visualization purpose. Default using the default_script_key value.
description	string	The Service description which will be visible by potential subscribers; be specific.
contact	object	Service author, exposed to subscribers as contact information.
contact.name	string	Contact name
contact.email	string(email)	Contact email
tags	[ string {1..20} ] {..10}	Service grouping & search purpose
type	"S", "P"	Indicates whether the service uses a Product or an Application template. Default: "S"
whitelist	[ string ]	List of businesses allowed to use this service. Default: []
parameters	[ object ]	Configuration parameters used by this service, and exposed to user.
parameters[].name	^[a-zA-Z][a-zA-Z0-9_]{2,99}$	Parameter Name
parameters[].type	"string", "boolean", "number", "integer", "array", "object"	Parameter Type Default: "string"
parameters[].items	object	Schema used for validating payload
parameters[].items.enum	[ string ]	Enumeration validation
parameters[].items.type	"array", "boolean", "integer", "null", "number", "object", "string"	Type validation
parameters[].items.items	object	Array validation
parameters[].items.title	string	Payload name, also used as event handler Lua function parameter name Default: "event"
parameters[].items.format	string	String format validation
parameters[].items.default	boolean, integer, null, number, string	Default value
parameters[].items.maximum	number	Maximum number validation Maximum: 1000000000
parameters[].items.minimum	number	Minimum number validation Maximum: 1000000000
parameters[].items.pattern	string(regex)	Regex string validation
parameters[].items.examples	array	Example of payload
parameters[].items.maxItems	integer	MaxItems array validation Maximum: 1000000000
parameters[].items.minItems	integer	MinItems array validation Maximum: 1000000000
parameters[].items.required	[ string ]	Required properties object validation Default: []
parameters[].items.maxLength	integer	MaxLength string validation Maximum: 1000000000
parameters[].items.minLength	integer	MinLength string validation Maximum: 1000000000
parameters[].items.properties	object	Properties object validation Default: {}
parameters[].items.description	string	Parameter description
parameters[].items.uniqueItems	boolean	UniqueItems array validation
parameters[].items.maxProperties	integer	MaxProperties object validation Maximum: 1000000000
parameters[].items.minProperties	integer	MinProperties object validation Maximum: 1000000000
parameters[].items.additionalItems	object	AdditionalItems array validation
parameters[].items.exclusiveMaximum	number	ExclusiveMaximum number validation Maximum: 1000000000
parameters[].items.exclusiveMinimum	number	ExclusiveMinimum number validation Maximum: 1000000000
parameters[].items.patternProperties	object	PatternProperties object validation Default: {}
parameters[].items.additionalProperties	object	AdditionalProperties object validation
parameters[].properties	object	List of properties
parameters[].description	string	A text description explaining the parameter function.
operations	[ object ]	Operations exposed by this service.
operations[].name	^[a-zA-Z][a-zA-Z0-9]+$	Name used from scripting environment.
operations[].script	string(lua)	Script executed to handle the event.
operations[].response	object	Schema used for validating payload
operations[].response.enum	[ string ]	Enumeration validation
operations[].response.type	"array", "boolean", "integer", "null", "number", "object", "string"	Type validation
operations[].response.items	object	Array validation
operations[].response.title	string	Payload name, also used as event handler Lua function parameter name Default: "event"
operations[].response.format	string	String format validation
operations[].response.default	boolean, integer, null, number, string	Default value
operations[].response.maximum	number	Maximum number validation Maximum: 1000000000
operations[].response.minimum	number	Minimum number validation Maximum: 1000000000
operations[].response.pattern	string(regex)	Regex string validation
operations[].response.examples	array	Example of payload
operations[].response.maxItems	integer	MaxItems array validation Maximum: 1000000000
operations[].response.minItems	integer	MinItems array validation Maximum: 1000000000
operations[].response.required	[ string ]	Required properties object validation Default: []
operations[].response.maxLength	integer	MaxLength string validation Maximum: 1000000000
operations[].response.minLength	integer	MinLength string validation Maximum: 1000000000
operations[].response.properties	object	Properties object validation Default: {}
operations[].response.description	string	Parameter description
operations[].response.uniqueItems	boolean	UniqueItems array validation
operations[].response.maxProperties	integer	MaxProperties object validation Maximum: 1000000000
operations[].response.minProperties	integer	MinProperties object validation Maximum: 1000000000
operations[].response.additionalItems	object	AdditionalItems array validation
operations[].response.exclusiveMaximum	number	ExclusiveMaximum number validation Maximum: 1000000000
operations[].response.exclusiveMinimum	number	ExclusiveMinimum number validation Maximum: 1000000000
operations[].response.patternProperties	object	PatternProperties object validation Default: {}
operations[].response.additionalProperties	object	AdditionalProperties object validation
operations[].parameters	object	Schema used for validating payload
operations[].parameters.enum	[ string ]	Enumeration validation
operations[].parameters.type	"array", "boolean", "integer", "null", "number", "object", "string"	Type validation
operations[].parameters.items	object	Array validation
operations[].parameters.title	string	Payload name, also used as event handler Lua function parameter name Default: "event"
operations[].parameters.format	string	String format validation
operations[].parameters.default	boolean, integer, null, number, string	Default value
operations[].parameters.maximum	number	Maximum number validation Maximum: 1000000000
operations[].parameters.minimum	number	Minimum number validation Maximum: 1000000000
operations[].parameters.pattern	string(regex)	Regex string validation
operations[].parameters.examples	array	Example of payload
operations[].parameters.maxItems	integer	MaxItems array validation Maximum: 1000000000
operations[].parameters.minItems	integer	MinItems array validation Maximum: 1000000000
operations[].parameters.required	[ string ]	Required properties object validation Default: []
operations[].parameters.maxLength	integer	MaxLength string validation Maximum: 1000000000
operations[].parameters.minLength	integer	MinLength string validation Maximum: 1000000000
operations[].parameters.properties	object	Properties object validation Default: {}
operations[].parameters.description	string	Parameter description
operations[].parameters.uniqueItems	boolean	UniqueItems array validation
operations[].parameters.maxProperties	integer	MaxProperties object validation Maximum: 1000000000
operations[].parameters.minProperties	integer	MinProperties object validation Maximum: 1000000000
operations[].parameters.additionalItems	object	AdditionalItems array validation
operations[].parameters.exclusiveMaximum	number	ExclusiveMaximum number validation Maximum: 1000000000
operations[].parameters.exclusiveMinimum	number	ExclusiveMinimum number validation Maximum: 1000000000
operations[].parameters.patternProperties	object	PatternProperties object validation Default: {}
operations[].parameters.additionalProperties	object	AdditionalProperties object validation
operations[].description	string	A text description explaining the operation behavior used as operation documentation.
events	[ object ]	Events exposed by this service.
events[].name	^[a-zA-Z][a-zA-Z0-9]+$	Name used from scripting environment.
events[].response	object	Schema used for validating payload
events[].response.enum	[ string ]	Enumeration validation
events[].response.type	"array", "boolean", "integer", "null", "number", "object", "string"	Type validation
events[].response.items	object	Array validation
events[].response.title	string	Payload name, also used as event handler Lua function parameter name Default: "event"
events[].response.format	string	String format validation
events[].response.default	boolean, integer, null, number, string	Default value
events[].response.maximum	number	Maximum number validation Maximum: 1000000000
events[].response.minimum	number	Minimum number validation Maximum: 1000000000
events[].response.pattern	string(regex)	Regex string validation
events[].response.examples	array	Example of payload
events[].response.maxItems	integer	MaxItems array validation Maximum: 1000000000
events[].response.minItems	integer	MinItems array validation Maximum: 1000000000
events[].response.required	[ string ]	Required properties object validation Default: []
events[].response.maxLength	integer	MaxLength string validation Maximum: 1000000000
events[].response.minLength	integer	MinLength string validation Maximum: 1000000000
events[].response.properties	object	Properties object validation Default: {}
events[].response.description	string	Parameter description
events[].response.uniqueItems	boolean	UniqueItems array validation
events[].response.maxProperties	integer	MaxProperties object validation Maximum: 1000000000
events[].response.minProperties	integer	MinProperties object validation Maximum: 1000000000
events[].response.additionalItems	object	AdditionalItems array validation
events[].response.exclusiveMaximum	number	ExclusiveMaximum number validation Maximum: 1000000000
events[].response.exclusiveMinimum	number	ExclusiveMinimum number validation Maximum: 1000000000
events[].response.patternProperties	object	PatternProperties object validation Default: {}
events[].response.additionalProperties	object	AdditionalProperties object validation
events[].parameters	object	Schema used for validating payload
events[].parameters.enum	[ string ]	Enumeration validation
events[].parameters.type	"array", "boolean", "integer", "null", "number", "object", "string"	Type validation
events[].parameters.items	object	Array validation
events[].parameters.title	string	Payload name, also used as event handler Lua function parameter name Default: "event"
events[].parameters.format	string	String format validation
events[].parameters.default	boolean, integer, null, number, string	Default value
events[].parameters.maximum	number	Maximum number validation Maximum: 1000000000
events[].parameters.minimum	number	Minimum number validation Maximum: 1000000000
events[].parameters.pattern	string(regex)	Regex string validation
events[].parameters.examples	array	Example of payload
events[].parameters.maxItems	integer	MaxItems array validation Maximum: 1000000000
events[].parameters.minItems	integer	MinItems array validation Maximum: 1000000000
events[].parameters.required	[ string ]	Required properties object validation Default: []
events[].parameters.maxLength	integer	MaxLength string validation Maximum: 1000000000
events[].parameters.minLength	integer	MinLength string validation Maximum: 1000000000
events[].parameters.properties	object	Properties object validation Default: {}
events[].parameters.description	string	Parameter description
events[].parameters.uniqueItems	boolean	UniqueItems array validation
events[].parameters.maxProperties	integer	MaxProperties object validation Maximum: 1000000000
events[].parameters.minProperties	integer	MinProperties object validation Maximum: 1000000000
events[].parameters.additionalItems	object	AdditionalItems array validation
events[].parameters.exclusiveMaximum	number	ExclusiveMaximum number validation Maximum: 1000000000
events[].parameters.exclusiveMinimum	number	ExclusiveMinimum number validation Maximum: 1000000000
events[].parameters.patternProperties	object	PatternProperties object validation Default: {}
events[].parameters.additionalProperties	object	AdditionalProperties object validation
events[].description	string	A text description explaining the event
events[].default_script	string(lua)	A default eventHandler script initialized when adding the service to a solution
mode	"async", "sync"	Default mode used for event triggering. By default broadcasts (trigger) are 'async' & single triggers (triggerOne) 'sync'

---

Operations

Please note that bold arguments are required, while italic arguments are optional.

getSubscriber

Get details of the solution subscribing to the exposed West Connectivity service.

SRS-ID: S-INTER-INT-002

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
subscriber_id	^[a-z][a-z0-9]+$	The solution registering to the exposed service.

Responses

Code	Body Type	Description
200	object	Successful request.
default	object	Standard http responses

Object Parameter of 200 response:

Name	Type	Description
id	string(uuid)	Unique Id
quota	object	Service quota Default: {}
quota.calls_daily	integer	Daily service call quota Maximum: 1000000000
quota.calls_monthly	integer	Monthly service call quota Maximum: 10000000000
triggers	object	Map of parameters to route events to a solution script. Default: {}
*	any	Any other properties are accepted.
created_at	string(date-time)	Auto-generated item creation date
parameters	object	Map of service parameters default value, contains parameters for all operations of this service. Definitions matching the operation parameters of the service swagger schema. Default: {}
*	any	Any other properties are accepted.
updated_at	string(date-time)	Auto-generated item last update date
solution_id	^[a-zA-Z0-9]+$	Solution reference, by extension also link to a business.

Object Parameter of default response:

Name	Type	Description
type	string	Error type
error	string	Error message
status	integer	Response code

Example

local subscriber = Interface.getSubscriber({subscriber_id="<target id>"}) print(subscriber.parameters)

listSubscribers

List solutions subscribing to the exposed West Connectivity service.

SRS-ID: S-INTER-INT-002

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
parameters	object	Filter the subscriber by their configuration parameters.
offset	integer	Filter the starting index to start returning object for pagination purpose Maximum: 1000000
limit	integer	Limit the number of items to return for pagination purpose Maximum: 1000 Minimum: 1 Default: 20

Responses

Code	Body Type	Description
200	object	Response including the paginated list of subscribers.
default	object	Standard http responses

Object Parameter of 200 response:

Name	Type	Description
items	[ object ]	An array of services configuration
items[].id	string(uuid)	Unique Id
items[].quota	object	Service quota Default: {}
items[].quota.calls_daily	integer	Daily service call quota Maximum: 1000000000
items[].quota.calls_monthly	integer	Monthly service call quota Maximum: 10000000000
items[].triggers	object	Map of parameters to route events to a solution script. Default: {}
*	any	Any other properties are accepted.
items[].created_at	string(date-time)	Auto-generated item creation date
items[].parameters	object	Map of service parameters default value, contains parameters for all operations of this service. Definitions matching the operation parameters of the service swagger schema. Default: {}
*	any	Any other properties are accepted.
items[].updated_at	string(date-time)	Auto-generated item last update date
items[].solution_id	^[a-zA-Z0-9]+$	Solution reference, by extension also link to a business.
total	integer	Total count of objects for pagination purpose

Object Parameter of default response:

Name	Type	Description
type	string	Error type
error	string	Error message
status	integer	Response code

Example

local resList = Interface.listSubscribers({parameters={mySetting="filtervalue"}})
for i, res in ipairs(resList) do


  local subscriber_id = res.solution_id

  -- do something..
end

setSubscriber

Set parameters or quota limitation of the solution subscribing to the exposed West Connectivity service. Native supported limitations are: calls_daily & calls_monthly limiting the number of available api requests. There is no default quota limitations.

SRS-ID: S-INTER-INT-002

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
subscriber_id	^[a-z][a-z0-9]+$	The solution registering to the exposed service.
quota	object	Service quota
quota.calls_daily	integer	Daily service call quota Maximum: 1000000000
quota.calls_monthly	integer	Monthly service call quota Maximum: 10000000000
parameters	object	Map of service parameters default value, contains parameters for all operations of this service. Definitions matching the operation parameters of the service swagger schema.

Responses

Code	Body Type	Description
204	nil	Successful request.
default	object	Standard http responses

Object Parameter of default response:

Name	Type	Description
type	string	Error type
error	string	Error message
status	integer	Response code

Example

-- Set subscriber parameters &/or quota
Interface.setSubscriber({subscriber_id="<target id>", parameters={key="value"}, quota={["calls_daily"]=100}})

trigger

Send an event to the service subscribers.

SRS-ID: S-INTER-INT-003

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
event	^[a-zA-Z][a-zA-Z0-9]+$	The event Name. Which the subscribers need to use as part of their eventhandler function.
mode	"sync", "async"	Indicates if the call is blocking and waits for the execution response (sync) or fire-and-forget (async). If not provided: - If set, the service configuration parameters.mode is used - 'async' otherwise Default: "async"
data	number, string, boolean, object, array, null	Any data
*	any	Any other properties are accepted.

Responses

Code	Body Type	Description
200	[ object ]	Synchronous events executed, returns the processing result from script engine. (mode=sync)
202	[ object ]	Asynchronous event triggered.
403	object	Non-solution services cannot use broadcast
404	object	Service not found
default	object	Standard http responses

Object Parameter of 200 response:

Name	Type	Description
result	number, string, boolean, object, array, null	Any data
*	any	Any other properties are accepted.
status	number	Response status code of the execution. Only availble if option "mode=sync" is given. Maximum: 10000
instance_id	string	The subscription unique identifier (serviceconfig.id)
solution_id	string	Subscriber solution id

Object Parameter of 202 response:

Name	Type	Description
result	number, string, boolean, object, array, null	Any data
*	any	Any other properties are accepted.
status	number	Response status code of the execution. Only availble if option "mode=sync" is given. Maximum: 10000
instance_id	string	The subscription unique identifier (serviceconfig.id)
solution_id	string	Subscriber solution id

Object Parameter of 403 response:

Name	Type	Description
type	string	Error type
error	string	Error message
status	integer	Response code

Object Parameter of 404 response:

Name	Type	Description
type	string	Error type
error	string	Error message
status	integer	Response code

Object Parameter of default response:

Name	Type	Description
type	string	Error type
error	string	Error message
status	integer	Response code

Example

-- By default, the event is triggered asynchronously.
-- (Unless the configuration parameters.mode is set)
Interface.trigger({event="event", data="alarm"})
-- Sending a blocking event and get the response.
local resList = Interface.trigger({event="event", data="feedback", mode="sync"}) for i, res in ipairs(resList) do


  local subscriber_id = res.solution_id
  local result = res.result
end

triggerOne

Send an event to the given service subscriber.

SRS-ID: S-INTER-INT-003

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
target	^[a-z0-9-]+$	The target subscriber solution or subscription id
event	^[a-zA-Z][a-zA-Z0-9]+$	The event Name. Which the subscribers need to use as part of their eventhandler function.
mode	"sync", "async"	Indicates if the call is blocking and waits for the execution response (sync) or fire-and-forget (async). If not provided: - If set, the service configuration parameters.mode is used - 'sync' otherwise Default: "sync"
data	number, string, boolean, object, array, null	Any data
*	any	Any other properties are accepted.

Responses

Code	Body Type	Description
200	object	Result object
202	nil	Asynchronous event triggered.
404	object	Target subscriber not found
default	object	Standard http responses

Object Parameter of 200 response:

Name	Type	Description
status	number	Status of response triggerOne

Object Parameter of 404 response:

Name	Type	Description
type	string	Error type
error	string	Error message
status	integer	Response code

Object Parameter of default response:

Name	Type	Description
type	string	Error type
error	string	Error message
status	integer	Response code

Example

-- By default, the event is trigger synchronously and response returns the execution result.
-- Unless set otherwise in the configuration parameters.mode
local result = Interface.triggerOne({event="event", data="alarm", target="<target id>"})
-- Sending a non-blocking trigger
Interface.triggerOne({event="event", data="feedback", target="<target id>", mode="async"})

---

Events

subscriberAdded

Notification indicating a solution has added the exposed service.

Arguments

subscription (object) - A service configuration object enable service to a solution

Name	Type	Description
id	string(uuid)	Unique Id of the subscription
parameters	object	Map of service parameters default value, contains parameters for all operations of this service. Definitions matching the operation parameters of the service swagger schema. Default: {}
*	any	Any other properties are accepted.
solution_id	^[a-zA-Z0-9]+$	Subscriber solution id, by extension also link to a business.

Example

print("Solution " .. subscription.solution_id .. " has added this service.")

subscriberRemoved

Notification indicating a subscriber solution configuration has removed the exposed service.

Arguments

subscription (object) - A service configuration object enable service to a solution

Name	Type	Description
id	string(uuid)	Unique Id of the subscription
parameters	object	Map of service parameters default value, contains parameters for all operations of this service. Definitions matching the operation parameters of the service swagger schema. Default: {}
*	any	Any other properties are accepted.
solution_id	^[a-zA-Z0-9]+$	Subscriber solution id, by extension also link to a business.

Example

print("Solution " .. subscription.solution_id .. " has removed this service.")

subscriberUpdated

Notification indicating a subscriber solution configuration has been updated.

Arguments

subscription (object) - A service configuration object enable service to a solution

Name	Type	Description
id	string(uuid)	Unique Id of the subscription
parameters	object	Map of service parameters default value, contains parameters for all operations of this service. Definitions matching the operation parameters of the service swagger schema. Default: {}
*	any	Any other properties are accepted.
solution_id	^[a-zA-Z0-9]+$	Subscriber solution id, by extension also link to a business.

Example

print("Solution " .. subscription.solution_id .. " has updated his configuration.")

CustomEvent

An operation has been call by a Subscriber Solution. The name of this event is dynamic and equal the operationId being used for the service call as defined in the Interface service operations. An eventHandler have to be created for each supported operations. This operation responses the data is returned from eventHandler function.

Arguments

operation (number, string, boolean, object, array, null) - Any data

Any data

Responses

Code	Body Type	Description
default	number, string, boolean, object, array, null	The operation execution result.

Example

-- Example of handler for a "light" operation
function handle_interface_light (operation)


  local err = lightModule.setLight(context.caller_id, operation)

  if err ~= nil then
    return {
      error = "Control light failed",
      status = 500,
      type = "ServerError"
    }
  else
    return "ok"
  end
end

Service Health Check

Operations

/solution/health

Enable the hosting system to check if service is active and running

Arguments

No Content

Responses

Name	Type	Description
200	string	OK

Errors

No content