Skip to main content

Templates

Define and share common Tasks with your team.

Introduction#

Templates are pre-defined Tasks stored in a Git repository. These special Tasks have variables defined in their scripts.

When creating a Task using a Template, you have to provide only the variables. A regular Task will be created using the Template script filled with the parameters you provide.

You can run a Task from Slack providing the parameters to the Runops bot, get reviews, and get result logs; all without touching a single line of code or command-line. But you can also use the Runops CLI.

Create a Template#

Let's create a Template for querying DynamoDB.

We will create a Template using Python with AWS's boto3 library. After creating the script, we commit it to the main branch of the Runops Templates repository.

pro-tip

Open the Templates repository for everyone at your company to contribute with scripts they already have.

Here is our template, lets save it to a file and commit it to the main branch of a Github repository.

#file: dynamodb-query.py
import boto3
client = boto3.client('dynamodb')
response = client.get_item(
Key={
'{{pk}}': {
'S': '{{pk_value}}',
},
'{{sk}}': {
'S': '{{sk_value}}',
},
},
TableName='{{table}}',
)
print(response)

This template has 5 parameters which are indicated by double curly braces:

{{pk}} - the name of the Partition Key

{{pk_value}}- the value of the Partition Key

{{sk}} - the name of the Sort Key

{{sk_value}} - the value of the Sort Key

{{table}} - the name of the DynamoDB table

Connect Runops to Github#

To connect Runops to your Templates repository, add the Github user runopsbot as a read-only collaborator to the repository.

You will soon be able to connect using OAuth from the Runops web app.

Check available templates#

Now we can see the template available. Listing the Templates will read all the files in the main branch of the Github repository:

$ runops templates list
┌──────────────────────────────┐
│ Name │
├──────────────────────────────┤
│ dynamodb-query.py │
├──────────────────────────────┼
│ other-template.sql │
└──────────────────────────────┘

To verify specific details about a template, like its params:

$ runops templates get --name dynamodb-query.py
┌──────────────────────────────┬────────────────────────────────────────┐
│ Attribute │ Value │
├──────────────────────────────┼────────────────────────────────────────┤
│ name │ dynamodb-query.py │
├──────────────────────────────┼────────────────────────────────────────┤
│ params │ {{pk}} │
│ │ {{pk_value}} │
│ │ {{sk}} │
│ │ {{sk_value}} │
│ │ {{table}} │
└──────────────────────────────┴────────────────────────────────────────┘

Use a Template#

Create a Task from the Template

runops templates run \
--name dynamodb-query \
--target aws-account-prod-a
--params \
table='Music'
pk='Artist', \
pk_value='Acme Band', \
sk='SongTitle'
sk_value='Happy Day'

Use Templates in Slack#

To run templates from Slack, run /runops templates anywhere in your Slack workspace:

Workflow#

A powerful workflow for Templates is having a central Git repository with scripts certified by stakeholders of a Target.

Engineers from multiple teams could submit Pull Requests to this repository. After testing, the Template gets merged into the main branch and becomes available to everyone to everyone in the company.

Ignoring files#

A .runopsignore file specifies intentionally untracked files that runops should ignore when listing templates.

Pattern Format#

  • A blank line matches no files
  • A line starting with # serves as a comment
  • Trailing spaces are ignored
  • The slash / is used as the directory separator
  • Using the slash / in the beginning, has a special meaning to indicate matching files in the root of the folder.
  • An asterisk * matches anything

