Property Descriptor API

Property descriptors define common properties for all customers, their type, and their default value.

This allows introducing a new property (with a default value) to all customers, while the property set for individual customers to override the default.

The descriptors define a type for the property, and optionally a JSON schema for JSON-type properties, which is enforced when setting the property value.

Fetch property descriptor by id or key

Needed permissions: viewCustomerPropertyDescriptors

This endpoint returns a property descriptor identified by UUID or key. The response can optionally include Json Schema, (settable via query parameter). If include Json Schema query parameter is set to false, JSON Schema field in the response will be null. For basic types JSON Schema is generated and for type jsonType JSON Schema is returned as saved in the db. Special handling is implemented for Property Descriptors of type enumType. Descriptors of type enumType have a predefined set of allowable values that can be managed through specialized endpoints. For more information proceed to section about Property descriptor enums.

curl -X 'GET' 
  'https://api.mnemonic.no/customeradmin/v2/propertydescriptor/{uuidOrKey}?includeSchema=false' 
  -H 'accept: application/json' 
  -H 'Argus-API-Key: my/api/key'

PropertyDescriptorResponse model will be returned.

Note

All endpoints for fetching, searching/listing, creating and updating and disabling a property descriptor return the same data model.

{"id": "c4c32359-2aa0-4448-834d-aa54afa1153b",
    "key": "test2",
    "description": "very good",
    "localizedDescription": "very good",
    "localizedDescriptions": {
      "norwegian": "veldig bra",
      "english": "very good"
    },
    "createdByUser": {
      "type": "user",
      "id": 23,
      "shortName": "someUser",
      "name": "Some User",
      "domain": {
        "id": 1,
        "name": "MNEMONIC"
      },
      "customer": {
        "id": 1,
        "name": "mnemonic",
        "shortName": "mnemonic",
        "domain": {
          "id": 1,
          "name": "MNEMONIC"
        }
      }
    },
    "lastUpdatedByUser": {
      "type": "user",
      "id": 23,
      "shortName": "someUser",
      "name": "Some User",
      "domain": {
        "id": 1,
        "name": "MNEMONIC"
      },
      "customer": {
        "id": 1,
        "name": "mnemonic",
        "shortName": "mnemonic",
        "domain": {
          "id": 1,
          "name": "MNEMONIC"
        }
      }
    },
    "deletedByUser": null,
    "createdTimestamp": 1678206365456,
    "lastUpdatedTimestamp": 1678206365456,
    "deletedTimestamp": 0,
    "flags": [],
    "defaultValue": "string",
    "section": "notification",
    "type": "string",
    "jsonSchema": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "string"
    }
  }

Update property descriptor

Needed permissions: updateCustomerPropertyDescriptor

This endpoint allows the user to update a property descriptor identified by UUID or key by using data from the request. It is possible to update:

• localizedDescriptions - english description is required and can not be deleted or updated to “”

• section

• defaultValue - has to be valid according to type (for the validation rules for jsonType read on JSON Schema validation)

• type - if update to jsonType JSON Schema must be provided in addition. If a descriptor is updated to enumType an enum entry is automatically generated for the default value of the descriptor.

• schema - possible to update only for type jsonType,

  Note

  It is not possible to update both default value and JSON Schema at the same time, when updating the schema it is verified if the default value is still valid according to the schema and when the default value is updated it is
  always validated against the schema for the jsonType

• deprecated - flag the descriptor as deprecated (has to be done before the descriptor is deleted)

curl -X 'PUT' 
  'https://api.mnemonic.no/customeradmin/v2/propertydescriptor/{uuidOrKey}' 
  -H 'accept: application/json' 
  -H 'Content-Type: application/json' 
  -H 'Argus-API-Key: my/api/key'
  -d '{
  "localizedDescriptions": {
    "english": "string",
    "norwegian": "string"
  },
  "section": "notification",
  "defaultValue": "string",
  "type": "string",
  "schema": "JsonNode",
  "deprecated": false
}'

Delete property descriptor

Needed permissions: deleteCustomerPropertyDescriptor

