Invoke Resource methods

Calls one method on a resource and hands the result back to the rule. It is the general-purpose escape hatch for things the palette has no dedicated op for: deleting a branch, reading the files attached to a topic, asking a repository for a revision.

Reach for it when no palette op already exists for what you want, and when you would otherwise write the same call by hand in CODE. The advantage over a code block is that the form reads the method list off the resource and fills in the parameter names for you. The op sits in the job group of the palette and expects a running job around it.

Fields

CI Class

The kind of resource you want to call a method on. One value only: picking a second replaces the first. The list shows every resource type in the system.

The field also accepts free text, and whatever you type is kept as a pill without being checked. A name that is not a real resource type is saved without complaint and stops the job when it runs.

At run time this field only matters when MID is empty. When you supply a MID, the resource is loaded from that identifier and the method runs against whatever type it turns out to be, even if that is not the type selected here. The class you pick here drives the method list in the form, not the call.

CI Methods

The method to call. The combo stays hidden until a class is chosen, then lists the methods available on it, sorted alphabetically and ignoring case. The list is long, because it holds the accessor for every field on the resource as well as the methods it takes from the roles it plays. Reading a field means calling the method with the field's name.

Two gaps worth knowing about. Methods the class inherits from a parent type never appear, so the constructor and anything else that comes from further up is out of reach, and the combo will not accept a name you type over it. Names beginning with _ are filtered out of the list as well.

Selecting a method resets both argument tabs and pre-fills them from the method's declared parameters, required ones first. That reset is unconditional, so reselecting the same method wipes arguments you already typed. Fill the class and the method in first, arguments last.

Methods declared without a parameter list get no pre-fill at all, and the tabs stay empty. You have to know the parameter names yourself in that case.

Changing CI Class reloads the method list, but only when the class you pick differs from the one the op was saved with. Switch away and then back again in the same sitting and you are left looking at the other class's methods until you close the op and open it again.

MID

The identifier of the resource to call the method on. Optional, and the field expands ${var} placeholders, so ${topic_mid} and ${current_branch.mid} both work.

Leave it blank and the method is called on the class rather than on any particular resource. That is what you want for a method that creates or searches, and wrong for anything that reads or changes one resource's state.

A variable that is present in the stash but holds nothing leaves the field blank, so the op switches to the class call without complaining and you get an obscure failure from inside the method instead of a clear message about a missing resource. Test the variable with IF var condition THEN and NOT EMPTY before the op when the value comes from something that might not be set. A variable that is not in the stash at all behaves differently: the literal ${topic_mid} text stays in the field and the op fails saying it could not find a resource with that identifier, which at least tells you which variable to go and look at.

Besides a plain identifier the field also takes a field:value lookup, for example name:myrepo or moniker:foo. The lookup searches every resource in the system rather than the class chosen above, so a name two resources share stops the job with a message listing both identifiers. A lookup or an identifier that matches nothing stops the job saying the resource record was not found.

Arguments

A two-tab panel holding the values passed to the method, Named first. Both tabs can be used at once. Positional arguments are always passed first, then the named ones, whatever order the tabs appear in.

Named

A YAML editor, one key: value pair per line. Values expand ${var} placeholders; keys do not.

Keys carry a leading $, which is how the form writes them when it pre-fills from the method signature:

$username: ${username}
$to_status: approved

That $ is not decoration. The first character of every key is removed before the call, so a key typed as username arrives at the method as sername and the method complains about an unknown argument or a missing one. Keep the sigil the form gave you.

Keys are re-sorted alphabetically each time the editor loads, and YAML comments are discarded on save. Neither affects the call, since named arguments are matched by name.

A value that is exactly one ${var} keeps its type, so a list in the stash arrives as a list. Mix that same variable with other text and the op stops the rule rather than stringifying it; only variables holding a single value can be pasted into a longer string.

Positional

A grid with a Name and a Value column, and a toolbar carrying Load CSV, Delete and Add. Add appends an empty row and opens it, Delete removes the selected row, and Load CSV fills the grid from pasted comma-separated text. Clicking a row opens it for editing with Save and Cancel on the row itself.

Only the Value column is passed to the method. The Name column is filled in from the method signature so you can see which slot you are filling, and it is never read at run time. Renaming a row changes nothing, and neither does clearing the name.

What does matter is row order, because that is the argument order. Rows are passed top to bottom, so a deleted row shifts every argument below it up one slot. If a method takes three positional arguments and you only want to set the third, you still have to fill the first two.

Value expands ${var} placeholders on the same terms as the Named tab.

The result

Whatever the method returned becomes the op's result: nothing if the method returned nothing, the single value if it returned one, a list if it returned several.

Put a name in the op's Return Key property to keep it. ${my_result} then holds the value for the rest of the rule. Without a Return Key the result is computed and dropped.

Return Key set to = spreads the result across the stash as top-level variables instead of putting it under one name, which is what you want when the method returns a plain record and you would rather read ${name} and ${status} directly. It only does that for a plain record. A method that returns a resource falls through it silently and nothing reaches the stash, and a method that returns a string or a list under = leaves the value in a stash entry named =, which nothing can reference.

Failure

Anything the method raises stops the job, and the job log shows it prefixed with the name of the op so you can find which one failed. A missing class, an unknown method name and an identifier that matches no resource all fail the same way.

The op takes part in rollback like any other. It is a plain call with no undo of its own, so a method that changes something needs its reverse wired up explicitly: guard the op with IF ROLLBACK, or place a second copy of the op calling the inverse method on the rollback path.

Combining with other ops

Get the identifier into the stash first. SET VAR to CI puts a resource in a variable so you can pass ${myvar.mid} here, and FOREACH CI walks a list of resources so you can call the same method on each of them.

For creating resources rather than calling methods on them, use Create CI. For Git work there are dedicated ops that are easier to read than a raw method call: Create a tag in a Git repository, Create a branch in a Git repository, Merge a branch in a Git repository and Delete a reference in a Git repository.

When the method takes structured input, build it with CODE into a stash variable and pass that variable as a single ${var} value here.

Examples

Read the files attached to a topic and keep the list. The method declares no parameters, so both tabs stay empty.

CI Class:    topic
CI Methods:  files
MID:         ${topic_mid}
Arguments
  Named:      (empty)
  Positional: (empty)
Return Key:  topic_files

Change a topic's status, passing both named arguments the method declares.

CI Class:    topic
CI Methods:  change_status_by_name
MID:         ${topic_mid}
Arguments
  Named:
    $username:  ${username}
    $to_status: approved

Call a method that takes its arguments by position, filling every slot up to the one you care about.

CI Class:    ssh_agent
CI Methods:  chmod
MID:         ${server_mid}
Arguments
  Positional:
    Name    Value
    $mode   0755
    $path   ${job_dir}/bin/deploy.sh