POST Metadata/UpdateItem

Updates settings that control a Custom Field, such as default and required user input values.

Requirements

  • Permissions:  The caller must have Write permission to the Metadata Distinguished Name (DN) and the Guid of the request.
  • Token scope:  Any valid scope, such as Agent, Certificate, or SSH:Manage

Headers

  • Content type: Content-Type:application/json.

  • Token: The bearer access token that you received. For example, Authorization:Bearer 4MyGeneratedBearerTknz==. For more information, see Passing a bearer token in your API calls.

Parameters

Specify either Item or Update, not both.

NOTE  For Metadata/UpdateItem, the following Metadata Items are read-only: ConfigAttribute, DN, GUID, Name, Type. If you try to update one of these values, an error occurs.

Input parameters

Name

Description

Item

Resets every Custom Field to the default except settings that you specify. Include every Metadata Item setting that you want to retain or change. To reset every Custom Field setting, specify only the DN and the Guid. If the request omits an attribute, the value reverts to the default.

  • A default Boolean attribute reverts to false.
  • A default String or nullable integer attribute reverts to null or empty.
  • A default Integer reverts to 0.

Update

Adds, updates, or resets only the Metadata Item that you specify. Retains all other Custom Field settings.

  • DN: The Distinguished Name (DN) of a Certificate or Device object that contains a Custom Field. If necessary, use the DN value from the GET Metadata/Items or POST Metadata/GetItemsForClass response.
  • Data: The Name of one or more Metadata Item attributes and its corresponding Value:
    • On the Data container, omit the DN.

    • If the Value is a set of choices, specify every item that you want to add, retain, or change. If you omit an item, the choice automatically deletes; it is no longer available in the UI.
    • To reset a set of choices, a string, or a nullable integer to the default, specify "Value": null.
    • To reset a Boolean value, to the default, specify "Value":["False"].

Returns

Response description

Name

Description

Locked

The status of the data:

  • true: The Policy value, which applies to the Custom Field, is locked.
  • false: The Custom Field value is capable of change.

Result

The reason for success or failure. For more information, see Metadata Result Codes.

Example 1: Update the entire Custom Field

Request for Example 1

POST https://tpp.venafi.example/vedsdk/Metadata/UpdateItem
Authorization:Bearer 4MyGeneratedBearerTknz==
{
   "Item":{
      "AllowedValues":[

      ],
      "Classes":[
         "X509 Certificate"
      ],
      "ConfigAttribute":"{24cb39d4-33ce-4d08-ade4-81d6b293551c}",
      "DN":"\\VED\\Metadata Root\\db1e5711-2bd0-45da-be4a-2c9e0baf4637",
      "DefaultValues":[

      ],
      "ErrorMessage":"Type the reason",
      "Guid":"{24cb39d4-33ce-4d08-ade4-81d6b293551c}",
      "Help":"Reason for certificate renewal",
      "Label":"CF-ReviewReason",
      "Name":"db1e5711-2bd0-45da-be4a-2c9e0baf4637",
      "Policyable":false,
      "RegularExpression":"^[A-Za-z0-9]*$",
      "RenderHidden":false,
      "RenderReadOnly":false,
      "Type":1
   }
}

Response for Example 1

HTTP/1.1 200 OK
{
   "Locked": false,
   "Result": 0
}

Example 2: Update only a few Custom Field values

Request for Example 2

POST https://tpp.venafi.example/vedsdk/Metadata/UpdateItem
Authorization:Bearer 4MyGeneratedBearerTknz==
{
   "Update":{
      "DN":"\\VED\\Metadata Root\\List of Cost Centers",
      "Data":[
         {
            "Name":"ErrorMessage",
            "Value":[ "You must select the Cost Center Region." ]
         },
         {
            "Name":"AllowedValues",
            "Value":[
               "NW Region",
               "SW Region",
               "E Region",
               "W Region"
            ]
         },
         {
            "Name":"DefaultValues",
            "Value":["NW Region"]
         },
         {
            "Name":"Mandatory",
            "Value":["True"]
         }
      ]
   }
}

Response for Example 2

HTTP/1.1 200 OK
{
   "Locked": false,
   "Result": 0
}

Example 3: Reset Custom Field values

Request for Example 3

POST https://tpp.venafi.example/vedsdk/Metadata/UpdateItem
Authorization:Bearer 4MyGeneratedBearerTknz==
{
   "Update":{
      "DN":"\\VED\\Metadata Root\\List of Cost Centers",
      "Data":[
         {
            "Name":"ErrorMessage",
            "Value":null
         },
                  {
            "Name":"DefaultValues",
            "Value": null
         }
      ]
   }
}

Response for Example 3

HTTP/1.1 200 OK
{
    "Locked": false,
    "Result": 0
}