Design Properties to Be Supported on Design Interfaces - CausewayOne Asset Management

Overview

To further enhance the flexibility of the data models in Alloy, we will be updating the Design Interfaces model to support all the properties that are currently supported by Designs. Allowing properties to be defined at interface level means that they only need to be defined once and then utilised by all designs (or interfaces) that implement the said interface.

Who will this affect?

At the time of writing, design interfaces can only be defined by the Yotta development team but as we continue to increase system capability, this change will allow users to define properties on a Design Interface that would then be used by Designs that implement that Design Interface. Users using Design, Interface and DoDI endpoints will need to ensure they make changes in line with the phased changes described below.

Details

We are changing backend capability to support Versioned, Colour, Icon, Geometry and Collections properties on design interfaces.

Passing the listed properties into Design create/edit requests DesignCreateWebRequestModel and DesignEditWebRequestModel. will therefore be optional as they may already be defined at interface level or if you would like to use the system defaults.

Introduction of these properties on Design Interfaces means that recursive logic will be applied to them, similar to the way Implements operates.

Phased change

Given the possible repercussions of this change, we will be dividing the work into 2 phases.

Phase 1

In Phase 1, we will maintain the current properties on Design model but mark them as Obsolete - Title, Subtitle, Colour, Icon, Versioned, Geometry and Collections. We will then introduce new properties that provide information about the parent; namely DodiTitle, DodiSubtitle, DodiColour, DodiIcon, DodiVersioned, DodiCollections, GeometryRequired and GeometryAllows. Please note that as a result, geometry will be split into two different properties, which will need to be sent with create and edit calls instead of the previous geometry property. Sending these properties will be optional in Phase 1 as we make the transition but then required in Phase 2.

All endpoints that get or list Design Interfaces will start returning the above properties if set.

Please note that as part of Phase 1, blueprint files will be updated to remove all previous geometry properties in favour of new geometryRequired and geometryAllows properties.

Supported geometyAllows types are Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon and GeometryCollection. In case that any of the existing designs had Feature or FeatureCollection type set, these will be removed from the design via upgrade script.

New Design Interface response

{
    "designInterface": {
        "name": "Test Name",
        "code": "designInterfaces_826135843",
        "context": "Customer",
        "implements": [...],
        "attributes": [...],
        "metadata": {...},
        "title": "Title",
        "subtitle": "Subtitle",
        "dodiTitle": {
            "value": "Title",
            "parent": "designInterfaces_826135843"
        },
        "dodiSubtitle": {
            "value": "Subtitle",
            "parent": "designInterfaces_826135843"
        },
        "dodiColour": {
            "value": "#123456",
            "parent": "designInterfaces_826135843"
        },
        "dodiIcon": {
            "value": "new-icon",
            "parent": "designInterfaces_826135843"
        },
        "geometryRequired": {
            "value": true,
            "parent": "designInterfaces_826135843"
        },
        "geometryAllows": {
            "values": ["LineString"],
            "parent": "designInterfaces_826135843"
        },
        "dodiCollections": {
            "values": ["Live"],
            "parent": "designInterfaces_826135843"
        },
        "discriminator": "DesignInterfaceWebModel"
    },
    "operationsSummary": {...}
}

New Design response

{
    "design": {
        "name": "Test design",
        "code": "designs_testDesign_5ebe5a71c2c5ca532cdb5c2e",
        "context": "Customer",
        "implements": [...],
        "attributes": [...],
        "metadata": {...},
        "title": "Title",
        "subtitle": "Subtitle",
        "colour": "#026227",
        "icon": "icon-bin-recycle-small",
        "versioned": false,
        "geometry": {
            "allows": [],
            "required": false
        },
        "collections": ["Live", "Archive"], 
        "dodiTitle": {
            "value": "Title",
            "parent": "designs_testDesign_5ebe5a71c2c5ca532cdb5c2e"
        },
        "dodiSubtitle": {
            "value": "Subtitle",
            "parent": "designs_testDesign_5ebe5a71c2c5ca532cdb5c2e"
        },
        "dodiColour": {
            "value": "#026227",
            "parent": "designs_testDesign_5ebe5a71c2c5ca532cdb5c2e"
        },
        "dodiIcon": {
            "value": "icon-bin-recycle-small",
            "parent": "designs_testDesign_5ebe5a71c2c5ca532cdb5c2e"
        },
        "dodiVersioned": {
            "value": false,
            "parent": "designs_testDesign_5ebe5a71c2c5ca532cdb5c2e"
        },
        "geometryRequired": {
            "value": false,
            "parent": "designs_testDesign_5ebe5a71c2c5ca532cdb5c2e"
        },
        "geometryAllows": {
            "values": [],
            "parent": "designs_testDesign_5ebe5a71c2c5ca532cdb5c2e"
        },
        "dodiCollections": {
            "values": ["Live", "Archive"],
            "parent": "designs_testDesign_5ebe5a71c2c5ca532cdb5c2e"
        },         
        "discriminator": "DesignWebModel"
    },
    "operationsSummary": {...}
}

