insight_service.yaml

swagger: '2.0'

################################################################################
#                           Service Metadata                                   #
################################################################################
info:
  version: "1.0"
  title: Example Insight
  description: |
    Example Insight
  contact:
    name: Exosite
    email: support@exosite.com

################################################################################
#                            API Information                                   #
################################################################################

# A hostname with a valid, signed, and active TSL certificate is required.
host: .io
basePath: /api/v1
tags:
  - name: insight
    description: Insight Module
schemes:
  - https  # Only https is supported.
consumes:
  - application/json # Only JSON is supported.
produces:
  - application/json # Only JSON is supported.

################################################################################
#                          Solution lifecycle Events                           #
################################################################################
# Following Operation should generally be restricted with "x-exosite-restricted: true"
x-exosite-init: createSolution # Triggered by Murano when this service is enabled in a solution
x-exosite-gc: delSolution # Triggered by Murano when the service is removed from a solution or if the solution is deleted

################################################################################
#                                Operations                                    #
################################################################################
paths:
  /:
    get:
      description: Alive check
      operationId: alive
      x-exosite-restricted: true # Indicate that this operation cannot be called from user scripts
      responses:
        '200':
          description: Solution successfully created
        default:
          description: Error
          schema:
            $ref: '#/definitions/ErrorResponse'

  # Administration endpoint used by Murano solution lifecycle events
  # Those operation uses the "x-exosite-restricted" to prevent the user to access them directly
  /{solution_id}:
    parameters:
      - name: solution_id
        x-exosite-from: solution_id # Indicate this value is injected from the user solution_id
        x-exosite-restricted: true # Indicate the user cannot provide this parameter
        type: string
        in: path
        description: The solution identifier. Set automatically.
        required: true
    post:
      description: Used by Murano to create a solution namespace.
      operationId: createSolution
      x-exosite-restricted: true # Indicate that this operation cannot be called from user scripts
      responses:
        '200':
          description: Solution successfully created
        default:
          description: Error
          schema:
            $ref: '#/definitions/ErrorResponse'
    delete:
      description: Used by Murano to remove a solution and clean its namespace.
      operationId: delSolution
      x-exosite-restricted: true
      responses:
        '205':
          description: Solution successfully removed.
        default:
          description: Error
          schema:
            $ref: '#/definitions/ErrorResponse'

  /{solution_id}/info:
    parameters:
      - name: solution_id
        type: string
        in: path
        description: The solution identifier. Set automatically by Murano at service call.
        x-exosite-from: solution_id # Indicate this value is injected from the user solution_id
        x-exosite-restricted: true # Indicate the user cannot provide this parameter
        required: true
    get:
      operationId: info
      description: Get some info about this Insight
      responses:
        "200":
          description: Insight Functions successfully listed
          schema:
            $ref: "#/definitions/InsightInfoResults"
        default:
          description: Errors
          schema:
            $ref: '#/definitions/ErrorResponse'

  /{solution_id}/insights:
    parameters:
      - name: solution_id
        type: string
        in: path
        description: The solution identifier. Set automatically by Murano at service call.
        x-exosite-from: solution_id # Indicate this value is injected from the user solution_id
        x-exosite-restricted: true # Indicate the user cannot provide this parameter
        required: true
    post:
      operationId: listInsights
      description: Get a list of available Insight Functions and info about them
      parameters:
      - name: body
        in: body
        description: Get a list of available insight functions
        required: true
        schema:
          $ref: '#/definitions/InsightsFilterParams'
      responses:
        "200":
          description: Insight Functions successfully listed
          schema:
            $ref: "#/definitions/InsightListResults"
        default:
          description: Errors
          schema:
            $ref: '#/definitions/ErrorResponse'

  /{solution_id}/insight/{function_id}:
    parameters:
      - name: solution_id
        type: string
        in: path
        description: The solution identifier. Set automatically by Murano at service call.
        x-exosite-from: solution_id # Indicate this value is injected from the user solution_id
        x-exosite-restricted: true # Indicate the user cannot provide this parameter
        required: true
    get:
      operationId: infoInsight
      description: Get info about one Insight Function
      parameters:
        - name: function_id
          type: string
          in: path
          description: Identifier of function
      responses:
        "200":
          description: Insight Functions successfully listed
          schema:
            $ref: "#/definitions/InsightInfo"
        default:
          description: Errors
          schema:
            $ref: '#/definitions/ErrorResponse'

  /{solution_id}/lifecycle:
    parameters:
      - name: solution_id
        type: string
        in: path
        description: The solution identifier. Set automatically by Murano at service call.
        x-exosite-from: solution_id # Indicate this value is injected from the user solution_id
        x-exosite-restricted: true # Indicate the user cannot provide this parameter
        required: true
    post:
      operationId: lifecycle
      description: |
        Notifications of when a linkage that will call the process function is created or deleted.
      parameters:
        - name: body
          in: body
          description: Lifecycle event
          required: true
          schema:
            $ref: '#/definitions/LifecycleEvent'
      responses:
        default:
          description: The response to this is ignored.

  /{solution_id}/process:
    parameters:
      - name: solution_id
        type: string
        in: path
        description: The solution identifier. Set automatically by Murano at service call.
        x-exosite-from: solution_id # Indicate this value is injected from the user solution_id
        x-exosite-restricted: true # Indicate the user cannot provide this parameter
        required: true
    post:
      operationId: process
      description: |
        Your function to process a bunch of Signal Data.

        It is good form to copy all the fields of a source SignalData into the new SignalData,
        then update the properties according to your function.
      parameters:
        - name: body
          in: body
          description: Data to process and arguments on how to process it
          required: true
          schema:
            $ref: "#/definitions/SignalDataObjectArray"
      responses:
        "200":
          description: Data successfully
          schema:
            $ref: "#/definitions/SignalDataArrayArray"
        default:
          description: Error that stops the pipeline.
            Non-fatal errors should produce new signals on a separate outlet.
          schema:
            $ref: '#/definitions/ErrorResponse'

