Activity API

Required fields

The following must be set before publishing:

• setApp() — Your app ID

• setType() — Must match an ISetting::getIdentifier()

• setAffectedUser() — The user who will see this activity

• setSubject() — A subject key and optional parameters

• setObject() — The object type, ID, and name

Optional fields

• setAuthor() — If unset, the current user is used

• setTimestamp() — If unset, the current time is used

• setMessage() — An additional message key and parameters

• setLink() — Should typically be set in IProvider::parse() instead

• setIcon() — Should typically be set in IProvider::parse() instead

Check responsibility

First, check whether the event belongs to your app. If not, throw UnknownActivityException so the activity app passes it to the next provider:

<?php
public function parse(string $language, IEvent $event, ?IEvent $previousEvent = null): IEvent {
    if ($event->getApp() !== 'myapp') {
        throw new \OCP\Activity\Exceptions\UnknownActivityException();
    }

    // ... parse the event
}

Set the parsed subject

At minimum, you must call setParsedSubject() with a translated, plain-text string:

$event->setParsedSubject(
    $this->l->t('You created %1$s', [$event->getObjectName()])
);

Additionally, you should call:

• setIcon() — A full URL to an icon for the activity

• setRichSubject() — A translated string with placeholders and a parameter array for rich display

Rich object strings

Rich subjects allow the UI to render interactive elements like file links and user avatars. The setRichSubject() method takes a translated string with placeholders and an array of typed objects:

$event->setRichSubject(
    $this->l->t('You added {file} to your favorites'),
    ['file' => [
        'type' => 'file',
        'id' => (string) $event->getObjectId(),
        'name' => basename($event->getObjectName()),
        'path' => $event->getObjectName(),
    ]]
);

Available object types and their required keys are defined in OCP\RichObjectStrings\Definitions.

Short vs. long translations

File-related activities support a short form (e.g. "Added to favorites") for the sidebar and a long form (e.g. "You added hello.jpg to your favorites") for the stream. Check IManager::isFormattingFilteredObject() to decide which form to use.

Merging activities

Related activities can be merged automatically using OCP\Activity\IEventMerger (inject via dependency injection). The merger combines events when all of the following are met:

• Same getApp()

• No message set (getMessage() is empty)

• Same getSubject()

• Same getObjectType()

• Time difference is less than 3 hours

• At most 5 events are merged

Do not merge events manually if these requirements are not met.

Capabilities

The API advertises its features via capabilities:

GET /ocs/v2.php/cloud/capabilities

<activity>
 <apiv2>
  <element>filters</element>
  <element>previews</element>
  <element>rich-strings</element>
 </apiv2>
</activity>

Endpoints

GET /ocs/v2.php/apps/activity/api/v2/activity
GET /ocs/v2.php/apps/activity/api/v2/activity/{filter}
GET /ocs/v2.php/apps/activity/api/v2/activity/filters

Parameters

HTTP status codes

Response headers

Link

URL for the next page of results, including all parameters: <https://cloud.example.com/ocs/v2.php/apps/activity/api/v2/activity/all?since=364>; rel="next"

X-Activity-First-Known

ID of the first known activity (when since was not recognized).

X-Activity-Last-Given

ID to use as since for the next request.

Activity element fields

Example response

{
  "activity_id": 1,
  "datetime": "2015-11-20T12:49:31+00:00",
  "app": "files",
  "type": "file_created",
  "user": "test1",
  "subject": "test1 created hello.txt",
  "subject_rich": {
    "0": "{user1} created {file1}",
    "1": {
      "user1": {
        "type": "user",
        "id": "test1",
        "name": "Test User"
      },
      "file1": {
        "type": "file",
        "id": 23,
        "name": "hello.txt",
        "path": "/test/hello.txt"
      }
    }
  },
  "icon": "https://cloud.example.com/apps/files/img/add-color.svg",
  "link": "https://cloud.example.com/apps/files/?dir=/test",
  "object_type": "files",
  "object_id": 23,
  "object_name": "/test/hello.txt",
  "previews": [
    {
      "source": "https://cloud.example.com/core/preview.png?file=/hello.txt&x=150&y=150",
      "link": "https://cloud.example.com/apps/files/?dir=/test&scrollto=hello.txt",
      "mimeType": "text/plain",
      "fileId": 23,
      "view": "files",
      "isMimeTypeIcon": false,
      "filename": "hello.txt"
    }
  ]
}