• Beta
Workflow Events
  • 18 Nov 2020
  • 6 Minutes To Read
  • Share
  • Dark
    Light

Workflow Events

  • Share
  • Dark
    Light

The CTO.ai Lifecycle Events are predefined events that track common points in most team's delivery lifecycle. You can send us some or all of these events and we will generate insight-rich visualizations on the CTO.ai Dashboard. The more events you send us, the deeper the insights we can surface.

We're releasing new Lifecycle Events as we hear of demand for them. Let us know if there is something you'd like us to add!

You can also create your own custom events, which will also show up on the dashboard, can be filtered or searched on, or can be queried directly from our API.

Skip to the Custom LifeCycle Events in the Table of Contents.

Change Events (abstract)

Change events are abstract. Your team can choose where to instrument them into your pipeline, based on what is most meaningful for you. How do you want to measure your change process?

Change Initiated

  • CTO.ai recommends that you send this event either when a feature branch is created, or when a ticket is created.

Change Succeeded

  • CTO.ai recommends that you send this event either when code is deployed, or when code is merged to a master branch.

Change Failure

  • CTO.ai recommends that you send this event either when an incident is created, or when a pipeline fails.

Change Failure Recovery

  • CTO.ai recommends that you send this event when an incident is resolved, or, alternatively, don’t send this event at all and let CTO.ai detect recovery based on Deployment Succeeded events.

Example:

POST /events
{ 
  "stage": "Change",
  "status": "Initiated",
  "change_id": "298673a9-a40f-4717-b288-060be948831b",
  "pipeline_id": "api-pipeline-1",
  "team_id": "02f71e12-fa48-45aa-a1f2-956b425e5bee"
}

Ticket Events

Ticket events integrate into your project management software.

POST /events
{ 
  "stage": "Ticket",
  "status": "Initiated",
  "stage_ref": "f22a7e12", // links together multiple ticket events
  "change_id": "298673a9-a40f-4717-b288-060be948831b",
  "pipeline_id": "api-pipeline-1",
  "team_id": "02f71e12-fa48-45aa-a1f2-956b425e5bee"
}

Status values: Initiated, Todo, InProgress, ReadyForReview, Done

Commit Events

Commit events track commit activity in your version control system.

POST /events
{ 
  "stage": "Commit",
  "status": "Succeeded",
  "stage_ref": "f22a7e12", // links together multiple commit events
  "change_id": "298673a9-a40f-4717-b288-060be948831b",
  "team_id": "02f71e12-fa48-45aa-a1f2-956b425e5bee"
}

Status values

Initiated could represent the creation of a feature branch or the creation of a pull request.

Succeeded could represent any successful commit or a merging to master.

Failed could represent a rejected pull request or a failed merge.

Pipeline Events

If your system has a concept of linear pipelines with defined starting points and ending points, you could make use of pipeline events.

POST /events
{ 
  "stage": "Pipeline",
  "status": "Initiated",
  "stage_ref": "f22a7e12", // links together multiple pipeline events
  "change_id": "298673a9-a40f-4717-b288-060be948831b",
  "team_id": "02f71e12-fa48-45aa-a1f2-956b425e5bee"
}

Status values: Initiated, Succeeded, Failed

Review Events

Version control systems sometimes emit review events, which can be captured here.

POST /events
{ 
  "stage": "Review",
  "status": "Succeeded",
  "stage_ref": "f22a7e12", // links together multiple review events
  "change_id": "298673a9-a40f-4717-b288-060be948831b",
  "team_id": "02f71e12-fa48-45aa-a1f2-956b425e5bee"
}

Status values: Initiated, Succeeded, Failed

Approval Events

Approval events emitted by your version control system.

POST /events
{ 
  "stage": "Approval",
  "status": "Succeeded",
  "stage_ref": "f2a8dae12", // links together multiple approval events
  "change_id": "298673a9-a40f-4717-b288-060be948831b",
  "team_id": "02f71e12-fa48-45aa-a1f2-956b425e5bee"
}

Status values: Initiated, Succeeded, Failed

Clone Events

Typically used to track clone events that happen at the beginning of a CICD run.

POST /events
{ 
  "stage": "Clone",
  "status": "Initiated",
  "stage_ref": "956b425e5bee", // links together multiple clone events
  "change_id": "298673a9-a40f-4717-b288-060be948831b",
  "pipeline_id": "api-pipeline-1",
  "team_id": "02f71e12-fa48-45aa-a1f2-956b425e5bee"
}

