Authoring Exchange Elements

This guide is designed to show you how to author your own Exchange Elements for private use.

Note: This feature is currently available for Professional and Enterprise Businesses only.

Table of contents

Element Types

Downloadable Content

Businesses can provide downloaded content for consumption by other business users. Each element has the ability to reference a single downloadable file.


Solution Template

Solution templates are self-contained solutions that provide a starting point for a new solution.

To get started with creating a new solution template:

  1. Download the latest version: Getting Started Solution Template (ZIP).
  2. Create your own public GitHub repo and commit the above ZIP contents to this repo.
  3. Add a version tag to the repo git tag -a -m "Release Version 0.0.1" "0.0.1"
  4. Read more: Documentation for the Getting Started Solution Template

    • Application Solution

      When authoring an Application Solution template, Murano will also include a collection of out-of-the-box, default services for every solution template. The default services for an Application Solution are listed below.

      Default Application Services
    • Product Solution

      When authoring a Product Solution template, Murano will also include a collection of out-of-the-box, default services for every solution template. The default services for a Product Solution are listed below.

      Default Product Services

OpenAPI Integration Service

Integration services are external API interfaces connected to Murano and made available in Exosite's Solution Scripting environment.

Exosite follows the spirit of open APIs and uses the Swagger API development framework as the scaffold for the OpenAPI Integration Service. Swagger is a popular API development framework that uses a set of properties defined in the Swagger Specification, extended by Exosite, to describe the interface to another service. Exosite's Open API integration service then reads that description file and automatically generates bindings that can be used in Exosite's Solution Scripting system. This service is the tool that is responsible for all of the service functions Exosite provides in the Scripting environment.

To get started with the OpenAPI Integration Service you will need to be partially familiar with the Swagger Specification and close to the API, or API documentation, of the service that you want to connect to Murano. The process itself is representing the API of the service you would like to connect as a Swagger specification.

As an example service please take a look at this small Dark Sky weather service integration: https://github.com/exosite/darksky_service/blob/master/darksky.yaml. Notice that the service specification has four main sections.

API Information

This Sections includes a summary of the integration along with attendant information about where more information can be found what format and encoding expectations a consumer of this service should expect.

info:
  version:      "0.2"
  title:        Dark Sky Weather Service Integration
  description:  |
                ## Use Dark Sky to get weather forecasts and historical weather data.
                This is a Murano Service integration with
                [Dark Sky](https://darksky.net) to allow your Murano solution
                to get weather forecasts and historical weather data. [Powered by Dark Sky](https://darksky.net/poweredby/)
  contact:
    name:       Exosite Support
    email:      support@exosite.com

Service Configuration Parameters

This is a special section Exosite extended from Swagger to make service configurations available through the Murano UI. Services like this Dark Sky service need to be configured with an API token in order to function.

x-exosite-config-parameters:
  - name:         auth_token
    description:  Dark Sky Authentication Token
    type:         string
    format:       password
    required:     true

Paths

This is the real body of the service specification where the endpoints of the Dark Sky service are defined and combined into a Murano solution scripting environment operation.

paths:
  /{auth_token}/{lat_and_long_or_time}:

    > parameters:

    get:
      tags:
        - calls
      operationId:  forecast
      summary:      Make a request to Dark Sky
      description:  Fetch a weather forecast or get historical weather data based of input latitude and longitude
      x-exosite-example:    


                    --#ENDPOINT GET /darksky/weather
                    weather_data = Darksky.forecast({lat_and_long_or_time = '44.977753,93.265011'})
      > parameters:

Definitions

The definitions section can be used by reference objects in order re-use specification code. If elements of the spec are copied and pasted more than once, they can be set here and reused.


The greatest detail about all these sections can be read in the Swagger Specification.

Access to create new or extend additional services is currently only available to authorized accounts. If you want to learn more, or want to get started, feel free to contact us. You can do this from either the 'Support' or 'Developer Forum' tabs at the top of this page.


Authoring a New Exchange Element (Professional & Enterprise Tiers Only)

To author a new Exchange Element, you will need to visit the Exchange Authoring form and fill out all fields accordingly.

  1. Go to the Authoring Form: http://www.exosite.io/business/exchange/author/

  2. Add a Unique Element Name:

  3. Choose Element Type:

    • NOTE: When a Solution Template type is chosen, a public GitHub repo URL is required.

  4. Short Description: Give a brief overview of the element. As you add your short description, the Live Preview card will be updated on the right.

  5. Thumbnail Image: The thumbnail will be used on the Element card, and once added to this form, the live preview will update accordingly. The thumbnail image must be fixed at 200x150 pixels.

  6. Background Color: Use the background color as a fallback in case your thumbnail does not fill the full area.

  7. Full Element Description: Provide as much content as necessary to fully detail what the element is and what it provides businesses that choose to use the element.

  8. Tech Specs: Use this area as a high-level bulletpoint explanation of the element.

  9. Contact: Provide the desired point-of-contact businesses can use if they need to contact the author of the element.

  10. Detail Image: This image is a larger image that will be displayed on the Element Details page when users click on the element card for more information.

  11. Attachment Upload: When authoring a content download element, use this Attachment Upload feature to include the content this element will supply. The element can only support a single attachment. If multiple files are required, a ZIP file can be uploaded instead.

  12. Preview [button]: This button will open a dialog modal that shows what the Element's details page will look like using the current form field values, color, and detail image.