Internal communication Interface Service

This service enable Murano Solution-to-Solution communication by exposing the solution as a Murano service. From this service you can expose 'operations' which can be called by subscribing solutions. Other solution can then subscribe to this interface and used the defined operations as they would with any other Murano service. Event triggers are also supported to send notification to one or all subscribers.

Operations

Events


Configuration parameters

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 {..100} Custom name used for visualization purpose. Default using the default_script_key value.
description string {..1000} 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 {..100} Contact name
contact.email string(email) Contact email
tags [ string {1..20} ] {..10} Service grouping & search purpose
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 ] {1..} 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
parameters[].items.minimum number Minimum number validation
parameters[].items.pattern string(regex) Regex string validation
parameters[].items.examples array Example of payload
parameters[].items.maxItems integer MaxItems array validation
parameters[].items.minItems integer MinItems array validation
parameters[].items.required [ string ] Required properties object validation
Default: []
parameters[].items.maxLength integer MaxLength string validation
parameters[].items.minLength integer MinLength string validation
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
parameters[].items.minProperties integer MinProperties object validation
parameters[].items.additionalItems object AdditionalItems array validation
parameters[].items.exclusiveMaximum number ExclusiveMaximum number validation
parameters[].items.exclusiveMinimum number ExclusiveMinimum number validation
parameters[].items.patternProperties object PatternProperties object validation
Default: {}
parameters[].items.additionalProperties object AdditionalProperties object validation
parameters[].properties object List of properties
parameters[].description string {..1000} 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 ] {1..} 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
operations[].response.minimum number Minimum number validation
operations[].response.pattern string(regex) Regex string validation
operations[].response.examples array Example of payload
operations[].response.maxItems integer MaxItems array validation
operations[].response.minItems integer MinItems array validation
operations[].response.required [ string ] Required properties object validation
Default: []
operations[].response.maxLength integer MaxLength string validation
operations[].response.minLength integer MinLength string validation
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
operations[].response.minProperties integer MinProperties object validation
operations[].response.additionalItems object AdditionalItems array validation
operations[].response.exclusiveMaximum number ExclusiveMaximum number validation
operations[].response.exclusiveMinimum number ExclusiveMinimum number validation
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 ] {1..} 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
operations[].parameters.minimum number Minimum number validation
operations[].parameters.pattern string(regex) Regex string validation
operations[].parameters.examples array Example of payload
operations[].parameters.maxItems integer MaxItems array validation
operations[].parameters.minItems integer MinItems array validation
operations[].parameters.required [ string ] Required properties object validation
Default: []
operations[].parameters.maxLength integer MaxLength string validation
operations[].parameters.minLength integer MinLength string validation
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
operations[].parameters.minProperties integer MinProperties object validation
operations[].parameters.additionalItems object AdditionalItems array validation
operations[].parameters.exclusiveMaximum number ExclusiveMaximum number validation
operations[].parameters.exclusiveMinimum number ExclusiveMinimum number validation
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 ] {1..} 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
events[].response.minimum number Minimum number validation
events[].response.pattern string(regex) Regex string validation
events[].response.examples array Example of payload
events[].response.maxItems integer MaxItems array validation
events[].response.minItems integer MinItems array validation
events[].response.required [ string ] Required properties object validation
Default: []
events[].response.maxLength integer MaxLength string validation
events[].response.minLength integer MinLength string validation
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
events[].response.minProperties integer MinProperties object validation
events[].response.additionalItems object AdditionalItems array validation
events[].response.exclusiveMaximum number ExclusiveMaximum number validation
events[].response.exclusiveMinimum number ExclusiveMinimum number validation
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 ] {1..} 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
events[].parameters.minimum number Minimum number validation
events[].parameters.pattern string(regex) Regex string validation
events[].parameters.examples array Example of payload
events[].parameters.maxItems integer MaxItems array validation
events[].parameters.minItems integer MinItems array validation
events[].parameters.required [ string ] Required properties object validation
Default: []
events[].parameters.maxLength integer MaxLength string validation
events[].parameters.minLength integer MinLength string validation
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
events[].parameters.minProperties integer MinProperties object validation
events[].parameters.additionalItems object AdditionalItems array validation
events[].parameters.exclusiveMaximum number ExclusiveMaximum number validation
events[].parameters.exclusiveMinimum number ExclusiveMinimum number validation
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

getSubscriber

Get details of the solution subscribing to the exposed Murano service.

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

Successful request.

Content: object A service configuration object enable service to a solution

Name Type Description
id string(uuid) Unique Id
quota object Service quota
Default: {}
quota.calls_daily integer Daily service call quota
quota.calls_monthly integer Monthly service call quota
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.
Standard http responses

Content: object Error 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 Murano service.

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
limit integer {1..1000} Limit the number of items to return for pagination purpose
Default: 20

Responses

Response including the paginated list of subscribers.

Content: object

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
items[].quota.calls_monthly integer Monthly service call quota
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
Standard http responses

Content: object Error 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 Murano service. Native supported limitations are: calls_daily & calls_monthly limiting the number of available api requests. There is no default quota limitations.

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
quota.calls_monthly integer Monthly service call quota
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

Successful request.

Content: nil

Standard http responses

Content: object Error 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.

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

Synchronous events executed, returns the processing result from script engine. (mode=sync)

Content: [ object ] Broadcast trigger result

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.
instance_id string The subscription unique identifier (serviceconfig.id)
solution_id string Subscriber solution id
Asynchronous event triggered.

Content: [ object ] Broadcast trigger result

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.
instance_id string The subscription unique identifier (serviceconfig.id)
solution_id string Subscriber solution id
Non-solution services cannot use broadcast

Content: object Error response

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

Content: object Error response

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

Content: object Error 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.

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

Synchronous event executed, returns the processing result from script engine. (mode=sync)

Content: number, string, boolean, object, array, null Any data

Asynchronous event triggered.

Content: nil

Target subscriber not found

Content: object Error response

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

Content: object Error 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.")

*

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

The operation execution result.

Content: number, string, boolean, object, array, null Any data

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