Setup Recipe File for Applications

Before uploading an application you must write a recipe file, recipe.json. In the hello world example application you can find the file under the application folder. This file describes the flow of data and some application metadata. This walkthrough goes through how to set up a recipe file for you application.

Overview

The file is in JSON and has a set of application metadata and instructions on how to run the application. It also describes how DCH should wire up the application to the operator through the dataFlowGraphs.

{
  "name": "NAME",
  "description": "DESCRIPTION",
  "author": "FREE TEXT AUTHOR",
  "version": "SEMANTIC VERSION",
  "resourceRequirement": "RESOURCE REQUIREMENT",
  "dataFlowGraphs": [  ],
  "configurationDocuments": [  ],
  "readablePorts": [  ],
  "writablePorts": [  ]
}

Basic application information

The recipe file provides some basic information and will set it when you first upload the application.

• name: You can provide a name of the application, but note that you can't change this name from the recipe file when you upload a new version. DCH uses the name to find your application when you upload.

• description: Give a description of your application. You will also be able to set this from the DCH frontend.

• author: Set the name of the Author. This is a free text field and can be a list of contributors.

• version: Set the version of the application. It has to be semantic version and all changes to the application requires a version increase, including changing the BRIQL queries, the recipe file or the operator version.

Dataflow

The flow of data in the application is specified in the dataFlowGraphs. You can multiple dataflows and they specify the inputs and outputs and whether to use an operator. A dataflow specification can have three properties:

• operator: [Optional] The operator to pass the data to and expect outputs from.

• input: [Optional] The inputs that the application needs access to. Supported types are

  • STREAM - A single stream provided by the BRIQL query with the same id.

  • STREAM_COLLECTION - A collection of streams provided by the BRIQL query with the same id.

  • BRIQL_RESULT - The BRIQL result in JSON provided by the BRIQL query with the same id.

  • MODEL_METADATA - A list of metadata, in JSON, of the sites or buildings the application is installed on.

  • DOCUMENT - A document that is empty, to be used by the user, or pre-populated with the bundled documents.

• output: [Optional] The outputs the application will populate or generate. Supported types are

  • STREAM - A single stream.

  • DOCUMENT - A document in any format.

{ ...
  "dataFlowGraphs": [
    {
      "operator": {
        "id": "OPERATOR_ID",
        "version": "OPERATOR_VERSION"
      },
      "input": [
        {
          "id": "INPUT_NODE_ID",
          "type": "STREAM | STREAM_COLLECTION | MODEL_METADATA | BRIQL_RESULT | DOCUMENT"
        }
      ],
      "output": [
        {
          "id": "OUTPUT_NODE_ID",
          "type": "DOCUMENT | STREAM"
        }
      ]
    }
  ]
}

Configuration Documents and Schemas

The application will often need to be configured by the user. You can set configuration documents that will be available to the user through the Settings button on the application page. You also have to option to provide a schema for you configuration. DCH will look for a document named [INPUT_NODE_ID] -schema.json and use this to present the configuration as a web form. The schema is specified using JSON Schema. In the section configurationDocuments you can specify multiple configurations. Set the id of the input node to use as a configuration. You can specify a label and description that is used in the settings view. You also set the type to show the user what the format of the file must be. Note that a configuration must use an input node of type DOCUMENT and must be writable as described in the next section.

{ ...
  "configurationDocuments": [
    {
      "documentId": "INPUT_NODE_ID",
      "label": "USER_FACING_LABEL",
      "type": "json",
      "description": "USER_FACING_DESCRIPTION"
    }
  ]
}

Readable and Writable ports

An application can have documents that is protected IP of the application and DCH offers a way to white list documents that the end user has access to. You can set documents as readable or writable. All other documents will not be allowed to access. Note that this is only for the user and the operator is not impacted by these settings. Setting a document as writable also makes it readable. If you need input from the user, you'll have to set the document to writable. But if you just want the application dashboard to be able to read the document to present findings, you will set the document to readable.

• readablePorts: [optional] Documents that are readable by the user. Takes a list of node ids. Can be input or output nodes.

• writablePorts: [optional] Documents that are writable by the user. Takes a list of node ids. Can be input or output nodes.

{ ...
  "readablePorts": [
    "NODE_ID"
  ],
  "writablePorts": [
    "NODE_ID"
  ]
}