![Advanced-UI](https://img.shields.io/static/v1?label=UI&message=Advanced&color=lightgrey)
![DB-Table](https://img.shields.io/static/v1?label=DB&message=Table&color=red)

This extension allows to versioning infofields of an asset. Prior to installing the plugin the database table at the end has to be created.

[MINITOC]

## Properties

To be configured in {home}/appserver/conf/custom.properties

##### versionedInfofields.license

> type: String, **required: yes**, default: -

The license key for the plugin (product: versionedInfofields), provided by *brix*.

##### versionedInfofields.visibleForGroups

> type: list of long (comma separated), required: no, default: -

Restrict the use of the plugin to this user group IDs (superadmins will always see it in any case). If not set, all users can use the plugin.

##### versionedInfofields.editorGroups

> type: list of long (comma separated), required: no, default: -

Restrict the use of the editor to this user group IDs (superadmins can always use it). If not set, all users can use the editor.

##### versionedInfofields.versionedInfofields

> type: list of long (comma separated), **required: yes**, default: -

List of the versioned information field ids.

##### versionedInfofields.authorization

> type: boolean, required: no, default: false

Enables or disables the CELUM authentication of the versioned infofields api.

##### versionedInfofields.versionDataSecret

> type: String, required: no, default: false

If a secret is specified, all requests to the Version Data Controller need to send a valid secret or they will be denied.

> > > > > > The secret can be sent as a GET-Parameter, alternatively you can pass the secret as an `Authentication` header, e.g. `Authentication: Bearer <your-secret>`

##### versionedInfofields.versionDataApiUser

> type: boolean, required: no, default: false

User that will be used for the Version Data Controller. If not set, the api user will be used.

### Version Editor

##### versionedInfofields.editorEnabled=

> type: boolean, required: no, default: false

Enables the version editor context menu entry (Versioned Infofields)

##### versionedInfofields.visibleOnVersion0=

> type: boolean, required: no, default: true

Show the version editor menu entry if the asset has version 0.

##### versionedInfofields.downloadFormats=

> type: list of downloadformat ids, required: no, default: -

Restrict the available download formats in the version viewer. If empty, the downloadformats are not restricted.

##### versionedInfofields.editorSearchExpression=

> type: boolean, required: no, default: false

Restricts the version editor tab in the version viewer to assets included in a search expression (see [Search Util 2](https://docs.brix.ch/celum_extensions/search_util_2)).

### Migration

There are system tasks to trigger the import and export.

#### Export

Exports asset data to an Excel file, so that it can be used for the import.

##### versionedInfofields.migration.export.dateFormat

> type: string, required: no, default: yyyy-MM-dd

The date format to use for the export (Java's SimpleDateFormat syntax).

##### versionedInfofields.migration.export.filter

> type: string, required: yes, default: -

The filter to use for the export (see [Search Util 2](https://docs.brix.ch/celum_extensions/search_util_2)).

##### versionedInfofields.migration.export.file

> type: string, required: yes, default: -

A file path where the file is exported. The file should end in `.xlsx`. E.g. C:/celum/migration/export.xlsx

##### versionedInfofields.migration.export.fields

> type: string, required: yes, default: -

A comma-separated list of fields to export. If versionId is missing only the active values are exported. Possible values:

- assetId
- assetVersion
- assetName
- assetType
- filename
- info_{id}: the information field with {id}, e.g. info_123

#### Import

Import versioned fields. Important to know:

- Only Excel files are supported and the file ending has to be `.xlsx`.
- The values for the currently active version are directly written on the asset.
- Localized information fields are supported, but currently it is only possible to write the default language.
- All information field columns have to have the information field id in square brackets in the end of the header, e.g. "Description [123]".
- Dropdowns have to have their item id in square brackets in the end, e.g. "Public [2]".
- Node referencing information fields are comma- or linebreak-separated values that either have the node id in square brackets in the end, e.g. "Dog [33], Cat [778]", or it is also possible to match by name only having "Dog, Cat". **To match by name the information field id in the header has to be followed by an "n", e.g. "Pets [123n]".**
- Text cells are always preferred (they guarantee that the value is returned as it is seen in the Excel file)
- Formulas are currently not supported.
- The import creates a copy of the import file with the same name appending "-processed" and at the same location. In this file the import state and possible errors can be seen for each row. E.g. after importing "import.xlsx" we will find "import-processed.xlsx" at the same location. The processed file can be corrected and imported again.

##### versionedInfofields.migration.import.dateFormat

> type: string, required: no, default: yyyy-MM-dd

The date format to use for the import (Java's SimpleDateFormat syntax).

##### versionedInfofields.migration.import.path

> type: string, required: yes, default: -

A folder for the import. The import task will look for *.xlsx files in this folder and if there is only one it will continue with this file, otherwise there is an error.

##### versionedInfofields.migration.import.onlySetValueIfDifferent

> type: boolean, required: no, default: true

Only set the values if they are different from the current ones.

##### versionedInfofields.migration.import.ignoreImportedRows

> type: boolean, required: no, default: true

Ignore imported rows. This is useful if a processed file is imported again. All rows with status "imported" will be ignored.

## API

### Versioned Infofields Controller

##### GET versionedInfofields/

Get a list of all versioned infofield values.

###### Parameters

No parameters

###### Response

```json
[
  {
    "assetId": 0,
    "version": 0,
    "fieldId": 0,
    "value": {}
  }
]
```

##### POST /versionedInfofields/

Save or update a versioned infofield value.

###### Parameters

| Name        | Description                                           |
| ----------- | ----------------------------------------------------- |
| RequestBody | {"assetId": 0,"fieldId": 0,"value": {},"version": 0 } |

###### Response

1

##### POST /versionedInfofields/values

Save or update multiple versioned infofield values.

###### Parameters

| Name        | Description                                             |
| ----------- | ------------------------------------------------------- |
| RequestBody | [{"assetId": 0,"fieldId": 0,"value": {},"version": 0 }] |

###### Response

1

##### GET /versionedInfofields/infofields

Get a list of all verisoned infofields.

###### Parameters

No parameters

###### Response

```json
[
    {
        "name": "infofield_name",
        "labels": {
            "_class": "com.celum.api.model.LocalizedValue",
            "values": {
                "en": "English Label"
            }
        },
        "editorInformation": {
            "_class": "com.celum.api.model.LocalizedValue",
            "values": {}
        },
        "readerInformation": {
            "_class": "com.celum.api.model.LocalizedValue",
            "values": {}
        },
        "required": false,
        "rootNode": {
            "_class": "com.celum.api.identifiers.NodeId",
            "id": 0
        },
        "nodeChooserViewable": true,
        "kind": "NODE_REFERENCE",
        "id": {
            "_class": "com.celum.api.identifiers.InformationFieldId",
            "id": 0
        },
        "maxSelections": -1,
        "rootSelectable": false,
        "valueType": "com.celum.api.model.informationfields.NodeReferences"
    },
    {
        "name": "dropdown",
        "labels": {
            "_class": "com.celum.api.model.LocalizedValue",
            "values": {
                "en": "Dropdown"
            }
        },
        "editorInformation": {
            "_class": "com.celum.api.model.LocalizedValue",
            "values": {}
        },
        "readerInformation": {
            "_class": "com.celum.api.model.LocalizedValue",
            "values": {}
        },
        "required": false,
        "options": {
            "en": [
                {
                    "key": 0,
                    "displayText": "option 0"
                }
            ]
        },
        "kind": "DROP_DOWN",
        "id": {
            "_class": "com.celum.api.identifiers.InformationFieldId",
            "id": 0
        },
        "sortOder": "MANUAL",
        "valueType": "java.lang.Integer"
    },
    {
        "name": "text",
        "labels": {
            "_class": "com.celum.api.model.LocalizedValue",
            "values": {
                "en": "Text"
            }
        },
        "editorInformation": {
            "_class": "com.celum.api.model.LocalizedValue",
            "values": {}
        },
        "readerInformation": {
            "_class": "com.celum.api.model.LocalizedValue",
            "values": {}
        },
        "required": false,
        "minLength": 0,
        "maxLength": 255,
        "validationPattern": null,
        "kind": "TEXT",
        "id": {
            "_class": "com.celum.api.identifiers.InformationFieldId",
            "id": 803
        },
        "valueType": "java.lang.String"
    }
]
```

##### GET /versionedInfofields/{assetId}

Get a list of all verisoned infofield values of an asset.

###### Parameters

| Name    | Description |
| ------- | ----------- |
| assetId | Integer     |

###### Response

```json
[
  {
    "assetId": 0,
    "version": 0,
    "fieldId": 0,
    "value": {}
  }
]
```

##### POST /versionedInfofields/{assetId}

Save or update multiple versioned infofield values of an asset.

###### Parameters

| Name        | Description                                |
| ----------- | ------------------------------------------ |
| assetId     | Integer                                    |
| RequestBody | [{"fieldId": 0,"value": {},"version": 0 }] |

###### Response

1

##### DELETE /versionedInfofields/{assetId}

Delete all versioned infofield values of an asset.

###### Parameters

| Name    | Description |
| ------- | ----------- |
| assetId | Integer     |

###### Response

1

##### GET /versionedInfofields/{assetId}/{version}

Ger all versioned infofield values of a version of an asset.

###### Parameters

| Name    | Description |
| ------- | ----------- |
| assetId | Integer     |
| version | Integer     |

###### Response

```json
[
  {
    "assetId": 0,
    "version": 0,
    "fieldId": 0,
    "value": {}
  }
]
```

##### POST /versionedInfofields/{assetId}/{version}

Save or update multiple versioned infofield values of a version of an asset.

###### Parameters

| Name        | Description                   |
| ----------- | ----------------------------- |
| assetId     | Integer                       |
| version     | Integer                       |
| RequestBody | [{"fieldId": 0,"value": {} }] |

###### Response

```json
[
  {
    "assetId": 0,
    "version": 0,
    "fieldId": 0,
    "value": {}
  }
]
```

##### DELETE /versionedInfofields/{assetId}/{version}

Delete all versioned infofield values of a version of an asset.

###### Parameters

| Name    | Description |
| ------- | ----------- |
| assetId | Integer     |
| version | Integer     |

###### Response

1

##### GET /versionedInfofields/{assetId}/{version}/{fieldId}

Get a specific versioned infofield value of an infofield of a version of an asset.

###### Parameters

| Name    | Description |
| ------- | ----------- |
| assetId | Integer     |
| version | Integer     |
| fieldId | Integer     |

###### Response

```json
{
  "assetId": 0,
  "version": 0,
  "fieldId": 0,
  "value": {}
}
```

##### POST /versionedInfofields/{assetId}/{version}/{fieldId}

Save or update a specific infofield value of an infofield of a version of an asset.

###### Parameters

| Name        | Description   |
| ----------- | ------------- |
| assetId     | Integer       |
| version     | Integer       |
| fieldId     | Integer       |
| RequestBody | {"value": {}} |

###### Response

1

##### DELETE /versionedInfofields/{assetId}/{version}/{fieldId}

Delete a specific infofield value of an infofield of a version of an asset.

###### Parameters

| Name    | Description |
| ------- | ----------- |
| assetId | Integer     |
| version | Integer     |
| fieldId | Integer     |

###### Response

1

### Version Data Controller

##### GET /versionedInfofields/versiondata/{assetId}/{version}?secret={your-secret}

Get the version data of a version of an asset

###### Parameters

| Name    | Description                     |
| ------- | ------------------------------- |
| assetId | Integer                         |
| version | Integer                         |
| secret  | String or Authentication Header |

> > > > > > The secret can be send as a GET-Parameter, alternatively you can pass the secret as an `Authentication` header, e.g. `Authentication: Bearer <your-secret>`

###### Response

```json
{
  "assetId": 0,
  "version": 0,
  "versionStatus": 0,
  "infofield1": "<infofield1-value>",
  "infofield2": "<infofield2-value>",
  "infofield3": "<infofield3-value>",
  "preview": "<preview-url>"
}
```

## Table

#### MYSQL

    CREATE TABLE versioned_infofields (
        ims_id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
        ims_asset_id BIGINT,
        ims_version INT(6),
        ims_field_id INT(6),
        ims_longtext_value LONGTEXT,
        ims_int_value INT,
        ims_text_value TEXT,
        ims_double_value DOUBLE,
        ims_bigint_value BIGINT,
        ims_date_value DATETIME(6),
        ims_tinyint_value TINYINT(1),
        ims_locale VARCHAR(2)
    );

#### MSSQL

    CREATE TABLE versioned_infofields (
        ims_id BIGINT IDENTITY PRIMARY KEY,
        ims_asset_id BIGINT,
        ims_version INT(6),
        ims_field_id INT(6),
        ims_longtext_value LONGTEXT,
        ims_int_value INT,
        ims_text_value TEXT,
        ims_double_value DOUBLE,
        ims_bigint_value BIGINT,
        ims_date_value DATETIME(6),
        ims_tinyint_value TINYINT(1),
        ims_locale VARCHAR(2)
    );

## Compatibility Matrix

| Versioned Infofields | CELUM (min. version) |
| -------------------- | -------------------- |
| 1.0                  | 5.13.4               |

## Release Notes

#### 1.0

> Release: 2022-01-10

Initial Version

#### 1.0

> Release: 2022-03-03

editorGroups property added