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

$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

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.

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

PreviousEntityPermissions NextReactions

Last updated 5 months ago