From 37bf42add7cfe4cc228b0501a90fe003a04b468e Mon Sep 17 00:00:00 2001 From: christinaausley <84338309+christinaausley@users.noreply.github.com> Date: Fri, 9 Aug 2024 10:28:23 -0400 Subject: [PATCH 1/3] draft docs for web modeler api tutorial (#3910) * draft docs for web modeler api tutorial * add to sidebar schema * update with POST * update modeler docs tutorial * resolve lingering comments and backport --------- Co-authored-by: Amara Graham --- docs/apis-tools/web-modeler-api/tutorial.md | 246 ++++++++++++++++++ .../apis-tools/web-modeler-api/tutorial.md | 246 ++++++++++++++++++ 2 files changed, 492 insertions(+) create mode 100644 docs/apis-tools/web-modeler-api/tutorial.md create mode 100644 versioned_docs/version-8.5/apis-tools/web-modeler-api/tutorial.md diff --git a/docs/apis-tools/web-modeler-api/tutorial.md b/docs/apis-tools/web-modeler-api/tutorial.md new file mode 100644 index 00000000000..946f47749aa --- /dev/null +++ b/docs/apis-tools/web-modeler-api/tutorial.md @@ -0,0 +1,246 @@ +--- +id: modeler-api-tutorial +title: Tutorial +sidebar_position: 3 +slug: /apis-tools/web-modeler-api/tutorial +description: "Step through an example to create a new project, add a collaborator, view project details, and delete a project using the Web Modeler API." +--- + +In this tutorial, we'll step through examples to highlight the capabilities of the Web Modeler API, such as creating a new project, adding a collaborator to a project, viewing the details of a project, and deleting a project. + +## Prerequisites + +- Create your first client by navigating to **Console > Organization > Administration API > Create new credentials**. Ensure you determine the scoped access for client credentials. For example, in this tutorial we will create a project, add a collaborator, and delete a project. Ensure you check the box for the Web Modeler scope. + +:::note +Make sure you keep the generated client credentials in a safe place. The **Client secret** will not be shown again. For your convenience, you can also download the client information to your computer. +::: + +- In this tutorial, we utilize a JavaScript-written [GitHub repository](https://github.com/camunda/camunda-api-tutorials) to write and run requests. Clone this repo before getting started. +- Ensure you have [Node.js](https://nodejs.org/en/download) installed as this will be used for methods that can be called by the CLI (outlined later in this guide). Run `npm install` to ensure you have updated dependencies. + +## Getting started + +- A detailed API description can be found [here](https://modeler.cloud.camunda.io/swagger-ui/index.html) via Swagger. With a valid access token, this offers an interactive API experience against your Camunda 8 cluster. +- You need authentication to access the API endpoints. Find more information [here](/apis-tools/web-modeler-api/authentication.md). + +## Set up authentication + +If you're interested in how we use a library to handle auth for our code, or to get started, examine the `auth.js` file in the GitHub repository. This file contains a function named `getAccessToken` which executes an OAuth 2.0 protocol to retrieve authentication credentials based on your client id and client secret. Then, we return the actual token that can be passed as an authorization header in each request. + +To set up your credentials, create an `.env` file which will be protected by the `.gitignore` file. You will need to add your `MODELER_CLIENT_ID`, `MODELER_CLIENT_SECRET`, `MODELER_AUDIENCE`, which is `modeler.cloud.camunda.io` in a Camunda 8 SaaS environment, and `MODELER_BASE_URL`, which is `https://modeler.camunda.io/api/v1`. + +These keys will be consumed by the `auth.js` file to execute the OAuth protocol, and should be saved when you generate your client credentials in [prerequisites](#prerequisites). + +Examine the existing `.env.example` file for an example of how your `.env` file should look upon completion. Do not place your credentials in the `.env.example` file, as this example file is not protected by the `.gitignore`. + +:::note + +In this tutorial, we will execute arguments to create a project, add a collaborator, and delete a project. You can examine the framework for processing these arguments in the `cli.js` file before getting started. + +::: + +## Create a new project (POST) and add a collaborator (PUT) + +First, let's script an API call to create a new project. + +To do this, take the following steps: + +1. In the file named `modeler.js`, outline the authentication and authorization configuration in the first few lines. This will pull in your `.env` variables to obtain an access token before making any API calls: + +```javascript +const authorizationConfiguration = { + clientId: process.env.MODELER_CLIENT_ID, + clientSecret: process.env.MODELER_CLIENT_SECRET, + audience: process.env.MODELER_AUDIENCE, +}; +``` + +2. Examine the function `async function createProject([projectName, adminEmail])` below this configuration. This is where you will script out your API call, defining a project name and the project administrator's email. +3. Within the function, you must first generate an access token for this request, so your function should now look like the following: + +```javascript +async function createProject([projectName, adminEmail]) { + const accessToken = await getAccessToken(authorizationConfiguration); +} +``` + +4. Using your generated client credentials from [prerequisites](#prerequisites), capture your Web Modeler base URL beneath your call for an access token by defining `modelerApiUrl`: + +```javascript +const modelerApiUrl = process.env.MODELER_BASE_URL; +``` + +5. On the next line, script the API endpoint to create your project: + +```javascript +const projectUrl = `${modelerApiUrl}/projects`; +``` + +6. Configure your POST request to the appropriate endpoint, including an authorization header based on the previously acquired `accessToken`. You will also add a body to outline information about the new project: + +```javascript +const projectOptions = { + method: "POST", + url: projectUrl, + headers: { + Accept: "application/json", + Authorization: `Bearer ${accessToken}`, + }, + data: { + name: projectName, + }, +}; +``` + +7. Call the add project endpoint and capture the data for the new project: + +```javascript + try { + const response = await axios(projectOptions); + + const newProject = response.data; + + console.log( + `Project added! Name: ${newProject.name}. ID: ${newProject.id}.` + ); +``` + +8. Next, we'll add a collaborator to the project you just created. After calling the add project endpoint, add an endpoint to add a collaborator to the project: + +```javascript +const collaboratorUrl = `${modelerApiUrl}/collaborators`; +``` + +9. Configure the API call, including a body with information about the project and the new collaborator: + +```javascript + const collaboratorOptions = { + method: "PUT", + url: collaboratorUrl, + headers: { + Accept: "application/json", + Authorization: `Bearer ${accessToken}` + }, + data: { + email: adminEmail, + projectId: newProject.id, + role: "project_admin" + } +``` + +10. Call the add collaborator endpoint and process the results: + +```javascript + const collaboratorResponse = await axios(collaboratorOptions); + + if (collaboratorResponse.status === 204) { + console.log(`Collaborator added! Email: ${adminEmail}.`); + } else { + console.error("Unable to add collaborator!"); + } + } catch (error) { + // Emit an error from the server. + console.error(error.message); + } +``` + +11. In your terminal, run `npm run cli modeler create` to create your project. + +:::note +This `create` command is connected to the `createProject` function at the bottom of the `modeler.js` file, and executed by the `cli.js` file. While we create a project in this tutorial, you may add additional arguments depending on the API calls you would like to make. +::: + +## View project details (GET) + +To view project details, take the following steps: + +1. Outline your function, similar to the steps above: + +```javascript +async function viewProject([projectId]) { + const accessToken = await getAccessToken(authorizationConfiguration); + const modelerApiUrl = process.env.MODELER_BASE_URL; + const url = `${modelerApiUrl}/projects/${projectId}`; +} +``` + +2. Configure the API call using the GET method: + +```javascript +const options = { + method: "GET", + url, + headers: { + Accept: "application/json", + Authorization: `Bearer ${accessToken}`, + }, +}; +``` + +3. Process the results from the API call. For example: + +```javascript +try { + const response = await axios(options); + const project = response.data; + + console.log("Project:", project); +} catch (error) { + console.error(error.message); +} +``` + +4. In your terminal, run `npm run cli modeler view `, where `` is the ID output by the command to create a project. + +## Delete a project + +To delete a project, take the following steps: + +1. Outline your function, similar to the steps above: + +```javascript +async function deleteProject([projectId]) { + const accessToken = await getAccessToken(authorizationConfiguration); + const modelerApiUrl = process.env.MODELER_BASE_URL; + const url = `${modelerApiUrl}/projects/${projectId}`; +``` + +2. Configure the API call using the DELETE method: + +```javascript +const options = { + method: "DELETE", + url, + headers: { + Accept: "application/json", + Authorization: `Bearer ${accessToken}`, + }, +}; +``` + +3. Process the results from the API call. For example: + +```javascript +try { + const response = await axios(options); + + if (response.status === 204) { + console.log(`Project ${projectId} was deleted!`); + } else { + console.error("Unable to delete project!"); + } +} catch (error) { + console.error(error.message); +} +``` + +4. In your terminal, run `npm run cli modeler delete `, where `` is the ID output by the command to create a project. + +## If you get stuck + +Having trouble configuring your API calls or want to examine an example of the completed tutorial? Navigate to the `completed` folder in the [GitHub repository](https://github.com/camunda/camunda-api-tutorials/tree/main/completed), where you can view an example `modeler.js` file. + +## Next steps + +You can script several additional API calls as outlined in the [Web Modeler API reference material](/apis-tools/web-modeler-api/index.md). diff --git a/versioned_docs/version-8.5/apis-tools/web-modeler-api/tutorial.md b/versioned_docs/version-8.5/apis-tools/web-modeler-api/tutorial.md new file mode 100644 index 00000000000..946f47749aa --- /dev/null +++ b/versioned_docs/version-8.5/apis-tools/web-modeler-api/tutorial.md @@ -0,0 +1,246 @@ +--- +id: modeler-api-tutorial +title: Tutorial +sidebar_position: 3 +slug: /apis-tools/web-modeler-api/tutorial +description: "Step through an example to create a new project, add a collaborator, view project details, and delete a project using the Web Modeler API." +--- + +In this tutorial, we'll step through examples to highlight the capabilities of the Web Modeler API, such as creating a new project, adding a collaborator to a project, viewing the details of a project, and deleting a project. + +## Prerequisites + +- Create your first client by navigating to **Console > Organization > Administration API > Create new credentials**. Ensure you determine the scoped access for client credentials. For example, in this tutorial we will create a project, add a collaborator, and delete a project. Ensure you check the box for the Web Modeler scope. + +:::note +Make sure you keep the generated client credentials in a safe place. The **Client secret** will not be shown again. For your convenience, you can also download the client information to your computer. +::: + +- In this tutorial, we utilize a JavaScript-written [GitHub repository](https://github.com/camunda/camunda-api-tutorials) to write and run requests. Clone this repo before getting started. +- Ensure you have [Node.js](https://nodejs.org/en/download) installed as this will be used for methods that can be called by the CLI (outlined later in this guide). Run `npm install` to ensure you have updated dependencies. + +## Getting started + +- A detailed API description can be found [here](https://modeler.cloud.camunda.io/swagger-ui/index.html) via Swagger. With a valid access token, this offers an interactive API experience against your Camunda 8 cluster. +- You need authentication to access the API endpoints. Find more information [here](/apis-tools/web-modeler-api/authentication.md). + +## Set up authentication + +If you're interested in how we use a library to handle auth for our code, or to get started, examine the `auth.js` file in the GitHub repository. This file contains a function named `getAccessToken` which executes an OAuth 2.0 protocol to retrieve authentication credentials based on your client id and client secret. Then, we return the actual token that can be passed as an authorization header in each request. + +To set up your credentials, create an `.env` file which will be protected by the `.gitignore` file. You will need to add your `MODELER_CLIENT_ID`, `MODELER_CLIENT_SECRET`, `MODELER_AUDIENCE`, which is `modeler.cloud.camunda.io` in a Camunda 8 SaaS environment, and `MODELER_BASE_URL`, which is `https://modeler.camunda.io/api/v1`. + +These keys will be consumed by the `auth.js` file to execute the OAuth protocol, and should be saved when you generate your client credentials in [prerequisites](#prerequisites). + +Examine the existing `.env.example` file for an example of how your `.env` file should look upon completion. Do not place your credentials in the `.env.example` file, as this example file is not protected by the `.gitignore`. + +:::note + +In this tutorial, we will execute arguments to create a project, add a collaborator, and delete a project. You can examine the framework for processing these arguments in the `cli.js` file before getting started. + +::: + +## Create a new project (POST) and add a collaborator (PUT) + +First, let's script an API call to create a new project. + +To do this, take the following steps: + +1. In the file named `modeler.js`, outline the authentication and authorization configuration in the first few lines. This will pull in your `.env` variables to obtain an access token before making any API calls: + +```javascript +const authorizationConfiguration = { + clientId: process.env.MODELER_CLIENT_ID, + clientSecret: process.env.MODELER_CLIENT_SECRET, + audience: process.env.MODELER_AUDIENCE, +}; +``` + +2. Examine the function `async function createProject([projectName, adminEmail])` below this configuration. This is where you will script out your API call, defining a project name and the project administrator's email. +3. Within the function, you must first generate an access token for this request, so your function should now look like the following: + +```javascript +async function createProject([projectName, adminEmail]) { + const accessToken = await getAccessToken(authorizationConfiguration); +} +``` + +4. Using your generated client credentials from [prerequisites](#prerequisites), capture your Web Modeler base URL beneath your call for an access token by defining `modelerApiUrl`: + +```javascript +const modelerApiUrl = process.env.MODELER_BASE_URL; +``` + +5. On the next line, script the API endpoint to create your project: + +```javascript +const projectUrl = `${modelerApiUrl}/projects`; +``` + +6. Configure your POST request to the appropriate endpoint, including an authorization header based on the previously acquired `accessToken`. You will also add a body to outline information about the new project: + +```javascript +const projectOptions = { + method: "POST", + url: projectUrl, + headers: { + Accept: "application/json", + Authorization: `Bearer ${accessToken}`, + }, + data: { + name: projectName, + }, +}; +``` + +7. Call the add project endpoint and capture the data for the new project: + +```javascript + try { + const response = await axios(projectOptions); + + const newProject = response.data; + + console.log( + `Project added! Name: ${newProject.name}. ID: ${newProject.id}.` + ); +``` + +8. Next, we'll add a collaborator to the project you just created. After calling the add project endpoint, add an endpoint to add a collaborator to the project: + +```javascript +const collaboratorUrl = `${modelerApiUrl}/collaborators`; +``` + +9. Configure the API call, including a body with information about the project and the new collaborator: + +```javascript + const collaboratorOptions = { + method: "PUT", + url: collaboratorUrl, + headers: { + Accept: "application/json", + Authorization: `Bearer ${accessToken}` + }, + data: { + email: adminEmail, + projectId: newProject.id, + role: "project_admin" + } +``` + +10. Call the add collaborator endpoint and process the results: + +```javascript + const collaboratorResponse = await axios(collaboratorOptions); + + if (collaboratorResponse.status === 204) { + console.log(`Collaborator added! Email: ${adminEmail}.`); + } else { + console.error("Unable to add collaborator!"); + } + } catch (error) { + // Emit an error from the server. + console.error(error.message); + } +``` + +11. In your terminal, run `npm run cli modeler create` to create your project. + +:::note +This `create` command is connected to the `createProject` function at the bottom of the `modeler.js` file, and executed by the `cli.js` file. While we create a project in this tutorial, you may add additional arguments depending on the API calls you would like to make. +::: + +## View project details (GET) + +To view project details, take the following steps: + +1. Outline your function, similar to the steps above: + +```javascript +async function viewProject([projectId]) { + const accessToken = await getAccessToken(authorizationConfiguration); + const modelerApiUrl = process.env.MODELER_BASE_URL; + const url = `${modelerApiUrl}/projects/${projectId}`; +} +``` + +2. Configure the API call using the GET method: + +```javascript +const options = { + method: "GET", + url, + headers: { + Accept: "application/json", + Authorization: `Bearer ${accessToken}`, + }, +}; +``` + +3. Process the results from the API call. For example: + +```javascript +try { + const response = await axios(options); + const project = response.data; + + console.log("Project:", project); +} catch (error) { + console.error(error.message); +} +``` + +4. In your terminal, run `npm run cli modeler view `, where `` is the ID output by the command to create a project. + +## Delete a project + +To delete a project, take the following steps: + +1. Outline your function, similar to the steps above: + +```javascript +async function deleteProject([projectId]) { + const accessToken = await getAccessToken(authorizationConfiguration); + const modelerApiUrl = process.env.MODELER_BASE_URL; + const url = `${modelerApiUrl}/projects/${projectId}`; +``` + +2. Configure the API call using the DELETE method: + +```javascript +const options = { + method: "DELETE", + url, + headers: { + Accept: "application/json", + Authorization: `Bearer ${accessToken}`, + }, +}; +``` + +3. Process the results from the API call. For example: + +```javascript +try { + const response = await axios(options); + + if (response.status === 204) { + console.log(`Project ${projectId} was deleted!`); + } else { + console.error("Unable to delete project!"); + } +} catch (error) { + console.error(error.message); +} +``` + +4. In your terminal, run `npm run cli modeler delete `, where `` is the ID output by the command to create a project. + +## If you get stuck + +Having trouble configuring your API calls or want to examine an example of the completed tutorial? Navigate to the `completed` folder in the [GitHub repository](https://github.com/camunda/camunda-api-tutorials/tree/main/completed), where you can view an example `modeler.js` file. + +## Next steps + +You can script several additional API calls as outlined in the [Web Modeler API reference material](/apis-tools/web-modeler-api/index.md). From cb5d00b636ad2e8a926c3ebf19c0504a9c09674c Mon Sep 17 00:00:00 2001 From: christinaausley <84338309+christinaausley@users.noreply.github.com> Date: Fri, 9 Aug 2024 10:46:49 -0400 Subject: [PATCH 2/3] zeebe api tutorial (#4058) * zeebe api tutorial * Update docs/apis-tools/zeebe-api-rest/tutorial.md Co-authored-by: Steven Hicks * Update docs/apis-tools/zeebe-api-rest/tutorial.md Co-authored-by: Steven Hicks * resolve lingering comments and backport --------- Co-authored-by: Steven Hicks --- .../zeebe-api-rest/sidebar-schema.js | 1 + docs/apis-tools/zeebe-api-rest/tutorial.md | 182 ++++++++++++++++++ .../zeebe-api-rest/sidebar-schema.js | 1 + .../apis-tools/zeebe-api-rest/tutorial.md | 182 ++++++++++++++++++ 4 files changed, 366 insertions(+) create mode 100644 docs/apis-tools/zeebe-api-rest/tutorial.md create mode 100644 versioned_docs/version-8.5/apis-tools/zeebe-api-rest/tutorial.md diff --git a/docs/apis-tools/zeebe-api-rest/sidebar-schema.js b/docs/apis-tools/zeebe-api-rest/sidebar-schema.js index 2b8a3446bc4..af9f3d63522 100644 --- a/docs/apis-tools/zeebe-api-rest/sidebar-schema.js +++ b/docs/apis-tools/zeebe-api-rest/sidebar-schema.js @@ -4,6 +4,7 @@ module.exports = { "Zeebe API (REST)": [ "apis-tools/zeebe-api-rest/zeebe-api-rest-overview", "apis-tools/zeebe-api-rest/zeebe-api-rest-authentication", + "apis-tools/zeebe-api-rest/zeebe-api-tutorial", { Specifications: require("./specifications/sidebar.js"), }, diff --git a/docs/apis-tools/zeebe-api-rest/tutorial.md b/docs/apis-tools/zeebe-api-rest/tutorial.md new file mode 100644 index 00000000000..ec299cbe3a6 --- /dev/null +++ b/docs/apis-tools/zeebe-api-rest/tutorial.md @@ -0,0 +1,182 @@ +--- +id: zeebe-api-tutorial +title: Tutorial +description: "New to the Zeebe API? Step through our tutorial to assign and unassign a user to and from a Zeebe user task." +--- + +In this tutorial, we'll step through examples to highlight the capabilities of the Zeebe API, such as assigning and unassigning a user to and from a Zeebe user task. + +## Prerequisites + +- If you haven't done so already, [create a cluster](/guides/create-cluster.md). +- Upon cluster creation, [create your first client](/guides/setup-client-connection-credentials.md). Ensure you check the `Zeebe` client scope box. + +:::note +Make sure you keep the generated client credentials in a safe place. The **Client secret** will not be shown again. For your convenience, you can also download the client information to your computer. +::: + +- In this tutorial, we utilize a JavaScript-written [GitHub repository](https://github.com/camunda/camunda-api-tutorials) to write and run requests. Clone this repo before getting started. +- Ensure you have [Node.js](https://nodejs.org/en/download) installed as this will be used for methods that can be called by the CLI (outlined later in this guide). Run `npm install` to ensure you have updated dependencies. + +## Getting started + +- You need authentication to access the API endpoints. Find more information [here](./zeebe-api-rest-authentication.md). + +## Set up authentication + +If you're interested in how we use a library to handle auth for our code, or to get started, examine the `auth.js` file in the GitHub repository. This file contains a function named `getAccessToken` which executes an OAuth 2.0 protocol to retrieve authentication credentials based on your client id and client secret. Then, we return the actual token that can be passed as an authorization header in each request. + +To set up your credentials, create an `.env` file which will be protected by the `.gitignore` file. You will need to add your `ZEEBE_CLIENT_ID`, `ZEEBE_CLIENT_SECRET`, `ZEEBE_BASE_URL`, and `ZEEBE_AUDIENCE`, which is `zeebe.camunda.io` in a Camunda 8 SaaS environment. For example, your audience may be defined as `ZEEBE_AUDIENCE=zeebe.camunda.io`. + +These keys will be consumed by the `auth.js` file to execute the OAuth protocol, and should be saved when you generate your client credentials in [prerequisites](#prerequisites). + +Examine the existing `.env.example` file for an example of how your `.env` file should look upon completion. Do not place your credentials in the `.env.example` file, as this example file is not protected by the `.gitignore`. + +:::note + +In this tutorial, we will execute arguments to assign and unassign a user to and from a Zeebe user task. You can examine the framework for processing these arguments in the `cli.js` file before getting started. + +::: + +## Assign a Zeebe user task (POST) + +:::note +In this tutorial, you will capture a **Zeebe user task** ID to assign and unassign users in this API. Camunda 8.5 introduced this new [user task](/components/modeler/bpmn/user-tasks/user-tasks.md) implementation type, and these Zeebe user tasks are different from job worker-based user tasks. See more details on task type differences in the [migrating to Zeebe user tasks documentation](/apis-tools/tasklist-api-rest/migrate-to-zeebe-user-tasks.md#task-type-differences). +::: + +First, let's script an API call to assign a Zeebe user task. + +To do this, take the following steps: + +1. In the file named `zeebe.js`, outline the authentication and authorization configuration in the first few lines. This will pull in your `.env` variables to obtain an access token before making any API calls: + +```javascript +const authorizationConfiguration = { + clientId: process.env.ZEEBE_CLIENT_ID, + clientSecret: process.env.ZEEBE_CLIENT_SECRET, + audience: process.env.ZEEBE_AUDIENCE, +}; +``` + +2. Examine the function `async function assignUser([userTaskKey, assignee])` below this configuration. This is where you will script out your API call. +3. Within the function, you must first generate an access token for this request, so your function should now look like the following: + +```javascript +async function assignUser([userTaskKey, assignee]) { + const accessToken = await getAccessToken(authorizationConfiguration); +} +``` + +4. Using your generated client credentials from [prerequisites](#prerequisites), capture your Zeebe API URL beneath your call for an access token by defining `zeebeApiUrl`: + +`const zeebeApiUrl = process.env.ZEEBE_BASE_URL` + +5. On the next line, script the API endpoint to assign a Zeebe user task.: + +```javascript +const url = `${ZeebeApiUrl}/user-tasks/${userTaskKey}/assignment`; +``` + +6. Configure your POST request to the appropriate endpoint, including an authorization header based on the previously acquired `accessToken`: + +```javascript +const options = { + method: "POST", + url, + headers: { + Accept: "application/json", + Authorization: `Bearer ${accessToken}`, + }, + data: { + // The body contains information about the new assignment. + assignee: assignee, + }, +}; +``` + +7. Call the assign endpoint, process the results from the API call, and emit an error message from the server if necessary: + +```javascript +try { + // Call the assign endpoint. + const response = await axios(options); + + // Process the results from the API call. + if (response.status === 204) { + console.log(`User task assigned to ${assignee}.`); + } else { + // Emit an unexpected error message. + console.error("Unable to assign this user!"); + } +} catch (error) { + // Emit an error from the server. + console.error(error.message); +} +``` + +8. In your terminal, run `node cli.js zeebe assign `, where `` is the Zeebe user task ID you've captured from Tasklist, and `` is the assignee's email address. Include your own email address if you would like to see these results in your user interface. + +:::note +This `assign` command is connected to the `assignUser` function at the bottom of the `zeebe.js` file, and executed by the `cli.js` file. While we will assign and unassign users in this tutorial, you may add additional arguments depending on the API calls you would like to make. +::: + +If you have a valid user and task ID, the assignment will now output. If you have an invalid API name or action name, or no arguments provided, or improper/insufficient credentials configured, an error message will output as outlined in the `cli.js` file. If no action is provided, it will default to "assign" everywhere, except when unassigning a user. + +## Unassign a Zeebe user task (DELETE) + +To unassign a user from a Zeebe user task, you can use the same Zeebe user task ID from the previous exercise and take the following steps: + +1. Outline your function, similar to the steps above: + +```javascript +async function unassignUser([userTaskKey]) { + const accessToken = await getAccessToken(authorizationConfiguration); + + const ZeebeApiUrl = process.env.ZEEBE_BASE_URL; + + const url = `${ZeebeApiUrl}/user-tasks/${userTaskKey}/assignee`; +} +``` + +2. Configure the API call using the DELETE method: + +```javascript +const options = { + method: "DELETE", + url, + headers: { + Accept: "application/json", + Authorization: `Bearer ${accessToken}`, + }, +}; +``` + +3. Process the results from the API call. For example: + +```javascript +try { + // Call the delete endpoint. + const response = await axios(options); + + // Process the results from the API call. + if (response.status === 204) { + console.log("User task has been unassigned!"); + } else { + // Emit an unexpected error message. + console.error("Unable to unassign this user task!"); + } +} catch (error) { + // Emit an error from the server. + console.error(error.message); +} +``` + +4. In your terminal, run `node cli.js zeebe unassign `, where `` is the Zeebe user task ID. + +## If you get stuck + +Having trouble configuring your API calls or want to examine an example of the completed tutorial? Navigate to the `completed` folder in the [GitHub repository](https://github.com/camunda/camunda-api-tutorials/tree/main/completed), where you can view an example `zeebe.js` file. + +## Next steps + +You can script several additional API calls as outlined in the [Zeebe API reference material](./zeebe-api-rest-overview.md). diff --git a/versioned_docs/version-8.5/apis-tools/zeebe-api-rest/sidebar-schema.js b/versioned_docs/version-8.5/apis-tools/zeebe-api-rest/sidebar-schema.js index 2b8a3446bc4..af9f3d63522 100644 --- a/versioned_docs/version-8.5/apis-tools/zeebe-api-rest/sidebar-schema.js +++ b/versioned_docs/version-8.5/apis-tools/zeebe-api-rest/sidebar-schema.js @@ -4,6 +4,7 @@ module.exports = { "Zeebe API (REST)": [ "apis-tools/zeebe-api-rest/zeebe-api-rest-overview", "apis-tools/zeebe-api-rest/zeebe-api-rest-authentication", + "apis-tools/zeebe-api-rest/zeebe-api-tutorial", { Specifications: require("./specifications/sidebar.js"), }, diff --git a/versioned_docs/version-8.5/apis-tools/zeebe-api-rest/tutorial.md b/versioned_docs/version-8.5/apis-tools/zeebe-api-rest/tutorial.md new file mode 100644 index 00000000000..ec299cbe3a6 --- /dev/null +++ b/versioned_docs/version-8.5/apis-tools/zeebe-api-rest/tutorial.md @@ -0,0 +1,182 @@ +--- +id: zeebe-api-tutorial +title: Tutorial +description: "New to the Zeebe API? Step through our tutorial to assign and unassign a user to and from a Zeebe user task." +--- + +In this tutorial, we'll step through examples to highlight the capabilities of the Zeebe API, such as assigning and unassigning a user to and from a Zeebe user task. + +## Prerequisites + +- If you haven't done so already, [create a cluster](/guides/create-cluster.md). +- Upon cluster creation, [create your first client](/guides/setup-client-connection-credentials.md). Ensure you check the `Zeebe` client scope box. + +:::note +Make sure you keep the generated client credentials in a safe place. The **Client secret** will not be shown again. For your convenience, you can also download the client information to your computer. +::: + +- In this tutorial, we utilize a JavaScript-written [GitHub repository](https://github.com/camunda/camunda-api-tutorials) to write and run requests. Clone this repo before getting started. +- Ensure you have [Node.js](https://nodejs.org/en/download) installed as this will be used for methods that can be called by the CLI (outlined later in this guide). Run `npm install` to ensure you have updated dependencies. + +## Getting started + +- You need authentication to access the API endpoints. Find more information [here](./zeebe-api-rest-authentication.md). + +## Set up authentication + +If you're interested in how we use a library to handle auth for our code, or to get started, examine the `auth.js` file in the GitHub repository. This file contains a function named `getAccessToken` which executes an OAuth 2.0 protocol to retrieve authentication credentials based on your client id and client secret. Then, we return the actual token that can be passed as an authorization header in each request. + +To set up your credentials, create an `.env` file which will be protected by the `.gitignore` file. You will need to add your `ZEEBE_CLIENT_ID`, `ZEEBE_CLIENT_SECRET`, `ZEEBE_BASE_URL`, and `ZEEBE_AUDIENCE`, which is `zeebe.camunda.io` in a Camunda 8 SaaS environment. For example, your audience may be defined as `ZEEBE_AUDIENCE=zeebe.camunda.io`. + +These keys will be consumed by the `auth.js` file to execute the OAuth protocol, and should be saved when you generate your client credentials in [prerequisites](#prerequisites). + +Examine the existing `.env.example` file for an example of how your `.env` file should look upon completion. Do not place your credentials in the `.env.example` file, as this example file is not protected by the `.gitignore`. + +:::note + +In this tutorial, we will execute arguments to assign and unassign a user to and from a Zeebe user task. You can examine the framework for processing these arguments in the `cli.js` file before getting started. + +::: + +## Assign a Zeebe user task (POST) + +:::note +In this tutorial, you will capture a **Zeebe user task** ID to assign and unassign users in this API. Camunda 8.5 introduced this new [user task](/components/modeler/bpmn/user-tasks/user-tasks.md) implementation type, and these Zeebe user tasks are different from job worker-based user tasks. See more details on task type differences in the [migrating to Zeebe user tasks documentation](/apis-tools/tasklist-api-rest/migrate-to-zeebe-user-tasks.md#task-type-differences). +::: + +First, let's script an API call to assign a Zeebe user task. + +To do this, take the following steps: + +1. In the file named `zeebe.js`, outline the authentication and authorization configuration in the first few lines. This will pull in your `.env` variables to obtain an access token before making any API calls: + +```javascript +const authorizationConfiguration = { + clientId: process.env.ZEEBE_CLIENT_ID, + clientSecret: process.env.ZEEBE_CLIENT_SECRET, + audience: process.env.ZEEBE_AUDIENCE, +}; +``` + +2. Examine the function `async function assignUser([userTaskKey, assignee])` below this configuration. This is where you will script out your API call. +3. Within the function, you must first generate an access token for this request, so your function should now look like the following: + +```javascript +async function assignUser([userTaskKey, assignee]) { + const accessToken = await getAccessToken(authorizationConfiguration); +} +``` + +4. Using your generated client credentials from [prerequisites](#prerequisites), capture your Zeebe API URL beneath your call for an access token by defining `zeebeApiUrl`: + +`const zeebeApiUrl = process.env.ZEEBE_BASE_URL` + +5. On the next line, script the API endpoint to assign a Zeebe user task.: + +```javascript +const url = `${ZeebeApiUrl}/user-tasks/${userTaskKey}/assignment`; +``` + +6. Configure your POST request to the appropriate endpoint, including an authorization header based on the previously acquired `accessToken`: + +```javascript +const options = { + method: "POST", + url, + headers: { + Accept: "application/json", + Authorization: `Bearer ${accessToken}`, + }, + data: { + // The body contains information about the new assignment. + assignee: assignee, + }, +}; +``` + +7. Call the assign endpoint, process the results from the API call, and emit an error message from the server if necessary: + +```javascript +try { + // Call the assign endpoint. + const response = await axios(options); + + // Process the results from the API call. + if (response.status === 204) { + console.log(`User task assigned to ${assignee}.`); + } else { + // Emit an unexpected error message. + console.error("Unable to assign this user!"); + } +} catch (error) { + // Emit an error from the server. + console.error(error.message); +} +``` + +8. In your terminal, run `node cli.js zeebe assign `, where `` is the Zeebe user task ID you've captured from Tasklist, and `` is the assignee's email address. Include your own email address if you would like to see these results in your user interface. + +:::note +This `assign` command is connected to the `assignUser` function at the bottom of the `zeebe.js` file, and executed by the `cli.js` file. While we will assign and unassign users in this tutorial, you may add additional arguments depending on the API calls you would like to make. +::: + +If you have a valid user and task ID, the assignment will now output. If you have an invalid API name or action name, or no arguments provided, or improper/insufficient credentials configured, an error message will output as outlined in the `cli.js` file. If no action is provided, it will default to "assign" everywhere, except when unassigning a user. + +## Unassign a Zeebe user task (DELETE) + +To unassign a user from a Zeebe user task, you can use the same Zeebe user task ID from the previous exercise and take the following steps: + +1. Outline your function, similar to the steps above: + +```javascript +async function unassignUser([userTaskKey]) { + const accessToken = await getAccessToken(authorizationConfiguration); + + const ZeebeApiUrl = process.env.ZEEBE_BASE_URL; + + const url = `${ZeebeApiUrl}/user-tasks/${userTaskKey}/assignee`; +} +``` + +2. Configure the API call using the DELETE method: + +```javascript +const options = { + method: "DELETE", + url, + headers: { + Accept: "application/json", + Authorization: `Bearer ${accessToken}`, + }, +}; +``` + +3. Process the results from the API call. For example: + +```javascript +try { + // Call the delete endpoint. + const response = await axios(options); + + // Process the results from the API call. + if (response.status === 204) { + console.log("User task has been unassigned!"); + } else { + // Emit an unexpected error message. + console.error("Unable to unassign this user task!"); + } +} catch (error) { + // Emit an error from the server. + console.error(error.message); +} +``` + +4. In your terminal, run `node cli.js zeebe unassign `, where `` is the Zeebe user task ID. + +## If you get stuck + +Having trouble configuring your API calls or want to examine an example of the completed tutorial? Navigate to the `completed` folder in the [GitHub repository](https://github.com/camunda/camunda-api-tutorials/tree/main/completed), where you can view an example `zeebe.js` file. + +## Next steps + +You can script several additional API calls as outlined in the [Zeebe API reference material](./zeebe-api-rest-overview.md). From 8d1058143fa5a54cfad937adb298aff377d5509a Mon Sep 17 00:00:00 2001 From: Jan Friedenstab <8794084+jfriedenstab@users.noreply.github.com> Date: Fri, 9 Aug 2024 18:40:48 +0200 Subject: [PATCH 3/3] docs(bpmn): explain binding types for call activities, business rule tasks, and user tasks (#4132) --- .../choosing-the-resource-binding-type.md | 33 +++++++++++++++++++ .../business-rule-tasks.md | 17 ++++++++-- .../bpmn/call-activities/call-activities.md | 19 ++++++++--- .../modeler/bpmn/user-tasks/user-tasks.md | 18 ++++++++-- .../adjusting-bpmn-models.md | 21 +++++++++--- optimize_sidebars.js | 4 +++ sidebars.js | 1 + 7 files changed, 99 insertions(+), 14 deletions(-) create mode 100644 docs/components/best-practices/modeling/choosing-the-resource-binding-type.md diff --git a/docs/components/best-practices/modeling/choosing-the-resource-binding-type.md b/docs/components/best-practices/modeling/choosing-the-resource-binding-type.md new file mode 100644 index 00000000000..cce41816b8b --- /dev/null +++ b/docs/components/best-practices/modeling/choosing-the-resource-binding-type.md @@ -0,0 +1,33 @@ +--- +title: Choosing the resource binding type +tags: + - BPMN +description: "Choose the resource binding type and understand the differences between 'latest' and 'deployment' binding for linked resources." +--- + +Camunda 8 offers version binding for linked processes, decisions, or forms. This allows you to deploy new versions without disrupting live processes, and prevents production outages. + +You can choose the binding type for the linked target resource for the following BPMN process elements: + +- [Call activities](/docs/components/modeler/bpmn/call-activities/call-activities.md#defining-the-called-process) +- [Business rule tasks](/docs/components/modeler/bpmn/business-rule-tasks/business-rule-tasks.md#defining-a-called-decision) (if the DMN decision implementation is used) +- [User tasks](/docs/components/modeler/bpmn/user-tasks/user-tasks.md#user-task-forms) (if a Camunda Form is linked) + +The binding type determines the version of the target resource used at runtime. + +For example, for a call activity this would be the version of the called process to be instantiated. + +## Supported binding types + +Camunda 8 supports the following binding types: + +| Type | Description | +| :----------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `latest` |

Resolves to the **latest deployed version** of the target resource at the moment the process element is activated.

  • This can lead to unexpected behavior if you deploy a new version of the target resource without ensuring backwards compatibility with every deployed process that depends on it.

  • Therefore, using `latest` might not be suited for production environments that require stability and a predictable behavior.

| +| `deployment` |

Resolves to the specific version of the target resource that was **deployed together** with the currently running version of the process in the **same deployment**.

  • This option ensures predictable behavior by tying the two versions together, and allows you to deploy future versions of the target resource without disrupting ongoing process instances.

  • This option is ideal for self-contained projects without external or shared dependencies.

  • To use the `deployment` binding option, create and deploy a [process application in Web Modeler](/docs/components/modeler/web-modeler/process-applications.md#deploy-and-run-a-process-application), or deploy multiple resources together via the [Zeebe API](/docs/apis-tools/zeebe-api/gateway-service.md#deployresource-rpc).

| + +:::note + +If the binding type is not explicitly specified in your BPMN diagram, `latest` is used as the default. + +::: diff --git a/docs/components/modeler/bpmn/business-rule-tasks/business-rule-tasks.md b/docs/components/modeler/bpmn/business-rule-tasks/business-rule-tasks.md index e593128e0fc..ae2dd3409e1 100644 --- a/docs/components/modeler/bpmn/business-rule-tasks/business-rule-tasks.md +++ b/docs/components/modeler/bpmn/business-rule-tasks/business-rule-tasks.md @@ -42,6 +42,19 @@ e.g. `= "shipping_box_size_" + countryCode`). The expression is evaluated on act an incident at the business rule task is resolved) after input mappings have been applied. The expression must result in a `string`. +The `bindingType` attribute determines which version of the called decision is evaluated: + +- `latest`: the latest deployed version at the moment the business rule task is activated. +- `deployment`: the version that was deployed together with the currently running version of the process. + +To learn more about choosing binding types, see [Choosing the resource binding type](/docs/components/best-practices/modeling/choosing-the-resource-binding-type.md). + +:::note + +If the `bindingType` attribute is not specified, `latest` is used as the default. + +::: + A business rule task must define the process variable name of the decision result as `resultVariable`. The result of the decision is stored in this variable. The `resultVariable` is defined as a static value. @@ -92,12 +105,12 @@ to transform the variables passed to the job worker, or to customize how the var ### XML representation -A business rule task with a called decision: +A business rule task with a called decision that uses `deployment` binding: ```xml - + ``` diff --git a/docs/components/modeler/bpmn/call-activities/call-activities.md b/docs/components/modeler/bpmn/call-activities/call-activities.md index e3c522b341e..d592b3086f1 100644 --- a/docs/components/modeler/bpmn/call-activities/call-activities.md +++ b/docs/components/modeler/bpmn/call-activities/call-activities.md @@ -16,10 +16,21 @@ When the created process instance is completed, the call activity is left and th A call activity must define the BPMN process id of the called process as `processId`. -The new instance of the defined process is created by its **latest version** at the point when the call activity is activated. - Usually, the `processId` is defined as a [static value](/components/concepts/expressions.md#expressions-vs-static-values) (e.g. `shipping-process`), but it can also be defined as [expression](/components/concepts/expressions.md) (e.g. `= "shipping-" + tenantId`). The expression is evaluated on activating the call activity and must result in a `string`. +The `bindingType` attribute determines which version of the called process is instantiated: + +- `latest`: the latest deployed version at the moment the call activity is activated. +- `deployment`: the version that was deployed together with the currently running version of the calling process. + +To learn more about choosing binding types, see [Choosing the resource binding type](/docs/components/best-practices/modeling/choosing-the-resource-binding-type.md). + +:::note + +If the `bindingType` attribute is not specified, `latest` is used as the default. + +::: + ## Boundary events ![call-activity-boundary-event](assets/call-activities-boundary-events.png) @@ -50,12 +61,12 @@ By disabling this attribute, variables existing at higher scopes are no longer c ### XML representation -A call activity with static process id and propagation of all child variables turned on: +A call activity with static process id, propagation of all child variables turned on, and `deployment` binding: ```xml - + ``` diff --git a/docs/components/modeler/bpmn/user-tasks/user-tasks.md b/docs/components/modeler/bpmn/user-tasks/user-tasks.md index 8501d81ed12..0d365554597 100644 --- a/docs/components/modeler/bpmn/user-tasks/user-tasks.md +++ b/docs/components/modeler/bpmn/user-tasks/user-tasks.md @@ -106,7 +106,19 @@ Depending on your use case, two different types of form references can be used: Forms linked this way can be deployed together with the referencing process models. To link a user task to a Camunda Form, you have to specify the ID of the Camunda Form as the `formId` attribute of the task's `zeebe:formDefinition` extension element (see the [XML representation](#camunda-form-linked)). - Form ID references always refer to the latest deployed version of the Camunda Form. + + The `bindingType` attribute determines which version of the linked form is used: + + - `latest`: the latest deployed version at the moment the user task is activated. + - `deployment`: the version that was deployed together with the currently running version of the process. + + To learn more about choosing binding types, see [Choosing the resource binding type](/docs/components/best-practices/modeling/choosing-the-resource-binding-type.md). + + :::note + + If the `bindingType` attribute is not specified, `latest` is used as the default. + + ::: You can read more about Camunda Forms in the [Camunda Forms guide](/guides/utilizing-forms.md) or the [Camunda Forms reference](/components/modeler/forms/camunda-forms-reference.md) to explore all configuration options for form elements. @@ -176,12 +188,12 @@ Zeebe user task-specific features are not available to those user tasks. #### Camunda Form -A user task with a linked Camunda Form, an assignment definition, and a task schedule: +A user task with a linked Camunda Form (that uses `deployment` binding), an assignment definition, and a task schedule: ```xml - + diff --git a/docs/guides/migrating-from-camunda-7/adjusting-bpmn-models.md b/docs/guides/migrating-from-camunda-7/adjusting-bpmn-models.md index ecbb0e25ca5..dbf4fad9c46 100644 --- a/docs/guides/migrating-from-camunda-7/adjusting-bpmn-models.md +++ b/docs/guides/migrating-from-camunda-7/adjusting-bpmn-models.md @@ -108,6 +108,10 @@ The following attributes/elements can be migrated: - `camunda:candidateUsers` to `zeebe:assignmentDefinition candidateUsers` - `camunda:formKey` to `zeebe:formDefinition formKey`, but Camunda 8 requires you to embed the form definition itself into the root element of your BPMN XML models, see [the user task documentation](/components/modeler/bpmn/user-tasks/user-tasks.md#user-task-forms). - `camunda:formRef` to `zeebe:formDefinition formId` + - `camunda:formRefBinding` to `zeebe:formDefinition bindingType` + :::note + Camunda 8 only supports the `deployment` and `latest` binding types for user task forms. + ::: The following attributes/elements **cannot** yet be migrated: @@ -115,7 +119,7 @@ The following attributes/elements **cannot** yet be migrated: - `camunda:formHandlerClass` - `camunda:formData` - `camunda:formProperty` - - `camunda:formRefBinding` and `camunda:formRefVersion` (Camunda 8 always uses `latest` binding) + - `camunda:formRefVersion` - `camunda:taskListener` - `camunda:dueDate` - `camunda:followUpDate` @@ -131,10 +135,14 @@ The following attributes/elements can be migrated: - `camunda:decisionRef` to `zeebe:calledDecision decisionId` - `camunda:resultVariable` to `zeebe:calledDecision resultVariable` +- `camunda:decisionRefBinding` to `zeebe:calledDecision bindingType` + :::note + Camunda 8 only supports the `deployment` and `latest` binding types for business rule tasks. + ::: The following attributes are **not** yet supported: -- `camunda:decisionRefBinding`, `camunda:decisionRefVersion`, and `camunda:decisionRefVersionTag`(always use the latest version) +- `camunda:decisionRefVersion` and `camunda:decisionRefVersionTag` - `camunda:mapDecisionResult` (no mapping happens) - `camunda:decisionRefTenantId` @@ -146,15 +154,18 @@ A business rule task can also _behave like a service task_ to allow integration Call activities are generally supported in Zeebe. The following attributes/elements can be migrated: -- `camunda:calledElement` will be converted into `zeebe:calledElement` +- `camunda:calledElement` to `zeebe:calledElement processId` +- `camunda:calledElementBinding` to `zeebe:calledElement bindingType` + :::note + Camunda 8 only supports the `deployment` and `latest` binding types for call activities. + ::: - Data mapping - `camunda:in` to `zeebe:input` - `camunda:out` to `zeebe:output` The following attributes/elements **cannot** be migrated: -- `camunda:calledElementBinding`: Currently Zeebe always assumes 'late' binding. -- `camunda:calledElementVersionTag`: Zeebe does not know a version tag. +- `camunda:calledElementVersion` and `camunda:calledElementVersionTag` - `camunda:variableMappingClass`: You cannot execute code to do variable mapping in Zeebe. - `camunda:variableMappingDelegateExpression`: You cannot execute code to do variable mapping in Zeebe. diff --git a/optimize_sidebars.js b/optimize_sidebars.js index 37d8adea253..dee025895d4 100644 --- a/optimize_sidebars.js +++ b/optimize_sidebars.js @@ -1367,6 +1367,10 @@ module.exports = { "Choosing the DMN hit policy", "components/best-practices/modeling/choosing-the-dmn-hit-policy/" ), + docsLink( + "Choosing the resource binding type", + "components/best-practices/modeling/choosing-the-resource-binding-type/" + ), ], }, diff --git a/sidebars.js b/sidebars.js index 7b29eb8b627..9921cce87b0 100644 --- a/sidebars.js +++ b/sidebars.js @@ -648,6 +648,7 @@ module.exports = { "components/best-practices/modeling/modeling-with-situation-patterns", "components/best-practices/modeling/building-flexibility-into-bpmn-models", "components/best-practices/modeling/choosing-the-dmn-hit-policy", + "components/best-practices/modeling/choosing-the-resource-binding-type", ], Operations: [ "components/best-practices/operations/versioning-process-definitions",