### Start a Process Instance

Source: https://pycamunda.readthedocs.io/en/latest/src/usage.html

Use the `StartInstance` class from `pycamunda.processdef` to start a new process instance. Specify the process definition by its key or ID and optionally add initial variables.

```python
import pycamunda.processdef

url = 'http://localhost/engine-rest'

start_instance = pycamunda.processdef.StartInstance(url=url, key='MyProcessDefinition')
start_instance.add_variable(name='InitVariable', value=1)
process_instance = start_instance()
```

--------------------------------

### Install PyCamunda using pip

Source: https://pycamunda.readthedocs.io/en/latest/src/installation.html

Use this command to install the PyCamunda library from the Python Package Index.

```bash
pip install pycamunda

```

--------------------------------

### Get

Source: https://pycamunda.readthedocs.io/en/latest/src/api/processdef.html

Retrieves a specific process definition.

```APIDOC
## Get

### Description
Get a process definition.

### Method
__call__

### Parameters
#### Path Parameters
* **url** (str) - Required - Camunda Rest engine URL.
* **id** (str) - Optional - Id of the process definition.
* **key** (str) - Optional - Key of the process definition.
* **tenant_id** (str) - Optional - Id of the tenant the process definition belongs to.

### Response
#### Success Response
- **process_definition** (pycamunda.processdef.ProcessDefinition) - The process definition object.
```

--------------------------------

### Get Deployment Resources

Source: https://pycamunda.readthedocs.io/en/latest/src/api/deployment.html

Retrieves all resources associated with a specific deployment.

```APIDOC
## Get Deployment Resources

### Description
Get the resources of a deployment.

### Method
GET (inferred from SDK method)

### Endpoint
{url}/deployment/{id}/resources

### Parameters
#### Path Parameters
- **url** (string) - Required - Camunda Rest engine URL.
- **id** (string) - Required - Id of the the deployment.

### Response
#### Success Response (200)
- **Tuple[Resource]** (array) - A tuple containing Resource objects.
```

--------------------------------

### Options

Source: https://pycamunda.readthedocs.io/en/latest/src/api/authorization.html

Get a list of options the currently authenticated user can perform on the authorization resource.

```APIDOC
## Options

### Description
Get a list of options the currently authenticated user can perform on the authorization resource.

### Method
GET

### Endpoint
/authorization

### Parameters
#### Query Parameters
- **url** (string) - Required - Camunda Rest engine URL.
- **id** (string) - Optional - Id of the authorization

### Response
#### Success Response (200)
- **resourceOptions** (ResourceOptions) - Description of the resource options.
```

--------------------------------

### UserMemberOptions

Source: https://pycamunda.readthedocs.io/en/latest/src/api/tenant.html

Get a list of options the currently authenticated user can perform on the tenant membership resource.

```APIDOC
## UserMemberOptions

### Description
Get a list of options the currently authenticated user can perform on the tenant membership resource.

### Parameters
#### Path Parameters
- **url** (str) - Required - Camunda Rest engine URL.
- **id** (str) - Required - Id of the tenant.

### Method
OPTIONS

### Endpoint
/tenant/{id}/members

### Response
#### Success Response (200)
- **ResourceOptions** (pycamunda.resource.ResourceOptions) - Description of the options available.
```

--------------------------------

### Get Activity Instance

Source: https://pycamunda.readthedocs.io/en/latest/src/api/processinst.html

Retrieves the activity instance tree for a specific process instance.

```APIDOC
## Get Activity Instance

### Description
Get an activity instance tree for a specific process instance.

### Method
GET

### Endpoint
/process-instance/{id}/activity-instances

### Parameters
#### Path Parameters
- **id** (string) - Required - Id of the process instance.

### Response
#### Success Response (200 OK)
- **activityInstanceTree** (object) - The activity instance tree for the process instance.

#### Response Example
```json
{
  "activityInstanceTree": {
    "id": "someActivityId",
    "parentActivityInstanceId": null,
    "activityId": "someProcessDefinitionId",
    "activityType": "processDefinition",
    "startTime": "2023-01-01T10:00:00.000+0000",
    "endTime": null,
    "duration": null,
    "executionIds": [],
    "childActivityInstances": [],
    "childTransitionInstances": []
  }
}
```
```

--------------------------------

### Access Request URL with Process Definition ID

Source: https://pycamunda.readthedocs.io/en/latest/src/usage.html

Retrieve the constructed request URL for starting a process instance using its definition ID. This demonstrates the dynamic URL generation based on provided parameters.

```python
import pycamunda.processdef

url = 'http://localhost:8080/engine-rest'

if __name__ == '__main__':
    start_instance = pycamunda.processdef.StartInstance(url=url, id_='174cb832-a8a7')
    print(start_instance.url)
    start_instance = pycamunda.processdef.StartInstance(url=url, key='MyProcess')
    print(start_instance.url)

```

--------------------------------

### Get Process Instance

Source: https://pycamunda.readthedocs.io/en/latest/src/api/processinst.html

Retrieves details of a specific process instance by its ID.

