Repository navigation
Advanced
Below is an example of the syntax and keywords used to construct a module with it's available functionality.
{
"module": {
"name": "database",
"label": "Database",
"type": "bash",
"configurable": "true"
},
"required": {
"commands": [
"mysql",
"grep",
"docker"
]
},
"pages": [
{
"name": "main",
"label": "Database Administration",
"command": "${page:database_action}",
"prompts": [
{
"label": "Select database",
"name": "database_selected",
"options": "${command:get_databases}"
},
{
"label": "Are you sure you want to select all databases",
"name": "database_select_all",
"format": "continue",
"condition": "${value:prompt.database_selected} == 'all'"
}
]
}
]
}From the user perspective a module is a set of related functions, for example functions related to a developer managing a database, restoring of the local database with data from either mock source or a backup...
From a developer perspective a module is a contained unit of scripts which is provides a user one or more pages, each with one or more prompts, leading to different outcomes.
A module may require additional configuration per environment, such as the name of a docker container in order to mange it. These kind of configurations could be stored in a configuration file on another location within the environment.
If the module requires upfront configuration, please provide a page named configure, which will be displayed to the user to complete.
{
"module": {
"name": "module_admin",
"label": "Dr. Frankenstein",
"type": "bash",
"configurable": false
}
}| Name | Description | Required |
|---|---|---|
| name | Unique name to identify module within the module registry | x |
| label | Display name of module to user | x |
| type | For now only bash scripts are supported | x |
| configurable | If true, Igor will confirm if the user has completed the module configuration, otherwise Igor will request the user to complete it. | x |
Igor needs to know of all the commands, inclusive of binaries and scripts, which will be executed by the module, in order to check that the required commands is available on the CLI path. This is to ensure that the module has access to all it's underlying executable resources.
{
"required": {
"commands": [
"docker",
"sed",
"grep"
]
}
}| Name | Description | Required |
|---|---|---|
| commands | List of executables that should be available on the command line for Igor to invoke the functionality provided by the module. |
From the user perspective a page is a set of prompts, when answered, will execute a specific function with the arguments derived from the answers provided. For example the user will be prompted to select which version of the database to restore, where the user can select between latest or some older versions. Once the user selects, the restore of the local database is performed
From developer perspective a page is a list of prompts which can lead to other pages or the execution of an action, such as the restore of a local database.
{
"pages": [
{
"name": "first",
"label": "Workbench",
"command": "workbench_action",
"prompts": []
}
]
}| Name | Description | Required |
|---|---|---|
| name | Unique name to identify a page from all the pages found within the module | x |
| label | Display name of the page which will be presented to the user | x |
| command | Command to execute after all prompts have been responded too, too be discussed in more detail in the Command chapter | |
| prompts | To be discussed in more detail in the Prompt chapter | x |
From the user perspective a prompt is asking the user to provide some input, for example which backup version of the database to restore.
From developer perspective a prompt is either, single or multi select or text based CLI prompt to the user which response is used as input parameters to a script to execute.
{
"prompts": [
{
"label": "Enter your married name",
"name": "married_name",
"command": "save_user ${value:prompt.married_name}",
"format": "text",
"condition": "${value:page.main.prompt.married} == 'y'",
"validate": {
"command": "validate_married ${value:prompt.married_name}",
"message": "You are not married, your surname do not exist in our database"
},
"options": []
}
]
}| Name | Description | Required |
|---|---|---|
| name | Unique name which identifies the prompt from all the prompts within the page | x |
| label | Text to display to user | x |
| command | The command to execute after the user has responded to the prompt. If page has defined a command, it will not be executed, as the prompt command takes priority | |
| condition | A statement that needs to be true in order for the prompt to be presented to the user | |
| validate | Custom validation to perform on the input provided, with descriptive message, should the input be invalid | |
| format | What type of prompt, numeric, date, etc.., more details in the Format Chapter | x |
| options | List of all the selectable options, to be discussed in more detail in the Format chapter |
The response of the user to a prompt is stored within a map and is identified by the key ${value:page.unique_page_name.prompt.unique_prompt_name}, and can be:
-
referenced as arguments for a command
-
used as decisions to display a prompt to a user or not
-
added to labels and/or prompts to display a more descriptive label and/or question
{
"label": "You selected to ${value:page.main.prompt.action} to do are you sure",
"condition": "${value:page.main.prompt.action} == 'shutdown'",
"command": "backup_database ${value:page.database.prompt.database_name}"
}Depending on the scope, a shorthand key may be used. Within a page you may skip the page identification part and it will assume the prompt value you are searching for is within the same page, for example ${value:prompt.unique_prompt_name}.
Allows prompts to be visible to the user based on a condition, for example should Igor be executing within a local environment the the backing up of databases is disabled.
Making use of eval simple if statements are supported with combination of prompt responses and/or commands.
NOTE: Commands need to return 0 for success and 1 for failure.
{
"condition": "${command:is_valid_git_dir}",
"condition": "${value:page.main.prompt.action} == 'install'",
"condition": "${value:page.main.prompt.size} > 100"
}Enables custom validation to be executed on the input provided by a user to a specified prompt.
{
"validate": {
"command": "backup_exists ${value:page.main.prompt.database_selected} 'latest'",
"message": "Unable to reach backup source and/or there is no backup marked latest"
} Selection based prompt provides the user with a list of options to choose from. The result could either be single selection or a comma separated list of multiple selections.
Most basic of prompts, a simple string input expected from the user.
Second most prompt, validates that the user enters a numeric value.
Text based prompt, whichSyntax "prompts": [ { "label": "Select action to take", "name": "user_action", "command": "execute_action ${value:prompt.user_action}" "options": [] } ] validates that the file path provided does exist, on failure it will ask the user to enter the path to a valid file.
Text based prompt, which validates that the directory path provided does exist, on failure it will ask the user to enter the path to a valid directory.
A prompt, which asks the user to respond with either yes or no, allowing for defaulting to either yes or no, if the user selects Enter.
Similar to the yes no prompt, with the exception that when the user responds with no, Igor cancels the request and returns to the CLI.
Commands only exists from a developer perspective. Command is a function found within a bash script which can be invoked by Igor to perform an action. For example the command backup_database, is defined within a bash script named backup_database.sh, which provides the means for backing up a database with some required input parameters.
backup_database.sh
function backup_database() {
local database_name="$1"
local backup_filename="$2"
mysqldump -u root -p password "$database_name" > "$backup_filename"
}In essence for each command made available to Igor function name should match the filename.
Commands are executed within a brand new bash environment, as shown below.
env -i /bin/bash -c "/bin/bash ..."