Extension fields

Identity and Visit entities provide only a minimal set of built-in attributes, which should be sufficient for basic functionality. However, for integration with legacy systems and also to be able to fulfill special customer requirements, it might be required to store additional information for these entities as to what the basic API provides. This is realized through extension fields, which allow you to extend entities with custom additional attributes.

Declaration

Extension fields are declared on the tenant level (they can be either declared as part of new tenant registration or modified at any time later through tenant update). This declaration is therefore common to all PACSes within the scope of this tenant.

On API, extension fields are declared as map structures having the name of the extension field as the map key and the field declaration as the map value for this key:

{
  "identityExtensionFields": {
    "field1Name": { /* field declaration */ },
    "field2Name": { /* field declaration */ },
    "...": "..."
  },
 "identityCredentialExtensionFields": {
    "field1Name": { /* field declaration */ },
    "field2Name": { /* field declaration */ },
    "...": "..."
  },
  "visitExtensionFields": {
    "field1Name": { /* field declaration */ },
    "field2Name": { /* field declaration */ },
    "...": "..."  
  },
  "visitCredentialExtensionFields": {
    "field1Name": { /* field declaration */ },
    "field2Name": { /* field declaration */ },
    "...": "..."  
  }
}

Each field declaration consists of the following attributes:

{
  "type": "...", // Mandatory, one of [Boolean, Integer, Decimal, String, DateTime]
  "decription": "...", // Brief description of field purpose
  "required": false, // Flag if field is required, defaults to false
  "min": 0, // Minimal value, interpretation depends on used type, see further, null if not limited
  "max": 0, // Maximal value, interpretation depends on used type, see further, null if not limited
  "pattern": "..." // Regular expression the value must match (not applied to all types, see further), null if not to be applied
}

Validations

Validation based on field type:

• Boolean: Only the required flag is applied.

• Integer & Decimal:

  • min and max values are applied for defining the range of numeric value. Bounds are inclusive, i.e., value must be greater or equal to (or lower or equal) to given bounds.

  • pattern is not applied to numeric values.

• String:

  • For string values, min and max refers to number of string characters. Bounds are inclusive, i.e. string must include at least min characters and at most max characters.

  • String value is matched against a pattern containing regular expression.

• DateTime:

  • DateTime value is required to be given as ISO8601 string.

  • For DateTime values, min and max correspond to the number of seconds from "now" (the time when validation is being done). E.g., for time that must be after “now” and must not be after 24 hours, set 0 as min and 86400 *(24\*60\60) as max.

  • Pattern is also applied to the ISO8601 string value allowing to enforce some static restriction, e.g. to enforce date having particular month or time to be within specific range of day.

Mapping

Every PACS (and even each instance of the same PACS) might use different mapping of extension fields. Therefore, mapping itself is not done on the tenant level but needs to be configured for each PACS separately.

Mapping of extension fields (which can be done as part of new PACS registration or modified at any time later through PACS update) is done through map structure having the name of the extension field (matching the name declared on the tenant) as the map key and the mapping path as the map value for this key:

{
  "identityExtensionFields": {
    "field1Name": "$...",
    "field2Name": "$...",
    "...": "..."
  },
  "identityCredentialExtensionFields": {
    "field1Name": "$...",
    "field2Name": "$...",
    "...": "..."
  },
  "visitExtensionFields": {
    "field1Name": "$...",
    "field2Name": "$...",
    "...": "..."  
  },
  "visitCredentialExtensionFields": {
    "field1Name": "$...",
    "field2Name": "$...",
    "...": "..."  
  }
}

Mapping Path

Mapping of extension fields uses JSON path syntax. In particular, syntax is the following:

• $.[ext|self].[pacsAttributeName], where ext and self keywords denote whether mapping points to native entity attribute, or points to PACS entity extension field.

• For example:

  • In Lenel, we can have an extension field address pointing to a native field within Lenel: "address": "$.self.ADDR1".

  • In Genetec, there is no native field for storing the address; therefore, it needs to be mapped through PACS extension field: "address": "$.ext.Address".

Null Mapping

In some cases it is desirable to ignore particular extension fields on some PACSes (e.g., because it is not technically possible to store the field on PACS or it is some special-purpose information that needs to be stored only on some PACSes). For this, it is possible to use “null mapping” with following syntax:

• $.null

Using this, declared extension field values are not passed to the PACS.

PACS Entity Fields

AIS returns a list of all available fields for extendable entities as part of a particular PACS detail response.

Available fields, for each entity, are listed as an array containing objects with a full mapping path (which can be directly used in extension field mapping) and field type:

{
  "...": "...",
  "fields": {
    "identityFields": [
      {"path": "$.self.ADDR1", "type": "String"},
      {"path": "$.ext.EXT_FIELD_1", "type": "Integer"},
      {"path": "...", "type": "..."}
    ],
    "identityCredentialFields": [
      {"path": "...", "type": "..."}    
    ],
    "visitFields": [
      {"path": "...", "type": "..."}
    ],
    "visitCredentialFields": [
      {"path": "...", "type": "..."}
    ]
  }
}