Big Dieselapps Overview Pub

Here's the big Dieselapps overview. Each section links to detailed topics.

Markup, Wikis and DSL

Dieselapps is based on a Markdown Wiki with DSL. Read more at Markup and DSL. Every "page" is a wiki topic, with a category, content and tags. The category and the tags are meaningful, see stories and specs below.

Basically, the wiki pages are written in markdown and can contain specific DSL instructions.

## This is an example topic

With some floating text, and...


The rules engine

While the DSL has many capabilities, the most important is defining and using rules. See DSL Reference for details.

A rule defines the behavior for a specific message or event - in this case generates another message, which is typical:

$when home.guest_arrived(name=="Jane")
=> chimes.welcome(name="Jane")
=> (welcome = "Welcome, ${name}")

A message looks much like a function, it has a qualified name and a list of attributes or parameters as well as a resulting list of attributes - you can declare a message's signature:

$msg home.guest_arrived(name) : (welcome)

$msg elk.devices.query(name) : (deviceList, totalCount)

The attributes can be typed, have default values etc, see more in Message.

Nodes and traces

During a flow's execution, it will look like nodes in a tree. The nodes are generally messages, values/variables, or just other information (logs etc).

When you see a trace, you can hover on the colored tags for additional details and info.

Values and contexts

Besides messages, in a flow you can set and read values of attributes. These are stored in a "context" much like a function's variables, see above the lights value being set to "bright" or the example above, setting => (welcome=...)


The payload is a special value which is passed from message to message, you can think of it as the "current result". Each message can set the value of payload and it is the invisible hand-off from message to message.

For instance in this sequence, the result of snakk.json is populated in the payload and implicitely passed on to ctx.echo:

$send snakk.json(url="...")
$send ctx.echo


There are several predefined executors - these prefixes are reserved:

  • snakk - HTTP requests
  • diesel - special engine functions
  • ctx - context functions
  • wiki - interact with the wiki engine

Read about these at Default executors - the most important are:

  • ctx.set(name=expr) to set a value
  • snakk.json(url,verb) to read a URL
  • diesel.return to stop a flow and return a value
  • entry point for an API
  • ctx.echo to echo any values into the trace

Abstract message

So what are these messages?

  • an external event
  • a call out to an executor like snakk.json
  • a container for other messages
  • etc

The rules engine decomposes messages based on these rules. A flow can be started in several ways, the most common is via an API call and

The main entry-point to trigger workflows is /diesel/rest which internally raises a event, which can be handled with rules like:

$when (path ~path "/v1/ems/:env/device/:deviceType/:deviceId/config/:configRole/*configPath")
=> ems.cfg.query(env, deviceId, deviceType, configRole)

The ~path operator is special for handling URL paths and will not only match the URL but also extract the values like :configRole and *configPath which are then populated as values in the context.


To reach out to other services, the snakk executor is used, the most used messages are:

  • snakk.text - read test from an URL
  • snakk.json - read json from an URL

The result is placed in payload.

Specs and stories

While all topics are equal, some are special when using rules, these two categories:

  • Spec - specs can specify messages and rules
  • Story - stories can trigger messages and rules

So, the typical constructs for a spec are $mock and $when, while for stories, they would typically use $send and $expect.

Rules gotchas Exclusive

These two rules would both trigger for the .../sync url, so to make only the first one trigger ang ignore the second, we'll make the first one exclusive - a rule tagged as exclusive will dominate all other applicable rules and exclude them:

$when <exclusive> (path ~path "/v1/ems/:env/device/:deviceType/:deviceId/config/sync")
=> ems.cfg.sync(env, deviceType, deviceId)

$when (path ~path "/v1/ems/:env/device/:deviceType/:deviceId/config/:configRole")
=> ems.cfg.query(env, deviceId, deviceType, configRole)

The fiddle

See Diesel Fiddle Guide for details on using the fiddle.

Environments and development process

Dieselapps is ran in the cloud and a local environment. The cloud deployment cannot reach the internal network, so for development you need to use a local environment (on premises), unless all other components are avaialble from the internet.

In the cloud, there are two projects (app is your app's name):

  • devapp which is the development project, includes stories
  • app which is the production project, no test stories, just specs

Cloud development model

When developing on the cloud, you work in the devapp project and when ready, sync only the specs to the app production project. When you go to User/Diff menu from the devapp project, it will compare to the app project by default.

On premises dev model

When running local, say on mybox1, only the production project is cloned, for production.

Typical development process:

  • work local
  • when happy, sync to cloud

Was this useful?    

By: Razie | 2020-09-29 | Tags: academy , reference

Viewed 38 times ( | Print ) this page.

You need to log in to post a comment!

© Copyright DieselApps, 2012-2021, all rights reserved.