Notifications

Introduction

The notification entity holds information about which user should have received a notification and what contents this notification has. Also, the seen and read information for a notification is stored in this table.

Notifications are related to many different entities as polymorphic relations which intratool will resolve by given keys.

An internal notification basically consists of:

  • Type
  • Target entity
  • Notifiable entity

to resolve which type of information should be dispatched to whom.

Model & Relations

Namespace

Modules\Notification\Entities\DatabaseNotification

Relations

Relation Key Type Relation Field(s)
Targetable (see below) notifiable MorphTo notifiable_type, notifiable_id
Notifiable (see below) targetable MorphTo targetable_type, targetable_id

Targetable types

Notifiable types

Types

  • infoboardPostCreated
  • infoboardPostUpdated
  • infoboardCommentCreated
  • calendarEventCreated
  • calendarEventUpdated
  • manualChapterEntryCreated
  • manualChapterEntryUpdated
  • generic

Note

Targetable types are keys for different entities existing in our system. Every targetable type listed here has itself a relationship to notifications which can be accessed with the key notifications.

Affected entities are marked with the trait TriggersNotifications.

List

Get a list of all Notifications thar are related to the current authenticated User.

Definition

GET /api/notifications

Example Request

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/notifications', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);

Example Response

[
  {
    "id": "3dbac57e-d7a5-43b6-ab7b-8999f3a209d9",
    "type": "calendarEventCreated",
    "notifiable_type": "user",
    "notifiable_id": 1,
    "targetable_type": "calendarEvent",
    "targetable_id": 16,
    "data": {
      "title": "Neuer Termin im Kalender von Max Mustermann",
      "body": "example body",
      "url": "/kalender/#event=6voprwjq5x3w83n9y2k740e8"
    },
    "seen_at": null,
    "read_at": null,
    "created_at": "2019-05-10 11:34:57",
    "updated_at": "2019-05-10 11:34:57"
  },
  {
    "id": "6ec5bc5f-af49-4383-9c27-bb05c26906de",
    "type": "calendarEventUpdated",
    "notifiable_type": "user",
    "notifiable_id": 1,
    "targetable_type": "calendarEvent",
    "targetable_id": 9,
    "data": {
      "title": "Aktualisierter Termin im Kalender von Max Mustermann",
      "body": "Example body",
      "url": "/kalender/#event=wke24qrd5918plv7zxmg8j06"
    },
    "seen_at": null,
    "read_at": null,
    "created_at": "2019-04-09 19:13:07",
    "updated_at": "2019-04-09 19:13:07"
  },
  {
    "id": "dd1de37c-33f6-4477-9769-e0ea46bf00c0",
    "type": "infoboardPostCreated",
    "notifiable_type": "user",
    "notifiable_id": 1,
    "targetable_type": "infoboardPost",
    "targetable_id": 134,
    "data": {
      "title": "Neuer Eintrag im Infoboard von Max Mustermann",
      "body": "Example body",
      "url": "/infoboard/eintrag/2pmeg69yq73kv71zv54rownx"
    },
    "seen_at": null,
    "read_at": null,
    "created_at": "2019-05-10 10:25:04",
    "updated_at": "2019-05-10 10:25:04"
  },
  {
    "id": "f0d244ac-28f2-4906-9918-e1f38fd5d777",
    "type": "infoboardPostUpdated",
    "notifiable_type": "user",
    "notifiable_id": 1,
    "targetable_type": "infoboardPost",
    "targetable_id": 133,
    "data": {
      "title": "Aktualisierter Eintrag im Infoboard von Max Mustermann",
      "body": "Example body",
      "url": "/infoboard/eintrag/wke24qrd5918dwlv7zxmg8j0"
    },
    "seen_at": null,
    "read_at": null,
    "created_at": "2019-04-29 15:45:29",
    "updated_at": "2019-04-29 15:45:29"
  },
  {
    "id": "fa2f06fb-add3-4269-98e9-0a8828cde9ac",
    "type": "manualChapterEntryUpdated",
    "notifiable_type": "user",
    "notifiable_id": 1,
    "targetable_type": "manualChapterEntry",
    "targetable_id": 58,
    "data": {
      "title": "Aktualisierter Eintrag im Handbuch von Max Mustermann",
      "body": "Example body",
      "url": "/handbuch/anleitungen/#telefonische-kontakte"
    },
    "seen_at": null,
    "read_at": null,
    "created_at": "2019-04-04 22:07:55",
    "updated_at": "2019-04-04 22:07:55"
  }
]

