docs: enhance runbooks documentation with additional parameter functions and input types

learn/features/runbooks.mdx

@@ -1,5 +1,5 @@
 ---
 title: "Runbooks"
 description: "Create reusable, parameterized templates for common operations"
 ---
 
@@ -11,7 +11,7 @@
 
 ## What You'll Accomplish
 
 Runbooks let you create reusable templates for common operations. Instead of typing the same queries or commands repeatedly, you can:
 
 - Create parameterized templates stored in Git
 - Share approved procedures across your team
@@ -40,8 +40,8 @@
 ### Example Workflow
 
 1. **DBA creates** a runbook for looking up customer data
 2. **Template stored** in `runbooks/customer-lookup.runbook.sql`
 3. **Support team** selects the runbook, enters customer ID
 4. **Query executes** with proper validation and audit logging
 
 ---
@@ -52,10 +52,10 @@
 
 <Prerequisites />
 
 - A Git repository for storing runbooks
 - Git access credentials (SSH key or token)
 
 ### Step 1: Create a Runbook File
 
 Create a file in your repository with the `.runbook.<ext>` extension:
 
@@ -72,7 +72,7 @@
 ### Step 2: Configure Git Integration
 
 In the Web App:
 1. Go to **Manage > Runbooks**
 2. Click **Configure Repository**
 3. Enter your repository URL and credentials
 
@@ -83,9 +83,9 @@
   -c GIT_SSH_KEY=file://$HOME/.ssh/deploy_key
 ```
 
 ### Step 3: Run the Runbook
 
 1. Go to **Runbooks** in the sidebar
 2. Select `customer-lookup`
 3. Enter the customer ID
 4. Click **Execute**
@@ -94,7 +94,7 @@
 
 ## Template Syntax
 
 Runbooks use Go's `text/template` syntax. Parameters are defined with `{{ .parameter_name }}`.
 
 ### Basic Parameter
 
@@ -112,18 +112,26 @@
     | pattern "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$" }}
 ```
 
-### Parameter Functions
+### Parameter Functions                                   
 
 | Function | Description | Example |
 |----------|-------------|---------|
 | `description` | Help text for the input | `description "Customer ID"` |
 | `required` | Error message if empty | `required "This field is required"` |
 | `default` | Default value if not provided | `default "US"` |
+| `placeholder` | Placeholder text shown inside the input | `placeholder "e.g. 12345"` |
 | `type` | Input type for UI | `type "number"` |
 | `pattern` | Regex validation | `pattern "^[0-9]+$"` |
 | `options` | Dropdown options | `options "active" "inactive"` |
+| `order` | Integer that controls field order in the form | `order "1"` |
+| `minlength` | Minimum character length | `minlength "3"` |
+| `maxlength` | Maximum character length | `maxlength "100"` |
+| `asenv` | Pass value as environment variable instead of inline | `asenv "API_KEY"` |
 | `squote` | Wrap value in single quotes | `squote` |
 | `dquote` | Wrap value in double quotes | `dquote` |
+| `quotechar` | Wrap value with a custom character | `quotechar "$"` |
+| `encodeb64` | Encode value as base64 | `encodeb64` |
+| `decodeb64` | Decode a base64 value | `decodeb64` |
 
 ### Input Types
 
@@ -134,11 +142,16 @@
 | `email` | Email validation |
 | `date` | Date picker |
 | `time` | Time picker |
+| `tel` | Phone number input |
+| `url` | URL input |
+| `password` | Masked text input with show/hide toggle |
+| `textarea` | Multi-line text input |
+| `file` | File upload — value sent as base64 |
 | `select` | Dropdown (use with `options`) |
 
 ---
 
 ## Example Runbooks
 
 ### SQL: Customer Lookup
 
@@ -298,19 +311,19 @@
 
 ## Integration with Other Features
 
 | Feature | How It Works with Runbooks |
 |---------|---------------------------|
 | **Access Requests** | Runbook execution can require approval |
 | **Guardrails** | Rules apply to runbook-generated queries |
 | **Live Data Masking** | Results are masked automatically |
 | **Session Recording** | All executions are recorded |
 | **Parallel Mode** | Run runbooks across multiple connections |
 
 ---
 
 ## Troubleshooting
 
 ### Runbook Not Appearing
 
 **Check:**
 1. File ends with `.runbook.<ext>`
@@ -352,7 +365,7 @@
     Provide sensible defaults where appropriate
   </Card>
   <Card title="Version Control" icon="code-branch">
     Store runbooks in Git for history and review
   </Card>
 </CardGroup>
 
@@ -365,12 +378,12 @@
     Detailed Git setup and template syntax
   </Card>
   <Card title="Parallel Mode" icon="layer-group" href="/learn/features/parallel-mode">
     Run runbooks across multiple connections
   </Card>
   <Card title="Access Requests" icon="clock" href="/learn/features/access-requests/jit">
     Require approval for runbook execution
   </Card>
   <Card title="Session Recording" icon="video" href="/learn/features/session-recording">
     Audit runbook executions
   </Card>
 </CardGroup>

