# Ticket Events

## Motivation

Tickets are often entry points for new work. This includes new features, bug fixes, etc. Ticket events will allow us to track the complete lifecycle of a code change from inception to deployment and also give us the ability to extract metrics from this lifecycle.

## Proposal

### Ticket Propagation

Tickets will enter the CDEvents ecosystem through the *ticket.created* event.

Tickets will then need to be linked to the CI/CD lifecycle of a change. The most intuitive place to do that is at the start of the CI process. This means that whatever source control system that is being used would need some definition on how to persist the ticketing metadata to an actual CDEvent. One way to do this is by having a standard around commits and/or pull requests.

Below illustrates an example on what a commit may look like which allows for parsing of the ticketing information which can be used for some CDEvent.

jira:project-123 addresses some bug

This commit fixes an issue around whitespace in that prior to this we
considered whitespace as important, which causes comparing of string to be not
equal when they should have been.

This would allow the source control system or subsystem to create a CDEvent to persist this data using links.

{
  "context": {
    "version": "0.3.0",
    "id": "271069a8-fc18-44f1-b38f-9d70a1695819",
    "source": "/event/source/us-east1",
    "type": "dev.cdevents.change.merged.0.1.2",
    "links": [
        {
            "link_type": "RELATION",
            "link_kind": "TICKET",
            "target": {
                "subjectId": "project-123"
            },
            "tags": {
                "source": "jira"
            }
        }
    ],
    "timestamp": "2023-03-20T14:27:05.315384Z"
  },
  "subject": {
    "id": "PR-1",
    "source": "/event/source/PR-1",
    "type": "change",
    "content": {
      "repository": {
        "id": "TestRepo/TestOrg",
        "source": "https://example.org"
      }
    }
  }
}

### Schema

#### ticket.created

Ticket created is a CDEvent that can be sent when someone opens/creates a ticket within some ticketing system

{
    "context": {
        "version": "0.4.0-draft",
        "id": "5ca4eda2-5472-4fac-b07d-9eb7d5d3002a",
        "source": "/event/source/123",
        "type": "dev.cdevents.ticket.created.0.1.0",
        "timestamp": "2023-10-26T19:44:37+00:00Z"
    },
    "subject": {
      "id": "project-123",
      "source": "/ticket_system",
      "type": "ticket",
      "content": {
            "summary": "Fix bug in service",
            "type": "BUG",
            "group": "Jenkins Backend",
            "creator": "App User",
            "assignee": "App Dev",
            "priority": "HIGH",
            "labels": ["feature", "label2"],
            "milestone": "123"
      },
    },
    "customData": {},
}

| field | description | example |
| ----------- | ----------- | ----------- |
| id | Unique id within the ticketing system | jira-123 |
| summary | The summary that the user provided upon ticket creation | base64 encodings can fail regex expressions |
| type | This is an enum, but also a freeform value, that associates the ticket type | `BUG`, `FEATURE`, `SOMECUSTOMSTRING` |
| group | Who the ticket is currently assigned to | Backend |
| creator | The original ticket author | John Smith |
| assignee | Who is currently investigating the ticket | App Dev |
| priority | The priority that is associated with the ticket which can indicate the importance of the ticket | `HIGH`, `MEDIUM`, `LOW`, `SOMECUSTOMSTRING` |
| labels | Labels associated to the ticket | feature, label2 |
| milestone | An ID that represents goal for when this ticket is to be completed. For example, github uses a number that links to a milestone which includes all issues and PRs associated to that milestone along with the due date for the milestone. | 123, sprint-123, Q1 |

#### ticket.updated

The ticket updated event may be sent when a ticket has been updated in some ticketing system and can reflect what changed within the ticket.

{
    "context": {
        "version": "0.4.0-draft",
        "id": "5ca4eda2-5472-4fac-b07d-9eb7d5d3002a",
        "source": "/event/source/123",
        "type": "dev.cdevents.ticket.updated.0.1.0",
        "timestamp": "2023-10-26T19:44:37+00:00Z"
    },
    "subject": {
      "id": "ticket-123",
      "source": "/ticket_system",
      "type": "ticket",
      "content": {
            "changed": [
                {
                    "field": "group",
                    "from": "Jenkins Backend",
                    "to": "Jira Backend"
                }
            ],
            "author": "John Smith"
      },
    },
    "customData": {},
}

| field | description | example |
| ----------- | ----------- | ----------- |
| changed | Are the associated changes to the ticket | |
| author | Is the person who authored the updates | John Smith |

#### ticket.closed

{
    "context": {
        "version": "0.4.0-draft",
        "id": "5ca4eda2-5472-4fac-b07d-9eb7d5d3002a",
        "source": "/event/source/123",
        "type": "dev.cdevents.ticket.closed.0.1.0",
        "timestamp": "2023-10-26T19:44:37+00:00Z"
    },
    "subject": {
      "id": "ticket-123",
      "source": "/ticket_system",
      "type": "ticket",
      "content": {
          "resolution": "completed",
          "author": "John Smith",
      },
    },
    "customData": {},
}

| field | description | example |
| ----------- | ----------- | ----------- |
| resolution | Indicates the closing status of the ticket | `COMPLETED`, `CANCELED`, or any valid string |
| author | Is the person who authored the updates | John Smith |

### Use Cases

#### Observability

Observability is really important for teams and businesses. The idea with the ticket proposal is that it allows interested users to see and gather metrics around tickets to when the fix was deployed. A good example of this is let's assume we have a bug fix. The bug fix gets created as a ticket. The assigned engineer will then look at the ticket, and do further investigation. Once the bug has been reproduced and identified, the engineer will create a pull request for the fix. This will make its way to various environments and eventually be deployed to production.

It is a lot of work to gather these information to build metrics. In the example above, we would manually need to see when the ticket was created, when the PR was merged, what artifact the commit was apart of, and then lastly track when it was deployed to production. These steps can be very involved, and having CDEvents introduce the ticket concept allows for these metrics to be easily retrieved and looked at.

#### Interoperability with Ticketing Systems

Ticket events could be used to take some action when a ticket is updated. For instance, when a ticket is assigned or transitioned to a different status. Prior to this tickets acted as individual systems that required manual work in maintaining any ticket's status. With this feature, it allows for ticketing systems to choose to hook into the CI/CD lifecycle.

#### TODO

How do we associate ticket events to other CDEvents?