```APIDOC
## Get Process Instance

### Description
Retrieves details of a specific process instance.

### Method
GET (implied by class name and typical REST patterns)

### Endpoint
/process-instance/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Id of the process instance.

#### Query Parameters
None explicitly documented.

#### Request Body
None explicitly documented.

### Request Example
None explicitly documented.

### Response
#### Success Response (200)
- **ProcessInstance** (object) - Details of the process instance.

#### Response Example
None explicitly documented.
```

--------------------------------

### GetActivityInstanceStats

Source: https://pycamunda.readthedocs.io/en/latest/src/api/processdef.html

Get runtime statistics for a process definition. This method does not include historic data.

```APIDOC
## GetActivityInstanceStats

### Description
Get runtime statistics for a process definition. Does not include historic data.

### Method
GET

### Endpoint
/process-definition/{id}/statistics

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the process definition.

#### Query Parameters
- **tenantId** (string) - Optional - Id of the tenant the process definition belongs to.
- **failedJobs** (boolean) - Optional - Whether the number of failed jobs should be included.
- **incidents** (boolean) - Optional - Whether to include the number of incidents.
- **incidentsForType** (string or IncidentType or None) - Optional - Include only incidents of a specific type.

### Request Example
```json
{
  "url": "http://localhost:8080/engine-rest",
  "id": "someProcessDefinitionId",
  "tenantId": "someTenantId",
  "failedJobs": true,
  "incidents": true,
  "incidentsForType": "someIncidentType"
}
```

### Response
#### Success Response (200)
- **activity_stats** (list of ActivityStats) - A list containing runtime statistics for activities within the process definition.

#### Response Example
```json
{
  "activity_stats": [
    {
      "id": "someActivityId",
      "instances": 10,
      "failedJobs": 2,
      "incidents": [
        {
          "incidentType": "someIncidentType",
          "count": 5
        }
      ]
    }
  ]
}
```
```

--------------------------------

### Evaluate

Source: https://pycamunda.readthedocs.io/en/latest/src/api/condition.html

Triggers the evaluation of conditional start events. This class can be instantiated with connection details and then used to add variables and send the evaluation request.

```APIDOC
## Evaluate

### Description
Triggers the evaluation of conditional start events. This class can be instantiated with connection details and then used to add variables and send the evaluation request.

### Class Signature
`pycamunda.condition.Evaluate(url: str, business_key: Optional[str] = None, tenant_id: Optional[str] = None, without_tenant_id: bool = False, process_definition_id: Optional[str] = None)`

### Parameters
#### Initialization Parameters
- **url** (str) - Required - Camunda Rest engine URL.
- **business_key** (Optional[str]) - Optional - Business key for the process instances that might be started.
- **tenant_id** (Optional[str]) - Optional - Tenant id of the conditions to evaluate.
- **without_tenant_id** (bool) - Optional - Whether to evaluate only conditions that have no tenant. Defaults to False.
- **process_definition_id** (Optional[str]) - Optional - Process definition id of the conditions to evaluate.

### Methods
#### `__call__`
- **Description**: Sends the evaluation request.
- **Returns**: Tuple[pycamunda.processinst.ProcessInstance]

#### `add_variable`
- **Description**: Adds a variable for the evaluation of the conditions.
- **Parameters**:
  - **name** (str) - Required - Name of the variable.
  - **value** (Any) - Required - Value of the variable.
  - **type** (Optional[str]) - Optional - Value type of the variable.
  - **value_info** (Optional[Mapping[KT, VT_co]]) - Optional - Additional information regarding the value type.
- **Returns**: None
```

--------------------------------

### Options

Source: https://pycamunda.readthedocs.io/en/latest/src/api/filter.html

Get a list of options the currently authenticated user can perform on the filter resource. This method retrieves available actions for the filter.

```APIDOC
## Options

### Description
Get a list of options the currently authenticated user can perform on the filter resource.

### Method
GET

### Endpoint
/filter/{id}/options

### Parameters
#### Path Parameters
- **id** (string) - Optional - Id of the filter.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **options** (list) - A list of available options for the filter.

#### Response Example
```json
{
  "options": [
    "read",
    "update"
  ]
}
```
```

--------------------------------

### GetList

Source: https://pycamunda.readthedocs.io/en/latest/src/api/processdef.html

Query for a list of process definitions using a variety of parameters. The size of the result set can be retrieved by using the Get List Count method.

