# Annotator

# Data Model

# Introduction

The service can save and manage the notes added from a Digital user related to one or more entities of external services. With the same model it is possible to represent even folders, groups of identifiers of external entities that have logical relationship between them. To use the service it is necessary a user token that is compatible with teamsystemId.

# Model

Annotation is the base model in which the entire service is based. It has the following format:

```JSON
{
    "id": "string",
    "type": "string",
    "text": "string",
    "classification": "string",
    "referencing_date": "date",
    "reference_period": "string",
    "reference_type": "string",
    "reference_ids": [
      "string"
    ],
    "deleted": "boolean",
    "ownership": {
        "type": "string",
        "identifier": "string"
    },
    "item_classifier": "string",
    "inserted_by": "string",
    "inserted_at": "date",
    "modified_at": "date"
}
```

- **id**: unique identifier of the annotation, in UUID format
- **type**: specifies the annotation type. It can have the following values: 
    - **NOTE**
    - **FOLDER**
- **text**: contains information about the annotation. It has a maximum length of 1000 characters. Depending on the type, the information contained can be: 
    - **note text**: the text value, in case the annotation is of type NOTE
    - **folder name**: the name of the folder, in case the annotation is of type FOLDER
- **classification**: it can have the following possible values: 
    - **PERSONALIZZATO**
    - **BANCA**
    - **BILANCIO**
    - **DICHIARAZIONI**
    - **CONTENZIOSO**
- **referencing\_date**: the referencing date
- **reference\_period:** the year of reference
- **reference\_type**: the reference type, at the moment the only possible value is **DOCSTORE**
- **reference\_ids**: the ids of the related documents
- **deleted**: specifies if the annotation is deleted or not
- **ownership**: specifies the ownership of the annotation. It contains the following 2 fields: 
    - **type**: it can be **WS** or **ITEM**
    - **identifier**: the item identifier
- **item\_classifier**: it can be **ACCOUNTANT** or **COMPANY**
- **inserted\_by**: the name of the creator of the annotation
- **inserted\_at**: the timestamp of the annotation creation
- **modified\_at**: the timestamp of the last edit of the annotation

# API

# Get annotation

This API is responsible for retrieving the annotation with the given **id**.

<p class="callout info">**\[GET\]/api/v1/annotations/{id}**</p>

**Response:** Annotation.

### Header

