Validation of Queue Items¶
All items (plans and instructions) submitted to the queue subjected to validation before they are inserted into the queue. If validation of an item fails, the item is rejected and an error message is returned as part of the response to the API request. If a batch of items is submitted to the queue (e.g. using queue_item_add_batch 0MQ API), each item in the batch is validated before any items are added to the queue. If validation of any item in the batch fails then the whole batch is rejected.
Validation of Instructions¶
A submitted item can be a plan or an instruction. Validation of instructions is relatively simple because the set of instructions and their parameters is fixed. Validation involves the following steps:
Verify that the instruction name is a name of an existing instruction.
Verify that the instruction name is in the list of allowed instructions for the user submitting the plan (to be implemented).
Verify that the submitted request contains all the required instruction parameters.
Verify that the submitted request contains no parameters that are not supported.
Verify that the submitted parameter values are valid.
Validation of Plans¶
Validation of plan parameters is more sophysticated and based on plan representations
stored in the file
existing_plans_and_devices.yaml, which is created by analysing
the startup script(s) or the module with qserver-list-plans-devices CLI tool.
Alternatively, RE Manager may be configured to create/update the list of
existing plans and devices stored on disk each time RE Worker environment is opened or
plans and devices in RE namespace are changed. See Updating the List of Existing Plans and Devices
for available options. The lists of existing plans and device used by RE Manager
(stored internally in RAM) are always kept up to date during runtime to reflect changes
in RE namespace. The lists are reloaded from disk file when RE Manager is started and
used until RE Worker environment is opened the first time and startup scripts are
successfully loaded, therefore it is important to keep
Each user is assigned to a user group. Each user group is assigned permissions
to use a subset of names of existing plans and devices in API requests. The permissions
are defined in the file
user_group_permissions.yaml. The lists of allowed plans and
devices for a given group are generated from the lists of existing plans and devices
based on the respective set of permissions. Plan validation includes the following steps:
Verify that the plan name is in the list of allowed plans for the user submitting the plan.
Verify that the set of submitted plan parameters (a list of
argsand a dictionary of
kwargs) can be successfully passed to the plan: attempt to bind
kwargsto plan parameters using plan signature recreated based from the plan representation found in the list of allowed plans; check parameter types based on the type annotations (if specified) and check if numerical values are within the allowed ranges (if specified). This step does not guarantee that the plan will run successfully, but may catch many parameter errors.
Verify that the user is allowed to use plans and devices that are passed as plan parameters (i.e. check if the plans and devices are in the lists of allowed plans and devices).
Only names of plans and devices can be passed as parameters in API requests. The names are replaced by the respective objects from RE Worker namespace before the parameters are passed to the plan.
Each plan is validated at least twice: at the time the plan is submitted to the Queue Server and
directly before execution. Validation is also run each time plan parameters are modified
(see queue_item_update 0MQ API). Third party Python applications
may perform validation before sending the plan to the queue by calling
Once a plan is successfully submitted to the queue, it is expected to successfully pass the second validation immediately before it is set for execution. Nevertheless, if the lists of existing plans and devices or user group permissions are modified between the time when the plan was added to the queue and the time the plan is set for execution, the second validation may fail.
API for Plan Validation¶
Validate the dictionary of plan parameters.