This endpoint allows the user to delete a previously deprecated property descriptor identified by UUID or key. Please note that some customers may still have values for the descriptor, check the log message for information.

curl -X 'DELETE' 
  'https://api.mnemonic.no/customeradmin/v2/propertydescriptor/{uuidOrKey}' 
  -H 'accept: application/json' 
  -H 'Argus-API-Key: my/api/key'

Fetch JSON Schema for a property descriptor

Needed permissions: viewCustomerPropertyDescriptors

This endpoint returns a JsonNode with JSON Schema for a property descriptor identified by UUID or key. For basic types schema is generated and for jsonType the schema saved in db is returned.

curl -X 'GET' 
  'https://api.mnemonic.no/customeradmin/v2/propertydescriptor/{uuidOrKey}/jsonschema' 
  -H 'accept: application/json' 
  -H 'Argus-API-Key: my/api/key'

Searching for descriptors

Needed permissions: viewCustomerPropertyDescriptors

Searching for descriptors can be done using the simple search GET endpoint or the advanced search POST endpoint.

Please read the General integration guide to learn about general concepts for search endpoints.

Simple search

For simple search it is possible to search for descriptors by keywords and sort the results

curl -X 'GET'  
  'https://api.mnemonic.no/customeradmin/v2/propertydescriptor?offset=0&limit=25'
  -H 'accept: application/json' 
  -H 'Argus-API-Key: my/api/key'

Other parameters include limit and offset.

Advanced search

Advanced search has access to all possible filtering parameters for property descriptors, and follows the general advanced search structure as described in the General integration guide.

curl -X 'POST'   
  'https://api.mnemonic.no/customeradmin/v2/propertydescriptor/search' 
  -H 'accept: application/json' 
  -H 'Content-Type: application/json' 
  -H 'Argus-API-Key: my/api/key'
  -d '{
  "section": [
    "notification"
  ],
  "type": [
    "string"
  ],
  "includeFlags": [
    "deleted"
  ],
  "excludeFlags": [
    "deprecated"
  ],
  "keywords": [
    "string"
  ],
  "subCriteria": [
    {
      "section": [
        "notification"
      ],
      "type": [
        "string"
      ],
      "includeFlags": [
        "deprecated"
      ],
      "excludeFlags": [
        "deprecated"
      ],
      "keywords": [
        "string"
      ],
      "subCriteria": [
        "string"
      ],
      "required": false,
      "exclude": false
    }
  ],
  "includeDeleted": false,
  "limit": 0,
  "offset": 0,
  "sortBy": [
    "key"
  ]
}'

Note

Search options “keywordMatchStrategy” and “keywordFieldStrategy” are not supported. See the Swagger API documentation for more details on valid request parameters.

Add a new property descriptor

Needed permissions: createCustomerPropertyDescriptors

This endpoint creates a descriptor based on parameters provided

  curl -X 'POST' 
  'https://api.mnemonic.no/customeradmin/v2/propertydescriptor' 
  -H 'accept: application/json' 
  -H 'Content-Type: application/json' 
  -H 'Argus-API-Key: my/api/key'
  -d '{
  "key": "test2",
  "localizedDescriptions": {
    "norwegian": "veldig bra",
    "english": "very good"
  },
  "section": "notification",
  "defaultValue": "string",
  "type": "string",
  "schema": ""
}'

Note

The default value will be validated against the type provided and for jsonType it will be validated against JSON Schema.

Note

Description in english is required.

Note

If a descriptor of enumType is created an enum entry is automatically generated for the default value of the descriptor.

Property descriptor enums

For property descriptors of enumType, these endpoints allow managing the valid enums for the descriptor, and listing/searching current enum values.

Searching for enum entries

Needed permissions: viewCustomerPropertyDescriptors

Searching for enum entries can be done using the simple search GET endpoint or the advanced search POST endpoint.

Please read the General integration guide to learn about general concepts for search endpoints.

Simple search

For simple search it is possible to search for enum entries for a descriptor by keywords and sort the results

curl -X 'GET' 
  'https://api.mnemonic.no/customeradmin/v2/propertydescriptor/{enumTypeDescritporUUIDOrKey}/values?
  offset=0&limit=25&keywords=keyword1&sortBy=value' 
  -H 'accept: application/json' 
  -H 'Argus-API-Key: my/api/key'

