Skip to content

SET VAR to CI

Turns a resource id sitting in the stash into the resource itself, and stores the object under a stash key. Ops downstream can then read the resource's attributes instead of carrying a bare number around.

Most rules never need it. ${ci(myvar).name} reads an attribute straight out of a stored id, and FOREACH CI does the same conversion for every entry of a list. This op earns its place when several later ops need the same resource and you would rather load it once.

prepend text + whatever your code returns one line of text 1234 or name:foo look it up found no match the resource lands in the key ${myvar.name} the op fails and the rule stops a name that matches two resources fails the same way

Configuration

This op has no form. Its Config tab is a YAML editor, pre-filled with three keys. Edit the values beside them; anything else you add there is carried around with the rule and ignored.

variable

The stash key to write, as a bare flat name. It starts out as my_varname, which is a placeholder rather than a useful default. Change it.

The name is taken literally, so a dot in it is part of the name rather than a path into nested data. topic.owner here writes a key genuinely called topic.owner, which is not the same thing as the owner inside topic. Whatever the key held before is replaced.

This key is also the fallback source. Leave from_code empty and the op reads the key you named here, loads the resource that id points at, and writes the object back over the id. One key in, one key out.

from_code

Perl that produces the id, not the id itself. That distinction is the single biggest trap on this op. Ids are numbers, so typing 1042 works. Typing a word such as my_server does not: it is read as code, and the rule refuses to save with a syntax error pointing at that line. Read the value out of the stash instead, with $$stash{server_mid}. To look a resource up by name rather than by id, put the prefix in prepend, where text is taken literally, and leave the code to fetch the name.

The result is expanded for ${...} placeholders before the lookup, so code that returns a template string works too.

The result is always treated as one line of text. Only one resource is ever loaded. Point this at a stash key holding a list of ids and the list is turned into text, giving an id that is not an id and a lookup that fails; loop with FOREACH CI instead.

Leave it empty and the op falls back to variable, as described above. Leave both empty and the op fails saying the id is missing. Give it an id that no resource carries and the failure names the id, which is the quickest way to tell a typo apart from an empty stash key.

prepend

Literal text stuck on the front of whatever from_code produced. ${...} is not expanded here, so a placeholder in this field ends up in the id as raw characters and breaks the lookup.

Its real use is choosing how the lookup happens:

Resulting text What is searched
1234 the resource with that id
name:foo the one resource named foo
moniker:foo the one resource with that moniker

So a stash key holding a bare name becomes usable by setting prepend to name:. The prefix is not limited to those two. Any word followed by a colon is read as the name of an attribute to search on, and the text after the colon is the value to match. The flip side is that a value which happens to contain a colon is searched rather than looked up as an id, and is never found.

A search has to land on exactly one resource. Two matches count as no match: the op fails with the same not-found message you get for a name nobody has, and it does not tell you that the name was ambiguous or which resources shared it. When a name: lookup fails on a name you can see in the UI, search the resources list for that name before you go looking for anything subtler.

What later ops see

The key holds the resource itself. Attributes are readable through dotted paths, so ${myvar.name} and ${myvar.moniker} work, and condition rows in IF var condition THEN can walk into it the same way.

The object is a snapshot taken when the op ran. Changes made to the resource afterwards, by this rule or by someone in the UI, are not reflected until you load it again.

Nothing about the lookup reaches the job log, not the id that was used and not the resource that came back. A failed lookup ends the rule at this op unless you set Error Handling on the node to trap or ignore errors, or wrap the op in TRY statement with a CATCH statement.

During a rollback the op runs again and reloads from the database. A resource deleted during the forward run will therefore fail the rollback here. Clear Run Rollback on the node when the object is only needed on the way forward.

Combining with other ops

Get the id into the stash first, with SET VAR from a topic field or SET EXPR from a lookup, then convert it here.

Hand the loaded resource to Invoke Resource methods to call one of its methods, or read its attributes into a command line built by Run a Remote Script.

To create the resource rather than load one, use Create CI, which leaves the new resource in the stash for you.

Examples

Load the resource whose id an earlier op left in build_server, replacing the id with the object.

variable:   build_server
from_code:
prepend:

Load a server by name, with the name coming from the stash.

variable:   target_server
from_code:  $$stash{server_name}
prepend:    'name:'

Load a fixed resource, with the id written into the op instead of read from the stash.

variable:   artifact_repo
from_code:  1042
prepend: