Versions Compared

Old Version 1

changes.mady.by.user Rasmus Hjelmberg Duemose Hansen

Saved on

compared with

New Version Current

changes.mady.by.user Rasmus Hjelmberg Duemose Hansen

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

There are generally 3 apis you should APIs to be aware of when working with combo values. Each API covers slightly different use cases. Those use cases are outlined in this document.

CRUD on combo values

This is the most general use case, where you don’t care about the combo values for specific cases and want to manage which combo values are availablean integration should manage the combo node definitions.

This requires the Editor_SystemTools_Metadata role.

There are 6 endpoints to be aware of here. These should feel natural if you have worked with REST before.

Response properties

Name

Type

Description

id

int

A language-independent id for this combo value.

optionValue

string

A language-independent string value for this combo value.

sortIndex

int

A value indicating how this node should be sorted in relation to all other combo value.

metaFieldId

int

The metafield id of the metafield this combo value belongs to.

itemId

int

The itemId of the combo value.

itemGuid

string/guid/uuid

The itemGuid of the combo value.

labels

dictionary

The translations of this combo value. The key is the languageId.

labels.label

string

The title/name/label of the combo value in this language.

labels.languageId

int

The language id of this translation.

labels.comboValueId

int

The language specific id of this combo value.

Get all combo values

URL: /digizuitecore/legacyservice/api/admin/combo-values

...

Expand
titleExample

Request

Code Block
GET https://<my-dam>/digizuitecore/legacyservice/api/admin/combo-values
Authorization: AccessKey MIIC...dEK

Response

Code Block
languagejson
[
  {
    "id": 50239,
    "optionValue": "five",
    "sortIndex": 0,
    "metaFieldId": 50398,
    "itemId": 20460,
    "itemGuid": "8129443f-be24-4c48-9579-b8c91be41385",
    "labels": {
      "1": {
        "label": "fem",
        "languageId": 1,
        "comboValueId": 50239
      },
      "3": {
        "label": "five",
        "languageId": 3,
        "comboValueId": 50240
      }
    }
  }
]

Get a specific combo value

URL: /digizuitecore/legacyservice/api/admin/combo-values/{id}

...

Expand
titleExample

Request

Code Block
GET https://<my-dam>/digizuitecore/legacyservice/api/admin/combo-values/50239
Authorization: AccessKey MIIC...dEK

Response

Code Block
languagejson
{
  "id": 50239,
  "optionValue": "five",
  "sortIndex": 0,
  "metaFieldId": 50398,
  "itemId": 20460,
  "itemGuid": "8129443f-be24-4c48-9579-b8c91be41385",
  "labels": {
    "1": {
      "label": "fem",
      "languageId": 1,
      "comboValueId": 50239
    },
    "3": {
      "label": "five",
      "languageId": 3,
      "comboValueId": 50240
    }
  }
}

Create a new combo value

URL: /digizuitecore/legacyservice/api/admin/combo-values

...

This api is also available as a bulk variant, that takes an array of the objects described here: /digizuitecore/legacyservice/api/admin/combo-values/bulk-create

Request parameters:

Name

Type

Description

optionValue

string

A language-independent string value for this combo value.

sortIndex

int

A value indicating how this combo value should be sorted in relation to all other combo values.

metaFieldId

int

The metafield id of the metafield this combo valuebelongs to.

accessRightsMode

enum, string, one of:

  • CalculateAutomatically

  • DoNothing

Controls how access rights/item security is created when this combo value is created.

  • CalculateAutomatically: Security is inherited from the metafield.

  • DoNothing: No item security is created for this combo value, which means nobody can access it. If you use this, you should make sure to create item security entries yourself.

If not specified, CalculateAutomatically will be used.

labels

array of object

The translations that should be created for this object.

labels.languageId

int

The id of the language this translation is for.

labels.label

string

The language specific translation of this value.

Expand
titleExample

Request

Code Block
POST https://<my-dam>/digizuitecore/legacyservice/api/admin/combo-values
Authorization: AccessKey MII...HVtw=
Content-Type: application/json

{
  "optionValue": "api-test",
  "sortIndex": 0,
  "labels": [
    {
      "label": "Api test - English",
      "languageId": 3
    },
    {
      "label": "Api test - Danish",
      "languageId": 1
    }
  ],
  "metaFieldId": 10192,
  "accessRightsMode": "CalculateAutomatically"
}

Response

Code Block
languagejson
{
  "id": 50243,
  "optionValue": "api-test",
  "sortIndex": 0,
  "metaFieldId": 10192,
  "itemId": 20500,
  "itemGuid": "9f2bfb9e-3d40-4940-be8e-d6d325c4c925",
  "labels": {
    "1": {
      "label": "Api test - Danish",
      "languageId": 1,
      "comboValueId": 50243
    },
    "3": {
      "label": "Api test - English",
      "languageId": 3,
      "comboValueId": 50244
    }
  }
}

Update a combo value

URL: /digizuitecore/legacyservice/api/admin/combo-values/{comboId}

...

Auth required: YES

Request parameters:

Name

Type

Description

