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 Definition

Relations

Relation
Key
Type
Relation Field(s)

Targetable (see below)

notifiable

Morph to

notifiable_type, notifiable_id

Notifiable (see below)

targetable

Morph to

targetable_type, targetable_id

Targetable types

Notifiable types

Types

  • infoboardPostCreated

  • infoboardPostUpdated

  • infoboardCommentCreated

  • calendarEventCreated

  • calendarEventUpdated

  • ManualEntryCreated

  • ManualEntryUpdated

  • generic

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": "ManualEntryUpdated",
    "notifiable_type": "user",
    "notifiable_id": 1,
    "targetable_type": "ManualEntry",
    "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

List by target entity type

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

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"
  }
]

List by target entity

Lists all Notifications with the given target entity type and target entity ID. This enables you to get all notifications related to a specific content.

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"
  }
]

Show

Show 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"
}

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.

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