Name to ID resolution

How it works

The Foreman's API uses unique numeric IDs to reference resources. While they are very easy to deal with in scripts, human users appreciate more readable identifiers. Most of the Foreman's resources are also searchable by name. HammerCLIForeman's commands use ID resolution to make a developer's life easier by handling the translation of names to numeric IDs.

The ID resolution process consists of two parts: - building correct parameters (option builders are described here) - the translation process itself (IdResolver takes care of that)

ID resolution step by step

IdResolver implements the method <resource_name>_id(cli_options) for each of the resources. Under the hood, the method: - returns cli_options['option_id'] if it's not nil - looks at index method's parameters, finds all required *_id params there and makes sure they're present (if not it tries to resolve them recursively) - extends the original options with a search field that searches for the name - calls the index method and returns the result

It can end up with an exception when: - the options necessary for search (typically name) are not present - one of the dependent resources couldn't be found - the resource was not found - more resources were found

APIdoc requirements

The builtin name to id resolution in hammer-cli-foreman works if the following conditions are met: - the API parameters that need to be resolved must respect <resource_name>_id format - the resource's API controller needs to have the action index - the index action has to support searching by name - the index action's docs mention all required *_id parameters - all the above conditions have been fulfilled for any resource referenced from the previous index action

Command requirements

Option builders should take care of all the requirements for you, but just for the sake of completeness: - the command's action needs to have parameter id - the command needs to have defined options --id, --name and possibly options for other identifiers of the primary resource (resource specified in the command) - the command needs to define options --<resource_name>-id, --<resource_name> (but with the reader method option<resource_name>_name!) and possibly others for remaining identifiers of all the dependent resources

Behaviour tuning

Most of the resources are searchable by name. However there are exceptions that either don't have a name or offer more searchable fields. In such cases you have to update the definition of searchable fields.