optionValue

string

A language-independent string value for this combo value.

sortIndex

int

A value indicating how this combo value should be sorted in relation to all other combo values.

comboId

int

A language-independent id for this combo value.

Expand
titleExample

Request

Code Block
PUT https://<my-dam>/digizuitecore/legacyservice/api/admin/combo-values/50243
Authorization: AccessKey MII...HVtw=
Content-Type: application/json

{
  "optionValue": "api-test-updated",
  "sortIndex": 42,
  "comboId": 50243
}

Response

Code Block
{
  "id": 50243,
  "optionValue": "api-test-updated",
  "sortIndex": 42,
  "metaFieldId": 10192,
  "itemId": 20500,
  "itemGuid": "9f2bfb9e-3d40-4940-be8e-d6d325c4c925",
  "labels": {
    "1": {
      "label": "Api test - Danish",
      "languageId": 1,
      "comboValueId": 50243
    },
    "3": {
      "label": "Api test - English",
      "languageId": 3,
      "comboValueId": 50244
    }
  }
}

Update a combo value translation

URL: /digizuitecore/legacyservice/api/admin/combo-values/{comboId}/{languageId}

...

Auth required: YES

Request parameters:

Name

Type

Description

label

string

The translated label for the combo in the specified language.

comboId

int

The language-independent id for this combo value.

languageId

int

The id of the language to update the combo in

Expand
titleExample

Request

Code Block
PUT https://<my-dam>/digizuitecore/legacyservice/api/admin/combo-values/50243/3
Authorization: AccessKey MII...Vtw=
Content-Type: application/json

{
  "label": "Api test - English - updated"
}

Response

Code Block
languagejson
{
  "label": "Api test - English - updated",
  "languageId": 3,
  "comboId": 50243,
  "comboValueId": 50244
}

Delete a combo value

URL: /digizuitecore/legacyservice/api/admin/combo-values/{comboId}

...

Auth required: YES

Request parameters:

Name

Type

Description

comboId

(tick)

int

The language-independent id for this combo value.

synchronous

bool

If false or not passed, the value will be deleted in the background. This means you can still get the value back in the api and can still keep using it for a little while.

If true, the request will be held until the api is completely done cleaning up.

Expand
titleExample

Request

Code Block
DELETE https://<my-dam>/digizuitecore/legacyservice/api/admin/combo-values/50243
Authorization: AccessKey MII...Vtw=

Response

<Empty response>

Get combos to display

URL:

  • /digizuitecore/legacyservice/api/combo/values/metafield/{metafieldId}

  • /digizuitecore/legacyservice/api/combo/values/metafield/{metafieldId}/assignable

  • /digizuitecore/legacyservice/api/combo/values/metafield/{metafieldItemGuid}

  • /digizuitecore/legacyservice/api/combo/values/metafield/{metafieldItemGuid}/assignable

Method: GET

Auth required: YES

This gets the combo nodes which the authorized user has access to based on item security. It is available in two flavors. One which returns everything the user has read access to and the /assignable variant of the endpoint which returns everything the user has write access to. The difference between the two is what the user can assign to an asset (i.e. write) and what the user can see as assigned on the asset (i.e. read).

Request parameters:

Name

Type

Description

metafieldId

int

The metafield id of the tree metafield to fetch nodes for.

metafieldItemGuid

string/guid/uuid

The itemGuid of the tree metafield to fetch nodes for.

Response properties:

Name

Type

Description

id

int

A language-independent id for this combo value.

optionValue

string

A language-independent string value for this combo value.

sortIndex

int

A value indicating how this node should be sorted in relation to all other combo value.

metaFieldId

int

The metafield id of the metafield this combo value belongs to.

itemId

int

The itemId of the combo value.

itemGuid

string/guid/uuid

The itemGuid of the combo value.

labels

dictionary

The translations of this combo value. The key is the languageId.

labels.label

string

The title/name/label of the combo value in this language.

labels.languageId

int

The language id of this translation.

labels.comboValueId

int

The language specific id of this combo value.

Expand
titleExample

Request:

Code Block
GET https://<my-dam>/digizuitecore/legacyservice/api/combo/values/metafield/50243
Authorization: AccessKey MIIC...dEK

Response:

Code Block
languagejson
{
  "errorCode": 0,
  "errorMessage": "",
  "hasError": true,
  "items": [
    {
      "id": 50243,
      "optionValue": "api-test-updated",
      "sortIndex": 42,
      "metaFieldId": 10192,
      "itemId": 20500,
      "itemGuid": "9f2bfb9e-3d40-4940-be8e-d6d325c4c925",
      "labels": {
        "1": {
          "label": "Api test - Danish",
          "languageId": 1,
          "comboValueId": 50243
        },
        "3": {
          "label": "Api test - English",
          "languageId": 3,
          "comboValueId": 50244
        }
      }
    }
  ]
}

Create new combo nodes while updating asset metadata

See documentation and examples here: https://digizuite.atlassian.net/wiki/spaces/DD/pages/3519873239/DC+5.8+core+api+Update+metadata#ComboValue-request-properties