Count

Get the count of all Notifications the current authenticated User is allowed to view.

Definition

GET /api/notifications/count

Example Request

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/notifications/count', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);

Example Response

2

Get

Get a single Notification by id.

Definition

GET /api/notifications/{id}

Example Request

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/notifications/3dbac57e-d7a5-43b6-ab7b-8999f3a209d9', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);

Example Response

{
  "id": "3dbac57e-d7a5-43b6-ab7b-8999f3a209d9",
  "type": "calendarEventCreated",
  "notifiable_type": "user",
  "notifiable_id": 1,
  "targetable_type": "calendarEvent",
  "targetable_id": 16,
  "data": {
    "title": "Neuer Termin im Kalender von Max Mustermann",
    "body": "Example body",
    "url": "/kalender/#event=6voprwjq5x3w83n9y2k740e8"
  },
  "seen_at": null,
  "read_at": null,
  "created_at": "2019-05-10 11:34:57",
  "updated_at": "2019-05-10 11:34:57"
}

Get by target entity type

Gets all Notifications with the given target entity type. This enables you to get all notifications related to a specific type of content. e.g. infoboardPost

Definition

GET /api/notifications/type/{targetEntityType}

Example Request

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/notifications/infoboardPost', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);

Example Response

[
  {
    "id": "017b276f-65f9-4d00-9789-aa6aa0967203",
    "type": "infoboardPostCreated",
    "notifiable_type": "user",
    "notifiable_id": 1,
    "targetable_type": "infoboardPost",
    "targetable_id": 850,
    "data": {
      "title": "Neuer Eintrag im Infoboard von Max Mustermann",
      "body": "Bitte \u00c4nderungen ber\u00fccksichtigen",
      "url": "/infoboard/eintrag/kn978r25g376561dqwzem4px"
    },
    "seen_at": null,
    "read_at": null,
    "created_at": "2019-04-23 09:16:52",
    "updated_at": "2019-04-23 09:16:52"
  }
]

Get by target entity

Gets all Notifications with the given target entity type and target entity id. This enables you to get all notifications related to a specific content, e.g. a infoboard post.

Definition

GET /api/notifications/{targetEntityType}/{targetEntity}

Example Request

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/notifications/infoboardPost/850', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);

Example Response

[
  {
    "id": "017b276f-65f9-4d00-9789-aa6aa0967203",
    "type": "infoboardPostCreated",
    "notifiable_type": "user",
    "notifiable_id": 1,
    "targetable_type": "infoboardPost",
    "targetable_id": 850,
    "data": {
      "title": "Neuer Eintrag im Infoboard von Max Mustermann",
      "body": "Bitte \u00c4nderungen ber\u00fccksichtigen",
      "url": "/infoboard/eintrag/kn978r25g376561dqwzem4px"
    },
    "seen_at": null,
    "read_at": null,
    "created_at": "2019-04-23 09:16:52",
    "updated_at": "2019-04-23 09:16:52"
  }
]

Create

Create a new Notification.

This will dispatch a generic notification based on given information to all clients within the given departments and / or users and should be used with care.

Definition

POST /api/notifications

Request Keys

Key Type Default Description
title * string - The title of the notification.
body* string - The body text of the notification.
url * string - The url the dispatched notification should point to.
department_ids array The array of departments that should be targeted by the notification.
user_ids array - The array of users that should be targeted by the notification.

The fields with * are required.

