Documentation (2024.2 Enterprise)

# Event

An event is a historical entry of some user or bot action that took place in Helix TeamHub. An event identifies an action that has a subject (a Helix TeamHub account id), and a specific point of time.

Events can also be live. When an event is created, it is usually also marked complete by setting the progress value as 100. However, if an event has a progress value below 100, has a fairly recent timestamp and has also been updated (i.e. the progress value has been incremented) recently, an event is interpreted as a live event. You can expect live updates to these events and show this to the user.

The action-target pair of values is a powerful way of describing all the meaningful things people can do in Helix TeamHub. The author and the hash of linked objects identify the data objects related to the event.

- Attributes
- Operations
  - `GET /events`
  - `GET /events/:id`
  - `POST /events`
  - `PUT /events/:id`

## Attributes

### id

A URL-friendly identifier for the event.

- Type: `string`
- Unique: `true` (in company scope)

### subject

The subject of the event (the identifier of a User or Collaborator). It can be expanded to get the full objects by including the query parameter `expand=subject` in the request.

- Type: `string` / `object`

### timestamp

Date and time of the action, in ISO-8601 format.

- Type: `timestamp`

### operation

A verb describing what the author has done with the target. One of `added`, `assigned`, `completed`, `created`, `deleted`, `failed`, `reassigned`, `removed`, `unvoted`, `updated`, `voted`.

- Type: `string`

### target

A noun describing what the object of the action is. One of `bookmark`, `bot`, `branch`, `build`, `code_review_comment`, `code_review_description`, `code_review_line_comment`, `code_review_require_build`, `code_review_state`, `code_review_threshold`, `code_review_title`, `code_review`, `collaborator`, `comment_reply`, `commit_comment`, `commit_line_comment`, `event_comment`, group_member, `milestone`, `project`, `project_short_name`, `project_name`, `project_description`, `project_visibility`, `project_collaborator`, `project_description`, `project_group`, `project_hook`, `project_name`, `project_short_name`, `project_user`, `project_visibility`, `project`, `push`, `repository_hook`, `repository`, `reviewer`, `tag`, `task_branch`, `task_comment`, `task_commit`, `task_description`, `task_member`, `task_milestone`, `task_state`, `task_title`, `task`, `user`.

- Type: `string`

### ref

Only applicable to `push`, `branch`, `bookmark` and `tag` targets. A string describing the Branch, Bookmark or Tag affected (for example `master`).

- Type: `string`

### bookmarks

Only applicable to `push` and `build` targets. A list of bookmarks' names related to the event.

- Type: `array`

### commits

Only applicable to `push`, `branch`, `build` and `task_commit` targets. A list of commit identifiers related to the event. The list may contain at maximum 100 commit identifiers. It can be expanded to get the full Commit objects by including the query parameter `expand=objects.commits` in the request.

- Type: `array`

### commit_count

Only applicable to `push` and `branch` targets. The total number of commit identifiers related to the event. Note that the count might be larger than the size of `commits` array.

- Type: `int`

### last_commit

Only applicable to `push` and `branch` targets. The last commit identifier related to the event. Note that this commit identifier might not be in the `commits` array.

- Type: `string`

### files

Only applicable to `push` target. Contains details about changed files.

- Type: `object`

    "files": {
      "added": [
        "app/model/user.rb",
        "spec/models/user_spec.rb"
      ],
      "modified": [
        "readme.md",
      ],
      "deleted": [
        "user.rb",
      ]
    }

### code_reviews

Only applicable to `push` and `build` targets. A list of Code Reviews related to the event. It can be expanded to get the full Code Review objects by including the query parameter `expand=objects.code_reviews` in the request.

- Type: `array`

### role

Only applicable to `project_user`, `project_collaborator`, `project_group` and `bot` targets. The role the User or Collaborator has directly in the project.

### short_name

Only applicable to `project` target. The URL-friendly identifier for the Project.

- Type: `string`

