Penstock

Guide / Draw and edit

Element templates

An element template turns a plain task into a ready-made one, for example "send an e-mail", with a short form of its own.

Free Camunda 7 and Camunda 8. The connector browser is for Camunda 8.

What it is

An element template is a JSON file. It says: "this task is a Slack message, and it needs a channel and a text". When you apply it, the properties panel shows only those two fields and Penstock writes the technical settings for you. Penstock uses the Camunda template format. For the format itself, read Camunda's documentation.

Where Penstock finds templates

Two places, and nothing else in the project is scanned:

elementTemplates:
  - templates/connectors
  - shared/payment-task.json

Like the rest of penstock.yaml, the list can differ per folder. The file nearest the diagram wins. See penstock.yaml.

A file may hold one template or an array of templates. Both work.

What is skipped without an error

Penstock re-reads a file when its modification time changes, so an edited template is picked up without restarting your tool.

Apply a template

  1. Select a task or event in a Camunda 7 or Camunda 8 diagram.
  2. In the properties panel, use the template chooser at the top. Pick a template.
  3. Fill in the fields the template shows.

The element records which template it came from. Under Camunda 7 that is camunda:modelerTemplate. Under Camunda 8 it is zeebe:modelerTemplate. The Classic profile has no template support.

Templates from your worker code

Pro

A template can also be written from the worker that does the job. Create Element Template is offered on a job worker in your code: a @JobWorker method, a newWorker().jobType(...) registration or a Camunda 7 external task subscription. It writes the template of the job type or topic into .camunda/element-templates, with one field for each variable the worker reads, typed by the Java type, an enum as a dropdown, and the variables the worker sets as output mappings. If a template for the same job type is there already, it is brought up to date: its version is raised and the labels and descriptions you wrote are kept.

A template says which worker it came from. One whose variables no longer match that worker is marked, and the step names the gap in the code check. From a template you can also write a job worker, in Java Spring, Node or Python, through the same generator the Camunda 7 to Camunda 8 conversion uses. In a terminal, penstock templates generate writes one template for every worker in the project, and --check writes nothing and fails when a template has drifted. See Code links.

The connector browser

Camunda publishes ready-made connector templates: Slack, e-mail, REST, and many more. Penstock has a browser for them.

Open it

  1. Open a Camunda 8 diagram.
  2. Open More and choose Templates…. A dialog called Connector Templates opens.
  3. The first time, it says Downloading the connector templates from GitHub…. Wait a moment.

The templates are not bundled with Penstock. They are downloaded from Camunda's public camunda/connectors repository on GitHub, and kept in ~/.penstock/connectors/. Every tool on your machine shares that folder. Penstock asks GitHub at most once a day. It sends no credentials, no cookies and no project data. Opening a diagram never downloads anything. See Security and privacy.

Find a template

Each card shows the name, a short description, the element type, the version, and the Camunda version it needs. A template Camunda has deprecated is badged Deprecated, with its own reason where the template gives one, and sorted after the current ones rather than in among them. Details opens the whole template: its fields, grouped, and a link to the documentation. The details are shown inside the browser itself rather than in a second window.

A connector that ships several templates installs all of them at once: that path asks for a folder, warns that it will write one file per template and overwrite files of the same names, and waits for you to confirm. To take one template of such a connector, open Details and install it from the list.

Install one

  1. Press Install on a card, or Install template in its details.
  2. A save panel opens, pre-filled with the template's own file name, in the nearest .camunda/element-templates folder above the diagram, using one that already exists where the project has one. Save it there, or into a folder your elementTemplates list already names. Cancel writes nothing.
  3. If penstock.yaml has no elementTemplates list yet, the file you saved is added as its first entry. A list that exists is left alone.
  4. The open diagram uses it at once. You do not need to reopen it.

A message says Template "…" installed. The card then says Installed and its button is off.

A diagram that names a template you do not have

When a diagram uses a connector template that is not in the project, Penstock looks in the downloaded set. If it is there, the diagram uses it. If not, a small badge on the element says Template not downloaded with a Download button. Press it to fetch the catalogue.

From a terminal

penstock connectors                 # list the current templates
penstock connectors resolve io.camunda.connectors.HttpJson.v2
penstock connectors --refresh       # ask GitHub now

See Every command.

What you see

Common problems

A template does not appear.
Check three things in this order. The diagram's engine must be Camunda 7 or Camunda 8, not Classic. The file must be in a .camunda/element-templates folder at or above the diagram, or under a path in elementTemplates. The file must still exist. penstock doctor reports a listed path that is missing. Then read the log of your tool: a file that is too large or not valid JSON is skipped with a message.
There is no Templates… item.
The connector browser is only for Camunda 8 diagrams.
The browser says the connector templates could not be downloaded.
Penstock could not reach GitHub. Check the network and the proxy settings of your tool, then press Retry. If it worked before, Penstock uses the templates it already downloaded. It tries again automatically after a while.
Install says nothing was written.
You cancelled the save dialog. Nothing is written when you cancel.

See also