96 lines
4.2 KiB
Plaintext
96 lines
4.2 KiB
Plaintext
[#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.
|