camundactl 0.1.0a4

A Camunda cli that interacts with the rest api

camundactl

camundactl (cctl) is a command line interface (cli) that interacts with the camunda rest api. It provides commands for all endpoints with the ability to filtes and different output format. The cli usaged is heavily inspired by kubecl to work with kubernetes.

Features

• request all endpoints, defined in the camunda openapi.json
• generate get, delete and apply commands from openapi.json
• dedicated implementations for describe
• multiple output formats: table, json, jsonpath, template (jinja2)
• shell autocomplete for zsh, bash, fish)
• shell autocomplete for processInstanceId, incidentIds, aso.
• configuration for multipe camunda engines
• ...

Contents

• Examples
• Installation
• Configuration
  • Format
  • Add/Select/List/Remove Engine
  • Autocomplete
• Usage
  • Global Options
  • get Command
  • describe Command
  • delete Command
  • apply Command
  • config Command
  • output Option

Examples

Load two active process instances and use only the columns id and suspended

$ cctl get processInstances --max-results 2 -o table -oH id,suspended
id                                    suspended
------------------------------------  -----------
0027da48-0a61-11ec-bd5f-0242ac120014  False
003248e7-0b05-11ec-990f-0242ac12000d  False

Load all active process instances and use the result in a jinja2 template.

$  cctl get processInstances -o template -oT '{{result|length}}'
1337

Load five active process instances and apply jsonpath formatting.

$ cctl get processInstances -o jsonpath -oJ '$.[*].id' --max-results 5
0027da48-0a61-11ec-bd5f-0242ac120014
003248e7-0b05-11ec-990f-0242ac12000d
005ec7db-0a6c-11ec-bd5f-0242ac120014
00957ceb-0b18-11ec-990f-0242ac12000d
00f522c0-0b10-11ec-990f-0242ac12000d

Load only one active process instance and ouput as json.

$ cctl get processInstances -o json --max-results 1
[
  {
    "links": [],
    "id": "0027da48-0a61-11ec-bd5f-0242ac120014",
    "definitionId": "f87b25ce-0577-11ec-8801-0242ac12000a",
    "businessKey": null,
    "caseInstanceId": null,
    "ended": false,
    "suspended": false,
    "tenantId": null
  }
]

Pipe commands together. Get all active process instances by process defintion and delete them:

$ cctl get processInstances --process-definition-id f87b25ce-0577-11ec-8801-0242ac12000a -o jsonpath -oJ "$.[*].id" | xargs -n 1 cctl delete processInstance -o template -oT "Ok"
Ok
Ok
Ok
...

Installation

camundactl can be installed via pip.

$ pip install camundactl

Configuration

camundactl uses a config file. The locations differ from os. If the configuration file does not it exists, it becomes created.

• MacOS: $HOME/Libarary/Application Support/camundactl/config.yml
• Linux: $HOME/.config/camundactl/config.yml
• Windows: $HOME/Appdata/Local/camundactl/config.yml

Format

version: beta1
extra_paths:
  - module.to.my.plugin
current_engine: localhost
engines:
  - name: localhost
    url: http://localhost:8080/engine-rest
    auth:
      user: camunda
      password: camunda
  - name: client-a
    url: http://localhost:8080/engine-rest
    auth:
      user: camunda
      password: camunda
  - name: client-c
    url: https://localhost:8080/engine-rest
    verify: false
    auth:
      user: camunda
      password: camunda

• version defines the current config file version for later update purpose
• extra_path is a list of python modules that can be autodiscovered in command discovering to add user defined commands or plugins
• current_engine is the currently selected engine to be used
• engine contains a list of engines within you can switch witch cctl config engines activate ANOTHER.
  • name the engines display name
  • url the urls of the camunda engine rest api
  • auth is an object of user and password for basic authentication
  • verify is a boolen that ignores ssl verification (default true)

Add/List/Activate/Remove Engines

Add an engine

Add a camunda engine to the list of engines and directly select it.

$ cctl config engines add local http://localhost:8080/engine-rest --select

List all engines

List all engines that are configured. The * indicates the currently selected engine.

$ cctl config engines ls
local *
client-a

Activate an engine

Activates the client-a engine.

$ cctl config engines activate client-a

Remove an engine

Removes the client-a engine.

$ cctl config engines remove client-a

Autocomplete

camundactl provides the functionality to autocomplete at the console.

camundactl bases on click, which autocomplete method could be used.

Example for zsh

$ _CCTL_COMPLETE=zsh_source cctl > $HOME/.cctl-completion.sh

You can find more Details on the project-page: https://click.palletsprojects.com/en/8.0.x/shell-completion/

Usage

Gloabl options

--help --log -e, --engine

get Resource Information

Get commands provides the ability to request ressource information from a given engine. It contains all OpenAPI Operations of the Verb get.

delete Resource Information

Delete commands provide the ability to delete specific ressources in the camunda engine.

apply Resource Information

Apply commands provide the ability to apply changes to the camunda engine. They combine the functionality of put and post verbs and these operations.

As kubectl you can use apply in combination with files that contains the payload.

You can use JSON or YAML payloads.

$ cat EOF>>
value: hello-world
type: String
EOF >> variable.yaml

$ cctl apply processInstanceVariable foobar 0027da48-0a61-11ec-bd5f-0242ac120014 -y variable.yml

Schema validation If provided, the given payload becomes validated against the openapi schema. The openapi documentation sometimes does not fully match the api. (e.g. while updating variables. The values is describes as object but values of primitive variables are also allowed.)

To skip this use the option --skip-validation.

describe Resource Information

