Skip to content

Commit

Permalink
Merge branch 'main' into optimize-history-update
Browse files Browse the repository at this point in the history
  • Loading branch information
@christinaausley
christinaausley authored Aug 30, 2023
2 parents 2120fd9 + 4288460 commit 8182d7d
Show file tree
Hide file tree
Showing 64 changed files with 706 additions and 178 deletions.
30 changes: 16 additions & 14 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,22 +9,24 @@ This repository contains the Camunda Platform 8 documentation, which can be foun

---

[![development guidelines](./howtos/documentation-guidelines.svg)](./howtos/documentation-guidelines.md)
## For authors

[![technical writing style guide](./howtos/technical-writing-styleguide.svg)](./howtos/technical-writing-styleguide.md)
Did you know Camunda Engineers are the primary documentation authors?

[![technical writing cheatsheet](./howtos/technical-writing-cheatsheet.svg)](./howtos/technical-writing-cheatsheet.md)
- [Documentation guidelines](./howtos/documentation-guidelines.md)
- [Setup](./howtos/setup.md)
- [Redirect rules](./howtos/redirect-rules.md)
- [Features](./howtos/markdown-and-mdx-features.md)
- [Technical writing cheatsheet](./howtos/technical-writing-cheatsheet.md)
- [Technical writing style guide](./howtos/technical-writing-styleguide.md)

---

[![release-procedure](./howtos/release-procedure.svg)](./howtos/release-procedure.md)

---

[![setup](./howtos/setup.svg)](./howtos/setup.md)

[![configuration](./howtos/configuration.svg)](./howtos/configuration.md)
## For maintainers

[![versioning](./howtos/versioning.svg)](./howtos/versioning.md)
Documentation strategy and infrastructure is owned by the Developer Experience team at Camunda.

[![markdown and mdx features](./howtos/markdown-and-mdx-features.svg)](./howtos/markdown-and-mdx-features.md)
- [Setup](./howtos/setup.md)
- [Configuration](./howtos/configuration.md)
- [Redirect rules](./howtos/redirect-rules.md)
- [Features](./howtos/markdown-and-mdx-features.md)
- [Versioning](./howtos/versioning.md)
- [Release Procedure](./howtos/release-procedure.md)
33 changes: 33 additions & 0 deletions docs/apis-tools/grpc.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -944,6 +944,39 @@ Returned if:

- Retries is not greater than 0.

### `DeleteResource` RPC

#### Input `DeleteResourceRequest`

```protobuf
message DeleteResourceRequest {
// The key of the resource that should be deleted. This can either be the key
// of a process definition, or the key of a decision requirements definition.
int64 resourceKey = 1;
}
```

#### Output: `DeleteResourceResponse`

```protobuf
message DeleteResourceResponse {
}
```

#### Errors

##### GRPC_STATUS_NOT_FOUND

Returned if:

- No resource exists with the given key.

##### GRPC_STATUS_FAILED_PRECONDITION

Returned if:

- The deleted resource is a process definition, and there are running instances for this process definition.

## Technical error handling

In the documentation above, the documented errors are business logic errors.
Expand Down
35 changes: 21 additions & 14 deletions docs/apis-tools/operate-api/overview.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -101,8 +101,8 @@ curl -b cookie.txt -X POST 'http://localhost:8080/v1/process-definitions/search'
| `GET /v1/process-definitions/{key}` | Get process definition by key | |
| `GET /v1/process-definitions/{key}/xml` | Get process definition by key as XML | |
| **Process instances** | | |
| `POST /v1/process-instances/search` | Search for process instances | New field added: `processDefinitionKey` <br/><br/>**Warning**<br/>1. New fields could break deserialization, so ignore fields not used.<br/>2. The `processDefinitionKey` field will only contain data from version 8.1.8 onward |
| `GET /v1/process-instances/{key}` | Get process instance by key | New field added: `processDefinitionKey` <br/><br/>**Warning**<br/>1. New fields could break deserialization, so ignore fields not used.<br/>2. The `processDefinitionKey` field will only contain data from version 8.1.8 onward |
| `POST /v1/process-instances/search` | Search for process instances | New field added: `processDefinitionKey` <br/>New field added: `parentFlowNodeInstanceKey` <br/><br/>**Warning**<br/>1. New fields could break deserialization, so ignore fields not used.<br/>2. The `processDefinitionKey` field will only contain data from version 8.1.8 onward |
| `GET /v1/process-instances/{key}` | Get process instance by key | New field added: `processDefinitionKey` <br/>New field added: `parentFlowNodeInstanceKey` <br/><br/>**Warning**<br/>1. New fields could break deserialization, so ignore fields not used.<br/>2. The `processDefinitionKey` field will only contain data from version 8.1.8 onward |
| `DELETE /v1/process-instances/{key}` | Delete process instance _and dependent_ data by key | |
| `GET /v1/process-instances/{key}/statistics` | Get flow node statistic by process instance key | New endpoint |
| `GET /v1/process-instances/{key}/sequence-flows` | Get sequence flows of process instance by key | New endpoint |
Expand All @@ -124,7 +124,7 @@ curl -b cookie.txt -X POST 'http://localhost:8080/v1/process-definitions/search'
| `GET /v1/drd/{key}/xml` | Get decision requirements by key as XML | |
| **Decision instances** | | |
| `POST /v1/decision-instances/search` | Search for decision instances | |
| `GET /v1/decision-instances/{key}` | Get decision instances by key | The field `id` must be used here as path variable, because the `key` field is not unique for decision instances |
| `GET /v1/decision-instances/{id}` | Get decision instance by id | The field `id` must be used here as path variable, because the `key` field is not unique for decision instances |

