Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

zeebe api tutorial #4058

Merged
merged 5 commits into from
Aug 9, 2024
Merged

zeebe api tutorial #4058

merged 5 commits into from
Aug 9, 2024

Conversation

christinaausley
Copy link
Contributor

Description

Zeebe API docs tutorial -- relates to https://github.com/camunda/developer-experience/issues/142 and camunda/camunda-api-tutorials#8.

When should this change go live?

  • This is a bug fix, security concern, or something that needs urgent release support.
  • This is already available but undocumented and should be released within a week.
  • This on a specific schedule and the assignee will coordinate a release with the DevEx team. (apply hold label or convert to draft PR)
  • This is part of a scheduled alpha or minor. (apply alpha or minor label)
  • There is no urgency with this change and can be released at any time.

PR Checklist

  • My changes are for an already released minor and are in /versioned_docs directory.
  • My changes are for the next minor and are in /docs directory (aka /next/).

@christinaausley christinaausley added component:zeebe Issues related with Zeebe project component:docs Documentation improvements, including new or updated content theme:api-streamline Issues related to the theme of streamlining APIs labels Jul 23, 2024
@christinaausley christinaausley self-assigned this Jul 23, 2024
Copy link
Contributor

github-actions bot commented Jul 23, 2024

👋 🤖 ✅ Looks like the changes were ported across versions, nice job! 🎉

You can read more about the versioning within our docs in our documentation guidelines.

Copy link
Collaborator

@pepopowitz pepopowitz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A couple small details! Nice work.

docs/apis-tools/zeebe-api-rest/tutorial.md Outdated Show resolved Hide resolved
docs/apis-tools/zeebe-api-rest/tutorial.md Outdated Show resolved Hide resolved
@christinaausley
Copy link
Contributor Author

This is ready for final review 🥳


:::

## Assign a Zeebe user task (POST)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Since Zeebe user tasks are a bit of a new concept, it might be worth mentioning briefly in this tutorial that task assignment happened in Tasklist previously. We don't have to add this now, but it might be something to get broader feedback on.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In addition, I think we should call out that they can capture a Zeebe user task ID, which they will use to assign/unassign in this API, from Tasklist....but it has to be a Zeebe task, not a legacy task.

We could link them to this doc, which describes the difference between zeebe user tasks & legacy user tasks. It's an important distinction that I personally overlooked, and I think it's likely that readers will do the same.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adjusted in latest commit 👍

}
```

8. In your terminal, run `node cli.js zeebe assign <task id> <[email protected]>`, where `<task id>` is the Zeebe user task ID, and `<[email protected]>` is the assignee's email address.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 You could consider having the user assign their own email address if they want to see it in the UIs.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗒️ if you were wondering, like me, what would happen if one assigned a task via the API to a user not in their organization, the answer is:

It will work just fine.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, I don't have a specific suggestion, but this might also be a good place to specify where they got a Zeebe user task ID from. ("The ID you've captured from Tasklist" or something like that)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adjusted in latest commit 👍

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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking feedback: I was surprised that the action wasn't required in the API reference docs.

A custom action value that will be accessible from user task events resulting from this endpoint invocation. If not provided, it will default to "assign".

I did see that this is consistent (if no action is provided, it will default) everywhere except when unassigning a user. I'll let you decide if you want to call this out and how you want to note it. Alternatively, you can wait for feedback on this.

Copy link
Collaborator

@pepopowitz pepopowitz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should do a little more to help users understand the distinction between Zeebe user tasks and legacy tasks. Nice work, almost there!


:::

## Assign a Zeebe user task (POST)
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In addition, I think we should call out that they can capture a Zeebe user task ID, which they will use to assign/unassign in this API, from Tasklist....but it has to be a Zeebe task, not a legacy task.

We could link them to this doc, which describes the difference between zeebe user tasks & legacy user tasks. It's an important distinction that I personally overlooked, and I think it's likely that readers will do the same.

docs/apis-tools/zeebe-api-rest/tutorial.md Outdated Show resolved Hide resolved
}
```

8. In your terminal, run `node cli.js zeebe assign <task id> <[email protected]>`, where `<task id>` is the Zeebe user task ID, and `<[email protected]>` is the assignee's email address.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗒️ if you were wondering, like me, what would happen if one assigned a task via the API to a user not in their organization, the answer is:

It will work just fine.

}
```

8. In your terminal, run `node cli.js zeebe assign <task id> <[email protected]>`, where `<task id>` is the Zeebe user task ID, and `<[email protected]>` is the assignee's email address.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, I don't have a specific suggestion, but this might also be a good place to specify where they got a Zeebe user task ID from. ("The ID you've captured from Tasklist" or something like that)

@christinaausley
Copy link
Contributor Author

This is ready for final review 👍

Copy link
Member

@akeller akeller left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I won't have time to walk through this tutorial myself, but I'm happy with how it's written! Thank you for incorporating my feedback! 🚀

@christinaausley christinaausley merged commit cb5d00b into main Aug 9, 2024
7 checks passed
@christinaausley christinaausley deleted the zeebe-api-docs-tutorial branch August 9, 2024 14:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
component:docs Documentation improvements, including new or updated content component:zeebe Issues related with Zeebe project theme:api-streamline Issues related to the theme of streamlining APIs
Projects
Archived in project
Development

Successfully merging this pull request may close these issues.

3 participants