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.

Sign up for GitHub

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

[FX-4604] Allow updating External Ticket References #271

Merged
merged 1 commit into from
Dec 18, 2024
Merged

[FX-4604] Allow updating External Ticket References #271

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 56 additions & 0 deletions versions/v2/content/external-ticket-references.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -171,6 +171,62 @@ You get a `201` response code for a successful request.
| `external_id` | An arbitrary external identifier for the ticket reference. |
| `finding_id` | The Cobalt ID of the finding this external ticket belongs to. |

## Update an External Ticket Reference

```sh
curl -X PATCH \
--location 'https://api.us.cobalt.io/external_ticket_references/efr_9ekpSErugPH8zst2pBcjPo' \
-H "Accept: application/vnd.cobalt.v2+json" \
-H "Content-Type: application/vnd.cobalt.v2+json" \
-H "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \
-H "X-Org-Token: YOUR-V2-ORGANIZATION-TOKEN" \
--data '{"title":"TEST-37","external_url":"https://my-project.atlassian.net/browse/TEST-37","external_id":"10214","finding_id":"vl_JTovzf8AW1afCRpKJejse3"}'
```

> The above command returns the updated external ticket reference and a `200` response code when successful.

```json
{
"resource": {
"id": "efr_9ekpSErugPH8zst2pBcjPo",
"title": "TEST-37",
"ticketing_system": "jira",
"external_url": "https://my-project.atlassian.net/browse/TEST-37",
"external_id": "10214",
"finding_id": "vl_JTovzf8AW1afCRpKJejse3"
Copy link
Contributor

Choose a reason for hiding this comment

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

I've seen in the api PR that we also return referenceType?
https://github.com/cobalthq/cobalt-api/pull/1349/files#diff-dfe6776effd5e16b02bb720d7d3deb4cd2cdfebb6aad7353ddadd35acdc55accR116

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Yeah we do. It's intentionally omitted from the documentation so that we can remove it later.

Context:
We initially called the functionality "External Finding References" (you'll still find this name in lots of the code).
Before we released (documented) these public API routes, we thought about it again and decided that the name "External Ticket Reference" made a lot more sense, so we released the API routes under that name. As part of that renaming, we also added the ticketing_system property that has the same value as reference_type. reference_type was still exposed because it was used by early workato recipes that were in use by a small handful of customers. The idea is to remove the duplicate (undocumented) API routes with the name /external_finding_references and remove the reference_type property sometime soon-ish.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

After thinking about it some more, I should probably add an explicit note to the docs telling customers not to use the referenceType property because it will be removed. That could be a follow up PR tho

Copy link
Contributor

Choose a reason for hiding this comment

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

Thanks for explaining.

}
}
```

This endpoint updates an external ticket reference. On a successful request, it will return a `200` response code
along with the updated external ticket reference information.

### HTTP Request

`PATCH https://api.us.cobalt.io/external_ticket_references/:id`

### Request Body

| Field | Optional | Description |
| ------------------ |----------|-----------------------------------------------------------------------------------------------------------|
| `title` | true | A short descriptive title of the external ticket. For example, the ticket ID. |
| `external_url` | true | The URL of the external ticket. |
| `external_id` | true | An arbitrary external identifier for the ticket reference. |
| `finding_id` | true | The Cobalt ID of the finding this external ticket belongs to. |

### Response

You get a `200` response code for a successful request.

| Field | Description |
| ------------------ |-----------------------------------------------------------------------------------------------------------|
| `id` | A unique ID representing the external ticket reference. Starts with `efr_` |
| `title` | A short descriptive title of the external ticket. For example, the ticket ID. |
| `ticketing_system` | One of the [supported ticketing systems](#supported-ticketing-systems) or a custom ticketing system type. |
| `external_url` | The URL of the external ticket. |
| `external_id` | An arbitrary external identifier for the ticket reference. |
| `finding_id` | The Cobalt ID of the finding this external ticket belongs to. |

## Delete an External Ticket Reference

```sh
Expand Down
Loading