```APIDOC
## GetList

### Description
Query for a list of process definitions using a list of parameters. The size of the result set can be retrieved by using the Get List Count method.

### Method
GET

### Endpoint
/process-definition

### Parameters
#### Query Parameters
- **id** (string) - Optional - Filter by id.
- **id_in** (Iterable[string]) - Optional - Filter whether the id is one of multiple ones.
- **name** (string) - Optional - Filter by name.
- **name_like** (string) - Optional - Filter by a substring of the name.
- **deployment_id** (string) - Optional - Filter by deployment id.
- **key** (string) - Optional - Key of the process definition.
- **key_in** (Iterable[string]) - Optional - Filter whether the key is one of multiple ones.
- **key_like** (string) - Optional - Filter by a substring of the key.
- **category** (string) - Optional - Filter by category.
- **category_like** (string) - Optional - Filter by a substring of the category.
- **version** (string) - Optional - Filter by version.
- **latest_version** (boolean) - Optional - Whether to include only the latest versions. Defaults to False.
- **resource_name** (string) - Optional - Filter by resource name.
- **resource_name_like** (string) - Optional - Filter by a substring of the resource name.
- **startable_by** (string) - Optional - Filter by user names that are allowed to start an instance of the process definition.
- **active** (boolean) - Optional - Whether to include only active process definitions. Defaults to False.
- **suspended** (boolean) - Optional - Whether to include only suspended process definitions. Defaults to False.
- **incident_id** (string) - Optional - Filter by incident id.
- **incident_type** (string or IncidentType or None) - Optional - Filter by incident type.
- **incident_message** (string) - Optional - Filter by the incident message.
- **incident_message_like** (string) - Optional - Filter by a substring the incident message.
- **tenant_id_in** (Iterable[string]) - Optional - Filter whether the tenant id is one of multiple ones.
- **without_tenant_id** (boolean) - Optional - Whether to include only process definitions that belong to no tenant. Defaults to False.
- **include_without_tenant_id** (boolean) - Optional - Whether to include process definitions that belong to no tenant. Defaults to False.
- **version_tag** (string) - Optional - Filter by the version tag.
- **version_tag_like** (string) - Optional - Filter by a substring of the version tag.
- **without_version_tag** (boolean) - Optional - Whether to include only process definition without a version tag.
- **startable_in_tasklist** (boolean) - Optional - Filter by process definition that are startable in tasklist.
- **not_startable_in_tasklist** (boolean) - Optional - Filter by process definitions that are not startable in tasklist.
- **startable_permission_check** (boolean) - Optional - Filter by process definitions that the user is allowed to start.
- **sort_by** (string) - Optional - Sort the results by ‘category’, ‘key’, ‘id_’, ‘name’, ‘version’, ‘deployment_id’, ‘tenant_id’ or version_tag. Sorting by ‘version_tag’ is string-based.
- **ascending** (boolean) - Optional - Sort order. Defaults to True.
- **first_result** (integer) - Optional - Pagination of results. Index of the first result to return.
- **max_results** (integer) - Optional - Pagination of results. Maximum number of results to return.

### Response
#### Success Response (200)
- **ProcessDefinition** (List[pycamunda.processdef.ProcessDefinition]) - A list of process definition objects.

#### Response Example
```json
[
  {
    "id": "someProcessDefinitionId",
    "key": "someProcessDefinitionKey",
    "category": "someCategory",
    "name": "Some Process Definition Name",
    "version": 1,
    "deploymentId": "someDeploymentId",
    "resourceName": "someResourceName.bpmn",
    "diagramResourceName": "someDiagramResourceName.png",
    "tenantId": "someTenantId",
    "historyTimeToLive": "P7D",
    "startableInTasklist": true,
    "versionTag": "v1.0"
  }
]
```
```

--------------------------------

### Get Tenant

Source: https://pycamunda.readthedocs.io/en/latest/src/api/tenant.html

Retrieves a specific tenant by its ID. This operation is useful for fetching detailed information about a single tenant.

```APIDOC
## Get Tenant

### Description
Retrieves a specific tenant by its ID.

### Method
GET

### Endpoint
/v1/tenant/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Id of the tenant.

### Response
#### Success Response (200)
- **id** (string) - The ID of the tenant.
- **name** (string) - The name of the tenant.
```

--------------------------------

### GetList

Source: https://pycamunda.readthedocs.io/en/latest/src/api/user.html

Query for a list of users using a list of parameters. The size of the result set can be retrieved by using the Get User Count method.

```APIDOC
## GetList

### Description
Query for a list of users using a list of parameters. The size of the result set can be retrieved by using the Get User Count method.

### Method
GET

### Endpoint
/user

### Parameters
#### Query Parameters
- **id** (string) - Optional - Id of the user.
- **first_name** (string) - Optional - Filter by the first name of the user.
- **first_name_like** (string) - Optional - Filter by a substring of the first name.
- **last_name** (string) - Optional - Filter by the last name of the user.
- **last_name_like** (string) - Optional - Filter by a substring of the last name.
- **email** (string) - Optional - Filter by the email of the user.
- **email_like** (string) - Optional - Filter by a substring of the email.
- **member_of_group** (string) - Optional - Filter for users which are a member of a group.
- **member_of_tenant** (string) - Optional - Filter for users which are a member of a tenant.
- **sort_by** (string) - Optional - Sort the results by id, first_name, last_name or email of the user.
- **ascending** (boolean) - Optional - Sort order. Defaults to true.
- **first_result** (integer) - Optional - Pagination of results. Index of the first result to return.
- **max_results** (integer) - Optional - Pagination of results. Maximum number of results to return.

### Response
#### Success Response (200)
- **users** (list of User objects) - A list of user objects matching the query criteria.

### Request Example
```python
from pycamunda.user import GetList

users = GetList(url="http://localhost:8080/engine-rest").
    filter_by_last_name("Doe").
    execute()
```

### Response Example
```json
[
  {
    "id": "user1",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com"
  },
  {
    "id": "user2",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@example.com"
  }
]
```
```

--------------------------------

