Skip to content

Internal communication Interface Service

Summary

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

Name Tag Summary
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

Name Summary
subscriberAdded New subscription

| subscriberRemoved | Subscription removal |

| subscriberUpdated | Subscription update |

| * | Interface operation handler |


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 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
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
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 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
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 ] 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 ] 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 ] 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

Description

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

Arguments

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

Responses

  • Returns {object} when Successful request.

    A service configuration object enable service to a solution {object}

    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.
  • Returns {object} when Standard http responses

    Error response {object}

    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

Description

List solutions subscribing to the exposed Murano service.

Arguments

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 Limit the number of items to return for pagination purpose
Default: 20

Responses

  • Returns {object} for Response including the paginated list of subscribers.

    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
  • Returns {object} when Standard http responses

    Error response {object}

    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

Description

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

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

  • Returns nil for Successful request.

  • Returns {object} when Standard http responses

    Error response {object}

    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

Description

Send an event to the service subscribers.

Arguments

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

  • Returns {[ object ]} when Synchronous events executed, returns the processing result from script engine. (mode=sync)

    Broadcast trigger result {object}

    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
  • Returns {[ object ]} when Asynchronous event triggered.

    Broadcast trigger result {object}

    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
  • Returns {object} when Non-solution services cannot use broadcast

    Error response {object}

    Name Type Description
    type string Error type
    error string Error message
    status integer Response code
  • Returns {object} when Service not found

    Error response {object}

    Name Type Description
    type string Error type
    error string Error message
    status integer Response code
  • Returns {object} when Standard http responses

    Error response {object}

    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

Description

Send an event to the given service subscriber.

Arguments

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

  • Returns number*, *string*, *boolean*, *object*, *array*, *null when Synchronous event executed, returns the processing result from script engine. (mode=sync)

    Any data {object}

  • Returns nil for Asynchronous event triggered.

  • Returns {object} when Target subscriber not found

    Error response {object}

    Name Type Description
    type string Error type
    error string Error message
    status integer Response code
  • Returns {object} when Standard http responses

    Error response {object}

    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

Description

Notification indicating a solution has added the exposed service.

Arguments

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

Description

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

Arguments

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

Description

Notification indicating a subscriber solution configuration has been updated.

Arguments

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.")

*

Description

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

Any data

Responses

  • Returns number*, *string*, *boolean*, *object*, *array*, *null when The operation execution result.

    Any data {object}

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