Skip to content

Agama DS candidate notation

Jump to bottom
Jose edited this page Sep 16, 2022 · 8 revisions

Overview

A candidate graphical notation for Agama Developer Studio is presented here. In short, it is a simplification of the flowcharting notation most programmers are familiar with and is focused on some peculiarities of Agama flows.

You may like to check this page before proceeding.

DSL's most-commonly used features

So far almost all bodies of implemented flows use just the following:

  • Call
  • Trigger
  • RRF
  • Finish
  • Log
  • Assignments and variable manipulations
  • Repeat/Quit (rarely)
  • When (without otherwise)

These hold enough power to do interesting stuff

When/Otherwise are the equivalents of C's if...else in case you don't know Agama DSL. Repeat/Quit resembles for...break

Note only Repeat and When are structural

When (w/o Otherwise) is common

A pattern that appears frequently in Agama flows is where upon a given condition the flow is simply terminated.

C-like example:

...
if (my boolean condition) {
    do A
    return X
}
do B
...

which is a better version than:

...
if (my boolean condition) {
    do A
    return X
} else {
    do B
    ...
}

Otherwise usage is a bit uncommon. Flows tend to look a lot like:

...
if (condition_1) {
    ...
}
...
if (condition_2) {
    ...
    if (condition_2_1) {
        ...
    }
    ...
}
...

no elses...

Proposal: No Otherwise

What if we don't offer an "else" equivalent in our graphical editor?

Not allowed Allowed
not_allowed allowed

It turns out this brings some benefits for diagramming as we'll see later

Note: In the table above, a rectangle denotes a process which can be a single step, or composite (containining diamonds and rectangles inside)

Unable to avoid the "else" in a flow? There is a workaround. Say we have:

if (cond) {
    A
} else {
    B
}

this can be re-arranged to:

A_done = false
if (cond) {
    A
    A_done = true
}
if (A_done is false) {
    B
}

a bit ugly, right

Proposed notation

  1. Use a rectangle to represent one of:

    • Call
    • Trigger
    • RRF
    • Quit (see below)
    • Finish
    • A set of consecutive assignments and/or variable manipulations

  2. Use an inverted dashed triangle to denote When (without otherwise). Think of it as the lower half of a diamond - I preferred it dashed because the (solid) inverted triangle is already used in flowcharting techniques for merging: when two or more sub-processes become one

  3. No nesting: no rectangles/triangles inside rectangles/triangles

  4. However, a set of consecutive rectangles can be grouped to configure iteration (Repeat). A Quit rectangle can appear at most once in a group of this kind

Note the proposal does not cover how an Agama flow header should be specified. However, that's clearly an easy task.

Layout rules

  • Consecutive elements (rectangles and triangles) are layed out like a string of beads (i.e. in a thread/strand) horizontally from left to right
  • No arrows to indicate direction, just an horizontal line
  • Under a triangle a new horizontal line is originated and the rules apply again
  • The last (right-most) element on a line originated by a triangle does not need to be chained to the next executable element in the upper line sequence:
    • unless a Finish rectangle was reached, the flow simply continues at the element to the right of the originating triangle
    • if there is nothing to the right of that triangle, try one level upwards and so on
  • The contents under a triangle can be collapsed to hide detail

Example

example1

Text inside elements is descriptive. Actual details would be shown on hover, like the boolean expression applicable to the triangle.

More rules

  • On a given line, there can be at most one Finish rectangle
  • Call, Trigger, RRF, Quit, and Finish rectangles can hold any number of assignments/variable manipulations before the given operation is executed. This helps making diagrams more compact, specifically by grouping data manipulation statements directly related to the operation of interest
  • Call, Trigger, RRF, and Quit can hold any number of Log statements anywhere

A more complete example

Click here

In this authentication flow the user's first login is detected and the user routed to other flows in order to enroll a second-factor. First, a mobile phone number is attempted, if failed, an OTP device is tried. This flow succeeds when a user has enrolled a credential (upon first login) or passed the 2fa authentication flow (subsequent logins).

The green callouts are not part of the diagram. They were added as a hint of the things people could see when the given element is explored.

Benefits

  • Simple representation:

    • No arrows needed
    • Collapsible
    • Hierarchical like a tree - in contrast to flow charts which resemble directed cyclic graphs

  • Easy to follow: left to right, top-bottom-up

  • Agama code generation should not be too hard

  • With this notation, the UI editor is probably easier to code in comparison to using the classical programming flowchart notation

  • ... and drag-and-drop may not be strictly necessary: one could right-click anywhere in an horizontal line to insert a component at that point

  • Developers might benefit from this tool, specially when they are starting with Agama

Wish list

  • Place icons on the rectangles to easily distinguish their kind

  • When creating/editing a Trigger rectangle, allow to pick the flow to trigger from the list of existing registered flows

  • When creating/editing a Call rectangle, allow to pick the Java class and method to invoke (like in "Actions" of former demo videos). This would be sophisticated

Clone this wiki locally