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)
The latter part is implemented three option sources wrapped in
IdResolution
for easier addressing. With this extension the
whole structure of option processors in hammer-cli-foreman
is:
- DefaultInputs - CommandLine - SavedDefaults - IdResolution
- IdParams - IdsParams - SelfParam
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 - returns
HammerCLI::NilValue if the correspondent search option is set to
HammerCLI::NilValue (i.e. NIL specified on CLI) - 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
Differences in resolution of list of id's¶ ↑
the lookup method is called <resource_name>_ids
and in
addition: - returns cli_options['option_ids']
if it's not
nil - returns empty list ([]
) when the search option is set to
empty string or empty list
It also ends up with exception when any of the ids was not resolved.
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¶ ↑
The resolution can be tuned at various levels.
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 (SEARCHABLES) in id_resolver.
If you need to modify the lookup query (the search
field) you
can override the default one by adding a method returning the correct
lookup options to the resolver class. The method should be called according
to the following schema: -
create_<resource_name>_search_options(options)
for
single id lookup (takes precedence over the next one for single id lookups)
- create_<resource_plural_name>_search_options(options)
combine for single and/or multiple ids lookup -
create_<resource_plural_name>_search_options(options,
mode)
combined with extra parameter suggesting the lookup mode and
being set to :single
, :multi
or nil
For examples check the id_resolver
.
It is possible to completely override the resolution procedure by adding a
method(s) called <resource_name>_id
and/or
<resource_name>_ids
to the id_resolver
. It
will get the options hash as an input and expects id
(list of
ids
respectively) or a ResolverError
on its
return.