// This module is included in the following assembly:
//
// *openshift_pipelines/understanding-openshift-pipelines.adoc

[id="about-whenexpression_{context}"]
= When expression

When expressions guard task execution by setting criteria for the execution of tasks within a pipeline. They contain a list of components that allows a task to run only when certain criteria are met. When expressions are also supported in the final set of tasks that are specified using the `finally` field in the pipeline YAML file.

The key components of a when expression are as follows:

* `input`: Specifies static inputs or variables such as a parameter, task result, and execution status. You must enter a valid input. If you do not enter a valid input, its value defaults to an empty string.
* `operator`: Specifies the relationship of an input to a set of `values`. Enter `in` or `notin` as your operator values.
* `values`: Specifies an array of string values. Enter a non-empty array of static values or variables such as parameters, results, and a bound state of a workspace.

The declared when expressions are evaluated before the task is run. If the value of a when expression is `True`, the task is run. If the value of a when expression is `False`, the task is skipped.

You can use the when expressions in various use cases. For example, whether:

* The result of a previous task is as expected.
* A file in a Git repository has changed in the previous commits.
* An image exists in the registry.
* An optional workspace is available.

The following example shows the when expressions for a pipeline run. The pipeline run will execute the `create-file` task only if the following criteria are met: the `path` parameter is `README.md`,  and the `echo-file-exists` task executed only if the `exists` result from the `check-file` task is `yes`.

[source,yaml]
----
apiVersion: tekton.dev/v1beta1
kind: PipelineRun <1>
metadata:
  generateName: guarded-pr-
spec:
  serviceAccountName: 'pipeline'
  pipelineSpec:
    params:
      - name: path
        type: string
        description: The path of the file to be created
    workspaces:
      - name: source
        description: |
          This workspace is shared among all the pipeline tasks to read/write common resources
    tasks:
      - name: create-file <2>
        when:
          - input: "$(params.path)"
            operator: in
            values: ["README.md"]
        workspaces:
          - name: source
            workspace: source
        taskSpec:
          workspaces:
            - name: source
              description: The workspace to create the readme file in
          steps:
            - name: write-new-stuff
              image: ubuntu
              script: 'touch $(workspaces.source.path)/README.md'
      - name: check-file
        params:
          - name: path
            value: "$(params.path)"
        workspaces:
          - name: source
            workspace: source
        runAfter:
          - create-file
        taskSpec:
          params:
            - name: path
          workspaces:
            - name: source
              description: The workspace to check for the file
          results:
            - name: exists
              description: indicates whether the file exists or is missing
          steps:
            - name: check-file
              image: alpine
              script: |
                if test -f $(workspaces.source.path)/$(params.path); then
                  printf yes | tee /tekton/results/exists
                else
                  printf no | tee /tekton/results/exists
                fi
      - name: echo-file-exists
        when: <3>
          - input: "$(tasks.check-file.results.exists)"
            operator: in
            values: ["yes"]
        taskSpec:
          steps:
            - name: echo
              image: ubuntu
              script: 'echo file exists'
...
      - name: task-should-be-skipped-1
        when: <4>
          - input: "$(params.path)"
            operator: notin
            values: ["README.md"]
        taskSpec:
          steps:
            - name: echo
              image: ubuntu
              script: exit 1
...
    finally:
      - name: finally-task-should-be-executed
        when: <5>
          - input: "$(tasks.echo-file-exists.status)"
            operator: in
            values: ["Succeeded"]
          - input: "$(tasks.status)"
            operator: in
            values: ["Succeeded"]
          - input: "$(tasks.check-file.results.exists)"
            operator: in
            values: ["yes"]
          - input: "$(params.path)"
            operator: in
            values: ["README.md"]
        taskSpec:
          steps:
            - name: echo
              image: ubuntu
              script: 'echo finally done'
  params:
    - name: path
      value: README.md
  workspaces:
    - name: source
      volumeClaimTemplate:
        spec:
          accessModes:
            - ReadWriteOnce
          resources:
            requests:
              storage: 16Mi
----
<1> Specifies the type of Kubernetes object. In this example, `PipelineRun`.
<2> Task `create-file` used in the pipeline.
<3> `when` expression that specifies to execute the `echo-file-exists` task only if the `exists` result from the `check-file` task is `yes`.
<4> `when` expression that specifies to skip the `task-should-be-skipped-1` task only if the `path` parameter is `README.md`.
<5> `when` expression that specifies to execute the `finally-task-should-be-executed` task only if the execution status of the `echo-file-exists` task and the task status is `Succeeded`, the `exists` result from the `check-file` task is `yes`, and the `path` parameter is `README.md`.

The *Pipeline Run details* page of the {product-title} web console shows the status of the tasks and when expressions as follows:

* All the criteria are met: Tasks and the when expression symbol, which is represented by a diamond shape are green.
* Any one of the criteria are not met: Task is skipped. Skipped tasks and the when expression symbol are grey.
* None of the criteria are met: Task is skipped. Skipped tasks and the when expression symbol are grey.
* Task run fails: Failed tasks and the when expression symbol are red.

