Archive Trac docs multistage

Docs Multistage

Legacy Trac archive page imported from docs_multistage. Source: https://genapp.rocks/wiki/wiki/docs_multistage. Review age, links, and examples before treating as current.

multistage execution

---

N.B. Preliminary Design Document

---

staging

• multistage execution provides the ability for an executable show and hide the inputs of a job through repeated submission and results of a module.

• the module file needs a special section defined in fields which lists the possible stages and groups the associated input fields by ids

• in particular, the "multistage" tag is a set of tags which define the stages and associated input field ids for each stage

  • the values of the "multistage" stage tags should be considered labels visible to the user, since these may be displayed

• e.g.

...
    "fields" : [
        {
            "role" : "input"
            ,"type" : "info"
            ,"multistage" : { "stage_X": [ "c", "d" ], "stage_Y" : [ "e", "f" ] }
        }
        ,{
            "role" : "input"
            ,"id"   : "a"
            ...
        }
        ,{
            "role" : "input"
            ,"id"   : "b"
            ...
        }
        ,{
            "role" : "input"
            ,"id"   : "c"
            ...
        }
        ,{
            "role" : "input"
            ,"id"   : "d"
            ...
        }
        ,{
            "role" : "input"
            ,"id"   : "e"
            ...
        }
        ,{
            "role" : "input"
            ,"id"   : "f"
            ...
        }

• in the above example case, when the user first view the module, only inputs "a" & "b" will appear
• when a submitted job's underlying executable returns a "_stage" tag in the output JSON

    "_stage" : {
                 "show" : [ ... ] 
                 ,"hide" : [ ... ]
                 ,"submit" : {
                                "text" : "text for the submit button"
                                 ,"id"  : "id to be returned under stage:id when submitted"
                             }
               }

• required:
  • the "show" tag lists stage tags to display. Each tag defines a set of fields to display as specified the the modules "multistage" definition (above)
  • if the "show" tag is empty, i.e. has no values listed inside the [], this forces a reset of the user interface and all stages will be hidden
• optional:
  • the "hide" tag is used to hide previously displayed stage tags' fields
  • the "submit":"text" tag has replacement text for the submit button which will be displayed instead of "Submit"
  • the "submit":"id" tag holds a string or number that will be returned in the JSON input when submitted as "stage":"id":...
  • this can be useful for an executable keeping track of specific job submissions
• when this object is received by the user interface
• previously displayed input fields will be disabled (grayed out, but still visible)
• any "show" tag list referenced fields will be displayed and active
• any "hide" tag list referenced fields will be hidden
• if specified, the "submit" button text will be replaced
• a "Go back" button will be displayed
  • pressing this will push the user interface back to the state before the previous "submit"
• any fields referenced in the "multistage" object by the list of tags returned under "_stage":"show" will be displayed and the input will be active
• any fields previously displayed (i.e. with a previous _stage or the original input) will be disabled (grayed out, but still visible)
• any fields referenced by the list of
• e.g.
  • show & enable input fields
  • in stage_X : {{{ "_stage" : { "show" : [ "stage_X" ] } }}}
  • in stage_Y : {{{ "_stage" : { "show" : [ "stage_X" ] } }}}
  • in stage_X and stage_Y : {{{ { "_stage" : { "show" : [ "stage_X", "stage_Y" ] } }}}
• when a subsequent "submit" occurs, the executable will receive all non-hidden inputs (even if disabled) and an extra JSON input:

   "_stage" : {
               "active" : [ ... ]
               ,"id" : ...
              }

• the active tag will list the stages that were active (e.g. what was returned during in the previous "_stage":"show":[])
• the "id" will be present if "_stage":"submit":"id" was present

changing input field values

• it may be that you wish to have complex dynamic inputs based upon processing results
• this can be accomplished by having the executable include the "_inputs" tag in the output JSON

    "_inputs" : {
                  "some_id" : value
                  ,"some_other_id" : value
                  ,"some_repeat_id" : [ value1, value2, ... ]
                  ...
                }

• these values will be updated in the user interface
• careful application of this to read-only fields and repeaters can provide quite complex input
• the repeater id should be set to match the length of the repeat vectors if used

attaching to jobs

• full support is provided for re-attaching to jobs in any "stage" so that a user can continue to "submit" or "go back"