not quite implemented. It's planned to use this commands to collect and output complex informationations about a given ressoure including combining multiple endpoints (e.g. process instances with all occured incidents and variable information.)

output Option

The -o/--output option defines the output format. The default ist table. All other options are described in the following.

Table Output

The camunda responses are nearly all of type application/json. If the response is of type array a table will be printed. If it's an object a table with key and value headers are used.

Options

• -o table
• -oH, --output-headers gives the possibility to select the columns to show
• -oCL, --output-cell-length cell values of type string are limited to 40 characters.

Example

$ cctl get processInstances -o table -oH id,suspended

JSON Output

Prints the json API response with end indent of 2.

Options

• -o json

JSON-Path Output

-o jsonpath activates a jsonpath output. With -oJ you can apply the jsonpath filter which will be applied. For this jsonpath-ng is used. There you can find further information about the filter format.

Template Output

Raw Output

root command

$ python -m camundactl --help

Usage: __main__.py [OPTIONS] COMMAND [ARGS]...

Options:
  -l, --log-level TEXT  activates the logger with the given level
  -e, --engine TEXT     define the engine name to be used
  --help                Show this message and exit.

Commands:
  delete
  describe
  get

delete command

$ python -m camundactl delete --help

Usage: __main__.py delete [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  attachment                      Removes an attachment from a task by...
  deployment                      Deletes a deployment by id.
  processDefinition               Deletes a running process instance by...
  processDefinitionsByKey         Deletes process definitions by a given...
  processDefinitionsByKeyAndTenantId
                                  Deletes process definitions by a given...
  processInstance                 Deletes a running process instance by...
  processInstanceVariable         Deletes a variable of a process...
  task                            Removes a task by id.
  taskLocalVariable               Removes a local variable from a task...
  taskVariable                    Removes a variable that is visible to...

get command

$ python -m camundactl get --help

Usage: __main__.py get [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  activityInstanceTree            Retrieves an Activity...
  activityStatistics              Retrieves runtime...
  activityStatisticsByProcessDefinitionKey
                                  Retrieves runtime...
  activityStatisticsByProcessDefinitionKeyAndTenantId
                                  Retrieves runtime...
  attachment                      Retrieves a task...
  attachmentData                  Retrieves the binary...
  attachments                     Gets the attachments...
  comment                         Retrieves a task...
  comments                        Gets the comments for...
  deployedForm                    Retrieves the...
  deployedStartForm               Retrieves the...
  deployedStartFormByKey          Retrieves the...
  deployedStartFormByKeyAndTenantId
                                  Retrieves the...
  deployment                      Retrieves a...
  deploymentResource              Retrieves a...
  deploymentResourceData          Retrieves the binary...
  deploymentResources             Retrieves all...
  deploymentsCount                Queries for the...
  eventSubscriptions              Queries for event...
  eventSubscriptionsCount         Queries for the...
  externalTask                    Retrieves an external...
  externalTaskErrorDetails        Retrieves the error...
  externalTasks                   Queries for the...
  externalTasksCount              Queries for the...
  form                            Retrieves the form...
  formVariables                   Retrieves the form...
  identityLinks                   Gets the identity...
  interval                        Retrieves a list of...
  latestProcessDefinitionByTenantId
                                  Retrieves the latest...
  metrics                         Retrieves the `sum`...
  processDefinition               Retrieves a process...
  processDefinitionBpmn20Xml      Retrieves the BPMN...
  processDefinitionBpmn20XmlByKey
                                  Retrieves latest...
  processDefinitionBpmn20XmlByKeyAndTenantId
                                  Retrieves latest...
  processDefinitionByKey          Retrieves the latest...
  processDefinitionDiagram        Retrieves the diagram...
  processDefinitionDiagramByKey   Retrieves the diagram...
  processDefinitionDiagramByKeyAndTenantId
                                  Retrieves the diagram...
  processDefinitionStatistics     Retrieves runtime...
  processDefinitions              Queries for process...
  processDefinitionsCount         Requests the number...
  processEngineNames              Retrieves the names...
  processInstance                 lists all active...
  processInstanceVariable         Retrieves a variable...
  processInstanceVariableBinary   Retrieves the content...
  processInstanceVariables        Retrieves all...
  processInstances                Queries for process...
  processInstancesCount           Queries for the...
  renderedForm                    Retrieves the...
  renderedStartForm               Retrieves the...
  renderedStartFormByKey          Retrieves the...
  renderedStartFormByKeyAndTenantId
                                  Retrieves the...
  restAPIVersion                  Retrieves the version...
  schemaLog                       Queries for schema...
  startForm                       Retrieves the key of...
  startFormByKey                  Retrieves the key of...
  startFormByKeyAndTenantId       Retrieves the key of...
  startFormVariables              Retrieves the start...
  startFormVariablesByKey         Retrieves the start...
  startFormVariablesByKeyAndTenantId
                                  Retrieves the start...
  task                            Retrieves a task by...
  taskLocalVariable               Retrieves a variable...
  taskLocalVariableBinary         Retrieves a binary...
  taskLocalVariables              Retrieves all...
  taskVariable                    Retrieves a variable...
  taskVariableBinary              Retrieves a binary...
  taskVariables                   Retrieves all...
  tasks                           Queries for tasks...
  tasksCount                      Retrieves the number...
  topicNames                      Queries for distinct...

autocomplete

_CCTL_COMPLETE=zsh_source cctl

TODO / Ideas

• output column length in options or parameter (currently hard 40)

• display

  • list of strings
  • list of objects
  • object with keys
  • object with one value

• use template loader to save and load templates somewhere and let use use them or save some for default

• templates with more context variables. not just "result"