Examples#

  • The pattern hello.* matches any file or directory whose name begins with hello. If one wants to restrict this only to the directory and not in its subdirectories, one can prepend the pattern with a slash, i.e. /hello.*; the pattern now matches hello.txt, hello.c but not a/hello.java.
  • The pattern doc/frotz and /doc/frotz have the same effect in any .runopsignore file. In other words, a leading slash is not relevant if there is already a middle slash in the pattern.
  • The pattern foo/*, matches foo/test.json (a regular file), foo/bar (a directory), and all contents in the subdirectories also, like foo/bar/test.sql.
# ignore all files and folder in the root directory that ends with .sql
/*.sql
# ignore all files and folders in all directories
*.md
# ignore /dev/scripts/.placeholder file
dev/scripts/.placeholder
# ignore all files and folders that ends with .sh or .sql in /dev/scripts folder
dev/scripts/*.[sh|sql]
# ignore all files and folders that begins with config inside /prod/scripts folder
/prod/scripts/config*

Parameters Validation#

We have a way to create validations for each parameter and this will provide security for your template at the form level. Each parameter could receive any validations following these specifications:

The types are consist in:
text, email, url, number, tel, time, date, select.
┌─────────────────┬─────────────────┬─────────────────────┬─────────────────────────────────────┐
│ Attribute │ Types │ Default value │ Desciption │
├─────────────────┼─────────────────┼─────────────────────┼─────────────────────────────────────┤
│ description │ All │ │ String. Text that appears inside │
│ │ │ │ of the helper tooltip. │
├─────────────────┼─────────────────┼─────────────────────┼─────────────────────────────────────┤
│ placeholder │ All │ "Define a value for │ String. Text that appears in the │
| | | {{parameter_name}}" │ form control when it has no value │
│ │ │ │ set. │
├─────────────────┼─────────────────┼─────────────────────┼─────────────────────────────────────┤
│ required │ All │ true │ Boolean. A value is required or │
│ │ │ │ must be check for the form to be │
│ │ │ │ submittable. │
├─────────────────┼─────────────────┼─────────────────────┼─────────────────────────────────────┤
│ pattern │ text, url, tel, │ │ JavaScript regular expression. │
│ │ email │ │ Pattern the value must match to be │
│ │ │ │ valid. │
├─────────────────┼─────────────────┼─────────────────────┼─────────────────────────────────────┤
│ maxlength │ text, url, tel, │ │ Maximum length (number of │
│ │ email │ │ characters) of value. │
├─────────────────┼─────────────────┼─────────────────────┼─────────────────────────────────────┤
│ minlength │ text, url, tel, │ │ Minimum length (number of │
│ │ email │ │ characters) of value. │
├─────────────────┼─────────────────┼─────────────────────┼─────────────────────────────────────┤
│ max │ number, time, │ │ Number. Maximum value. │
│ │ date │ │ │
├─────────────────┼─────────────────┼─────────────────────┼─────────────────────────────────────┤
│ min │ number, time, │ │ Number. Minimum value. │
│ │ date │ │ │
├─────────────────┼─────────────────┼─────────────────────┼─────────────────────────────────────┤
│ step │ number, time, │ │ Incremental values that are valid. │
│ │ date │ │ │
├─────────────────┼─────────────────┼─────────────────────┼─────────────────────────────────────┤
│ options │ select │ │ Array of strings. Options that │
│ │ │ │ appears in the select HTML element. │
└─────────────────┴─────────────────┴─────────────────────┴─────────────────────────────────────┘
pro-tip

We are using parts of the same types and atributes from the HTML element input, you can find more informations here.

Creating the file for validation#

These validations are stored in a JSON file with the same name of their template file and with the .config extension instead.

For other-template.sql

Use other-template.config

You can use as example this file:

{
"name": {
"type": "text",
"description": "this is a text without pattern"
},
"shorter_name": {
"type": "text",
"description": "this is a text with patterns",
"maxlength": 10,
"minlength": 2
},
"email": {
"type": "email",
"description": "this is a email with pattern"
},
"github_link": {
"type": "url",
"description": "this is a url without pattern"
},
"age": {
"type": "number",
"description": "this is a number without pattern"
},
"school_grade": {
"type": "number",
"description": "this is a number float with range",
"min": 0,
"max": 10,
"step": 0.1
},
"less_than_ten": {
"type": "number",
"description": "this is a number with range",
"min": 0,
"max": 9
},
"telephone": {
"type": "tel",
"description": "this is a tel with pattern",
"placeholder": "999-999-9990",
"pattern": "[0-9]{3}-[0-9]{3}-[0-9]{4}"
},
"lunch_time": {
"type": "time",
"description": "this is a time without pattern"
},
"birthday": {
"type": "date",
"description": "this is a date without range"
},
"best_day_last_year": {
"type": "date",
"description": "this is a date with patterns",
"min": "2021-01-01",
"max": "2021-12-31"
},
"which_your_favourite_band": {
"type": "select",
"description": "this is a select options",
"options": ["backstreet boys", "the cure", "maroon 5", "the cranberries"]
}
}