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"
}