### Get and Set Request Parameters in PyCamunda

Source: https://pycamunda.readthedocs.io/en/latest/src/usage.html

Demonstrates how to access and modify request parameters using attribute descriptors in PyCamunda. This allows for dynamic setting of query parameters like first name and last name.

```python
import pycamunda.user

url = 'http://localhost:8080/engine-rest'

get_users = pycamunda.user.GetList(url=url, first_name='John')
print(get_users.first_name, get_users.last_name)
get_users.last_name = 'Doe'
print(get_users.first_name, get_users.last_name)

```

--------------------------------

### StartInstance

Source: https://pycamunda.readthedocs.io/en/latest/src/api/processdef.html

Initiates a new process instance for a specified process definition. You can identify the process definition by its ID or Key. Additional parameters allow for tenant ID, business key, case instance ID, and control over listeners, I/O mappings, and variable return.

```APIDOC
## StartInstance

### Description
Starts a process instance of a specific process definition. The process definition can be chosen by providing either the id or the key. If chosen by key, the latest version of that process definition is used. In case the key of the process definition is provided, the tenant id can be provided as well.

### Method
POST (Implicit, as it's a class that sends a request)

### Endpoint
(Not explicitly defined, but implies interaction with Camunda REST API for process definition start)

### Parameters
#### Path Parameters
None explicitly defined in this SDK method signature.

#### Query Parameters
None explicitly defined in this SDK method signature.

#### Request Body
(Implicitly constructed by the `__call__` method and `add_variable` methods)

- **url** (str) - Required - Camunda Rest engine URL.
- **id** (str) - Optional - Id of the process instance.
- **key** (str) - Optional - Key of the process definition.
- **tenant_id** (str) - Optional - Id of the tenant the process definition belongs to.
- **business_key** (str) - Optional - The business key to initialize the process instance with.
- **case_instance_id** (str) - Optional - The case instance id to initialize the process instance with.
- **skip_custom_listeners** (bool) - Optional - Whether to skip custom listeners and notify only builtin ones. Defaults to False.
- **skip_io_mappings** (bool) - Optional - Whether to skip input/output mappings. Defaults to False.
- **with_variables_in_return** (bool) - Optional - Whether the variables that were used by the process instance during execution should be returned. Defaults to False.

### Methods
#### `__call__()`
Sends the request to start the process instance.

#### `add_start_after_activity_instruction(id: str, variables: Optional[Mapping[str, Variable]] = None)`
Adds an instruction to start execution at the single outgoing sequence flow of an activity.

#### `add_start_before_activity_instruction(id: str, variables: Optional[Mapping[str, Variable]] = None)`
Adds an instruction to start execution before a given activity is entered.

#### `add_start_transition_instruction(id: str, variables: Optional[Mapping[str, Variable]] = None)`
Adds an instruction to start execution at the single outgoing sequence flow of an activity.

#### `add_variable(name: str, value: Any, type: Optional[str] = None, value_info: Optional[str] = None)`
Adds a variable to initialize the process instance with.

### Response
#### Success Response
- **ProcessInstance** (pycamunda.processinst.ProcessInstance) - The started process instance object.

#### Response Example
(Not explicitly provided in the source text)
```

--------------------------------

### Create

Source: https://pycamunda.readthedocs.io/en/latest/src/api/user.html

Creates a new user with the provided details.

```APIDOC
## Create

### Description
Create a new user.

### Method
POST

### Endpoint
/user

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **id** (str) - Optional - Id of the user.
- **first_name** (str) - Optional - First name of the user.
- **last_name** (str) - Optional - Last name of the user.
- **email** (str) - Optional - Email of the user.
- **password** (str) - Optional - Password of the user.

### Request Example
```json
{
  "url": "http://localhost:8080/engine-rest",
  "id": "newUser123",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane.doe@example.com",
  "password": "securepassword"
}
```

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### pycamunda.tenant.Options

Source: https://pycamunda.readthedocs.io/en/latest/src/api/tenant.html

Retrieves a list of options the currently authenticated user can perform on the tenant resource.

```APIDOC
## pycamunda.tenant.Options

### Description
Get a list of options the currently authenticated user can perform on the tenant resource.

### Parameters
#### Path Parameters
* **url** (str) - Required - Camunda Rest engine URL.
* **id** (str) - Optional - Id of the tenant.

### Method
__call__

### Request Example
```json
{
  "example": "Not applicable for this method, as it is a class constructor."
}
```

### Response
#### Success Response
- **ResourceOptions** (pycamunda.resource.ResourceOptions) - The available options for the tenant resource.
```

--------------------------------

### Get Batch

Source: https://pycamunda.readthedocs.io/en/latest/src/api/batch.html

Retrieves a specific batch by its ID.

```APIDOC
## Get Batch

### Description
Retrieves a specific batch by its ID.

### Method
GET

### Endpoint
/batch/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Id of the batch.

