Event annotations, an alpha feature for Imply 3.4, allows Pivot users to mark and annotate ranges in timeline-based data cubes. They let you associate data in the timeline with significant events, such as a marketing campaign or a software version upgrade, and document those events for other Pivot users.
An event annotation is visible to any other Pivot user who has access to the data cube.
By default, event annotations are disabled. To enable them, enable the experimental features flag in the Advanced administration page in the Pivot UI.
Like any Imply experimental feature, the event annotations feature is considered experimental and is subject to change or removal at any time. Experimental features are provided "as is," and are not subject to Imply's SLAs.
An annotation typically applies to a time range, but it can also apply to a single point in the timeline by making the start and end times the same. Note however that such single-point-in-time annotations can only be created and retrieved via the Event Annotation API; they are not visible in the UI.
From the data cube settings (accessible from the more options menu at the top right of the data field), viewers can choose to show or hide event annotations in a data cube.
Working with event annotations (alpha)
There are two ways to add and view annotations, in the Pivot UI and using an API.
Working with annotations in the Pivot UI
- Select a range in the timeline, click the more options icon, and then click Add annotation.
- Add a note in markdown format.
Annotations can be removed by selecting inside the annotation time range, opening the more options menu again, and selecting Remove annotation from the menu. Edit permissions on the data cube are required to remove annotations.
Annotations can be added and viewed on time series line charts and area stacks. Hovering the mouse over a highlighted area will reveal the annotation contents. Visibility of annotations is not restricted by user permissions.
Working with event annotations by API
You can view, create, and remove annotations via the Pivot API as described below.
Note: As the API for an alpha feature, keep in mind that the following API should be considered unstable and subject to change.
Returns all annotations
Returns the named annotation, or 500 if the annotation doesn't exist
Creates a new annotation based on the payload
Updates an existing annotation based on the payload (
Error 404 (deleting an entire collection isn't allowed)
Deletes an annotation based on the passed in name, or returns a 400 response if the annotation doesn't exist.
Example cURL request
curl -X POST --header "Content-Type:application/json" --header "x-imply-api-token:2e7db1ef-4bce-4330-83eb-e01941014656" --data '
"body": "Some content",
The eventAnnotation parameters are:
- name: A unique name for the annotation.
- body: Markdown content that can be used to document the annotation.
- start: The start time of the annotation range, in the format YYYY-MM-DDThh:mm:ssTZD, such as "2020-05-28T01:26:03.412Z". This can also be a number, for line-charts with numeric x-axis.
- end: The end time of the annotation range, in the format YYYY-MM-DDThh:mm:ssTZD. This can also be a number, for line-charts with numeric x-axis.
- creationDate: The date the annotation was created.
- dataCube: The ID of the data cube, discoverable by API or via the UI as visible in the data cube URL.
- creator: The user ID of the annotation creator.
- color: The color of the annotation range in the UI, as a hexadecimal number; optional, and not editable in the UI.
- editor: The last user who modified the annotation. This is optional, and not editable or surfaced in the UI.
- editionDate: A date that represents the origination date of the current version of the annotation. This is optional, and not editable or surfaced in the UI.
Known issues and limitations
DELETE event-annotations/:name returns a 400 error if the resource is not found; it should return a 404 error.
DELETE event-annotations should return 405 but currently returns the login page.