Annotations

On April 11, 2022 Adobe announced the full release of the annotations feature for Adobe Analytics.

The Analytics 2.0 Annotations APIs allow you to retrieve, update, or create annotations programmatically through Adobe I/O. These APIs use the same data and methods that Adobe uses inside the product UI.

More detailed API documentation and information can be found on developer.adobe.com. The first version of our support in adobeanalyticsr includes functions for retreiving annotations (aw_get_annotations()) as well as building them (annotation_build()).

Getting Annotations

The basic function to get a dataframe of annotations from a specific company is the function aw_get_annotations(). There are 8 different arguments that can help you refine the annotations and metadata returned from the API. In addition, there are 2 arguments, “debug” and “company_id”, which which are not directly related to the data.

The following is an explanation of the different arguments you can use.

1. “id” - Filter the results to one specific annotation by the annotation id. If not used, a list of annotations will be returned limited by the ‘limit’ and ‘page’ arguments.
2. “expansion” - Obtain additional information around an annotation. You can include multiple expansions using the ‘c()’ function. Expansion options include the following:
   • name: The name of the annotation.
   • description The annotation’s description.
   • dateRange The date range of the annotation.
   • color: An enum representing the annotation’s color. Supported values include STANDARD1 through STANDARD9. These correspond to these colors in order: ‘blue’, ‘purple’, ‘green’, ‘orange’, ‘red’, ‘light green’, ‘pink’, ‘dark green’, and ‘yellow’.
   • applyToAllReports: A boolean that determines if the annotation applies to all report suites.
   • scope: An object including the metrics and filters that the annotation uses.
   • createdDate: The date that the annotation was created.
   • modifiedDate: The date that the annotation was last modified.
   • modifiedById: The ID of the user who last modified the annotation.
   • tags: The tags applied to the annotation.
   • shares: The shares applied to the annotation.
   • approved: A boolean that determines if the annotation is approved by an admin.
   • favorite: A boolean that determines if the user has this annotation favorited (starred).
   • usageSummary: An object that shows where this annotation is used.
   • owner: An object showing the ID, name, and login of the user that created the annotation.
   • companyId: The login company ID of the annotation.
   • reportSuiteName: The report suite’s friendly name.
   • rsid: The report suite ID.
3. “includeType” - Include additional segments not owned by the user. Available values are all (default) and shared. The all option takes precedence over “shared”.
4. “locale” - A query string that returns strings localized by Adobe into the desired language. Localization does not apply to user-defined fields, such as annotation names.
5. “filterByModifiedAfter” - An ISO 8601 date that returns only annotations that were modified after the desired date. example datetime format: ‘YYYY-MM-DDTHH:MM:SSZ’
6. “filterByDateRange” - Two ISO 8601 dates separated by a forward slash (/) that returns only annotations that fully reside within the desired date range. example format: ‘MM:SSZ/YYYY-MM-DDTHH:MM:SSZ’
7. “limit” - An integer that represents the number of results per page. Default is 10
8. “page” - An integer that represents which page to return results. The first page is 0. The API supports up to 1000 pages
9. “debug” - Include the output and input of the api call in the console for debugging. Default is FALSE
10. “company_id” - As with all API calls to Adobe Analytics, the Company ID is required. If an environment variable called AW_COMPANY_ID exists in .Renviron or elsewhere and no company_id argument is provided, then the AW_COMPANY_ID value will be used. Use get_me to get a list of available company_id values.

The basic function to pull a data set of 10 annotations can be done like this:

annotes <- aw_get_annotations(limit = 10, expansion = c('name', 'description', 'scope'), debug = F, includeType = 'shared')
annotes$name
annotes[annotes$name == "Test Annotation", ]$lists$scope

Build a basic annotation

(jsonlite::fromJSON(ann))

$id
[1] "626f451ac7bee35c05060753"

ann <- annotation_build("A new annotation",
                        "the description can be long or short, depending on what you need",
                        color = 'orange', 
                        filter_id = list('page', 's300003965_5eab136b34d05f0ff1c318ff'), 
                        filter_compType = list('d', 's'), 
                        filter_verb = list('exists'), 
                        filter_dimType = list('string'),
                        debug = T)