### Response
#### Success Response (200)
- **id** (string) - The ID of the batch.
- **type** (string) - The type of the batch.
- **totalJobs** (integer) - The total number of jobs created for this batch.
- **jobsCreated** (integer) - The number of jobs created so far.
- **jobsFailed** (integer) - The number of failed jobs.
- **progress** (integer) - The completion percentage of the batch.
- **startTime** (string) - The timestamp when the batch execution started.
- **endTime** (string) - The timestamp when the batch execution finished.
- **tenantId** (string) - The ID of the tenant the batch belongs to, or null if it belongs to no tenant.
- **state** (string) - The current state of the batch (e.g., 'PENDING', 'EXECUTING', 'COMPLETED', 'FAILED').
```

--------------------------------

### Get Group

Source: https://pycamunda.readthedocs.io/en/latest/src/api/group.html

Retrieves a specific group by its ID.

```APIDOC
## Get Group

### Description
Retrieves a specific group by its ID.

### Method
GET

### Endpoint
/group/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Id of the group.

#### Query Parameters
None

### Request Example
None provided

### Response
#### Success Response (200)
- **id** (string) - The ID of the group.
- **name** (string) - The name of the group.
- **type** (string) - The type of the group.

#### Response Example
None provided
```

--------------------------------

### Create

Source: https://pycamunda.readthedocs.io/en/latest/src/api/authorization.html

Create an authorization.

```APIDOC
## Create

### Description
Create an authorization.

### Method
POST

### Endpoint
/authorization

### Parameters
#### Request Body
- **type** (integer or AuthorizationType) - Required - Type of the authorization.
- **permissions** (Iterable[string]) - Required - Permissions provided by this authorization. A permission can be ‘READ’ or ‘CREATE’ for example.
- **user_id** (string) - Optional - Id of the user this authorization is for. The value ‘*’ means all users.
- **group_id** (string) - Optional - Id of the group this authorization is for.
- **resource_type** (string or ResourceType) - Required - Resource type this authorization is for.
- **resource_id** (string) - Required - Id of the resource. The value ‘*’ means all instances of a resource.

### Response
#### Success Response (200)
- **authorization** (Authorization) - The created authorization object.
```

--------------------------------

### Get Incident

Source: https://pycamunda.readthedocs.io/en/latest/src/api/incident.html

Retrieves a specific incident by its ID.

```APIDOC
## Get Incident

### Description
Retrieves a specific incident by its ID.

### Method
GET

### Endpoint
/incident/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Id of the incident.

#### Query Parameters
None

### Request Example
None provided in source.

### Response
#### Success Response (200)
- **incident** (pycamunda.incident.Incident) - The retrieved incident object.

#### Response Example
None provided in source.
```

--------------------------------

### Get API Version

Source: https://pycamunda.readthedocs.io/en/latest/src/api/version.html

Retrieves the version of the Camunda REST API.

```APIDOC
## Get API Version

### Description
Retrieves the version of the Camunda REST API.

### Method
GET

### Endpoint
/version

### Parameters
#### Query Parameters
- None explicitly documented for this method.

### Request Example
```python
from pycamunda.version import Get

version_api = Get("http://localhost:8080/engine-rest")
version = version_api()
print(version)
```

### Response
#### Success Response (200)
- **version** (str) - The version string of the Camunda REST API.

#### Response Example
```json
{
  "version": "7.15.0-alpha1"
}
```
```

--------------------------------

### Create Tenant

Source: https://pycamunda.readthedocs.io/en/latest/src/api/tenant.html

Creates a new tenant with a specified ID and name. This operation is fundamental for onboarding new tenants into the system.

```APIDOC
## Create Tenant

### Description
Creates a new tenant with a specified ID and name.

### Method
POST

### Endpoint
/v1/tenant

### Parameters
#### Request Body
- **id** (string) - Required - Id of the tenant.
- **name** (string) - Required - Name of the tenant.

### Response
#### Success Response (201)
- No content returned on successful creation.
```

--------------------------------

### Activity Instance API

Source: https://pycamunda.readthedocs.io/en/latest/src/api.html

API for retrieving information about activity instances and transition instances within Camunda processes.

```APIDOC
## Activity Instance API

### Description
API for retrieving information about activity instances and transition instances within Camunda processes.

### Endpoints
- TransitionInstance
- ActivityInstance
```

--------------------------------

### Execute Migration Plan

Source: https://pycamunda.readthedocs.io/en/latest/src/api/migration.html

Executes a migration plan for specified process instances. This class allows adding migration instructions and can be instantiated directly or from a migration plan.

```APIDOC
## Execute Migration Plan

### Description
Executes a migration plan for specified process instances. This class allows adding migration instructions and can be instantiated directly or from a migration plan.

### Class
`pycamunda.migration.Execute`

### Methods
#### `__init__`
- **url** (str) - Camunda Rest engine URL.
- **source_process_definition_id** (str) - Id of the source process definition for the migration.
- **target_process_definition_id** (str) - Id of the target process definition for the migration.
- **process_instance_ids** (Iterable[str]) - Process instance ids to migrate.
- **skip_custom_listeners** (bool) - Optional - Whether execution listeners should be invoked.
- **skip_io_mappings** (bool) - Optional - Whether input / output mappings should be executed.
- **async_** (bool) - Optional - Whether to run this request asynchronously.

#### `__call__`
Sends the execution request.
Returns: `Optional[pycamunda.batch.Batch]`

