added execution prompts/forms

Author: ansibleguy

CHANGELOG.md

@@ -5,6 +5,7 @@
 ### 0.0.21
 
 * Added [validation against XSS](https://github.com/ansibleguy/webui/issues/44)
+* Execution prompts/forms to provide job overrides
 
 ----
 

README.md

@@ -94,7 +94,7 @@ See also: [Contributing](https://github.com/ansibleguy/webui/blob/latest/CONTRIB
 
     - [x] Manual/immediate execution
 
-    - [ ] Custom Execution-Forms
+    - [x] Custom Execution-Forms
 
     - [ ] Support for [ad-hoc commands](https://docs.ansible.com/ansible/latest/command_guide/intro_adhoc.html)
 

docs/source/_static/img/job_exec.png

@@ -0,0 +1,48 @@
+.. _usage_jobs:
+
+.. include:: ../_include/head.rst
+
+.. include:: ../_include/warn_develop.rst
+
+.. |job_exec| image:: ../_static/img/job_exec.png
+   :class: wiki-img
+
+====
+Jobs
+====
+
+You can use the UI at :code:`Jobs - Manage` to create and execute jobs.
+
+----
+
+Create
+******
+
+To get an overview - Check out the demo at: `demo.webui.ansibleguy.net <https://demo.webui.ansibleguy.net>`_ | Login: User :code:`demo`, Password :code:`Ansible1337`
+
+The job creation form will help you by browsing for playbooks and inventories. For this to work correctly - you should first select the repository to use (*if any is in use*).
+
+You can optionally define a :code:`schedule` in `Cron-format <https://crontab.guru/>`_ to automatically execute the job. Schedule jobs depend on :ref:`Global Credentials <usage_credentials>` (*if any are needed*).
+
+:code:`Credential categories` can be defined if you want to use user-specific credentials to manage your systems. The credentials of the executing user will be dynamically matched if the job is set to :code:`Needs credentials`.
+
+For transparency - the full command that is executed is added on the logs-view.
+
+----
+
+Execute
+*******
+
+You have two options to execute a job:
+
+* **Quick execution** - run job as configured without overrides
+
+* **Custom execution** - run job with execution-specific overrides
+
+    The fields available as overrides can be configured in the job settings!
+
+    You can define required and optional overrides.
+
+    |job_exec|
+
+    Extra-vars can also be prompted. These need to be supplied in the following format: :code:`var={VAR-NAME}#{DISPLAY-NAME}` per example: :code:`var=add_user#User to add`

docs/source/usage/jobs.rst

@@ -1,8 +1,11 @@
+from re import match as regex_match
+
 from django.core.exceptions import ObjectDoesNotExist
 from django.db.utils import IntegrityError
 from rest_framework.views import APIView
 from rest_framework import serializers
 from rest_framework.response import Response
+from rest_framework.exceptions import ValidationError
 from drf_spectacular.utils import extend_schema, OpenApiResponse, OpenApiParameter
 
 from aw.config.hardcoded import JOB_EXECUTION_LIMIT
@@ -33,9 +36,30 @@ def validate(self, attrs: dict):
             if field in attrs:
                 validate_no_xss(value=attrs[field], field=field)
 
+        for prompt_field in ['execution_prompts_required', 'execution_prompts_optional']:
+            if is_set(attrs[prompt_field]):
+                if regex_match(Job.execution_prompts_regex, attrs[prompt_field]) is None:
+                    raise ValidationError('Invalid execution prompt pattern')
+
+                translated = []
+                for field in attrs[prompt_field].split(','):
+                    if field in Job.execution_prompt_aliases:
+                        translated.append(Job.execution_prompt_aliases[field])
+
+                    else:
+                        translated.append(field)
+
+                attrs[prompt_field] = ','.join(translated)
+
         return attrs
 
 
+class JobExecutionRequest(serializers.ModelSerializer):
+    class Meta:
+        model = JobExecution
+        fields = JobExecution.api_fields_exec
+
+
 def _find_job(job_id: int) -> (Job, None):
     try:
         return Job.objects.get(id=job_id)
@@ -285,6 +309,7 @@ def put(self, request, job_id: int):
         request=None,
         responses={
             200: OpenApiResponse(JobReadResponse, description='Job execution queued'),
+            400: OpenApiResponse(JobReadResponse, description='Bad parameters provided'),
             403: OpenApiResponse(JobReadResponse, description='Not privileged to execute the job'),
             404: OpenApiResponse(JobReadResponse, description='Job does not exist'),
         },
@@ -300,7 +325,23 @@ def post(self, request, job_id: int):
                 if not has_job_permission(user=user, job=job, permission_needed=CHOICE_PERMISSION_EXECUTE):
                     return Response(data={'msg': f"Not privileged to execute the job '{job.name}'"}, status=403)
 
-                queue_add(job=job, user=user)
+                if len(request.data) > 0:
+                    serializer = JobExecutionRequest(data=request.data)
+                    if not serializer.is_valid():
+                        return Response(
+                            data={'msg': f"Provided job-execution data is not valid: '{serializer.errors}'"},
+                            status=400,
+                        )
+
+                    execution = JobExecution(
+                        user=user, job=job, **serializer.validated_data,
+                    )
+
+                else:
+                    execution = JobExecution(user=user, job=job, comment='Triggered')
+
+                execution.save()
+                queue_add(execution=execution)
                 return Response(data={'msg': f"Job '{job.name}' execution queued"}, status=200)
 
         except ObjectDoesNotExist:

src/ansibleguy-webui/aw/api_endpoints/job.py

@@ -26,6 +26,7 @@ class Meta:
 
     job_name = serializers.CharField(required=False)
     job_comment = serializers.CharField(required=False)
+    comment = serializers.CharField(required=False)
     user_name = serializers.CharField(required=False)
     status_name = serializers.CharField(required=False)
     failed = serializers.BooleanField(required=False)
@@ -48,6 +49,7 @@ def get_job_execution_serialized(execution: JobExecution) -> dict:
     serialized['job'] = execution.job.id
     serialized['job_name'] = execution.job.name
     serialized['job_comment'] = execution.job.comment
+    serialized['comment'] = execution.comment
     serialized['user'] = execution.user.id if execution.user is not None else None
     serialized['user_name'] = execution.user_name
     serialized['time_start'] = execution.time_created_str

src/ansibleguy-webui/aw/api_endpoints/job_util.py

@@ -13,7 +13,8 @@
             'credentials_needed': 'Needs Credentials',
             'credentials_default': 'Default Job Credentials',
             'credentials_category': 'Credentials Category',
-            'form': 'Execution Form',
+            'execution_prompts_required': 'Execution Prompts - Required',
+            'execution_prompts_optional': 'Execution Prompts - Optional',
         },
         'credentials': {
             'connect_user': 'Connect User',
@@ -41,18 +42,6 @@
             'git_override_initialize': 'Git Override Initialize-Command',
             'git_override_update': 'Git Override Update-Command',
         },
-        'execution_form_field': {
-            'help': 'Help Text',
-            'var': 'Variable',
-            'var_type': 'Variable Type',
-            'field_type': 'Field Type',
-            'multiple': 'Multiple Choices',
-            'separator': 'Multiple-Choice Separator',
-            'validate_error': 'Validation Error-Message',
-            'validate_regex': 'Validation Regex',
-            'validate_max': 'Maximum Value',
-            'validate_min': 'Minimum Value',
-        },
     },
     'settings': {
         'permissions': {
@@ -141,7 +130,10 @@
             'credentials_category': 'The credential category can be used for dynamic matching of '
                                     'user credentials at execution time',
             'enabled': 'En- or disable the schedule. Can be ignored if no schedule was set',
-            'form': 'Select a Job-Execution form to display on ad-hoc executions',
+            'execution_prompts_required': 'Required job attributes and/or variables to prompt at custom execution. '
+                                          'Comma-separated list of key-value pairs.<br>'
+                                          "Variables can be supplied like so: 'var={VAR-NAME}#{DISPLAY-NAME}'<br>"
+                                          "Example: 'limit,check,var=add_user#User to add' ",
         },
         'credentials': {
             'vault_file': 'Path to the file containing your vault-password',
@@ -173,18 +165,6 @@
             'git_override_update': 'Advanced usage! Completely override the command used to update '
                                    '(pull) the repository',
         },
-        'execution_form_field': {
-            'var_type': '<b>WARNING</b>: Choose env-var for secret values! Commandline arguments are viewable and '
-                        'will be logged',
-            'multiple': 'If multiple the form should support multiple user-choices',
-            'separator': 'If multiple choices are used - they will be joined on serialization before they get passed '
-                         'to the Ansible Execution. This separator will be used on that join operation',
-            'validate_error': 'Error-Message to display on validation error',
-            'validate_regex': 'Regex to validate the value. Test it here: '
-                              '<a href="https://regex101.com/">regex101.com</a>. (flavor needs to be JavaScript)',
-            'validate_max': 'Field-type integer: maximum integer; Field-type string: maximum length',
-            'validate_min': 'Field-type integer: minimum integer; Field-type string: minimum length',
-        },
     },
     'settings': {
         'permissions': {

src/ansibleguy-webui/aw/config/form_metadata.py

@@ -1,18 +1,17 @@
-from aw.model.job import Job, JobQueue
+from aw.model.job import JobExecution, JobQueue
 from aw.utils.debug import log
-from aw.base import USERS
 
 
-def queue_get() -> (tuple[Job, USERS], None):
+def queue_get() -> (JobExecution, None):
     next_queue_item = JobQueue.objects.order_by('-created').first()
     if next_queue_item is None:
         return None
 
-    job, user = next_queue_item.job, next_queue_item.user
+    execution = next_queue_item.execution
     next_queue_item.delete()
-    return job, user
+    return execution
 
 
-def queue_add(job: Job, user: USERS):
-    log(msg=f"Job '{job.name}' added to execution queue", level=4)
-    JobQueue(job=job, user=user).save()
+def queue_add(execution):
+    log(msg=f"Job '{execution.job.name} {execution.id}' added to execution queue", level=4)
+    JobQueue(execution=execution).save()

src/ansibleguy-webui/aw/execute/queue.py

@@ -85,14 +85,16 @@ def status(self):
     def check(self):
         log('Checking for queued jobs', level=7)
         while True:
-            queue_item = queue_get()
-            if queue_item is None:
+            execution = queue_get()
+            if execution is None:
                 break
 
-            job, user = queue_item
-
-            log(f"Adding job-thread for queued job: '{job.name}' (triggered by user '{user.username}')", level=4)
-            self._add_thread(job=job, execution=JobExecution(user=user, job=job, comment='Triggered'), once=True)
+            log(
+                f"Adding job-thread for queued job: '{execution.job.name}' "
+                f"(triggered by user '{execution.user.username}')",
+                level=4,
+            )
+            self._add_thread(job=execution.job, execution=execution, once=True)
 
     def reload(self, signum=None):
         if not self.reloading and not self.stopping:

src/ansibleguy-webui/aw/execute/scheduler.py

@@ -81,6 +81,7 @@ class Job(BaseJob):
         'name', 'playbook_file', 'inventory_file', 'repository', 'schedule', 'enabled', 'limit', 'verbosity',
         'mode_diff', 'mode_check', 'tags', 'tags_skip', 'verbosity', 'comment', 'environment_vars', 'cmd_args',
         'credentials_default', 'credentials_needed', 'credentials_category',
+        'execution_prompts_required', 'execution_prompts_optional',
     ]
     form_fields_primary = ['name', 'playbook_file', 'inventory_file', 'repository']
     form_fields = CHANGE_FIELDS
@@ -104,6 +105,18 @@ class Job(BaseJob):
     credentials_category = models.CharField(max_length=100, **DEFAULT_NONE)
     repository = models.ForeignKey(Repository, on_delete=models.SET_NULL, related_name='job_fk_repo', **DEFAULT_NONE)
 
+    execution_prompts_max_len = 2000
+    execution_prompts_regex = (r'^(limit|verbosity|comment|mode_diff|diff|mode_check|check|environment_vars|env_vars|'
+                               r'tags|tags_skip|skip_tags|cmd_args|var=[^,#]*?|var=[^#]*?#[^,]*?|[,$])+$')
+    execution_prompt_aliases = {
+        'check': 'mode_check',
+        'diff': 'mode_diff',
+        'env_vars': 'environment_vars',
+        'skip_tags': 'tags_skip',
+    }
+    execution_prompts_required = models.CharField(max_length=execution_prompts_max_len, **DEFAULT_NONE)
+    execution_prompts_optional = models.CharField(max_length=execution_prompts_max_len, **DEFAULT_NONE)
+
     def __str__(self) -> str:
         limit = '' if self.limit is None else f' [{self.limit}]'
         return f"Job '{self.name}' ({self.playbook_file} => {self.inventory_file}{limit})"
@@ -194,9 +207,13 @@ class JobExecution(BaseJob):
     api_fields_read = [
         'id', 'job', 'job_name', 'user', 'user_name', 'result', 'status', 'status_name', 'time_start', 'time_fin',
         'failed', 'error_s', 'error_m', 'log_stdout', 'log_stdout_url', 'log_stderr', 'log_stderr_url', 'job_comment',
-        'credential_global', 'credential_user', 'command', 'log_stdout_repo', 'log_stderr_repo',
+        'comment', 'credential_global', 'credential_user', 'command', 'log_stdout_repo', 'log_stderr_repo',
         'log_stdout_repo_url', 'log_stderr_repo_url',
     ]
+    api_fields_exec = [
+        'comment', 'limit', 'verbosity', 'mode_diff', 'mode_check', 'environment_vars', 'tags', 'tags_skip',
+        'cmd_args',
+    ]
     log_file_fields = ['log_stdout', 'log_stderr', 'log_stdout_repo', 'log_stderr_repo']
 
     # NOTE: scheduled execution will have no user
@@ -275,8 +292,6 @@ def user_name(self) -> str:
 
 
 class JobQueue(BareModel):
-    job = models.ForeignKey(Job, on_delete=models.CASCADE, related_name='jobqueue_fk_job')
-    user = models.ForeignKey(
-        USERS, on_delete=models.SET_NULL, null=True,
-        related_name='jobqueue_fk_user',
+    execution = models.ForeignKey(
+        JobExecution, on_delete=models.CASCADE, related_name='jobqueue_fk_jobexec', **DEFAULT_NONE,
     )

src/ansibleguy-webui/aw/model/job.py

@@ -391,6 +391,10 @@ input:invalid {
 	border-color: red;
 }
 
+.aw-exec-form {
+    overflow: hidden;
+}
+
 .mb-3 {
     margin-bottom: 0.1rem !important;
 }

src/ansibleguy-webui/aw/static/css/aw.css

@@ -8,7 +8,7 @@
     }
 
     form .form-control, .aw-fs-choices {
-        width: 35vw;
+        width: 45vw;
     }
 
     .aw-responsive-lg {
@@ -50,7 +50,7 @@
     }
 
     form .form-control, .aw-fs-choices {
-        width: 50vw;
+        width: 60vw;
     }
 
     .aw-responsive-lg {
@@ -78,7 +78,7 @@
     }
 
     form .form-control, .aw-login, .aw-login-fields, .aw-fs-choices {
-        width: 70vw;
+        width: 90vw;
     }
 
     .aw-btn-action-icon {

src/ansibleguy-webui/aw/static/css/aw_mobile.css

@@ -225,6 +225,10 @@ function escapeHTML(data) {
     return data;
 }
 
+function capitalizeFirstLetter(string) {
+    return string.charAt(0).toUpperCase() + string.slice(1);
+}
+
 // API CALLS
 const CSRF_TOKEN = getCookie('csrftoken');