Skip to content

Commit 28738de

Browse files
hcourdenthcourdent
authored
Some docs fixes to match tootips (windmill-labs#157)
1 parent ae81a6e commit 28738de

File tree

5 files changed

+138
-65
lines changed

5 files changed

+138
-65
lines changed

‎docs/reference/context_variables.png renamed to ‎docs/core_concepts/2_variables_and_secrets/context_variables.png

File renamed without changes.

‎docs/core_concepts/2_variables_and_secrets/index.md

Lines changed: 80 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,82 @@ When writing scripts, you may want to reuse variables, or safely pass secrets to
44
scripts. You can do that with **Variables**. Windmill has user-defined variables
55
and contextual variables.
66

7-
:::info Secrets
7+
Variables are dynamic values that have a key associated to them and can be retrieved during the execution of a Script or Flow.
8+
9+
All Variables (not just secrets) are encrypted with a workspace specific symmetric key to avoid leakage.
10+
11+
There are two types of Variables in Windmill: user-defined and contextual.
12+
13+
## User-defined Variables
14+
15+
User-defined Variables is essentially a key-value store where every user can
16+
read, set and share values at given keys as long as they have the privilege to
17+
do so.
18+
19+
They are editable in the UI and also readable if they are not
20+
Secret Variables.
21+
22+
Inside the Scripts, one would use the Windmill client to interact with the
23+
user-defined Variables.
24+
25+
Python:
26+
27+
```python
28+
import wmill
29+
30+
wmill.get_variable("u/user/foo")
31+
wmill.set_variable("u/user/foo", value)
32+
```
33+
34+
TypeScript (Deno):
35+
36+
```typescript
37+
import * as wmill from 'https://deno.land/x/windmill/index.ts';
38+
39+
wmill.getVariable('u/user/foo');
40+
wmill.setVariable('u/user/foo', value);
41+
```
42+
43+
Note that there is a similar API for getting and setting [Resources](../3_resources_and_types/index.md)
44+
which are simply Variables that can contain any JSON values, not just a string
45+
and that are labeled with a [Resource Type](../3_resources_and_types/index.md#create-a-resource-type) to be automatically
46+
discriminated in the auto-generated form to be of the proper type (e.g a
47+
parameter in TypeScript of type `pg: wmill.Resource<'postgres'>` is only going to
48+
offer a selection over the resources of type postgres in the auto-generated UI)
49+
50+
There is also a concept of [state](../../reference/index.md#state-and-internal-state) to share values
51+
across script executions.
52+
53+
54+
## Contextual variables
55+
56+
Contextual Variables are variables whose values are contextual to the Script
57+
execution. They are are automatically set by Windmill. This is how the Deno and Python clients get their implicit
58+
credentials to interact with the platform.
59+
60+
See the `Contextual` tab on the <a href="https://app.windmill.dev/variables" rel="nofollow">Variable page</a> for the list of reserved variables and what they are used for.
61+
62+
You can use them in a Script by clicking on "+Context Var":
63+
64+
![Contextual variable](./context_variables.png)
65+
66+
| Name | Value |
67+
| -------------- | ------------------------------------------------------------------------------------------------------------------- |
68+
| `WM_WORKSPACE` | Workspace id of the current script |
69+
| `WM_TOKEN` | Token ephemeral to the current script with equal permission to the permission of the run (Usable as a bearer token) |
70+
| `WM_EMAIL` | Email of the user that executed the current script |
71+
| `WM_USERNAME` | Username of the user that executed the current script |
72+
| `WM_BASE_URL` | Base URL of this instance |
73+
| `WM_JOB_ID` | Job id of the current script |
74+
| `WM_JOB_PATH` | Path of the script or flow being run if any |
75+
| `WM_FLOW_JOB_ID` | Job id of the encapsulating flow if the job is a flow step |
76+
| `WM_FLOW_PATH` | Path of the encapsulating flow if the job is a flow step |
77+
| `WM_SCHEDULE_PATH` | Path of the schedule if the job of the step or encapsulating step has been triggered by a schedule |
78+
| `WM_PERMISSIONED_AS` | Fully Qualified (u/g) owner name of executor of the job |
79+
| `WM_STATE_PATH` | State resource path unique to a script and its trigger |
80+
81+
82+
## Secrets
883

984
Secrets are encrypted when stored on Windmill. From a usage standpoint, secrets
1085
are kept safe in three different ways:
@@ -15,19 +90,11 @@ are kept safe in three different ways:
1590
unless explicitly shared. A secret in `f/devops/secret` will be accessible by anyone with read access to `f/devops`.
1691
- Secrets **cannot be viewed outside of scripts**. Note that a user could still
1792
`print` a secret if they have access to it from a script.
18-
- Accessing secrets generates `variables.decrypt_secret` event that ends up in
19-
the [Audit Logs](https://app.windmill.dev/audit_logs). It means that **you can audit who accesses secrets**. Additionally you can audit results, logs and
93+
- Accessing secrets generates `variables.decrypt_secret` event that ends up in
94+
the <a href="https://app.windmill.dev/audit_logs" rel="nofollow">Audit Logs</a>. It means that **you can audit who accesses secrets**. Additionally you can audit results, logs and
2095
script code for every script run.
2196

22-
:::
23-
24-
## Contextual variables
25-
26-
Contextual variables are automatically set by Windmill. See the `Contextual` tab
27-
on the [Variables page](https://app.windmill.dev/variables) for the list of
28-
reserved variables and what they are used for.
29-
30-
## Add a variable or secret
97+
## Add a Variable or Secret
3198

3299
You can define variables from the **Variables** page. Like all objects in
33100
Windmill, variable ownership is defined by the **path** - see
@@ -84,4 +151,4 @@ curl -s -H "Authorization: Bearer $WM_TOKEN" \
84151
| jq -r .value
85152
```
86153

87-
The last example is in bash and showcase well how it works under the hood: It fetches the secret from the API using the job's permissions through the ephemeral token passed as environment variable to the job.
154+
The last example is in bash and showcase well how it works under the hood: It fetches the secret from the API using the job's permissions through the ephemeral token passed as environment variable to the job.

‎docs/getting_started/8_trigger_scripts/index.md

Lines changed: 28 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,16 @@
11
# Triggering Scripts
22

3-
Scripts can be triggered in 6 ways:
3+
Scripts can be triggered in 6 ways.
4+
5+
On-demand triggers:
46
- [Auto-generated UIs](#auto-generated-uis)
57
- [Customized UIs with the App Editor](#customized-uis-with-the-app-editor)
6-
- [Trigger Scripts from Flows](#trigger-scripts-from-flows)
8+
- [Trigger Scripts from Flows](#trigger-scripts-from-flows) that have their [own ways of triggering](../9_trigger_flows/index.md)
9+
- [Trigger Scripts from CLI (Command Line Interface)](#trigger-scripts-from-cli-command-line-interface)
710
- [Schedule the Execution of a Script](#schedule-the-execution-of-a-script)
11+
12+
Triggers from external events:
813
- [Trigger Scripts from Webhooks](#trigger-scripts-from-webhooks)
9-
- [Trigger Scripts from CLI (Command Line Interface)](#trigger-scripts-from-cli-command-line-interface)
1014

1115

1216
:::info Scripts in Windmill
@@ -15,7 +19,9 @@ Scripts can be triggered in 6 ways:
1519

1620
:::
1721

18-
## Auto-generated UIs
22+
## On-demand triggers
23+
24+
### Auto-generated UIs
1925

2026
Windmill automatically generates user interfaces (UIs) for scripts and flows based on their parameters.
2127

@@ -49,7 +55,7 @@ More details on our page dedicated to [Auto-generated UIs](../../core_concepts/6
4955

5056
:::
5157

52-
## Customized UIs with the App Editor
58+
### Customized UIs with the App Editor
5359

5460
Windmill embeds a WYSIWYG app editor. It allows you to build your own UI with drag-and-drop components and to connect your data to scripts and flows in minutes.
5561

@@ -69,7 +75,7 @@ More details on our page dedicated to [Windmill App Editor](../../getting_starte
6975

7076
:::
7177

72-
## Trigger Scripts from Flows
78+
### Trigger Scripts from Flows
7379

7480
Flows are basically sequences of scripts that execute on after each other or [in parallel](../../flows/13_flow_branches.md#branch-all).
7581

@@ -89,7 +95,7 @@ More details on our page dedicated to [Triggering flows](../9_trigger_flows/inde
8995

9096
:::
9197

92-
## Schedule the Execution of a Script
98+
### Schedule the Execution of a Script
9399

94100
Windmill allows you to schedule scripts using a user-friendly interface and control panels, **similar to [cron](https://crontab.guru/)** but with more features.
95101

@@ -111,7 +117,21 @@ More details on our page dedicated to [Scheduling jobs](../../core_concepts/1_sc
111117

112118
:::
113119

114-
## Trigger Scripts from Webhooks
120+
### Trigger Scripts from CLI (Command Line Interface)
121+
122+
The `wmill` cli allows you to interact with Windmill instances right from your terminal.
123+
124+
![Trigger Windmill from Command Line Interface](../../assets/advanced/cli/setup.gif)
125+
126+
:::info
127+
128+
More details on our pages dedicated to [CLI](../../advanced/3_cli/index.md).
129+
130+
:::
131+
132+
## Triggers from external events
133+
134+
### Trigger Scripts from Webhooks
115135

116136
In Windmill, webhooks are autogenerated for each Script and Flow, providing either asynchronous or synchronous execution modes.
117137

@@ -139,16 +159,4 @@ Each script (and flow) has its own webhooks on Windmill ...
139159

140160
More details on our page dedicated to [Webhooks](../../core_concepts/4_webhooks/index.md).
141161

142-
:::
143-
144-
## Trigger Scripts from CLI (Command Line Interface)
145-
146-
The `wmill` cli allows you to interact with Windmill instances right from your terminal.
147-
148-
![Trigger Windmill from Command Line Interface](../../assets/advanced/cli/setup.gif)
149-
150-
:::info
151-
152-
More details on our pages dedicated to [CLI](../../advanced/3_cli/index.md).
153-
154162
:::

‎docs/getting_started/9_trigger_flows/index.md

Lines changed: 26 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,20 @@
11
# Triggering Flows
22

3-
Scripts can be triggered in 6 ways:
3+
Flows can be triggered in 6 ways.
4+
5+
On-demand triggers:
46
- [Auto-generated UIs](#auto-generated-uis)
57
- [Customized UIs with the App Editor](#customized-uis-with-the-app-editor)
68
- [Schedule the Execution of a Flow](#schedule-the-execution-of-a-flow)
7-
- [Scheduling + Trigger Scripts](#scheduling--trigger-scripts)
8-
- [Trigger Flows from Webhooks](#trigger-flows-from-webhooks)
99
- [Trigger Flows from CLI (Command Line Interface)](#trigger-flows-from-cli-command-line-interface)
1010

11+
Triggers from external events:
12+
- [Scheduling + Trigger Scripts](#scheduling--trigger-scripts)
13+
- [Trigger Flows from Webhooks](#trigger-flows-from-webhooks)
1114

15+
## On-demand Triggers
1216

13-
## Auto-generated UIs
17+
### Auto-generated UIs
1418

1519
Windmill automatically generates user interfaces (UIs) for scripts and flows based on their parameters.
1620

@@ -44,7 +48,7 @@ More details on our page dedicated to [Auto-generated UIs](../../core_concepts/6
4448

4549
:::
4650

47-
## Customized UIs with the App Editor
51+
### Customized UIs with the App Editor
4852

4953
Windmill embeds a WYSIWYG app editor. It allows you to build your own UI with drag-and-drop components and to connect your data to scripts and flows in minutes.
5054

@@ -64,7 +68,7 @@ More details on our page dedicated to [Windmill App Editor](../../getting_starte
6468

6569
:::
6670

67-
## Schedule the Execution of a Flow
71+
### Schedule the Execution of a Flow
6872

6973
Windmill allows you to schedule scripts using a user-friendly interface and control panels, **similar to [cron](https://crontab.guru/)** but with more features.
7074

@@ -86,7 +90,21 @@ More details on our page dedicated to [Scheduling jobs](../../core_concepts/1_sc
8690

8791
:::
8892

89-
## Scheduling + Trigger Scripts
93+
### Trigger Flows from CLI (Command Line Interface)
94+
95+
The `wmill` cli allows you to interact with Windmill instances right from your terminal.
96+
97+
![Trigger Windmill from Command Line Interface](../../assets/advanced/cli/setup.gif)
98+
99+
:::info
100+
101+
More details on our pages dedicated to [CLI](../../advanced/3_cli/index.md).
102+
103+
:::
104+
105+
## Triggers from External Events
106+
107+
### Scheduling + Trigger Scripts
90108

91109

92110
A particular use case of schedules are Trigger Scripts. Their purpose is to pull data from an external source and return all of the new items since the last run.
@@ -99,7 +117,7 @@ More details on our page dedicated to [Trigger Scripts](../../flows/10_flow_trig
99117

100118
:::
101119

102-
## Trigger Flows from Webhooks
120+
### Trigger Flows from Webhooks
103121

104122
In Windmill, webhooks are autogenerated for each Script and Flow, providing either asynchronous or synchronous execution modes.
105123

@@ -130,18 +148,6 @@ More details on our page dedicated to [Webhooks](../../core_concepts/4_webhooks/
130148

131149
:::
132150

133-
## Trigger Flows from CLI (Command Line Interface)
134-
135-
The `wmill` cli allows you to interact with Windmill instances right from your terminal.
136-
137-
![Trigger Windmill from Command Line Interface](../../assets/advanced/cli/setup.gif)
138-
139-
:::info
140-
141-
More details on our pages dedicated to [CLI](../../advanced/3_cli/index.md).
142-
143-
:::
144-
145151

146152
<!-- Resources -->
147153

‎docs/reference/index.md

Lines changed: 4 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -277,7 +277,7 @@ is a **simplified git** with two simplifying assumptions:
277277

278278
### Python client
279279

280-
By authenticating with the [reserved variable](#contextual-variables)
280+
By authenticating with the [reserved variable](../core_concepts/2_variables_and_secrets/index.md#contextual-variables)
281281
`WM_TOKEN`, the Python client can interact with the Windmill platform from
282282
within the script jobs. This can be used, for instance, to:
283283

@@ -531,7 +531,7 @@ direct consequence, the variables (including secrets) that are accessible to the
531531
scripts are only those whom the user or group has visibility on, given his
532532
[permissions](#permissions-and-acl).
533533

534-
Similarly for the [Contextual Variable](#contextual-variables) `WM_TOKEN` which
534+
Similarly for the [Contextual Variable](../core_concepts/2_variables_and_secrets/index.md#contextual-variables) `WM_TOKEN` which
535535
contains an ephemeral token (ephemeral to the script execution), which has the
536536
same privilege and permissions as the owner in `permissioned_as`. The
537537
[Python client](#python-client) inside the script implicitly uses that same
@@ -623,20 +623,12 @@ hash, and both the edit and the execution would be visible from the
623623
### [Contextual Variables](../core_concepts/2_variables_and_secrets/index.md#contextual-variables)
624624

625625
Contextual Variables are variables whose values are contextual to the Script
626-
execution. This is how the Deno and Python clients get their implicit
626+
execution. They are are automatically set by Windmill. This is how the Deno and Python clients get their implicit
627627
credentials to interact with the platform.
628628

629-
| Name | Value |
630-
| -------------- | ------------------------------------------------------------------------------------------------------------------- |
631-
| `WM_TOKEN` | Token ephemeral to the current script with equal permission to the permission of the run (Usable as a bearer token) |
632-
| `WM_EMAIL` | Email of the user that executed the current script |
633-
| `WM_USERNAME` | Username of the user that executed the current script |
634-
| `WM_JOB_ID` | Job id of the current job |
635-
| `WM_WORKSPACE` | The workspace id of the current job |
636-
637629
You can use them in a Script by clicking on "+Context Var":
638630

639-
![contextual variable](./context_variables.png)
631+
![contextual variable](../core_concepts/2_variables_and_secrets/context_variables.png)
640632

641633
## [Resource](../core_concepts/3_resources_and_types/index.md)
642634

0 commit comments

Comments
 (0)