### name

Only applicable to `build` and `project` targets. The name of the build (for example `Development`) or the name of the Project.

- Type: `string`

### description

Only applicable to `project_description`, `task_description` and `code_review_description` targets. The free-form description of the Project, Task or Code Review.

- Type: `string`

### title

Only applicable to `task_title` and `code_review_title` targets. The state for the Task or Code Review.

- Type: `string`

### state

Only applicable to `task_state` and `code_review_state` targets. The human-readable title for the Task or Code Review.

- Type: `string`

### visibility

Only applicable to `project` target. The visibility flag of the Project.

- Type: `string`

### objects

A hash of linked objects related to the event. The interpretation of this value depends on the action-target pair of the event.

For example: `{"project": { "id": "luotsi" }, "repository": {"id": "chef" }}`.

- Type: `object`

### progress

The progress value of an event, as percentage. Must be between 0 and 100. When progress is 100, the event is considered complete.

- Type: `int`

### resources

A list of links to external resources related to the event, usually defined as an array of URLs to link to.

Example: `["http://jenkins.eficode.com/project"]`.

- Type: `array`

## Operations

### GET /events

Get all events within the company. Results may be restricted using query parameters. Returned as a metadata-results object.

#### Example Request: Get two latest events for a project

    curl -X GET \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      https://helixteamhub.cloud/api/events?project=luotsi&limit=2

#### Example Response

    {
      "metadata": {
        "more_results": true,
        "next_offset": 2,
        "count": 2
      },
      "results": [
        {
          "api_status": 200,
          "api_timestamp": "2012-10-25T09:47:30Z",
          "id": "50883cfe1229c02952000036",
          "created_at": "2012-10-24T19:09:50Z",
          "updated_at": "2012-10-24T19:09:50Z",
          "subject": {
            "id": "assimov"
          },
          "operation": "created",
          "target": "push",
          "progress": 100,
          "objects": {
              "project": {
                "id": "luotsi"
              },
              "repository": {
                "id": "devrel"
              },
              "commits": [
                  {
                    "id": "a6e0210cdd2f473104d75c35a7d1052e12b11b46"
                  },
                  {
                    "id": "393fe81b0f6c39f3006f748f5b16cdddcbe01c80"
                  }
              ],
              "last_commit": "393fe81b0f6c39f3006f748f5b16cdddcbe01c80",
              "commit_count": 2,
              "ref": "master"
          },
          "timestamp": "2012-10-24T19:09:50Z"
        },
        {
          "api_status": 200,
          "api_timestamp": "2012-10-25T09:47:30Z",
          "id": "50880fe31229c0295a00002d",
          "created_at": "2012-10-24T15:57:23Z",
          "updated_at": "2012-10-24T15:57:23Z",
          "subject": {
            "id": "jlaiho"
          },
          "operation": "created",
          "target": "push",
          "progress": 100,
          "objects": {
              "project": {
                "id": "luotsi"
              },
              "repository": {
                "id": "luotsi"
              },
              "commits": [
                  {
                    "id": "b63c10447d5c0f1b7f013af7ffe56742b449d100"
                  },
                  {
                    "id": "831c9809309e640a5191a639a7f002012f2a842c"
                  }
                  ...
              ]
              "last_commit": "a6e0210cdd2f473104d75c35a7d1052e12b11b46",
              "commit_count": 2815
          },
          "timestamp": "2012-10-24T15:57:23Z"
        }
      ]
    }

#### Example Request: Get an event for the most recently added project user in a project

    curl -X GET \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      https://helixteamhub.cloud/api/events?project=luotsi&limit=1&operation=created&target=project_user