Status values: Initiated, Succeeded, Failed

Build Events

The build step in a CICD pipeline.

POST /events
{ 
  "stage": "Build",
  "status": "Initiated",
  "stage_ref": "956b425e5bee", // links together multiple build events
  "change_id": "298673a9-a40f-4717-b288-060be948831b",
  "pipeline_id": "api-pipeline-1",
  "team_id": "02f71e12-fa48-45aa-a1f2-956b425e5bee"
}

Status values: Initiated, Succeeded, Failed

Lint Events

The lint step in a CICD pipeline.

POST /events
{ 
  "stage": "Lint",
  "status": "Initiated",
  "stage_ref": "956b425e5bee", // links together multiple lint events
  "change_id": "298673a9-a40f-4717-b288-060be948831b",
  "pipeline_id": "api-pipeline-1",
  "team_id": "02f71e12-fa48-45aa-a1f2-956b425e5bee"
}

Status values: Initiated, Warning, Succeeded, Failed

Test Events (generic)

This could apply to any kind of test, or to all tests if you do not need to distinguish between them.

POST /events
{ 
  "stage":" "Test",
  "status": "Initiated",
  "stage_ref": "956b425e5bee", // links together multiple test events
  "change_id": "298673a9-a40f-4717-b288-060be948831b",
  "pipeline_id": "api-pipeline-1",
  "team_id": "02f71e12-fa48-45aa-a1f2-956b425e5bee"
}

Status values: Initiated, Succeeded, Failed

Unit Test Events

The unit test step in a CICD pipeline.

POST /events
{ 
  "stage":" "UnitTest",
  "status": "Initiated",
  "stage_ref": "956b425e5bee", // links together multiple unit test events
  "change_id": "298673a9-a40f-4717-b288-060be948831b",
  "pipeline_id": "api-pipeline-1",
  "team_id": "02f71e12-fa48-45aa-a1f2-956b425e5bee"
}

Status values: Initiated, Succeeded, Failed

End-to-End Test Events

The end-to-end test step in a CICD pipeline, or in a production end-to-end testing environment.

POST /events
{ 
  "stage":" "E2eTest",
  "status": "Initiated",
  "stage_ref": "956b425e5bee", // links together multiple e2e test events
  "change_id": "298673a9-a40f-4717-b288-060be948831b",
  "pipeline_id": "api-pipeline-1",
  "team_id": "02f71e12-fa48-45aa-a1f2-956b425e5bee"
}

Status values: Initiated, Succeeded, Failed

Performance Test Events

The performance test event in a CICD pipeline, or in a production performance testing environment.

POST /events
{ 
  "stage":" "PerformanceTest",
  "status": "Initiated",
  "stage_ref": "956b425e5bee", // links together multiple perf test events
  "change_id": "298673a9-a40f-4717-b288-060be948831b",
  "pipeline_id": "api-pipeline-1",
  "team_id": "02f71e12-fa48-45aa-a1f2-956b425e5bee"
}

Status values: Initiated, Succeeded, Failed

Security Audit Events

Scan for known or potential vulnerabilities.

POST /events
{ 
  "stage":" "SecurityAudit",
  "status": "Initiated",
  "stage_ref": "956b425e5bee", // links together multiple sec audit events
  "change_id": "298673a9-a40f-4717-b288-060be948831b",
  "pipeline_id": "api-pipeline-1",
  "team_id": "02f71e12-fa48-45aa-a1f2-956b425e5bee"
}

Status values: Initiated, Succeeded, Failed

Licensing Audit Events

Licensing audits check for incorporated third-party code that may have an incompatible license.

POST /events
{ 
  "stage":" "LicensingAudit",
  "status": "Initiated",
  "stage_ref": "956b425e5bee", // links together multiple licensing audit events
  "change_id": "298673a9-a40f-4717-b288-060be948831b",
  "pipeline_id": "api-pipeline-1",
  "team_id": "02f71e12-fa48-45aa-a1f2-956b425e5bee"
}

Status values: Initiated, Succeeded, Failed

Artifact Storage Events

Send an artifact storage event if your pipelines uses a separate step to store built artifacts for later use.

POST /events
{ 
  "stage":" "ArtifactStorage",
  "status": "Initiated",
  "stage_ref": "956b425e5bee", // links together multiple artifact storage events
  "change_id": "298673a9-a40f-4717-b288-060be948831b",
  "pipeline_id": "api-pipeline-1",
  "team_id": "02f71e12-fa48-45aa-a1f2-956b425e5bee"
}

