OliveTin/docs/modules/ROOT/pages/args/env.adoc

[#env-vars]
= Environment variables

All argument names and values are also passed as environment variables as well, which can be very useful when passing several arguments to a script, for example.

[source,yaml]
.`config.yaml`
----
actions:
  - title: Print names of new files
    shell: /opt/newfile.py
    arguments:
      - name: filename
        type: unicode_identifier

      - name: filesizebytes
        type: unicode_identifier

      - name: fileisdir
        type: unicode_identifier

    execOnFileCreatedInDir:
      - /home/user/Downloads/
----

This is an example of a python script using the environment variables;

[source,python]
.`/opt/newfile.py`
----
#!/usr/bin/env python

import os

print(os.environ['OLIVETIN'])
print(os.environ['FILENAME'])
print(os.environ['FILESIZEBYTES'])
print(os.environ['FILEISDIR'])
----

[#execution-request-variables]
== Execution Request Variables

OliveTin injects two execution request variables into every action execution. They are available as template variables (e.g. in `shell`, `shellAfterCompleted`, or other template fields) and as environment variables passed to the process.

* `ot_username` — The username of the user who started the execution. In templates (version 3k) use `{{ .Arguments.ot_username }}`; in the process environment it is `OT_USERNAME`. For unauthenticated or automated runs this may be `guest`, `cron`, or similar, depending on how the action was triggered.
* `ot_executionTrackingId` — A unique identifier for this execution. In templates (version 3k) use `{{ .Arguments.ot_executionTrackingId }}`; in the process environment it is `OT_EXECUTIONTRACKINGID`. Useful for logging, correlating with the API or execution log, or idempotency in scripts.

In version 2k, the template syntax was `{{ ot_username }}` and `{{ ot_executionTrackingId }}` (without the `.Arguments.` prefix). Version 3k uses the `.Arguments.` form.

Example in a shell command (version 3k):

[source,yaml]
----
shell: echo "Run by {{ .Arguments.ot_username }} (execution {{ .Arguments.ot_executionTrackingId }})"
----

Example in a script using environment variables:

[source,shell]
----
#!/bin/sh
echo "Started by $OT_USERNAME with tracking id $OT_EXECUTIONTRACKINGID"
----

In xref:action_execution/aftercompletion.adoc[Execute after completion] (`shellAfterCompleted`), the same variables are available as template variables (e.g. `{{ .Arguments.ot_username }}`, `{{ .Arguments.ot_executionTrackingId }}` in version 3k); user-defined argument values are not passed there.

[#olivetin-env-var]
== The OLIVETIN environment variable

OliveTin sets the environment variable `OLIVETIN` to `1` for every action it runs. Scripts can check this variable to detect whether they are running inside OliveTin (for example, to adjust logging, skip interactive prompts, or enable OliveTin-specific behavior).

[source,shell]
.Example: detect OliveTin in a shell script
----
#!/bin/sh
if [ "$OLIVETIN" = "1" ]; then
  echo "Running under OliveTin"
else
  echo "Running outside OliveTin"
fi
----

== Using process environment in templates

To use the *process* environment (the environment OliveTin was started with) inside action template fields such as `shell` or `shellAfterCompleted`, use the `.Env` template variable: `{{ .Env.VAR_NAME }}`. This substitutes the value at execution time. See xref:advanced_configuration/config_envs.adoc#using-env-in-template-replacements[Using .Env in template replacements] for details and examples.

For other template features, including JSON encoding of argument and entity values, see xref:args/templates.adoc[Templates in actions].

== Notes

. Argument names are converted to uppercase for environment variables, `name: filename` becomes `FILENAME`.
. OliveTin sets `OLIVETIN=1` in the process environment for every action; see <<olivetin-env-var,The OLIVETIN environment variable>> above.
. The execution request variables are exposed as `OT_USERNAME` and `OT_EXECUTIONTRACKINGID` in the process environment; see <<execution-request-variables,Execution Request Variables>> above.
. The environment variables are passed into the execution context which uses a shell (/bin/sh on Linux), so it is also possible to use them with the $ notation in the `shell` line, like this; `shell: echo $FILENAME` for example.