Phase 2

Phase 2 will see all the obsolete properties and code removed, therefore API users should start updating integrations once Phase 1 is complete to make use of the new optional properties that will be returned on all DoDIs. For example, after Phase 2 DesignGeometryWebModel will no longer exist. Also callers will need to handle a new special parent code for defaulted properties (see below).

Recursive logic and design defaults

As part of this change get and list Designs, Design Interfaces and DoDI endpoints will start applying recursive logic to all implements to work out the above properties. In the case where none of the properties are set on Design or Design Interfaces it implements, the following defaults will be applied to the design on fetch. Defaults can be recognised by the parent value code engine_defaultedProperties instead of a valid DoDI code. Please make sure to handle this new special parent code.

DodiVersioned: false
DodiColour: #3d8fbd
DodiIcon: icon-shape-circle
DodiCollections: Live
GeometryRequired: false
GeometryAllows: all types

[
    "Point",
    "MultiPoint",
    "LineString",
    "MultiLineString",
    "Polygon",
    "MultiPolygon",
    "GeometryCollection"
]

Design response with inheritance information

The following design is created with name and title only, this is why the subtitle property is missing while all other properties are either inherited from two implemented interface or defaulted.

{
  "design": {
    "name": "Test",
    "code": "designs_test_5ebe6176d8b0871ef02c815b",
    "context": "Customer",
    "implements": [
      {
        "code": "designInterfaces_items",
        "parent": "designs_test_5ebe6176d8b0871ef02c815b"
      },
      {
        "code": "designInterfaces_versioned_5ebe5239d489976e7024e52c",
        "parent": "designs_test_5ebe6176d8b0871ef02c815b"
      }
    ],
    "attributes": [...],
    "metadata": {...},
    "dodiTitle": {
      "value": "Title",
      "parent": "designs_test_5ebe6176d8b0871ef02c815b"
    },
    "dodiColour": {
      "value": "#3d8fbd",
      "parent": "engine_defaultedProperties"
    },
    "dodiIcon": {
      "value": "icon-system-circle-thin",
      "parent": "designInterfaces_items"
    },
    "dodiVersioned": {
      "value": true,
      "parent": "designInterfaces_versioned_5ebe5239d489976e7024e52c"
    },
    "dodiCollections": {
      "values": ["Live"],
      "parent": "engine_defaultedProperties"
    },
    "geometryRequired": {
      "value": false,
      "parent": "engine_defaultedProperties"
    },
    "geometryAllows": {
      "values": ["Point", "MultiPoint", "LineString", "MultiLineString", "Polygon", "MultiPolygon", "GeometryCollection", "Feature", "FeatureCollection"],
      "parent": "engine_defaultedProperties"
    },
    ...
}

Compatibility check

During Design creation or editing, a new compatibility check will be run to validate the request to ensure the changes on the Design are compatible with the implemented interfaces.

For example, if current state of Design is Versioned = true and new implement is trying to change this to Versioned = false, a Bad Request error will be returned. Similarly there are validations on Geometry and Collections, which will only allow setting the same values. For example, if the Collection on the implemented Design Interface is set to Live and Design collections were not previously specified it would not be possible to edit Design and set collections to Live and Inventory, as these do not match the collections of the implemented interface.

In essence, any definitions at the interface level will constrain implemented designs to follow the implemented definitions. When a design implements multiple interfaces, the compatibility check will ensure that all implemented interface are workable together on the implementing Design.

Phase 1 Expected Release Date

24th September 2020

Phase 2 Expected Release Date

February 2021