Overview

The dexi.yml you'll see mentioned throughout this documentation describes how dexi.io should interact with your service. This includes configuration, authentication, components and REST endpoints.

Metadata

The top section of the YML format is metadata for the app itself. An exhaustive list of properties are shown below:

Property	Description	Example	Required?
apiVersion	The API version. Should always be `apps.dexi.io/v1.0` at the moment	apps.dexi.io/v1.0	Yes
kind	The kind of YML document. Should always be `App` at the moment	App	Yes
name	A unique identifier for your app. Recommended format is lowercase and snake-casing	google-drive	Yes
title	A human-friendly title for your app.	Google Drive	Yes
description	A longer description of what your app provides	"Read files from and write files to Google Drive"	Yes
categories	A list of valid app categories. The list of categories is fixed and you must choose one or more of the available categories. Click here for the complete list	- files - database	No
keywords	Contains an array of keywords (strings) to help users find your app in the dexi app store.	- google - drive - files	No
appUrl	A url to more information about the app or about your company	https://dexi.io	Yes

Example:

apiVersion: apps.dexi.io/v1.0
kind: App
name: google-drive
title: Google Drive Integration
description: Connect to Google Drive
categories:
  - files
keywords:
  - google
  - drive
  - files
appUrl: https://dexi.io

Properties

The properties section allows you to specify general values for use throughout the rest of the specification. The values in here are made available as variables - and are most often used for repetitive values that you'd like to be able to change in 1 place.

This section is not required but recommended for storing the "base url" of your service

properties:
  baseUrl: http://my-app.my-public-url.com/
  
# Which can then be referenced like this:
specification:
  validate:
    url: "${baseUrl}/dexi/activations/validate"
    method: POST

App configuration and validation

This section describes what kind of configuration, authentication and validation your app requires.

Property	Description	Required?
specification.validate	The endpoint for validating the provided configuration. See "Endpoints" for more information on the format	No
specification.configuration	An object containing all configuration fields. This configuration is prompted when the user activates your app and will be available for all your components. See Configuration Field Types for a list of field types and how to use them.	No

Example:

specification:
  validate: # Validation end point
    url: "${baseUrl}/dexi/activations/validate"
    method: POST

  configuration: #Configuration fields
    type:
      sortOrder: 1 #To ensure the order is retained add this
      title: "Type" #Label of the field
      required: true #If it is required
      type: enum #Enums allows to select from a list of specific values
      options:
        postgresql: PostgreSQL
        mysql: MySQL
        sqlserver: MS SQL
        sap: SAP Hana DB
        oracle: Oracle DB
      configuration:
        emptyText: Select database type...
    host:
      sortOrder: 2
      title: Host
      required: true
      help: The host of the database
      placeholder: my-database-host.com #Shown in the field when it is empty
      type: string
      dependsOn: [ "type" ] #Only enable this field when other fields have value

Components

The last section contains the actual components for your app. Each component is "single-purpose" and exposes a specific type of functionality. This is defined by its type property.

We currently have 2 groups of component types - "data" and "file" types. The data types are all prefixed with "data-" and deal with structured data such as rows from a database or results from a robot. Meaning data that have a row-like structure of { name: value} and exists as a list.

The basic structure of any component is the same - for further information about the specific components see Data Components, File Components or Other Components .

Property	Description	Example	Required?
name	Like the app name - this is a code name or identifier. Format is recommended to be lower case and snake-casing.	insert-row-into-database	Yes
type	The type decides what sort of component this is. As mentioned above see further documentation on these elsewhere.	data-storage	Yes
title	A human-readable title for the component. This is what the users sees and will use to determine if this component is what they are looking for	Write row to database	Yes
description	A longer description of what the component does	Writes a row to a database and ignores any duplicates it might encounter.	Yes
specification	This is an object that contains the actual details of the component. See further information on this structure for the individual component types as mentioned above this table.	See Data Components, File Components or Other Components	Yes

Example:

components:

- name: write-file-to-googledrive
  type: file-storage
  title: Save file to Google Drive
  description: Saves a file to your Google Drive
  specification:
    configuration:
      path:
        title: Path
        type: string
        help: The base path to the Google Drive folder where you would like the results to be placed.
        placeholder: ${app.defaultPath}
        defaultValue: ${app.defaultPath}
        required: true
    validate:
      url: "${baseUrl}/dexi/component/support/validate"
      method: POST
    endpoint:
      url: "${baseUrl}/dexi/file/storage/write"
      method: POST