03-flows.md

title	layout	order
Flows	doc_page.html	3

Flows

Flows are a list of executed steps. A command are a flow for piscosour. The flows don't work over a context, step do that, so flows can work over multiple steps, and different contexts.

The flow execution is sequential, step by step, and step are executed for each context. Note that if a step is no defined for any context it is no executed.

Flows are implements with three files in the recipe:

-rwxr-xr-x    1 pisco  staff   flows/flow-name/config.json
-rwxr-xr-x    1 pisco  staff   flows/flow-name/info.md

Where the config.json file has the configuration, info.md explain and document the flow.

Note, it exists a scaffold generator tool

config.json configuration

The config.json file has the definition of the flow. A example is:

{
  "name": "Create from scratch",
  "description": "Starting a repository from scratch",
  "type" : "normal",
  "excludes" : [ "any" ],
  "isGenerator": true,
  "params": {
    "param1": "value1",
    "param2": 2,
    "param3": true,
    "param4": { "object1": "value" }
  },
  "steps": {
    "step1": {
        "excludes" : [ "any" ],
        "params": {
            "param1": "value1",
            "param2": 2
        }
    },
    "step2": {
        "reloadContext" : true,
        "type" : "flow",
    },
    "step3": {
        "implementation-check" : false    
    }
  }
}

In the config.json file could be configured the following fields:

name property

Short name of the flow, it must be descriptive and unique.

• It is mandatory
• String type expected

description property

It is a short description about the flow.

• It is mandatory
• String type expected

type property

Type of the flows

• It is optional.
• String type expected.
• Two value options:

1. normal: appears in the command list. It is the default value.
2. internal: doesn't appear int command list. It is for an internal purpose.

excludes property

Is an array of contexts witch execution is excluded for all steps of this flow. For example:

{
  "name": "validate",
  "description": "Validate CI flow",
  "excludes": ["develop", "master", "feature", "hotfix", "release", "merger", "consolidation"],
    "steps": {
      "install": {
        "type": "flow"
      },
  ....
}

The execution of this flow will prompt this message on output:

[18:13:32] Run of flow "install" is excluded for context "feature"

isGenerator property

If the steps creates a context, then this flag must be with a 'true' value.

• It is optional
• The default value is 'false'.
• Boolean type expected

params property

Others customized paramaters, see parameters for more information.

• It is optional
• The default value is an empty array. "params": []"
• Array of objects expected

Example:

{
  "params": {
    "param1": "value1",
    "param2": 2,
    "param3": true,
    "param4": { "object1": "value" }
  }
}

Understanding parameters in flows

The 'config.json' file of a flow has the following possibilities:

a. Common parameters for all steps

{
  "params": {
    "param1": "value1",
    "param2": "value2",
    "param3": "value3"
  }
}

b. Common parameters for all contexts in a specific step

{
  "params": {},
  "steps" : {
    "stepName" : {
      "params" : {
        "param1": "value1",
        "param2": "value2",
        "param3": "value3",
      }
    }
  }
}

c. Parameters for a specific step and context

{
  "params": {},
  "steps" : {
    "stepName" : {
      "contextName" : {
        "params" : {
          "param1": "value1",
          "param2": "value2",
          "param3": "value3"
        }
      }
    }
  }
}

Allways the parameters are available with this.params.

Example:

module.export = {
  run: function() {
    console.log(
      this.params.param1,
      this.params.param2,
      this.params.param3);
  }
}

The priority is (from high to low):

1. Parameters for a specific step and context
2. Common parameters for all contexts in a specific step
3. Common parameters for all steps.

step property

List of sequential steps in the flow.

• It is mandatory
• Object with the list of step-key:config. Where config is an object that optionally contains:
  • type which can be flow or step (step is default value). Flow calls another flow with the name of the step. Nesting could be whatever.
  • params with the list of parameters of the step. See parameters for more information. Please note that it isn't appropriate to use params into the configuration of the flow. Usually this must be configurated in the step config.json file. The recommendation is to use params just to overwrite a step parameter.
  • input to share in a steps a previously emitted parameter in another steps. Please see parameters between steps for more information.
  • excludes array of contexts which execution is excluded for this step: Log output
  • implementation-check If this step is not implemented execution will fail unless this parameter was set to false (default is true).Log output
  • reloadContext (default is false): If true the presence of contexts is re-evaluated at this step. Searching for new contexts that appears. See example

The execution of a flow with exclude on it will prompt this message on output:

[18:13:32] Run of step "build" is excluded for context "feature"

The execution of a flow with implementation-check on it will prompt this message on output:

[18:13:32] Run of step "provide-env" is allowed to be not implemented for context "app"

reloadContext example:

{
  "name": "consolidate",
  "description": "[Git flow]: Check for semver relate updates",
  "steps": {
    "start" : {
      "type" : "flow"
    },
    "finish" : {
      "reloadContext" : true,
      "type" : "flow"
    }
  }
}

In this example start flow change old context named master to new context named consolidation, finish flow needs to reload contexts in order to realize that this new context is present and execute finish using the new context.

All options example:

{
  "steps": {
    "step1": {
        "excludes" : [ "any" ],
        "params": {
            "param1": "value1",
            "param2": 2
        }
    },
    "step2": {
        "reloadContext" : true,
        "type" : "flow",
    },
    "step3": {
        "implementation-check" : false    
    }
  }
}

Repeated steps

In some cases, it may be necessary to repeat the same step twice or more, with different parameters. Then it is possible to identify the step with a sufix separated with ':' character, like step1:id1.

Example:

{
  "steps": {
    "mystep:first": {
      "params": {
        "myparam": "value1"
      }
    },
    "mystep:second": {
      "params": {
        "myparam": "value2"
      }
    }
  }
}

In the above example, mystep is executed twice with different myparam configuration. It is advisable that the suffix has a semantic value which describe the differences.

Scaffold generator

Pisco provides a scaffold generator. Launch it placed inside your recipe with:

$ cd your-recipe
$ pisco recipe:add-flow