Status values: Initiated, Succeeded, Failed

Deployment Events

A deployment event in a CICD pipeline.

POST /events
{ 
  "stage": "Deployment",
  "status": "Initiated",
  "stage_ref": "956b425e5bee", // links together multiple deployment events
  "change_id": "298673a9-a40f-4717-b288-060be948831b",
  "pipeline_id": "api-pipeline-1",
  "team_id": "02f71e12-fa48-45aa-a1f2-956b425e5bee"
}

Release Events

A release event in the software delivery process.

POST /events
{ 
  "stage": "Release",
  "status": "Initiated",
  "stage_ref": "956b425e5bee", // links together multiple release events
  "change_id": "298673a9-a40f-4717-b288-060be948831b",
  "pipeline_id": "api-pipeline-1",
  "team_id": "02f71e12-fa48-45aa-a1f2-956b425e5bee"
}

Status values: Initiated, Succeeded, Failed

Support Request Events

Support Request events integrate into your customer support software.

POST /events
{ 
  "stage": "SupportRequest",
  "status": "Opened",
  "stage_ref": "073b7daf-1b50-4bfb-9574-3dd60303a98e", // uuid for the support request
  "team_id": "02f71e12-fa48-45aa-a1f2-956b425e5bee"
}

Status values: Opened, Updated, Resolved

Incident Events

Integrate this event into your incident management process to gather detailed data on your incident response maturity.

POST /events
{ 
  "stage": "Incident",
  "status": "Initiated",
  "stage_ref": "956b425e5bee", // links together multiple incident events
  "change_id": "298673a9-a40f-4717-b288-060be948831b",
  "pipeline_id": "api-pipeline-1",
  "team_id": "02f71e12-fa48-45aa-a1f2-956b425e5bee"
}

Status values

Initiated represents when an incident is detected and the incident response procedure is initialized.

Succeeded represents an incident that has been resolved.

Failed could represent an incident that has failed to be resolved and abandoned, or that has taken too long to resolve.

Recovery Events

When a pipeline or test succeeds after a failure, or when an incident is resolved.

POST /events
{ 
  "stage": "Recovery",
  "status": "Initiated",
  "stage_ref": "956b425e5bee", // links together multiple recovery events
  "change_id": "298673a9-a40f-4717-b288-060be948831b",
  "pipeline_id": "api-pipeline-1",
  "team_id": "02f71e12-fa48-45aa-a1f2-956b425e5bee"
}

Status values: Initiated, Succeeded, Failed

Custom Lifecycle Events

A custom lifecycle event is something you define. When you store custom events, you can query them using our API and build your own tools or metrics based on those events. You can also search, sort, and filter these events on our dashboard, as well as visualize some of them. The built-in visualizations for custom events are not as rich as for CTO.ai lifecycle events, but custom events give you infinite flexibility—The Ops Platform works alongside your tools, not against them.

Send a Custom Event

POST /events
{ 
  "stage": "CustomEvent1",
  "status": "CustomStatusA",
  "stage_ref": "956b425e5bee", // links together multiple events on the same stage
  "change_id": "298673a9-a40f-4717-b288-060be948831b",
  "pipeline_id": "api-pipeline-1",
  "team_id": "02f71e12-fa48-45aa-a1f2-956b425e5bee",
  "custom": {
    "CustomField1":"CustomValueA",
    "CustomField2":"CustomValueB",
    "CustomReferenceField" : [
      "298673aa9",
      "956b425ef",
      "02f371e12"
    ]
  }
}

Notice the "custom" field at the bottom of this JSON payload. This field allows you to insert arbitrary JSON from which you can reference an arbitrary number of other events that you've sent us. This allows you to create complex many-to-many relationships between your various events, including CTO.ai predefined Lifecycle Events, which can then surface the operation of very complex pipelines.

Retrieve Events

Read Events through HTTP

curl "https://api.cto.sh/api/v1/events?team_id=aaaa"

Sort your API results by timestamp or any other field in the result body.

curl "https://api.cto.sh/api/v1/events?team_id=aaaa&$sort[timestamp]=-1"

Limit your API results.

curl "https://api.cto.sh/api/v1/events?team_id=aaaa&$limit=10"
Was This Article Helpful?