Anvil
Reference

The macro steps

Anvil ships 17 steps in Anvil_Macros_Steps.mdzip, and a macro calls one through a step action. This page states what each step does, what each parameter means, and whether a macro feeds that parameter a constant on a value pin or a value on a flow.

This page is generated from the shipped archive by tools/model-library/generate_step_catalogue.py. Change the model rather than the page: tools/model-library/steps-documentation.json carries the text, tools/model-library/document_behaviors.py writes it into the archive, and StepCatalogueTest fails the build when the two disagree.

Acceptable owner

Answers the near element when it may own the given element, and otherwise the nearest owner of the near element that may. Fails when no owner up the chain accepts it.

ParameterTypeMultiplicityFed byMeans
elementElement1..1a flowThe element that needs an owner.
nearElement1..1a flowWhere the search starts. The step walks up this element's owners.

Returns Element [1..1].

Counterpart

Answers the copy of an element that an earlier Copy step in this run produced, looking inside the given copy. Answers nothing when the element was not part of what that Copy copied. Runs only inside a macro, where the pairs were recorded.

ParameterTypeMultiplicityFed byMeans
originalElement1..1a value pinAn element the template owns, whose copy is wanted. Pick the element inside the template, not the copy.
copyElement1..1a flowThe copy to look inside, as an earlier Copy step answered it.

Returns Element [0..1].

Copy

Copies the source element and everything it owns under the owner, and answers the copy. Records every original-to-copy pair for the rest of the run, so a Counterpart step finds the copy of any element the source owned. Fails when the owner is read-only or the tool refuses the paste.

ParameterTypeMultiplicityFed byMeans
sourceElement1..1a value pinThe element to copy, with everything under it. Pick the template.
ownerElement1..1a flowThe element the copy is placed under. An Acceptable owner step answers one that accepts it.

Returns Element [1..1].

Has stereotype

Answers whether the element carries the stereotype. Reads as a decision's input, so a macro branches on it.

ParameterTypeMultiplicityFed byMeans
elementElement1..1a flowThe element to test.
stereotypeStereotype1..1a value pinThe stereotype to look for. Pick a Stereotype element from a profile.
includeSubtypesBoolean1..1a value pinTrue also matches an element carrying a specialization of the stereotype; false matches the stereotype alone.

Returns Boolean [1..1].

Set owner

Moves each given element under the owner. Fails when the owner may not own one of them, or when one is read-only.

ParameterTypeMultiplicityFed byMeans
elementsElement0..*a flowThe elements to move.
ownerElement1..1a flowThe element they are moved under.

Returns nothing.

Set tag

Sets one tag of a stereotype on the element, applying the stereotype first when the element does not carry it. Fails when the tag belongs to no stereotype, or when the element is read-only.

ParameterTypeMultiplicityFed byMeans
elementElement1..1a flowThe element to tag.
tagProperty1..1a value pinThe tag to set. Pick the property of the stereotype that defines it, not the stereotype.
valueany0..*a flowThe values to write. One value for a tag that holds one.

Returns nothing.

Apply stereotype

Applies the stereotype to each given element. Fails on a read-only element.

ParameterTypeMultiplicityFed byMeans
elementsElement0..*a flowThe elements to stereotype.
stereotypeStereotype1..1a value pinThe stereotype to apply. Pick a Stereotype element from a profile.

Returns nothing.

Replace in names

Replaces every occurrence of the placeholder with the replacement, in the name of each given element and of every named element under it. Fails on an empty placeholder or a read-only element.

ParameterTypeMultiplicityFed byMeans
elementsElement0..*a flowThe elements to rename under, each renamed as well.
placeholderString1..1a value pinThe text to replace, spelled as the template's names spell it.
replacementString1..1a flowThe text that takes its place. An Ask text step answers what the modeller typed.

Returns nothing.

Open diagrams

Opens each diagram in the tool. A diagram the tool holds no presentation for is skipped.

ParameterTypeMultiplicityFed byMeans
diagramsDiagram0..*a flowThe diagrams to open. A Diagrams of step, or a Counterpart step, answers them.

Returns nothing.

Diagrams of

Answers the diagrams the given elements own, and every diagram under them when recursive.

ParameterTypeMultiplicityFed byMeans
elementsElement0..*a flowThe elements to read diagrams from.
recursiveBoolean1..1a value pinTrue reads every diagram under the elements; false reads only the diagrams they own directly.

Returns Diagram [0..*].

Confirm

Asks the modeller a yes-or-no question and answers true for yes. Cancelling the dialog cancels the run, which rolls the model back and reports nothing. Reads as a decision's input, so a macro branches on the answer.

ParameterTypeMultiplicityFed byMeans
titleString1..1a value pinThe dialog's title.
questionString1..1a value pinThe question the modeller answers yes or no to.

Returns Boolean [1..1].

Ask elements

Opens the tool's element selection dialog, restricted to the given types, and answers what the modeller picked. Cancelling the dialog cancels the run, which rolls the model back and reports nothing.

ParameterTypeMultiplicityFed byMeans
titleString1..1a value pinThe dialog's title.
typesClass0..*a value pinWhat the dialog offers. Pick a metaclass or a Stereotype element, or leave the pin empty to offer every element.
multipleBoolean1..1a value pinTrue lets the modeller pick several elements; false one.

Returns Element [0..*].

Ask choice

Asks the modeller to pick one of the offered options and answers it. Cancelling the dialog cancels the run, which rolls the model back and reports nothing.

ParameterTypeMultiplicityFed byMeans
titleString1..1a value pinThe dialog's title.
questionString1..1a value pinThe question shown above the options.
optionsString1..*a flowThe options to offer. An upstream step answers them; one value pin would offer one option, so a flow feeds this pin.

Returns String [1..1].

Ask text

Asks the modeller for one line of text and answers it. Cancelling the dialog cancels the run, which rolls the model back and reports nothing.

ParameterTypeMultiplicityFed byMeans
titleString1..1a value pinThe dialog's title.
questionString1..1a value pinThe question shown above the field.
initialString0..1a value pinThe text the field starts with. Leave the pin empty for an empty field.

Returns String [1..1].

Fail

Ends the run as a failure carrying the message. Nothing after it runs, and the model rolls back to where the run started. This is how a macro stops deliberately after a decision.

ParameterTypeMultiplicityFed byMeans
messageString1..1a value pinThe text shown to the modeller. A blank message is replaced by a generic one.

Returns nothing.

Notify

Shows the message as an information balloon once the run has committed. A macro may notify more than once; the balloons appear together at the end.

ParameterTypeMultiplicityFed byMeans
messageString1..1a value pinThe text the balloon carries.

Returns nothing.

Select in browser

Selects the element in the containment tree, so the modeller sees what the macro produced.

ParameterTypeMultiplicityFed byMeans
elementElement1..1a flowThe element to select.

Returns nothing.

  • Anvil: write a macro — drawing an Activity that calls these steps, and reaching it from the shortcut menu
  • contributing/add-a-step.md in the repository — writing a step of your own, binding it from a model library, and documenting it
  • How macros run — what one run commits, and how a value reaches a pin

On this page