################################################################################
#                                 Definitions                                  #
################################################################################
definitions:
  InsightInfoResults:
    type: object
    description: Info about this Insight Module
    properties:
      group_id_required:
        type: boolean
        description: True if the listInsights requires group_id to be something to list functions.
      name:
        type: string
        description: Presented name
      description:
        type: string
        description: Additional text about this insight. Markdown can be used.
      wants_lifecycle_events:
        type: boolean
        description: |
          True if this insight wants to be notified when linkages using it are created and deleted.
          Defaults to false.
      translations:
        type: object
        description: Translations of the name and description fields
        additionalProperties:
          type: object
          description: Keyed by each translated language code
          properties:
            name:
              type: string
              description: Presented name
            description:
              type: string
              description: Additional text about this insight. Markdown can be used.
    required: [group_id_required]

  InsightsFilterParams:
    type: object
    description: Filter options for insight functions
    properties:
      group_id:
        type: string
        description: |
          Which group of insight functions to get.  The meaning of the contents is up to the Insight Module.
          Including ignoring it and always returning all.
      limit:
        type: integer
        description: Limit how many insights to fetch
      offset:
        type: integer
        description: Offset into the returned insights
    required: [group_id]

  SignalTypeInputInfo:
    type: object
    description: |
      What data type the incoming Signal must have.  One of `primitive_type`, `data_type` or `data_unit`
      should be specified.
    required: [name]
    properties:
      primitive_type:
        type: string
        enum: [NUMERIC, STRING, BOOLEAN, JSON]
        description: If present, the primitive type that the connecting signal must have
      data_type:
        type: array
        description: If present, the type that the connecting signal must have
        items:
          type: string
          description: A required data type
      data_unit:
        type: array
        description: If present, the units that the connecting signal must have
        items:
          type: string
          description: A required unit.
      tag:
        type: string
        description: Optional tag to add to the SignalData for inlet matching
      name:
        type: string
        description: Name of this signal
      description:
        type: string
        description: Optional text to help users.
      translations:
        type: object
        description: Translations of the name and description fields
        additionalProperties:
          type: object
          description: Keyed by each translated language code
          properties:
            name:
              type: string
              description: Presented name
            description:
              type: string
              description: Optional text to help users.

  SignalTypeOutputInfo:
    type: object
    description: |
      What data type the incoming Signal must have.  One of `primitive_type`, `data_type` or `data_unit`
      should be specified.
    properties:
      primitive_type:
        type: string
        enum: [NUMERIC, STRING, BOOLEAN, JSON]
        description: If present, the primitive type that the connecting signal must have
      data_type:
        type: array
        description: If present, the type that the connecting signal must have
        items:
          type: string
          description: A required data type.
      data_unit:
        type: array
        description: If present, the unit that the connecting signal must have
        items:
          type: string
          description: A required unit.
      name:
        type: string
        description: Name of this outlet
      description:
        type: string
        description: Optional text to help users.
      suggested_name:
        type: string
        description: |
          A suggestion for what to name signals that get created for this outlet.
          This may include `{}` to indicate where to place the function name.
      translations:
        type: object
        description: Translations of the name and description fields
        additionalProperties:
          type: object
          description: Keyed by each translated language code 
          properties:
            name:
              type: string
              description: Presented name
            description:
              type: string
              description: Optional text to help users.
            suggested_name:
              type: string
              description: |
                A suggestion for what to name signals that get created for this outlet.
                This may include `{}` to indicate where to place the function name.

  ConstantInfo:
    type: object
    description: A constant that needs to be provided by the user
    properties:
      name:
        type: string
        description: The name of this constant; This is not shown to users and is the code identifier for this constant.
      type:
        type: string
        enum: [string, number, boolean]
        description: What kind of value this constant accepts
      description:
        type: string
        description: Some words for the user about this constant
      default:
        type: [string, number, boolean]
        description: Optional value to use if user doesn't specify one.
      enum:
        type: array
        description: An array of allowed values.
        items:
          description: An allowed value
          oneOf:
            - type: string
            - type: number
            - type: boolean
      enum_presented:
        type: array
        description: If present, the strings to display instead of the values in `enum`.  The length of this must match `enum`.
        items:
          type: string
          description: Presentable name for one value
      maximum:
        type: number
        description: For number type, the largest it can be
      minimum:
        type: number
        description: For number type, the smallest it can be
      multiple:
        type: boolean
        description: |
          When this is true, this constant will be an array of values instead of a single value.
          The UI will present the user a way to enter this constant multiple times.
      translations:
        type: object
        description: Translations of the name and description fields
        additionalProperties:
          type: object
          description: Keyed by each translated language code 
          properties:
            description:
              type: string
              description: Some words for the user about this constant
            enum_presented:
              type: array
              description: If present, the strings to display instead of the values in `enum`.
              items:
                type: string
    required: [name, type]

  InsightInfo:
    type: object
    description: One insight function
    properties:
      id:
        type: string
        description: The unique id for this insight function
      name:
        type: string
        description: A human friendly name for this insight function
      description:
        type: string
        description: A description of this insight function to display to users.
      translations:
        type: object
        description: Translations of the name and description fields
        additionalProperties:
          type: object
          description: Keyed by each translated language code
          properties:
            name:
              type: string
              description: A human friendly name for this insight function
            description:
              type: string
              description: A description of this insight function to display to users.
      type:
        type: string
        enum: [transform, rule, action]
        description: |
          What kind of insight this function is.  Determines how it gets used and how the UI
          presents it.  If omitted, then 'transform' is used.
      history:
        type: object
        description: |
          When this object is present, a timeseries query will be called and the results sent along
          to the function call.  The properties here will be used to augment the query.  Only the
          Signals connected to the calling of this function will be queried.
        properties:
          include_from:
            type: string
            enum: [INLETS, OUTLETS, BOTH]
            description: When fetching history, which connected signals to fetch from.  Defaults to BOTH.
        additionalProperties:
          type: object
          description: An additional parameter to the query.  Use only one property. (value, constant, template)
          properties:
            value:
              type: [string, number]
              description: The exact value to use
            constant:
              type: string
              description: Which of this function's constants to use the value of here
            template:
              type: string
              description: |
                Which of this function's constants to use the value of here, fitted into a template
                string.  The constants must be surrounded with '{{}}'.  For example '-{{days}}d'
      constants:
        type: array
        description: Additional user specified values to pass to this insight function
        items:
          $ref: '#/definitions/ConstantInfo'
      constants_multiple_maximum:
        type: number
        description: |
          If there are constants with multiple set to true, this states the maximum number of times the
          constants can be repeated. (The maximum size of the arrays.)
          If unspecified then the UI can apply any limit, including none.
      inlets:
        type: array
        description: The kinds of data that can be connected. (This is an unordered set)
        maxItems: 5
        items:
          $ref: '#/definitions/SignalTypeInputInfo'
      outlets:
        type: array
        description: What kind of data each output will produce. (This is an ordered array)
        maxItems: 5
        items:
          $ref: '#/definitions/SignalTypeOutputInfo'
    required:
      - id
      - name
      - description

  InsightListResults:
    type: object
    description: The found insight functions with count info
    properties:
      total:
        type: integer
        description: The total number of insight functions in this group
      count:
        type: integer
        description: Number of insight functions returned
      insights:
        type: array
        description: The insight functions
        items:
          $ref: '#/definitions/InsightInfo'
    required:
      - insights
      - total
      - count

  LifecycleEvent:
    type: object
    description: A Lifecycle event
    properties:
      event:
        type: string
        description: What action caused this event
        pattern: "(create|delete)"
      id:
        type: string
        description: The unique id for the linkage that has the event.  This id will match in the calls to process.
      args:
        type: object
        description: The arguments for this linkage that will be also passed to each call of process.

  SignalData:
    type: object
    description: A single instance of a piece of data inside a signal.
    properties:
      tags:
        type: object
        description: |
          Tag-Value pairs to help ID the data. Used to tie the data back to an
          Asset or Device or other things.
        additionalProperties:
          type: string
          description: Value for a tag
          minLength: 1
      ts:
        type: integer
        description: Unix timestamp in microseconds of when the data originated
      gts:
        type: integer
        description: Unix timestamp in microseconds of when this SignalData was generated
      value:
        type: [string, number, object]
        description: The value for this instance of data
      origin:
        type: string
        description: The original Publishing ID
        minLength: 1
      generated:
        type: string
        description: The Publishing ID that created this SignalData.
        minLength: 1
      ttl:
        type: integer
        description: Value used to help prevent data from infinitely cycling
    required:
      - ts
      - value
      - origin
      - generated

  HistoricalData:
    type: object
    description: The history of signals.  Each signal id is the key, with an array of timestamp, value pairs.
    additionalProperties:
      type: array
      description: The history of signals.  Each signal id is the key, with an array of timestamp, value pairs.
      items:
        type: object
        description: One point in history
        properties:
          ts:
            type: integer
            description: Unix timestamp in microseconds of when the data was stored
          value:
            type: [string, number, object]
            description: The value for this instance of data
          tags:
            type: object
            description: Tag-Value pairs to help ID the data.  (Tags here are a subset of those in SignalData)
            additionalProperties:
              type: string
              description: Value for a tag
              minLength: 1
        required: [ts, value]

  SignalDataArray:
    type: array
    description: Array of Signal Data
    items:
      $ref: '#/definitions/SignalData'

  SignalDataArrayArray:
    type: array
    description: Array of Array of Signal Data.  An array for each outlet, each outlet can have many signals.
    items:
      $ref: '#/definitions/SignalDataArray'

  SignalDataObjectArray:
    type: object
    description: The data and arguments to be processed.
    properties:
      id:
        type: string
        description: A unique ID for this instance of this function in an asset pipeline.
      data:
        $ref: '#/definitions/SignalDataArray'
      history:
        $ref: '#/definitions/HistoricalData'
      args:
        type: object
        description: Object of instance arguments.
        properties:
          function_id:
            type: string
            description: Which insight function to run
          group_id:
            type: string
            description: Which group_id this is under
          constants:
            type: object
            description: Additional constant parameters for the selected function


  ErrorResponse:
    type: object
    description: Error response that stops the pipeline.
    properties:
      message:
        type: string
        description: Error message
      status:
        type: number
        description: A numerical code for the error
      name:
        description: Error type
        type: string