#### `add_instruction`
Adds an instruction to execute.
- **source_activity_ids** (Iterable[str]) - The mapped activity ids from the source process definition.
- **target_activity_ids** (Iterable[str]) - The mapped activity ids from the target process definition.
- **update_event_trigger** (bool) - Optional - Whether event triggers will be updated during migration.

#### `from_migration_plan` (classmethod)
Creates an instance of Execute using a MigrationPlan instance.
- **url** (str) - Camunda REST engine URL.
- **migration_plan** (pycamunda.migration.MigrationPlan) - The migration plan to create the Execute instance from.
- **process_instance_ids** (Iterable[str]) - Process instance ids to migrate.
- **skip_custom_listeners** (bool) - Optional - Whether execution listeners should be invoked.
- **skip_io_mappings** (bool) - Optional - Whether input / output mappings should be executed.
- **async_** (bool) - Optional - Whether to run this request asynchronously.
Returns: `pycamunda.migration.Execute` instance.
```

--------------------------------

### Get Deployment

Source: https://pycamunda.readthedocs.io/en/latest/src/api/deployment.html

Retrieves a specific deployment by its ID from the Camunda engine.

```APIDOC
## Get Deployment

### Description
Get a deployment.

### Method
GET (inferred from SDK method)

### Endpoint
{url}/deployment/{id}

### Parameters
#### Path Parameters
- **url** (string) - Required - Camunda Rest engine url.
- **id** (string) - Required - Id of the deployment.

### Response
#### Success Response (200)
- **Deployment** (object) - Details of the deployment.
```

--------------------------------

### Get Case Definition Diagram

Source: https://pycamunda.readthedocs.io/en/latest/src/api/casedef.html

Retrieves the diagram for a specific case definition.

```APIDOC
## Get Case Definition Diagram

### Description
Gets the diagram of a case definition.

### Method
GET (implied)

### Endpoint
/case-definition/{id}/diagram

### Parameters
#### Query Parameters
- **id** (string) - Optional - Id of the case definition.
- **key** (string) - Optional - Key of the case definition.

### Request Example
```python
# Example usage (actual call might differ based on library implementation)
get_diagram = GetDiagram(url='YOUR_CAMUNDA_URL')
get_diagram(id='someCaseDefinitionId')
```
```

--------------------------------

### GetList

Source: https://pycamunda.readthedocs.io/en/latest/src/api/tenant.html

Queries for a list of tenants using various filtering and sorting parameters. Supports pagination.

```APIDOC
## GetList

### Description
Query for a list of tenants using a list of parameters. The size of the result set can be retrieved by using the Count class.

### Parameters
#### Query Parameters
- **id** (str, optional) - Filter by the id of the tenant.
- **name** (str, optional) - Filter by the name of the tenant.
- **name_like** (str, optional) - Filter by a substring of the name.
- **user_member** (str, optional) - Filter for tenants where the given user is member of.
- **group_member** (str, optional) - Filter for tenants where the given group is a member of.
- **including_groups_of_user** (bool, optional) - Filter for tenants where the user or one of his groups is a member of. Can only be used with user_member parameter.
- **sort_by** (str, optional) - Sort the results by id_ or name of the tenant.
- **ascending** (bool, optional) - Sort order. Defaults to True.
- **first_result** (int, optional) - Pagination of results. Index of the first result to return.
- **max_results** (int, optional) - Pagination of results. Maximum number of results to return.

### Method
GET

### Endpoint
/tenant

### Response
#### Success Response (200 OK)
- **tenants** (List[Tenant]) - A list of tenant objects.
```

--------------------------------

### Get Case Instance

Source: https://pycamunda.readthedocs.io/en/latest/src/api/caseinst.html

Retrieves a specific case instance by its ID or other criteria.

```APIDOC
## Get Case Instance

### Description
Retrieves a case instance.

### Method
GET (implied by the class name and typical API patterns)

### Endpoint
`/case-instance/{id}` (inferred, actual endpoint depends on pycamunda implementation)

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the case instance.

#### Query Parameters
- **case_definition_id** (string) - Optional - The ID of the case definition the case instance belongs to.
- **business_key** (string) - Optional - The business key of the case instance.
- **active** (boolean) - Optional - Whether the case instance is active. Defaults to False.
- **completed** (boolean) - Optional - Whether the case instance is completed. Defaults to False.
- **tenant_id** (string) - Optional - The tenant ID of the case instance. Can be a list of tenant IDs.

### Request Example
```python
from pycamunda.caseinst import Get

get_instance = Get(url="http://localhost:8080/engine-rest", id="aCaseInstanceId")
case_instance = get_instance()
```

### Response
#### Success Response (200)
- **CaseInstance** (object) - Represents the retrieved case instance.
```

--------------------------------

### Create Deployment

Source: https://pycamunda.readthedocs.io/en/latest/src/api/deployment.html

Creates a new deployment with one or multiple resources. Supports options for duplicate filtering and deploying only changed resources.

```APIDOC
## Create Deployment

### Description
Create a deployment with one or multiple resources (e.g. bpmn diagrams).

### Method
POST (inferred from SDK method)

### Endpoint
{url}/deployment