Advanced Key-Specifications

  • department_ids - The array needs to contain valid department ids as integers.
  • user_ids - The array needs to contain valid user ids as integers.
  • user_ids - Needs to be filled if there are no department_ids

Example Request

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/notifications', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'title' => 'My own notification',
        'body' => 'The body of my notification.',
        'url' => 'https://my-internal-system.de/',
        'department_ids' => [3,4,5],
        'user_ids' => [4, 6, 8, 10]
    ]
]);

Example Response

{
  "status": "success",
  "data": []
}

Update for user

Update all unread notifications for the current authenticated user. This route will return the count of affected rows on success.

Note

Notifications are dispatched by our system when you save the information. Thus given, you can not update any content of notifications that are already dispatched.

Definition

PUT /api/notifications/

Request Keys

Key Type Default Description
seen_at * datetime NULL The timestamp when a user has seen the notification.
read_at* datetime NULL The timestamp when a user has read the notification.

The fields with * are required.

Advanced Key-Specifications

  • read_at - This value will also set the seen_at information if no value is given for seen_at

Example Request

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/notifications/', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'seen_at' => '2019-01-01 15:00:00'
    ]
]);

Example Response

{
  "status": "success",
  "data": [25]
}

Update

Update a Notification.

Definition

PUT /api/notifications/{id}

Request Keys

Key Type Default Description
seen_at * datetime NULL The timestamp when a user has seen the notification.
read_at* datetime NULL The timestamp when a user has read the notification.

The fields with * are required.

Advanced Key-Specifications

  • read_at - This value will also set the seen_at information if no value is given for seen_at

Example Request

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/notifications/017b276f-65f9-4d00-9789-aa6aa0967203', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'seen_at' => '2019-01-01 15:00:00'
    ]
]);

Example Response

{
  "status": "success",
  "data": [
    {
      "id": "017b276f-65f9-4d00-9789-aa6aa0967203",
      "type": "infoboardPostCreated",
      "notifiable_type": "user",
      "notifiable_id": 1,
      "targetable_type": "infoboardPost",
      "targetable_id": 850,
      "data": {
        "title": "Neuer Eintrag im Infoboard von Max Mustermann",
        "body": "Bitte \u00c4nderungen ber\u00fccksichtigen",
        "url": "/infoboard/eintrag/kn978r25g376561dqwzem4px"
      },
      "seen_at": "2019-01-01 15:00:00",
      "read_at": null,
      "created_at": "2019-04-23 09:16:52",
      "updated_at": "2019-04-23 09:16:52"
    }
  ]
}

Update by target entity type

Update all notifications of the current authenticated user for a specific type.

This enables you to mass update all notifications of a specific target type.

This route will return the count of affected rows on success.

Definition

PUT /api/notifications/{targetableType}

Request Keys

Key Type Default Description
seen_at * datetime NULL The timestamp when a user has seen the notification.
read_at* datetime NULL The timestamp when a user has read the notification.

The fields with * are required.

Advanced Key-Specifications

  • read_at - This value will also set the seen_at information if no value is given for seen_at

Example Request

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/notifications/infoboardPost', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'seen_at' => '2019-01-01 15:00:00'
    ]
]);

Example Response

{
  "status": "success",
  "data": [25]
}

Update by target entity

Update a unread notification of the current authenticated user by it's target. This is useful if you want to update a notification related to a specific content.

Definition

PUT /api/notifications/{targetableType}/{targetableId}

Request Keys

Key Type Default Description
seen_at * datetime NULL The timestamp when a user has seen the notification.
read_at* datetime NULL The timestamp when a user has read the notification.

The fields with * are required.

Advanced Key-Specifications

  • read_at - This value will also set the seen_at information if no value is given for seen_at

Example Request

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/notifications/infoboardPost/1', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'seen_at' => '2019-01-01 15:00:00'
    ]
]);

Example Response

{
  "status": "success",
  "data": [25]
}
Last Updated: 10/14/2019