Other parameters include limit and offset.

Advanced search

Advanced search has access to all possible filtering parameters for enum entries of a property descriptor, and follows the general advanced search structure as described in the General integration guide.

curl -X 'POST'   
  'https://api.mnemonic.no/customeradmin/v2/propertydescriptor/{enumTypeDescriptorUUIDOrKey}/search' 
  -H 'accept: application/json' 
  -H 'Content-Type: application/json' 
  -H 'Argus-API-Key: my/api/key'
  -d '{
  "keywords": [
    "string"
  ],
  "subCriteria": [
    {
      "keywords": [
        "string"
      ],
      "subCriteria": [
        "string"
      ],
      "keywordMatchStrategy": "any",
      "keywordFieldStrategy": [
        "value"
      ],
      "required": false,
      "exclude": false
    }
  ],
  "keywordMatchStrategy": "any",
  "keywordFieldStrategy": [
    "value"
  ],
  "limit": 0,
  "offset": 0,
  "sortBy": [
    "value"
  ]
}'

See the Swagger API documentation for more details on valid request parameters.

The search endpoints return a list of enum entries. CustomerPropertyDescriptorEnumEntryResponse model will be returned.

Note

All endpoints related to enum entries management return the same data model.

{
  "propertyDescriptorId": "021f9aaa-26c8-40f5-b6b9-6493e7d85e8f",
  "value": "value1",
  "localizedValue": "value1",
  "localizedValues": {
    "english": "value1",
    "norwegian": "value1"
  },
  "description": "Some value",
  "localizedDescription": "Some value",
  "localizedDescriptions": {
    "english": "Some value",
    "norwegian": "Some value"
  }
}

Add a new enum entry

Needed permissions: updateCustomerPropertyDescriptors

This endpoint creates an enum entry for a descriptor based on parameters provided

  curl -X 'POST' 
  'https://api.mnemonic.no/customeradmin/v2/propertydescriptor/{enumTypeDescritporUUIDOrKey}/values' 
  -H 'accept: application/json' 
  -H 'Content-Type: application/json' 
  -H 'Argus-API-Key: my/api/key'
  -d '{
  "value": "string",
  "localizedValues": {
    "english": "string",
    "norwegian": "string"
  },
  "localizedDescriptions": {
    "english": "string",
    "norwegian": "string"
  }
}'

Note

Enum entries can be created only for descriptors of type enumType.

Note

The value is required and it is not editable. To edit the displayed value it is possible to do, by editing localizedValues.

Note

Description and localized value in english is required.

Update property descriptor enum entry

Needed permissions: updateCustomerPropertyDescriptor

This endpoint allows the user to update an enum entry for a property descriptor identified by UUID or key by using data from the request. It is possible to update:

• localizedDescriptions - english description is required and can not be deleted or updated to “”

• localizedValues - english value is required and can not be deleted or updated to “”

curl -X 'PUT' 
  'https://api.mnemonic.no/customeradmin/v2/propertydescriptor/{enumTypeDescritporUUIDOrKey}/values/
  {enumEntryUUIDOrValue}' 
  -H 'accept: application/json' 
  -H 'Content-Type: application/json' 
  -H 'Argus-API-Key: my/api/key'
  -d '{
  "localizedDescriptions": {
    "english": "string",
    "norwegian": "string"
  },
  "localizedValues": {
    "english": "string",
    "norwegian": "string"
  }
}'

Delete property descriptor enum entry

Needed permissions: updateCustomerPropertyDescriptor

This endpoint allows the user to delete an enum entry, identified by UUID or value, from a property descriptor identified by UUID or key.

curl -X 'DELETE' 
  'https://api.mnemonic.no/customeradmin/v2/propertydescriptor/{enumTypeDescritporUUIDOrKey}/values/
  {enumEntryUUIDOrValue}' 
  -H 'accept: application/json' 
  -H 'Argus-API-Key: my/api/key'

Note

The enum entry is deleted permanently. To restore it, the entry must be re-added.