### Parameters
#### Path Parameters
- **url** (string) - Required - Camunda Rest engine url
- **name** (string) - Required - Name of the deployment.

#### Query Parameters
- **source** (string) - Optional - Source of the deployment.
- **enable_duplicate_filtering** (boolean) - Optional - Whether to check if a deployment with the same name already exists. If one does, no new deployment is done.
- **deploy_changed_only** (boolean) - Optional - Whether to check if already deployed resources that are also contained in this deployment have changed. The ones that do not will not created again.
- **tenant_id** (string) - Optional - Id of the tenant to create the deployment for.

### Request Body
(Resources are added via `add_resource` method)

### Response
#### Success Response (200)
- **DeploymentWithDefinitions** (object) - Details of the created deployment and its definitions.
```

--------------------------------

### Get Decision Definition Diagram

Source: https://pycamunda.readthedocs.io/en/latest/src/api/decisiondef.html

Retrieves the diagram of a specific decision definition.

```APIDOC
## Get Decision Definition Diagram

### Description
Gets the diagram of a decision definition.

### Method
GET (Implied)

### Endpoint
/decision-definition/{id}/diagram

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the decision definition.

#### Query Parameters
- **key** (string) - Optional - Key of the decision definition.
- **tenant_id** (string) - Optional - Id of the tenant the decision definition belongs to.

### Response
#### Success Response (200)
- **binary** - The diagram image data.

### Request Example
```json
{
  "id": "someDecisionDefinitionId"
}
```

### Response Example
(Binary image data, e.g., SVG or PNG)
```

--------------------------------

### GetList

Source: https://pycamunda.readthedocs.io/en/latest/src/api/processinst.html

Retrieves a list of process instances based on specified filters. This method allows for comprehensive querying of process instances using parameters like IDs, keys, incident details, tenant information, and variable filters.

```APIDOC
## GetList

### Description
Retrieves a list of process instances.

### Method
GET

### Endpoint
/process-instance

### Parameters
#### Query Parameters
- **process_instance_ids** (Iterable[str]) - Optional - Filter by process instance ids.
- **business_key** (str) - Optional - Filter by business key.
- **business_key_like** (str) - Optional - Filter by a substring of the business key.
- **case_instance_id** (str) - Optional - Filter by case instance id.
- **process_definition_id** (str) - Optional - Filter by process definition id.
- **process_definition_key** (str) - Optional - Filter by process definition key.
- **process_definition_key_in** (Iterable[str]) - Optional - Filter whether the process definition key is one of multiple ones.
- **process_definition_key_not_in** (Iterable[str]) - Optional - Filter whether the process definition key is not one of multiple ones.
- **deployment_id** (str) - Optional - Filter by deployment id.
- **super_process_instance** (str) - Optional - Filter process instances that are a sub process of the provided id.
- **sub_process_instance** (str) - Optional - Filter process instances that are a super process of the provided id.
- **super_case_instance_id** (str) - Optional - Filter process instances that are a sub process of the provided case instance id.
- **sub_case_instance_id** (str) - Optional - Filter process instances that are a super process of the provided case instance id.
- **active** (bool) - Optional - Whether to include only active process instances.
- **suspended** (bool) - Optional - Whether to include only suspended process instances.
- **with_incident** (bool) - Optional - Whether to include only process instances that have incidents.
- **incident_id** (str) - Optional - Filter by incident id.
- **incident_type** (Union[str, _pycamunda.incident.IncidentType, None]) - Optional - Filter by incident type.
- **incident_message** (str) - Optional - Filter by the incident message.
- **incident_message_like** (str) - Optional - Filter by a substring the incident message.
- **tenant_id_in** (Iterable[str]) - Optional - Filter whether the tenant id is one of multiple ones.
- **without_tenant_id** (bool) - Optional - Whether to include only process instances that belong to no tenant.
- **activity_id_in** (Iterable[str]) - Optional - Filter whether the activity id is one of multiple ones.
- **root_process_instances** (bool) - Optional - Include only top level process instances.
- **leaf_process_instances** (bool) - Optional - Include only bottom level process instances.
- **process_definition_without_tenant_id_in** (bool) - Optional - Include only process instance where the process definition has no tenant id.
- **variables** (any) - Optional - TODO (add via its own method?)
- **variable_names_ignore_case** (bool) - Optional - Whether to ignore case sensitivity for variables names.
- **variable_values_ignore_case** (bool) - Optional - Whether to ignore case sensitivity for variable values.
- **sort_by** (str) - Optional - Sort the results by ‘instance_id’, ‘definition_key’, ‘definition_id’, ‘tenant_id’, ‘business_key’.
- **ascending** (bool) - Optional - Sort order.
- **first_result** (int) - Optional - Pagination of results. Index of the first result to return.
- **max_results** (int) - Optional - Pagination of results. Maximum number of results to return.

### Response
#### Success Response (200)
- **List of ProcessInstance objects**

