Page tree
Skip to end of metadata
Go to start of metadata

Introduction

Case Fields are extensions to the build-in fields in the Case system.

These extension fields allow users of the Case system to define new structured fields with different types and rules, and use them to add more structured data to cases.

Currently, the Case UI does not support Case Fields. 
As support for Case Fields is added to the UI, this guide will be updated.

Case Field Definitions

Case Field Definition defines a new field, specifying

  • the application domain (usually "MNEMONIC")
  • the field name - must be unique within the domain
  • the value type
    • Valid types: timestampType, ipType, documentType, floatType, textType, integerType, caseType, stringType, subjectType, assetType
  • multivalue - if true, the field permits having multiple values
  • access control rules
    • readRole defines who can read the field (user, tech, admin)
    • writeRole defines who can update the field (user, tech, admin)
  • value validation rules (optional)
    • different validators depending on the value type. See "Field Validators" below.
  • value source (optional)
    • allow specifying a set of valid values, or even an external endpoint to fetch valid values from
  • renderer options (optional)
  • a default value (optional)
  • customer this field can be used for (optional - by default, the field can be used for any customer)

Creating a new field

curl -XPOST -H"Argus-API-Key:$key" https://api.mnemonic.no/cases/v2/field/descriptor -d '
{
  "domain":"MNEMONIC",
  "name":"myNewField"
}'

By default, the field is created with value type "string" and readRole and writeRole "user"

Defining new fields require Administrator privileges.

Using case fields

Listing current field values

To list all existing fields on a case:

curl -XGET -H"Argus-API-Key:$key" https://api.mnemonic.no/cases/v2/case/123456/fields

{
    "count": 0,
    "data": {
        "descriptor": {
            "flags": [],
            "id": "5c5c30af-be27-44bd-90f8-65cf874d1efb",
            "name": "myNewField",
            "valueType": "stringType"
        },
        "displayName": "myNewField",
         "value": {
            "info": null,
            "key": "myValue",
            "label": "myValue"
        },
        "values": [
            {
                "info": null,
                "key": "myValue",
                "label": "myValue"
            }
        ]
    },
    "limit": 0,
    "messages": [],
    "metaData": {},
    "offset": 0,
    "responseCode": 200,
    "size": 0
}

The value contains the actual value, and the label, which may be different than the value, if there is an external value source.
The info object is only used for built-in value sources that support this.

Fetching a specific field

To fetch a specific field, use the field name:

curl -XGET -H"Argus-API-Key:$key" https://api.mnemonic.no/cases/v2/case/123456/fields/myNewField

Setting a field

curl -XPUT -H"Argus-API-Key:$key" https://api.mnemonic.no/cases/v2/case/123456/fields/myNewField -d '{"value":"myValue"}'

Multivalue fields

For fields with multivalue support:

  • the "value" output is always null
  • the "values" array may contain zero or more values
  • setting the field with the "value" parameter will overwrite any existing values, and replace it with a single value.
  • setting the field with the "valuesToSet" parameter will overwrite any existing values, and replace it with a set of values
  • setting the field with the "valuesToAdd" parameter will retain any existing values, and append the provided values
  • setting the field with the "valuesToRemove" parameter will retain any existing values, except the provided values which will be removed (if set)

Advanced field options

Using Field Access Control

The Administrator may change the Field Definition, setting the readRole or writeRole to either "user", "tech", or "admin".

To change the access mode of the field:

curl -XPUT -H"Argus-API-Key:$key" https://api.mnemonic.no/cases/v2/field/descriptor/myNewField -d '
{
  "readRole":"user",
  "writeRole":"tech"
}'


The access control works according to this table:


readRolewriteRole
userAll users that can view the case, can view the value of this fieldAll users that can write to the case, can change the value of this field
techOnly users with tech role for the case can view the value of this fieldOnly users with tech role for the case, which also has write permissions to the case, can view the value of this field
adminOnly users with service admin for this case can read the value of this fieldOnly users with service admin for this case can write the value of this field

Using Field Validators

The field can be configured to only allow values permitted by a "validator". This can be used to increase the data consistency of the field.

The possible validation rules depend on the value type:

Value TypeValidatorExample
integerType

minimum - Minimum value to allow

maximum - Maximum value to allow



"validator": { "integerSettings": { "minimum": 0, "maximum": 10 } }
floatType

minimum - Minimum value to allow

maximum - Maximum value to allow

"validator": { "floatSettings": { "minimum": 0.0, "maximum": 1.0 } }
stringType

regex - Value must match regular expression 

maxLength - Value cannot exceed this length

"validator": { "stringSettings": { "regex": "string", "maxLength": 10 } }
textTypemaxLength - Value cannot exceed this length
"validator": { "textSettings": { "maxLength": 10 } }
ipTypeipVersion - The permitted IP version
"validator": { "ipSettings": { "ipVersion": "IPv4" } }
subjectType

subjectType - user or group

requiredPermission - Only permit subjects having this permission

sameCustomer - Only permit subjects belonging to same customer as the current case

memberOf - Only permit subjects which are member of the specified group

{"subjectSettings": { "subjectType": "user", "requiredPermission": "string", "sameCustomer": true, "memberOf": 0}}
caseType

service - only permit cases for this service

caseType - only permit cases of  this type

category - only permit cases of this category

sameCustomer - only permit cases belonging to same customer as the current case

{ "caseSettings": { "service": "string", "caseType": "securityIncident", "category": "string", "sameCustomer": true} }


Using Field Value Sources

A Field value source allows defining permitted values both for autocompleting and validation.

A field source can be a static list of values, or reference an external endpoint.

Configuring a list sourceConfiguring an external source
  "valueSource": {
    "listType": {
      "entries": [
        { "key":"a", "label":"Category A" },
        { "key":"b", "label":"Category B" },
        { "key":"c", "label":"Category C" }
      ]
    }
  },

Valid values are now "a", "b" or "c", but these values will be rendered with the corresponding label.

  "valueSource": {
    "urlType": {
      "queryURL": "https://my.service/lookup?value=%s"
    }
  },

The endpoint must return a JSON array containing objects, each object with a property key and label

The endpoint will be invoked with the %s replaced with an autocompleter input.
It will also be invoked with the exact value when a field value is set, or to fetch the label of the current value. Any filtering on the provided parameter must therefore also return exact key match.

  • No labels