# SharedItems

## Introduction

`SharedItems` are used to share a targeted entity via a never-changing, unique URL.

Each `SharedItem` has a concrete [type](#types) which defines which targetables are allowed and which `config` information must/can be provided.

A SharedItem redirects to a URL defined by the targeted entity and [type](#types), when allowed by [redirect type](#redirect-types) and [EntityPermissions](https://docs.api.intratool.de/api-reference/entity-permissions).

## Model Definition

### Alias

`sharedItem`

### Relations

| Key                 | Relation                                                                            | Type       | Relation Field(s)                  |
| ------------------- | ----------------------------------------------------------------------------------- | ---------- | ---------------------------------- |
| `user`              | [User](https://docs.api.intratool.de/api-reference/users)                           | Belongs to | `user_id`                          |
| `targetable`        | `Targetable`                                                                        | Morph to   | `targetable_type`, `targetable_id` |
| `entityPermissions` | [EntityPermissions](https://docs.api.intratool.de/api-reference/entity-permissions) | Morph many |                                    |

### Types

* `calendarEvent` - Share a [CalendarEvent](https://docs.api.intratool.de/api-reference/calendar/calendar-events).
* `filemanagerDirectory` - Share a [FilemanagerDirectory](https://docs.api.intratool.de/api-reference/filemanager/filemanager-directories).
* `filemanagerFile` - Share a [FilemanagerFile](https://docs.api.intratool.de/api-reference/filemanager/filemanager-files).
* `form` - Share a [Form](https://docs.api.intratool.de/api-reference/forms/forms).
* `infoboardComment` - Share a [InfoboardComments](https://docs.api.intratool.de/api-reference/infoboard/infoboard-comments).
* `infoboardPost` - Share a [InfoboardPosts](https://docs.api.intratool.de/api-reference/infoboard/infoboard-posts).
* `manualChapter` - Share a [ManualChapter](https://docs.api.intratool.de/api-reference/manual/manual-chapters).
* `manualEntry` - Share a [ManualEntry](https://docs.api.intratool.de/api-reference/manual/manual-entries).

### Redirect Types

* `none` - Do not redirect to the targetable entity URL.
* `redirect` - Redirect to the targetable entity URL without granting access.
* `redirectWithGrantToken` - Redirect to the targetable entity URL and grant access for the entity by including a `GrantToken`.

### Targetable URL Types

`SharedItems` support multiple URL types to get a alternate redirect URL from the targetable entity. These targetable URL types can be requested by including them as URL parameter.

* `showFileContent` - Redirect to the file content URL of the targetable entity.
  * Supported types: `filemanagerFile`
* `downloadFileContent` - Redirect to the file download URL of the targetable entity.
  * Supported types: `filemanagerFile`

## List

Get a list of all `SharedItems`.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/shared-items`

**Example Request**

{% tabs %}
{% tab title="PHP" %}

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "uuid": "9ae0e631-37b4-4ef0-8a26-1526f329098a",
    "user_id": 1,
    "type": "manualEntry",
    "redirect_type": "redirectWithGrantToken",
    "targetable_type": "manualEntry",
    "targetable_id": 1,
    "config": {
      "show_subentries": true
    },
    "created_at": "2024-01-01 12:00:00",
    "updated_at": "2024-01-01 12:00:00",
    "deleted_at": null
  },
  {
    "uuid": "9ae33ff8-93b8-49b7-bbd6-7b44970c205f",
    "user_id": 1,
    "type": "form",
    "redirect_type": "redirect",
    "targetable_type": "form",
    "targetable_id": 1,
    "config": {},
    "created_at": "2024-01-01 13:00:00",
    "updated_at": "2024-01-01 13:00:00",
    "deleted_at": null
  }
]
```

## Show

Show a single `SharedItem` by `uuid`.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/shared-items/{uuid}`

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/shared-items/9ae33ff8-93b8-49b7-bbd6-7b44970c205f', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "uuid": "9ae33ff8-93b8-49b7-bbd6-7b44970c205f",
  "user_id": 1,
  "type": "form",
  "redirect_type": "redirect",
  "targetable_type": "form",
  "targetable_id": 1,
  "config": {},
  "created_at": "2024-01-01 13:00:00",
  "updated_at": "2024-01-01 13:00:00",
  "deleted_at": null
}
```

## \[Adm.] List

Get a list of all `SharedItems` the user is allowed to administrate.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/administration/shared-items`

**Example Request**

{% tabs %}
{% tab title="PHP" %}

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

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "uuid": "9ae0e631-37b4-4ef0-8a26-1526f329098a",
    "user_id": 1,
    "type": "manualEntry",
    "redirect_type": "redirectWithGrantToken",
    "targetable_type": "manualEntry",
    "targetable_id": 1,
    "config": {
      "show_subentries": true
    },
    "created_at": "2024-01-01 12:00:00",
    "updated_at": "2024-01-01 12:00:00",
    "deleted_at": null
  },
  {
    "uuid": "9ae33ff8-93b8-49b7-bbd6-7b44970c205f",
    "user_id": 1,
    "type": "form",
    "redirect_type": "redirect",
    "targetable_type": "form",
    "targetable_id": 1,
    "config": {},
    "created_at": "2024-01-01 13:00:00",
    "updated_at": "2024-01-01 13:00:00",
    "deleted_at": null
  }
]
```

## \[Adm.] Show

Show a single `SharedItem` the user is allowed to administrate by `uuid`.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/administration/shared-items/{uuid}`

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/administration/shared-items/9ae33ff8-93b8-49b7-bbd6-7b44970c205f', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "uuid": "9ae33ff8-93b8-49b7-bbd6-7b44970c205f",
  "user_id": 1,
  "type": "form",
  "redirect_type": "redirect",
  "targetable_type": "form",
  "targetable_id": 1,
  "config": {},
  "created_at": "2024-01-01 13:00:00",
  "updated_at": "2024-01-01 13:00:00",
  "deleted_at": null
}
```

## \[Adm.] Create

Create a new `SharedItem`.

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/administration/shared-items`

**Request Keys**

| Key               | Type            |     Default     | Description                                                                |
| ----------------- | --------------- | :-------------: | -------------------------------------------------------------------------- |
| `type` \*         | string          |        -        | The [type](#types) of the `SharedItem`.                                    |
| `redirect_type`   | string          | Based on `type` | The [redirect type](#redirect-types) of the `SharedItem`.                  |
| `targetable_type` | string          |        -        | The morph type for the `targetable` relation.                              |
| `targetable_id`   | integer, string |        -        | The morph ID for the `targetable` relation.                                |
| `config`          | array           | Based on `type` | The configuration for the `SharedItem`. Available values depend on `type`. |

Keys with `*` are required.

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/administration/shared-items', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'type' => 'filemanagerDirectory',
        'targetable_type' => 'filemanagerDirectory',
        'targetable_id' => 1
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "uuid": "9ae0b789-7da8-46ae-b426-f9a410e04aed",
    "user_id": 1,
    "type": "filemanagerDirectory",
    "redirect_type": "redirect",
    "targetable_type": "filemanagerDirectory",
    "targetable_id": 1,
    "config": {
      "show_subdirectories": false
    },
    "created_at": "2024-01-01 14:00:00",
    "updated_at": "2024-01-01 14:00:00",
    "deleted_at": null
  }
}
```

## \[Adm.] Update

Update an existing `SharedItem` by `uuid`.

**Definition**

<mark style="color:blue;">`PUT`</mark> `/api/administration/shared-items/{uuid}`

**Request Keys**

| Key             | Type   |     Default     | Description                                                                |
| --------------- | ------ | :-------------: | -------------------------------------------------------------------------- |
| `redirect_type` | string | Based on `type` | The [redirect type](#redirect-types) of the `SharedItem`.                  |
| `config`        | array  | Based on `type` | The configuration for the `SharedItem`. Available values depend on `type`. |

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/administration/shared-items/9ae0b789-7da8-46ae-b426-f9a410e04aed', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'redirect_type' => 'redirectWithGrantToken',
        'config' => [
              'show_subdirectories' => true
        ]
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "uuid": "9ae0b789-7da8-46ae-b426-f9a410e04aed",
    "user_id": 1,
    "type": "filemanagerDirectory",
    "redirect_type": "redirectWithGrantToken",
    "targetable_type": "filemanagerDirectory",
    "targetable_id": 1,
    "config": {
      "show_subdirectories": true
    },
    "created_at": "2024-01-01 14:00:00",
    "updated_at": "2024-02-02 15:00:00",
    "deleted_at": null
  }
}
```

## \[Adm.] Delete

Delete an existing `SharedItem` by `uuid`.

**Definition**

<mark style="color:red;">`DELETE`</mark> `/api/administration/shared-items/{uuid}`

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('DELETE', '/api/administration/shared-items/9ae0b789-7da8-46ae-b426-f9a410e04aed', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": null
}
```