### Response Example
```json
[
  {
    "id": "some-process-instance-id",
    "definitionId": "some-definition-id",
    "businessKey": "some-business-key",
    "caseInstanceId": null,
    "caseDefinitionId": null,
    "tenantId": null,
    "definition": {
      "id": "some-definition-id",
      "key": "some-definition-key",
      "category": "some-category",
      "name": "Some Process Name",
      "version": 1,
      "resource": "some-resource.bpmn",
      "deploymentId": "some-deployment-id",
      "description": "Some process description",
      "diagram": null,
      "suspended": false,
      "tenantId": null,
      "startable": true
    }
  }
]
```
```

--------------------------------

### Get Task

Source: https://pycamunda.readthedocs.io/en/latest/src/api/task.html

Retrieves a specific user task by its unique ID from the Camunda engine.

```APIDOC
## Get

### Description
Get an user task.

### Method
GET

### Endpoint
/engine-rest/task/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Id of the user task.

#### Query Parameters
- **url** (string) - Required - Camunda Rest engine URL.
```

--------------------------------

### GetList

Source: https://pycamunda.readthedocs.io/en/latest/src/api/deployment.html

Retrieves a list of deployments based on various filter criteria. Supports pagination and sorting.

```APIDOC
## GetList

### Description
Get a list of deployments.

### Parameters
#### Query Parameters
- **id** (string) - Optional - Filter by id.
- **name** (string) - Optional - Filter by name.
- **name_like** (string) - Optional - Filter by a substring of the name.
- **source** (string) - Optional - Filter by deployment source.
- **without_source** (boolean) - Optional - Filter deployments without source.
- **tenant_id_in** (Iterable[string]) - Optional - Filter whether the tenant id is one of multiple ones.
- **without_tenant_id** (boolean) - Optional - Whether to include only deployments that belong to no tenant.
- **include_deployments_without_tenant_id** (boolean) - Optional - Whether to include deployments that belong to no tenant.
- **after** (datetime) - Optional - Filter by the deployment date after the provided data.
- **before** (datetime) - Optional - Filter by the deployment date before the provided data.
- **sort_by** (string) - Optional - Sort the results by ‘id’, ‘name’, ‘deployment_time’ or ‘tenant_id’.
- **ascending** (boolean) - Optional - Sort order. Defaults to True.
- **first_result** (integer) - Optional - Pagination of results. Index of the first result to return.
- **max_results** (integer) - Optional - Pagination of results. Maximum number of results to return.

### Method
GET

### Endpoint
/deployment

### Request Example
```json
{
  "id": "some-deployment-id",
  "name": "my-deployment",
  "name_like": "my-",
  "source": "camunda-modeler",
  "without_source": false,
  "tenant_id_in": ["tenant1", "tenant2"],
  "without_tenant_id": false,
  "include_deployments_without_tenant_id": false,
  "after": "2023-01-01T10:00:00Z",
  "before": "2023-12-31T23:59:59Z",
  "sort_by": "deployment_time",
  "ascending": false,
  "first_result": 0,
  "max_results": 10
}
```

### Response
#### Success Response (200)
- **data** (List[Deployment]) - A list of deployment objects.

#### Response Example
```json
{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "name": "ProcessArchive1",
      "source": "camunda-modeler",
      "deploymentTime": "2023-10-27T10:00:00Z",
      "tenantId": null
    }
  ]
}
```
```

--------------------------------

### Create Task

Source: https://pycamunda.readthedocs.io/en/latest/src/api/task.html

Allows for the creation of a new user task with various optional and required fields.

```APIDOC
## Create Task

### Description
Create an user task.

### Method
POST (inferred from typical REST API patterns for creation)

### Endpoint
/task

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **id** (string) - Required - Id of the task.
- **name** (string) - Optional - Name of the task.
- **description** (string) - Optional - Description of the task.
- **assignee** (string) - Optional - The user the task is assigned to.
- **owner** (string) - Optional - The owner of the task.
- **delegation_state** (string) - Optional - The delegation state. Valid values are ‘RESOLVED’ and ‘PENDING’.
- **due** (datetime) - Optional - Due date of the task.
- **follow_up** (datetime) - Optional - Follow up date of the task.
- **priority** (integer) - Optional - Priority of the task.
- **parent_task_id** (string) - Optional - Id of the parent task in case this task is a subtask.
- **case_instance_id** (string) - Optional - Id of the case instance.
- **tenant_id** (string) - Optional - Id of the tenant.

### Request Example
```json
{
  "id": "task-id-123",
  "name": "My Task",
  "description": "This is a sample task.",
  "assignee": "user1",
  "priority": 10
}
```

### Response
#### Success Response (200)
(No specific response schema provided in source)

#### Response Example
(No specific response example provided in source)
```

--------------------------------

### UserMemberCreate

Source: https://pycamunda.readthedocs.io/en/latest/src/api/tenant.html

Create a membership between a tenant and an user.

```APIDOC
## UserMemberCreate

### Description
Create a membership between a tenant and an user.

### Parameters
#### Path Parameters
- **url** (str) - Required - Camunda Rest engine URL.
- **id** (str) - Required - Id of the tenant.
- **user_id** (str) - Required - Id of the user.

### Method
POST

### Endpoint
/tenant/{id}/members

### Request Body
(Not explicitly defined, but implied by the class constructor)

### Response
(Not explicitly defined, but the `__call__` method returns None on success)
```