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

infoboardPost (InfoboardPost)
infoboardComment (InfoboardComment)
calendarEvent (not documented yet).
manualChapterEntry (ManualChapterEntry)

Notifiable types

user (User)

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

PHP

php

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

Example Response

json

[
  {
    "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

PHP

php

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

Example Response

json

Get

Get a single Notification by id.

Definition

GET /api/notifications/{id}

Example Request

PHP

php

$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

json

{
  "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

PHP

php

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

Example Response

json

[
  {
    "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

PHP

php

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

Example Response

json

[
  {
    "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

PHP

php

$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

json

{
  "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

PHP

php

$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

json

{
  "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

PHP

php

$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

json

{
  "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

PHP

php

$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

json

{
  "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

PHP

php

$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

json

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

Notifications ​

Introduction ​

Model & Relations ​

List ​

Count ​

Get ​

Get by target entity type ​

Get by target entity ​

Create ​

Advanced Key-Specifications ​

Update for user ​

Advanced Key-Specifications ​

Update ​

Advanced Key-Specifications ​

Update by target entity type ​

Advanced Key-Specifications ​

Update by target entity ​

Advanced Key-Specifications ​

Notifications

Introduction

Model & Relations

List

Count

Get

Get by target entity type

Get by target entity

Create

Advanced Key-Specifications

Update for user

Advanced Key-Specifications

Update

Advanced Key-Specifications

Update by target entity type

Advanced Key-Specifications

Update by target entity

Advanced Key-Specifications