Skip to main content

How to enable bookmarks and recording categories in a content destination

This guide shows how to add evidence tagging to your body worn integration. With bookmarks and categories, camera users can mark and classify recordings while they're still in the field, and that context arrives with the recording in your content destination. You'll declare the right capabilities, publish your category list, and read the bookmark metadata that comes back.

The full reference is the body worn content destination API repository. This guide covers the bookmarks and categories workflow and links there for full detail.

Prerequisites​

How bookmarks and categories relate​

Categories are stored as bookmarks. On the BWS, a user marks a recording as belonging to a category; when the recording uploads, that category is included as a bookmark object. Because of this, you need the bookmark capability before categories will work.

Step 1: Declare the capabilities​

In your System/Capabilities.json, enable both StoreBookmarks and ReadCategories:

{
    "Read": {
        "ReadCategories": true
    },
    "Store": {
        "StoreBookmarks": true
    }
}

StoreBookmarks lets the BWS send bookmark objects with recordings. ReadCategories lets it read the category list you publish. Without StoreBookmarks, categories can't be stored, because they travel as bookmarks.

Remember to set the ETag header to the MD5 hash of the object when you serve it. If the checksum is wrong, the system controller logs object corrupt and ignores the capability.

Step 2: Publish your category list​

Publish the active categories as a JSON object named Categories.json in the System/ container. The BWS reads it with a GET request to System/Categories.json.

[
    { "Name": "Traffic stop", "Id": "cat-001" },
    { "Name": "Arrest", "Id": "cat-002" },
    { "Name": "Interview", "Id": "cat-003" }
]

Each entry has a display Name and a stable Id. Keep the Id constant even if you rename a category, so existing recordings stay correctly associated.

As with the capabilities file, set the ETag header to the MD5 hash of the object. The BWS uses it as a checksum.

If ReadCategories isn't fulfilled, or if FullStoreAndReadSupport is enabled and Categories.json is missing, the BWS falls back to its built-in default category list.

Step 3: Understand the sync timing​

The BWS reads categories from your content destination once per day. After you add the ReadCategories capability and publish Categories.json, it can take up to 24 hours for cameras to pick up the new list.

To sync immediately, an administrator can re-upload the content destination configuration file in AXIS Body Worn Manager. This forces an instant read instead of waiting for the daily cycle.

Step 4: Read bookmark metadata from recordings​

When a user tags or bookmarks a recording, the BWS uploads a bookmark object into the recording container. The object is named bookmark_<Timestamp>_<ID>, and its body holds the free-text description in UTF-8. Because each bookmark has a timestamp, a recording can carry several.

Bookmark objects carry this metadata:

FieldDescription
CategoryIDThe ID of the category applied to the recording.
CategoryNameThe display name for that category.
TagsA semicolon-separated list of key:value pairs, for example TriggerOn:Button;SomeTag:SomeValue.
StartTimeWhen the marked segment begins, RFC 3339 (UTC). Defaults to the start of the recording if the user didn't set it.
EndTimeWhen the marked segment ends, RFC 3339 (UTC). Absent if the user didn't set it.
LocationUp to 64 bytes, if location is available.

A category bookmark always includes CategoryID, CategoryName, and StartTime. Be prepared for unknown keys and values in the Tags list – the BWS can add keys you don't recognize, so don't reject a bookmark just because a tag is unfamiliar.

Step 5: Handle categories from undocked cameras​

Categories aren't updated on a camera until it docks and syncs. A camera that's been in the field since before you changed your list can upload a recording tagged with a category you've already removed.

Handle this gracefully. Treat an unknown CategoryID as a valid-but-retired category rather than an error: keep the recording, store the CategoryName that came with it, and surface it in your interface instead of dropping the tag. This keeps the chain of custody intact even when your category list changes over time.

Verify the setup​

  1. Publish Categories.json, then trigger a sync by re-uploading the configuration file in AXIS Body Worn Manager.
  2. Tag a recording in the field (for example, with the AXIS Body Worn Assistant mobile app) and dock the camera.
  3. Watch for a bookmark object named bookmark_<Timestamp>_<ID> in the recording container, and confirm the CategoryID and CategoryName match a category you published.