Header used on this API are those taken from <span style="color: #3366ff;">[header standards of TS Digital.](https://digital-docs.ts-paas.com/books/utilizzo-api-tsdigital/page/linee-guida-generali-api-ts-digital)</span>

`Content-type` is accepted in `application/json`

### Query Parameters

Parameters used to make a successful request.

- **id**: Unique identifier associated with the requested annotation. (<span style="background-color: #ffffff; color: #ff0000;">***required***</span>)

### Body

No body is needed to make this request.

### Response

##### On successful response

If successful, the **API** responds with HTTP code **200(OK)** with the following body:

```JSON
{
  "id": "string",
  "type": "string",
  "text": "string",
  "classification": "string",
  "referencingDate": "string",
  "referencePeriod": "string",
  "referenceType": "string",
  "referenceIds": [
    "string"
  ],
  "deleted": true,
  "ownership": {
    "type": "WS",
    "identifier": "string"
  },
  "itemClassifier": "string",
  "insertedBy": "string",
  "insertedAt": "2022-10-28T13:01:00.754Z",
  "modifiedAt": "2022-10-28T13:01:00.754Z"
}
```

- **id**: unique identifier of the annotation
- **type**: specifies the annotation type.
- **text**: contains information about the annotation. Depending on the type, the information contained can be: 
    - **note text**: the text value, in case the annotation is of type **NOTE**
    - **folder name**: the name of the folder, in case the annotation is of type **FOLDER**
- **classification**: the classification of the annotation
- **referencing\_date**: the referencing date
- **reference\_period:** the year of reference
- **reference\_type**: the reference type, at the moment the only possible value is **DOCSTORE**
- **reference\_ids**: the ids of the related documents
- **deleted**: specifies if the annotation is deleted or not
- **ownership**: specifies the ownership of the annotation. It contains the following 2 fields: 
    - **type**: it can be **WS** or **ITEM**
    - **identifier**: the item identifier
- **item\_classifier**: it can be **ACCOUNTANT** or **COMPANY**
- **inserted\_by**: the name of the creator of the annotation
- **inserted\_at**: the timestamp of the annotation creation
- **modified\_at**: the timestamp of the last edit of the annotation

##### On error response

In the event of an error, the **API** responds with a body **JSON** with the following format:

```JSON
{
  "code": "string",
  "timestamp": "2022-10-28T13:01:00.754Z",
  "message": "string",
  "subErrors": [
    {}
  ]
}
```

- **code**: A string representation of the HTTP error code, linked with the returned http error
- **timestamp**: Date and time of the answer, expressed as a string.
- **message**: Message expressing error.

Possible errors are:

- **400**: The request is malformed (parameters with incorrect format, invalid or inconsistent parameters).
- **401**: An authorization token has not been provided or the authorization token provided is invalid (eg: it has expired).
- **403**: The provided token is valid, but the user is not authorized to perform the operation.
- **404**: No annotation found with the given id
- **500**: An unexpected error occurred.

# Create annotation

This API is responsible for creating an annotation.

<p class="callout info">**\[POST\]/api/v1/annotations**</p>

**Response:** The id of the newly created annotation.

### Header

Header used on this API are those taken from <span style="color: #3366ff;">[header standards of TS Digital.](https://digital-docs.ts-paas.com/books/utilizzo-api-tsdigital/page/linee-guida-generali-api-ts-digital)</span>

`Content-type` is accepted in `application/json`

### Query Parameters

No query parameters are needed to make this request.

### Body

```JSON
{
  "id": "string",
  "type": "string",
  "text": "string",
  "classification": "string",
  "ownership": {
    "type": "WS",
    "identifier": "string"
  },
  "referencing_date": "string",
  "reference_period": "string",
  "reference_type": "string",
  "reference_ids": [
    "string"
  ],
  "item_classifier": "string",
  "inserted_by": "string"
}
```

- **id**: the identifier of the annotation, if not specified a random UUID will be generated instead
- **type**: specifies the annotation type.
- **text**: contains information about the annotation. Depending on the type, the information contained can be: 
    - **note text**: the text value, in case the annotation is of type **NOTE**
    - **folder name**: the name of the folder, in case the annotation is of type **FOLDER**
- **classification**: the classification of the annotation
- **ownership**: specifies the ownership of the annotation. It contains the following 2 fields: 
    - **type**: it can be **WS** or **ITEM**
    - **identifier**: the item identifier
- **referencing\_date**: the referencing date
- **reference\_period:** the year of reference
- **reference\_type**: the reference type, at the moment the only possible value is **DOCSTORE**
- **reference\_ids**: the ids of the related documents
- **item\_classifier**: it can be **ACCOUNTANT** or **COMPANY**
- **inserted\_by**: the name of the creator of the annotation

### Response

##### On successful response

If successful, the **API** responds with HTTP code **200(OK)** with the following body:

```JSON
{
  "id": "string"
}
```

- **id**: the unique identifier of the annotation

##### On error response

In the event of an error, the **API** responds with a body **JSON** with the following format:

```JSON
{
  "code": "string",
  "timestamp": "2022-10-28T13:01:00.754Z",
  "message": "string",
  "subErrors": [
    {}
  ]
}
```

- **code**: A string representation of the HTTP error code, linked with the returned http error
- **timestamp**: Date and time of the answer, expressed as a string.
- **message**: Message expressing error.

Possible errors are:

- **400**: The request is malformed (parameters with incorrect format, invalid or inconsistent parameters).
- **401**: An authorization token has not been provided or the authorization token provided is invalid (eg: it has expired).
- **403**: The provided token is valid, but the user is not authorized to perform the operation.
- **500**: An unexpected error occurred.

# Update annotation

This API is responsible for updating an annotation.

<p class="callout info">**\[PATCH\]/api/v1/annotations/{id}**</p>

**Response:** The id of the updated annotation.

The update operation is only available to the user who created the annotation.

### Header

Header used on this API are those taken from <span style="color: #3366ff;">[header standards of TS Digital.](https://digital-docs.ts-paas.com/books/utilizzo-api-tsdigital/page/linee-guida-generali-api-ts-digital)</span>

`Content-type` is accepted in `application/json`

### Query Parameters

Parameters used to make a successful request.

- **id**: Unique identifier associated with the requested annotation. (<span style="color: #ff0000;">***required***</span>)

### Body

```JSON
{
  "type": "string",
  "text": "string",
  "classification": "string",
  "ownership": {
    "type": "WS",
    "identifier": "string"
  },
  "referencing_date": "string",
  "reference_period": "string",
  "reference_type": "string",
  "reference_ids": [
    "string"
  ],
  "item_classifier": "string"
}
```

Each of the fields are optional; only the field included in the request will be updated on the database.

- **type**: specifies the annotation type.
- **text**: contains information about the annotation. Depending on the type, the information contained can be: 
    - **note text**: the text value, in case the annotation is of type **NOTE**
    - **folder name**: the name of the folder, in case the annotation is of type **FOLDER**
- **classification**: the classification of the annotation
- **ownership**: specifies the ownership of the annotation. It contains the following 2 fields: 
    - **type**: it can be **WS** or **ITEM**
    - **identifier**: the item identifier
- **referencing\_date**: the referencing date
- **reference\_period:** the year of reference
- **reference\_type**: the reference type, at the moment the only possible value is **DOCSTORE**
- **reference\_ids**: the ids of the related documents
- **item\_classifier**: it can be **ACCOUNTANT** or **COMPANY**

### Response

##### On successful response

If successful, the **API** responds with HTTP code **200(OK)** with the following body:

```JSON
{
  "id": "string"
}
```

- **id**: the unique identifier of the annotation

##### On error response

In the event of an error, the **API** responds with a body **JSON** with the following format:

```JSON
{
  "code": "string",
  "timestamp": "2022-10-28T13:01:00.754Z",
  "message": "string",
  "subErrors": [
    {}
  ]
}
```

- **code**: A string representation of the HTTP error code, linked with the returned http error
- **timestamp**: Date and time of the answer, expressed as a string.
- **message**: Message expressing error.

Possible errors are:

- **400**: The request is malformed (parameters with incorrect format, invalid or inconsistent parameters).
- **401**: An authorization token has not been provided or the authorization token provided is invalid (eg: it has expired).
- **403**: The provided token is valid, but the user is not authorized to perform the operation.
- **404**: No annotation found with the given id.
- **500**: An unexpected error occurred.

# Update references

This API is responsible for updating an annotation`s references.

<p class="callout info">**\[PUT\]/api/v1/annotations/{id}/{operation}**</p>

**Response:** The id of the updated annotation.

### Header

Header used on this API are those taken from <span style="color: #3366ff;">[header standards of TS Digital.](https://digital-docs.ts-paas.com/books/utilizzo-api-tsdigital/page/linee-guida-generali-api-ts-digital)</span>

`Content-type` is accepted in `application/json`

### Query Parameters

Parameters used to make a successful request.

- **id**: Unique identifier associated with the requested annotation. (<span style="color: #ff0000;">***required***</span>)
- **operation**: it can be **ATTACH** in case there need to be added references and **DETACH** in case the references need to be removed. (<span style="color: #ff0000;">***required***</span>)

### Body

```JSON
{
  "reference_ids": [
    "string"
  ]
}
```

- **reference\_ids**: the ids of the related documents to be added or removed

### Response

##### On successful response

If successful, the **API** responds with HTTP code **200(OK)** with the following body:

```JSON
{
  "id": "string"
}
```

- **id**: the unique identifier of the annotation

##### On error response

In the event of an error, the **API** responds with a body **JSON** with the following format:

```JSON
{
  "code": "string",
  "timestamp": "2022-10-28T13:01:00.754Z",
  "message": "string",
  "subErrors": [
    {}
  ]
}
```

- **code**: A string representation of the HTTP error code, linked with the returned http error
- **timestamp**: Date and time of the answer, expressed as a string.
- **message**: Message expressing error.

Possible errors are:

- **400**: The request is malformed (parameters with incorrect format, invalid or inconsistent parameters).
- **401**: An authorization token has not been provided or the authorization token provided is invalid (eg: it has expired).
- **403**: The provided token is valid, but the user is not authorized to perform the operation.
- **404**: No annotation found with the given id.
- **500**: An unexpected error occurred.

# Delete annotation

This API is responsible for soft deleting an annotation.

<p class="callout info">**\[DELETE\]/api/v1/annotations/{id}**</p>

**Response:** The id of the deleted annotation.

### Header

Header used on this API are those taken from <span style="color: #3366ff;">[header standards of TS Digital.](https://digital-docs.ts-paas.com/books/utilizzo-api-tsdigital/page/linee-guida-generali-api-ts-digital)</span>

`Content-type` is accepted in `application/json`

### Query Parameters

Parameters used to make a successful request.

- **id**: Unique identifier associated with the annotation to be deleted. (<span style="background-color: #ffffff; color: #ff0000;">***required***</span>)

### Body

No body is needed to make this request.

### Response

##### On successful response

If successful, the **API** responds with HTTP code **200(OK)** with the following body:

```JSON
{
  "id": "string"
}
```

- **id**: the unique identifier of the deleted annotation

##### On error response

In the event of an error, the **API** responds with a body **JSON** with the following format:

```JSON
{
  "code": "string",
  "timestamp": "2022-10-28T13:01:00.754Z",
  "message": "string",
  "subErrors": [
    {}
  ]
}
```

- **code**: A string representation of the HTTP error code, linked with the returned http error
- **timestamp**: Date and time of the answer, expressed as a string.
- **message**: Message expressing error.

Possible errors are:

- **400**: The request is malformed (parameters with incorrect format, invalid or inconsistent parameters).
- **401**: An authorization token has not been provided or the authorization token provided is invalid (eg: it has expired).
- **403**: The provided token is valid, but the user is not authorized to perform the operation.
- **404**: No annotation found with the given id.
- **500**: An unexpected error occurred.

# Search annotations

This API is responsible for searching annotations.

<p class="callout info">**\[POST\]/api/v1/annotations/search**</p>

**Response:** A list of the requested annotations.

### Header

Header used on this API are those taken from <span style="color: #3366ff;">[header standards of TS Digital.](https://digital-docs.ts-paas.com/books/utilizzo-api-tsdigital/page/linee-guida-generali-api-ts-digital)</span>

`Content-type` is accepted in `application/json`

### Query Parameters

No query parameters are needed to make this request.

### Body

```JSON
{
  "limit": "integer",
  "from": "integer",
  "ownership": {
    "type": "WS",
    "identifier": "string"
  },
  "sort": {
    "name": "CREATED",
    "order": "ASC"
  },
  "type": "string",
  "reference_ids": [
    "string"
  ],
  "show_deleted": true,
  "search_words": "string"
}
```

- **limit**: limits the number of annotations in the response. The default value is 100.
- **from**: specifies the value of the field next from a pagination call. The default value is 0.
- **ownership**: specifies the ownership of the annotation. It contains the following 2 fields: 
    - **type**: it can be **WS** or **ITEM**
    - **identifier**: the item identifier
- **sort**: specifies the sorting order. The **order** field specifies if the sorting has to be in ascending (**ASC**) or descending (**DESC**) order. The other field, **name**, can have the following values: 
    - **CREATED**: sorting on the creation date.
    - **UPDATED**: sorting on the last modified date.
    - **ALPHABETICAL**: sorting on alphabetical order.
- **type**: specifies the annotation type, **FOLDER** or **NOTE**.
- **reference\_ids**: the ids of the related documents
- **show\_deleted**: shows the deleted annotations if set to true. Default value is false.
- **search\_words**: search for terms in the text field of the entity. The default value is all.

### Response

##### On successful response

If successful, the **API** responds with HTTP code **200(OK)** with the following body:

```JSON
{
  "count": "integer",
  "data": [
    {
      "id": "string",
      "type": "string",
      "text": "string",
      "classification": "string",
      "referencingDate": "string",
      "referencePeriod": "string",
      "referenceType": "string",
      "referenceIds": [
        "string"
      ],
      "deleted": true,
      "ownership": {
        "type": "WS",
        "identifier": "string"
      },
      "itemClassifier": "string",
      "insertedBy": "string",
      "insertedAt": "2022-10-31T15:02:44.115Z",
      "modifiedAt": "2022-10-31T15:02:44.115Z"
    }
  ]
}
```

- **count**: the number of the annotations returned by the search that fulfill the search filters.
- **data**: an list containing all the annotations that fulfill the search filters.

The elements inside the **data** list contain the following fields:

- **id**: unique identifier of the annotation, in UUID format
- **type**: specifies the annotation type. It can have the following values: 
    - **NOTE**
    - **FOLDER**
- **text**: contains information about the annotation. It has a maximum length of 1000 characters. Depending on the type, the information contained can be: 
    - **note text**: the text value, in case the annotation is of type NOTE
    - **folder name**: the name of the folder, in case the annotation is of type FOLDER
- **classification**: it can have the following possible values: 
    - **PERSONALIZZATO**
    - **BANCA**
    - **BILANCIO**
    - **DICHIARAZIONI**
    - **CONTENZIOSO**
- **referencing\_date**: the referencing date
- **reference\_period:** the year of reference
- **reference\_type**: the reference type, at the moment the only possible value is **DOCSTORE**
- **reference\_ids**: the ids of the related documents
- **deleted**: specifies if the annotation is deleted or not
- **ownership**: specifies the ownership of the annotation. It contains the following 2 fields: 
    - **type**: it can be **WS** or **ITEM**
    - **identifier**: the item identifier
- **item\_classifier**: it can be **ACCOUNTANT** or **COMPANY**
- **inserted\_by**: the name of the creator of the annotation
- **inserted\_at**: the timestamp of the annotation creation
- **modified\_at**: the timestamp of the last edit of the annotation

##### On error response

In the event of an error, the **API** responds with a body **JSON** with the following format:

```JSON
{
  "code": "string",
  "timestamp": "2022-10-28T13:01:00.754Z",
  "message": "string",
  "subErrors": [
    {}
  ]
}
```

- **code**: A string representation of the HTTP error code, linked with the returned http error
- **timestamp**: Date and time of the answer, expressed as a string.
- **message**: Message expressing error.

Possible errors are:

- **400**: The request is malformed (parameters with incorrect format, invalid or inconsistent parameters).
- **401**: An authorization token has not been provided or the authorization token provided is invalid (eg: it has expired).
- **403**: The provided token is valid, but the user is not authorized to perform the operation.
- **500**: An unexpected error occurred.