## Search

Expand Down Expand Up @@ -354,15 +354,19 @@ Results for `process-instances`:
"bpmnProcessId": "called-process",
"startDate": "2022-03-17T11:53:41.758+0000",
"state": "ACTIVE",
"processDefinitionKey": 2251799813695996
"processDefinitionKey": 2251799813695996,
"parentKey": 4503599627370497,
"parentFlowNodeInstanceKey": 4503599627370535
},
{
"key": 2251799813699262,
"processVersion": 2,
"bpmnProcessId": "called-process",
"startDate": "2022-03-17T11:53:41.853+0000",
"state": "ACTIVE",
"processDefinitionKey": 2251799813695996
"processDefinitionKey": 2251799813695996,
"parentKey": 4503599627370497,
"parentFlowNodeInstanceKey": 4503599627370535
}
],
"sortValues": ["called-process", 2251799813699262],
Expand Down Expand Up @@ -390,7 +394,9 @@ Get the data for process instance with key `2251799813699213`:
"bpmnProcessId": "called-process",
"startDate": "2022-03-17T11:53:41.758+0000",
"state": "ACTIVE",
"processDefinitionKey": 2251799813695996
"processDefinitionKey": 2251799813695996,
"parentKey": 4503599627370497,
"parentFlowNodeInstanceKey": 4503599627370535
}
```

Expand Down Expand Up @@ -442,14 +448,15 @@ These values could be of type `string`, `number`, `boolean`, and `dateString`.

```
{
"key": <number>
"processVersion": <number>
"bpmnProcessId": <string>
"parentKey": <number>
"startDate": <dateString: yyyy-MM-dd'T'HH:mm:ss.SSSZZ>
"endDate": <dateString: yyyy-MM-dd'T'HH:mm:ss.SSSZZ>
"state": <string>
"processDefinitionKey": <number>
"key": <number>
"processVersion": <number>
"bpmnProcessId": <string>
"parentKey": <number>
"startDate": <dateString: yyyy-MM-dd'T'HH:mm:ss.SSSZZ>
"endDate": <dateString: yyyy-MM-dd'T'HH:mm:ss.SSSZZ>
"state": <string>
"processDefinitionKey": <number>
"parentFlowNodeInstanceKey": <number>
}
```

Expand Down
4 changes: 0 additions & 4 deletions docs/components/best-practices/modeling/building-flexibility-into-bpmn-models.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,10 +53,6 @@ Sometimes we need to build in flexible activities which are carried out at any p

### Escalation events

:::caution Camunda Platform 7 Only
Escalation events are [not yet supported in Camunda Platform 8](/components/modeler/bpmn/bpmn-coverage.md).
:::

Sometimes we need highly flexible means to cancel scopes or trigger additional activities from within a scope. The BPMN escalation events can be particularly useful to implement such requirements.

<div bpmn="best-practices/building-flexibility-into-bpmn-models-assets/escalation.bpmn" callouts="escalation,boundary,activity,followup" />
Expand Down
12 changes: 0 additions & 12 deletions docs/components/best-practices/modeling/creating-readable-process-models.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,10 +43,6 @@ Try to model symmetrically. Identify related splitting and joining gateways and

<div bpmn="best-practices/creating-readable-process-models-assets/modeling-symmetrically.bpmn" callouts="inclusive_gateway_splitting,inclusive_gateway_joining,exclusive_gateway_splitting,exclusive_gateway_joining" />

:::caution Camunda Platform 7 Only
Inclusive Gateways (OR) are [not yet supported in Camunda Platform 8](/components/modeler/bpmn/bpmn-coverage.md)
:::

<span className="callout">1</span>

The inclusive gateway splits the process flow into two paths which are ...
Expand Down Expand Up @@ -95,10 +91,6 @@ _Avoid very long (multi page) sequence flows_, especially when flowing against t

<div bpmn="best-practices/creating-readable-process-models-assets/avoiding-multi-page-sequence-flows.bpmn" callouts="throwing-linkevent-recourse-not-possible,catching-linkevent-recourse-not-possible" />

:::caution Camunda Platform 7 Only
Link events are [not yet supported in Camunda Platform 8](/components/modeler/bpmn/bpmn-coverage.md)
:::

<span className="callout">1</span>

You see a throwing link event here, which...
Expand All @@ -119,10 +111,6 @@ Model splitting the process flow by always using _gateway symbols_ like <img src

<div bpmn="best-practices/creating-readable-process-models-assets/explicit-gateways-instead-of-conditional-flows.bpmn" callouts="inclusive_gateway" />

:::caution Camunda Platform 7 Only
Inclusive Gateways (OR) and Conditional sequence flows are [not yet supported in Camunda Platform 8](/components/modeler/bpmn/bpmn-coverage.md)
:::

<span className="callout">1</span>

For example, you could've left out this inclusive gateway by drawing two outgoing sequence flows directly out of the preceding task **Choose menu** and attaching conditions to those sequence flows (becoming conditional sequence flows <img src="/img/bpmn-elements/conditional-flow.svg" className="inline-image" />). However, experience shows that readers understand the flow semantics of gateways better, which is why we do not make use of this possibility.
Expand Down
78 changes: 78 additions & 0 deletions docs/components/concepts/resource-deletion.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
---
id: resource-deletion
title: "Resource deletion"
description: "Use resource deletion to remove process definitions and decision requirements graphs from Camunda."
---

There are several reasons to delete resources from a cluster:

1. **It frees up storage space**, as Zeebe no longer needs to keep track of this definition in its state.
2. **It improves the overview in Operate**, as deleted processes are no longer shown in the UI.
3. **It is more secure**, as it prevents creation of process instances for a faulty process definition.

You can use resource deletion to remove resources from the Camunda Platform. There are two types of resources that can
be deleted:

1. [Process definitions](./processes.md)
2. [Decision Requirements Graphs (DRG)](../modeler/dmn/decision-requirements-graph.md)

You can delete a resource using [Operate](../../components/operate/operate-introduction.md), or by sending
the [delete resource command](/docs/apis-tools/grpc.md#deleteresource-rpc) to the Zeebe API.

## Deleting a process definition

You can delete a process definition by sending a [delete resource command](/docs/apis-tools/grpc.md#deleteresource-rpc)
and
providing the `process definition key` as the `resource key`.

It's possible to delete any version of a process instance. Once you have deleted a process definition, it no longer
exists in
Zeebe's state. As a result, it is not possible to create new process instances for this process definition. Trying
to create one will result in a `NOT_FOUND` exception. Deleting a process definition also deletes historical data.

Zeebe will **never** reuse a process version. When deleting a process definition, it keeps track of the version number.
Deploying a new process with the same id will increment the version as usual.

### Deleting the latest version

When deleting the `latest` known version of a process definition, the previous version becomes the new `latest`
version. Imagine there are three versions of a process deployed, where `Version 3` is the latest version. Deleting this
version
means:

- No more instances can be created for `Version 3`.
- Creating a new process instance of the `latest` version of this process will create a new process instance
of `Version 2`, as this version became the new `latest`.
- If `Version 2` contains any timer start event(s), they are reactivated. They are triggered according to the defined
schedule.
- If `Version 2` contains any message and/or signal start event(s), they are reactivated. Publishing a message or
broadcasting a signal causes correlation and creates a new process instance of `Version 2`.

Deleting `Version 2` before `Version 3` results in the same thing. The only difference is that `Version 1` becomes the
new `latest` instead.

### Call activities

A [call activity](/docs/components/modeler/bpmn/call-activities/call-activities.md) references a process by id. It's
possible that all process definitions for this process id are deleted. In this case, Zeebe creates an incident on the
call activity, informing you that the process cannot be not found.

### Limitations

As of now it is not possible to delete a process definition that has one or more running process instances. If you want
to delete the process definition you must first terminate/complete any running instances.

## Deleting a decision requirements graph

You can delete a decision requirements graph (DRG) by sending
a [delete resource command](/docs/apis-tools/grpc.md#deleteresource-rpc) and providing the `decision requirements key`
as the `resource key`.

Upon deleting a DRG, Zeebe also deletes decisions contained within. Trying to evaluate such a decision will result in
a `NOT_FOUND` exception. Deleting a DRG also deletes historical data.

### Business rule tasks

A [business rule task](/docs/components/modeler/bpmn/business-rule-tasks/business-rule-tasks.md) references a decision
by id. It's possible that all versions of this decision are deleted. When this happens, an incident is created on the
business rule task with the message that no decision with the given decision id is found.
Loading

0 comments on commit 8182d7d

Please sign in to comment.