setup/configuration/runbooks-configuration.mdx

@@ -1,11 +1,11 @@
 ---
 title: "Runbooks"
 ---
 
 This page explains the available options to configure Runbooks with your git server.
 
 <Note>
   This guide provides step-by-step instructions for configuring Runbooks using the command line. Currently, the Webapp supports configuration exclusively with SSH private keys with limited options.
 </Note>
 
 To start, make sure to install the hoop command line and login to your gateway instance:
@@ -76,7 +76,7 @@
 
 ## Testing
 
 To test the integration, issue the command below, it will return the last commit from the directory. When you add a **runbook** file it will show in the **items** attribute.
 
 ```sh
 hoop admin get runbooks -o json
@@ -112,7 +112,7 @@
 ```
 
 <Tip>
   Use a high value in case you don't change the runbooks often, this will reduce the number of requests to the git server.
 </Tip>
 
 ### JSON Payload
@@ -165,15 +165,15 @@
 
 ## How the template engine works
 
 Runbooks use the [GO text/template](https://pkg.go.dev/text/template) as the template engine. A runbook is a template to be run against a connection, the placeholders are rendered by inputs provided by an HTTP client.
 
 To define an input, the runbook must be enclosed with `{{ }}` and the input name must start with a dot. - Example - `{{ .myinput }}`
 
 The input name must comply with the regular expression `\.[a-zA-Z0-9_]+`
 
 ### Template Specification
 
 A client could implement input validation based on how templates are created, the specification of inputs are derived from a runbook. The template below:
 
 ```sql
 SELECT name FROM customers WHERE id = '{{ .customer_id }}'
@@ -217,11 +217,13 @@
   - url
   - email
   - select
+  - textarea
+  - password
   - file
 - required - if the this field is required
 - default - specifies a default value for an input if it’s empty
 
 The fields indicates how a client could create inputs to a runbook, the fields are defined as function templates in an placeholder using the pipe character `|`. Example:
 
 ```
 {{ .customer_id
@@ -232,11 +234,11 @@
 
 ### Ordering Fields 
 
 In some runbooks, you may want input fields to appear in a specific order for example:
 
 - showing required fields first
 - grouping related parameters together
 - improving the overall user experience when launching a runbook
 
 To define the order in which fields appear in the Web App, you can add the `order` attribute as shown in the example below.
 
@@ -277,6 +279,10 @@
   - `<type>` - the type of the input (see supported fields for a list of types)
 - `placeholder "<message>"` - used as attribute specification to client input validation
   - `<message>` - the description of the placeholder
+- `minlength "<length>"` - minimum character length for the input
+  - `<length>` - the minimum number of characters required
+- `maxlength "<length>"` - maximum character length for the input
+  - `<length>` - the maximum number of characters allowed
 - `options "<option>" "..."` - used as attribute specification to client input validation
   - `"<option>" "..."` - a list of strings describing each option
 - `squote` - wraps the input with single quotes: `'`
@@ -294,7 +300,7 @@
 
 Template functions may be “chained” by separating a sequence of commands with pipeline characters ‘|’. In a chained pipeline, the result of each command is passed as the last argument of the following command. The output of the final command in the pipeline is the value of the pipeline.
 
 The output of a command will be either one value or two values, the second of which has type error. If that second value is present and evaluates to non-nil, the runbook will fail to execute describing what went wrong.
 
 Examples:
 
@@ -329,7 +335,7 @@
           | options "red" "white" "black"}}
 ```
 
 #### asenv function
 
 The `asenv` function allows defining inputs and mapping then as environment variables in the connection runtime. Instead of injecting the value as an input directly to the template, it will gather the value and inject as an environment variable when executing the session.
 
@@ -355,7 +361,7 @@
 
 ### Linter
 
 The command line provides a linter to validate the runbook templates before executing them. It will check if the inputs are valid and if the template is well formed.
 
 - **Validating a file**
 
@@ -430,7 +436,7 @@
 
 This pattern guarantees that the input will be only a number, this prevents any user to inject any sql instruction
 
 - Use the asenv function to expose inputs as environment variables if your runtime supports it
 - This will map the `customer_id` input as an environment variable avoiding bash injections with shell control operators
 
 ```shell
@@ -438,11 +444,11 @@
 /path/to/my/script.sh "$CUSTOMER_ID"
 ```
 
 - The same applies to language runtimes.
 
 ```python
 # {{ .customer_id | asenv "CUSTOMER_ID" }}
 import os
 if __name__ == '__main__':
     print(os.environ['CUSTOMER_ID'])
-```
+```