wiki:docs_multistage

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"
Last modified 6 months ago Last modified on Aug 16, 2017, 10:25:14 PM