#### Example Response

    {
      "metadata": {
        "more_results": true,
        "next_offset": 1,
        "count": 1
      },
      "results": [
        {
          "api_status": 200,
          "api_timestamp": "2012-10-25T09:58:48Z",
          "id": "50879b531229c06d30000014",
          "created_at": "2012-10-24T07:40:03Z",
          "updated_at": "2012-10-24T07:40:03Z",
          "subject": {
            "id": "thuovinen"
          },
          "operation": "created",
          "target": "project_user",
          "progress": 100,
          "objects": {
              "user": {
                "id": "etuupainen"
              },
              "project": {
                "id": "luotsi"
              },
              "role": "guest"
          },
          "timestamp": "2012-10-24T07:40:03Z"
        }
      ]
    }

### GET /events/:id

Get a specific event.

#### Example Request

    curl -X GET \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      https://helixteamhub.cloud/api/events/50883cfe1229c02952000036

#### Example Response

    {
        "api_status": 200,
        "api_timestamp": "2012-10-25T09:47:30Z",
        "id": "50883cfe1229c02952000036",
        "created_at": "2012-10-24T19:09:50Z",
        "updated_at": "2012-10-24T19:09:50Z",
        "subject": {
          "id": "assimov"
        },
        "operation": "created",
        "target": "repository",
        "progress": 100,
        "objects": {
            "project": {
              "id": "luotsi"
            },
            "repository": {
              "id": "devrel"
            }
        },
        "timestamp": "2012-10-24T19:09:50Z"
    }

### POST /events

Create a new event. Only build events can be created through API by using a bot account. Operation can be either "completed" or "failed", name is optional.

#### Example Request

    curl -X POST \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      -H "Content-Type: application/json" \
      -d '{ "target": "build", "operation": "completed", "project": "luotsi", "repository": "chef", "name": "Development", "commits": ["d847a7a20f547b8990c31627599aee47441018e6"], "resources": ["http://domain.com/jenkins/job/development/2372"] }' \
      https://helixteamhub.cloud/api/events

#### Example Response

    {
      "api_status": 201,
      "api_timestamp": "2013-08-15T14:48:02Z",
      "id": "520cea221cf3593b29000004",
      "created_at": "2013-08-15T14:48:02Z",
      "updated_at": "2013-08-15T14:48:02Z",
      "subject": {
        "id": "luotsi-ci-bot"
      },
      "operation": "completed",
      "target": "build",
      "progress": 100,
      "objects": {
        "project": {
          "id": "luotsi"
        },
        "repository": {
          "id": "chef"
        },
        "commits": [
          {
            "id": "d847a7a20f547b8990c31627599aee47441018e6"
          }
        ],
        "resources": [
          "http://domain.com/jenkins/job/development/2372"
        ],
        "name": "Development"
      },
      "timestamp": "2013-08-15T14:48:02Z"
    }

### PUT /events/:id

Only progress and operation of an incomplete build event can be updated.

#### Example request

    curl -X PUT \
      -H "Accept: application/vnd.hth.v1" \
      -H "Authorization: hth.company_key='$COMPANY_KEY',account_key='$ACCOUNT_KEY'" \
      -H "Content-Type: application/json" \
      -d '{ "progress": 100, "operation": "completed" }' \
      https://helixteamhub.cloud/api/events/5211cf501cf3592d2100000d

#### Example response

    {
      "api_status": 200,
      "api_timestamp": "2013-08-19T07:55:39Z",
      "id": "5211cf501cf3592d2100000d",
      "created_at": "2013-08-19T07:54:56Z",
      "updated_at": "2013-08-19T07:55:39Z",
      "subject": {
        "id": "luotsi-ci-bot"
      },
      "operation": "completed",
      "target": "build",
      "progress": 100,
      "objects": {
        "project": {
          "id": "luotsi"
        },
        "repository": {
          "id": "chef"
        },
        "commits": [
          {
            "id": "d847a7a20f547b8990c31627599aee47441018e6"
          }
        ],
        "resources": [
          "http://domain.com/jenkins/job/development/2372"
        ],
        "name": "Development"
      },
      "timestamp": "2013-08-19T07:54:56Z"
    }

Your search for returned results

Your search for returned results