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

• infoboardPost (InfoboardPost)

• infoboardComment (InfoboardComment)

• calendarEvent (not documented yet).

• ManualEntry (ManualEntry)

Notifiable types

• user (User)

Types

• infoboardPostCreated

• infoboardPostUpdated

• infoboardCommentCreated

• calendarEventCreated

• calendarEventUpdated

• ManualEntryCreated

• ManualEntryUpdated

• generic

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

$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

PHP

$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

PHP

$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

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

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

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

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

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

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

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

$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

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

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

$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

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

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