Case Fields Integration Guide#

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.

Concepts#

Concept	Description
Case Field Descriptor	A meta object describing a new field. It provides a name, description and field type of the field.
Role based access	The field descriptor specifies a read role and a write role for the field, which is one of admin, tech or user. This allows a field to be either read/write for users, or e.g. read-only for users and write for tech users.
Case Field Policy	A policy describing a collection of fields to use. The policy is set on a service, allowing us to define which fields should be used on a per-service basis.
Customer Policy	The field policy can be overridden on for specific customer service subscriptions, allowing us to have a non-default policy for a specific customer service.
Customer Fields	A field descriptor which has customer specific meaning can be defined for a single customer. Else the field is defined globally, and can be used on any case.
Required fields	A field may be set as required-on-create or required-on-close in the field policy.
Multivalue fields	A field descriptor may specify the field to be multivalue, allowing multiple values for each field.
Field validators	A field may define validation rules, to ensure data consistency by only allowing defined values.
Value sources	A field may be defined with a value source, allowing the UI to present an autocompleter/selector for valid values. The value source may even reference an external JSON web service (following a specific spec), allowing the use of an externally defined value set.

Case Field Descriptor#

A 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
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)

Field types#

Valid field types are

Type	Description
`stringType`	A single text string (e.g. an “input field”).
`textType`	A long text value (e.g. a “text area”).
`integerType`	A integer numeric type.
`floatType`	A float numeric type.
`timestampType`	A numeric type which is rendered/understood as a timestamp.
`booleanType`	A boolean value (true/false).
`subjectType`	A reference to a user or group.
`assetType`	A reference to an asset.
`documentType`	A reference to a document or a folder.
`caseType`	A reference to a case.
`jsonType`	A valid JSON object.

Creating a new field#

New fields are created by administrators. If you need a new field for a use case, please contact mnemonic.

Using case fields#

Setting a field value#

To set a value for the field mySpecialField:

PUT https://api.mnemonic.no/cases/v2/case/1234/field/mySpecialField
{
    "value": "newValue"
}

Listing fields#

To fetch all fields set on a case:

GET https://api.mnemonic.no/cases/v2/case/1234/fields

See “Fetching a field value” below for explanation of returned data model, or swagger for more details.

Fetching a field value#

To fetch the value (or values for multivalue fields) for the field mySpecialField:

GET https://api.mnemonic.no/cases/v2/case/1234/fields/mySpecialField

This returns a response with the values set for the field. For single value fields, the value is also populated for convenience:

{
  "data": {
    "descriptor": {
      "id": "890eec62-f41d-47c9-8491-a6a7960b2835",
      "name": "mySpecialField",
      "valueType": "stringType"
    },
    "displayName": "My Special Field",
    "value": {
      "id": "7076d5e4-b994-4cf7-bba3-1bee6aeb2a82",
      "key": "someValue"
    },
    "values": [
      {
        "id": "7076d5e4-b994-4cf7-bba3-1bee6aeb2a82",
        "key": "someValue"
      }
    ]
  }
}

Field value info objects#

Fields have a “key”, and optionally a “label” (for value sourced fields). Fields sourced from Argus services also return a “info” field, which structure depends on the valueType. The info field contains a small info version of the referenced Argus object, for example (for an assetType object):

{
  "value": {
    "id": "7076d5e4-b994-4cf7-bba3-1bee6aeb2a82",
    "info": {
      "customer": {
        "domain": {
          "id": 1,
          "name": "MNEMONIC"
        },
        "id": 1,
        "name": "mnemonic",
        "shortName": "mnemonic"
      },
      "id": "5f44d0be-0c16-44b9-a07b-6e11f3f6c0ee",
      "name": "myAsset"
    },
    "key": "5f44d0be-0c16-44b9-a07b-6e11f3f6c0ee",
    "label": "myAsset"
  }
}

Setting multivalue fields#

By default, a field can only contain one value, and setting the value will overwrite existing value: When setting values for a multivalue field, the client may either set all values (overwrite):

PUT https://api.mnemonic.no/cases/v2/case/1234/field/mySpecialField
{
    "valuesToSet": ["a","b","c"]
}

or may add and remove values:

PUT https://api.mnemonic.no/cases/v2/case/1234/field/mySpecialField
{
    "valuesToAdd": ["d","e"],
    "valuesToRemove": ["a"]
}

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.

The access control works according to this table:

	`readRole`	`writeRole`
`user`	All users that can view the case, can view the value of this field	All users that can write to the case, can change the value of this field
`tech`	Only users with `tech` role for the case can view the value of this field	Only users with `tech` role for the case, which also has `write` permissions to the case, can write the value of this field
`admin`	Only users with service `admin` for this case can read the value of this field	Only 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 Type	Validators	Example
`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 } }`
`textType`	`maxLength`: Value cannot exceed this length	`"validator": { "textSettings": { "maxLength": 10 } }`
`ipType`	`ipVersion`: 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.

Querying the value source#

For fields with a value source, a separate endpoint allows the UI (and API clients) to query the value source for possible values:

GET https://api.mnemonic.no/cases/v2/field/values/mySpecialField?caseID=1234&service=ids&customer=mnemonic&keywords=searchword

This endpoint will return a list of value source entries

{
  "data": [
    {
      "key": 1,
      "label": "first value"
    },
    {
      "key": 2,
      "label": "second value"
    }
  ]
}

The value source query takes the following parameters:

keywords - Filter values by the provided keywords (keywords are ANDed by default)
caseID - Provide the caseID of the relevant case. This is used for explicit access control, if the current user does not have role based permission to the field.
service and customer - Provide the service (id or shortname) and the customer (id or shortname) to list values when creating a case. This is used if the current user does not have role based permission to the field.
domain - Provide domain to look up customer and/or service by shortname. This value defaults to the current users domain.
limit - Fetch at most this number of values from the value source. This defaults to 25.
offset - Skip the first offset values from the value source. By default, offset is 0.

Field Policies#

A field policy specifies a policy for use of fields on a specific service. A customer specific field policy specifies a policy for a specific service for a specific customer.

For any case, any available field may be used. A policy can specify:

mandatory fields (on create or on close)
special settings for fields when used in a service

Listing available policies#

To fetch all policies:

GET https://api.mnemonic.no/cases/v2/field/policy

The returned data structure will include the policy, and a list of the fields bound to that policy:

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "MyPolicy",
    "bindings": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "field": {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "name": "MyField",
          "valueType": "booleanType"
        },
        "displayName": "Custom Field Name",
        "requirementPolicy": "requiredOnCreate"
      }
    ]
  }
}

The requirementPolicy specifies if the field is required.
The displayName allows the policy to specify a custom display name for the field.