Skip to content

Configuration

Jump to bottom
Florian Krönert edited this page Sep 18, 2023 · 13 revisions

Basic Configuration

  • Create at least one "PowerKanban Config" record for each entity where you want to use PowerKanban. Give it a unique name and enter a configuration json such as the following into the value field. The "Entity Logical Name" field should be filled with the logical name (all lower case) of the entity which your PowerKanban Config should be used with.
  • Enable the PCF control for the entity you like and pass the unique name of the PowerKanban config you created as 'configName' property inside the PCF control if you want to use this config on start automatically. If you don't pass one, the kanban board will load with the config selector by default.
  • For all examples below, the lookups on the notification or subscription entity can be created yourself in your environment. There is a D365PowerKanbanSamples solution in every release, which contains the demo lookups which are used in the examples below. You can create these yourself with your own publisher and just replace the field names where they are used.

Examples

Basic config

{
    "primaryEntity": {
        "logicalName": "incident",
        "swimLaneSource": "statuscode"
    },
    "secondaryEntity": {
        "logicalName": "task",
        "parentLookup": "regardingobjectid",
        "swimLaneSource": "statuscode"
    }
}

Config with enabled subscription and notification feature

{
    "primaryEntity": {
        "logicalName": "incident",
        "swimLaneSource": "statuscode",
        "notificationLookup": "oss_incidentid",
        "subscriptionLookup": "oss_incidentid",
        "transitionCallback": "boardViewExtender.onStateTransition"
    },
    "secondaryEntity": {
        "logicalName": "task",
        "notificationLookup": "oss_taskid",
        "parentLookup": "regardingobjectid",
        "subscriptionLookup": "oss_taskid",
        "swimLaneSource": "statuscode"
    },
    "customScriptUrl": "/WebResources/oss_/D365BoardView/js/exampleExternalScript.js"
}

customScriptUrl is only needed when you have transitionCallback configured on either primary or secondary entity

Config with custom code callback on primary record drag and drop

{
    "primaryEntity": {
        "logicalName": "incident",
        "swimLaneSource": "statuscode",
        "transitionCallback": "boardViewExtender.onStateTransition"
    },
    "secondaryEntity": {
        "logicalName": "task",
        "parentLookup": "regardingobjectid",
        "swimLaneSource": "statuscode"
    },
    "customScriptUrl": "/WebResources/oss_/D365BoardView/js/exampleExternalScript.js"
}

JSON scheme

Below JSON schema describes the structure of the configuration. You can always fiddle online with a nice UI in the JSON Editor online demo, preloaded with below schema.

{
    "$schema": "http://json-schema.org/draft-07/schema",
    "$id": "http://example.com/example.json",
    "type": "object",
    "title": "PowerKanban Config",
    "description": "The schema of a complete PowerKanban configuration object",
    "default": {},
    "definitions": {
        "boardEntity": {
            "$id": "#boardEntity",
            "type": "object",
            "title": "The primaryEntity schema",
            "description": "This configures settings regarding the an entity in a PowerKanban board.",
            "default": {},
            "examples": [
                {
                    "logicalName": "incident",
                    "swimLaneSource": "statuscode",
                    "subscriptionLookup": "oss_incidentid",
                    "notificationLookup": "oss_incidentid",
                    "transitionCallback": "boardViewExtender.onStateTransition",
                    "preventTransitions": false,
                    "fitLanesToScreenWidth": false,
                    "hideCountOnLane": false,
                    "defaultOpenHandler": "inline",
                    "hiddenLanes": null,
                    "visibleLanes": null,
                    "emailSubscriptionsEnabled": false,
                    "emailNotificationsSender": { "Id": "someId", "LogicalName": "queue" },
                    "styleCallback": "boardViewExtender.styleCallback",
                    "persona": "ownerid"
                }
            ],
            "required": [
                "logicalName",
                "swimLaneSource",
            ],
            "properties": {
                "logicalName": {
                    "$id": "#/definitions/boardEntity/properties/logicalName",
                    "type": "string",
                    "title": "logicalName",
                    "description": "This is the logical name of this entity. Needs to be set.",
                    "default": "",
                    "examples": [
                        "incident"
                    ]
                },
                "swimLaneSource": {
                    "$id": "#/definitions/boardEntity/properties/swimLaneSource",
                    "type": "string",
                    "title": "swimLaneSource",
                    "description": "This defines which field to use for splitting data up into lanes. Always needed.",
                    "default": "",
                    "examples": [
                        "statuscode"
                    ]
                },
                "subscriptionLookup": {
                    "$id": "#/definitions/boardEntity/properties/subscriptionLookup",
                    "type": "string",
                    "title": "subscriptionLookup",
                    "description": "When using the subscription and notification feature, you need to create a new lookup on the subscription entity which points to the entity for which you want to subscribe for notifications. Pass the name of the lookup you created in here. If left out, subscription and notification controls will be unavailable",
                    "default": "",
                    "examples": [
                        "oss_incidentid"
                    ]
                },
                "notificationLookup": {
                    "$id": "#/definitions/boardEntity/properties/notificationLookup",
                    "type": "string",
                    "title": "notificationLookup",
                    "description": "When using the subscription and notification feature, you need to create a new lookup on the notification entity which points to the entity for which you want to receive notifications. Pass the name of the lookup you created in here. If left out, subscription and notification controls will be unavailable",
                    "default": "",
                    "examples": [
                        "oss_incidentid"
                    ]
                },
                "transitionCallback": {
                    "$id": "#/definitions/boardEntity/properties/transitionCallback",
                    "type": "string",
                    "title": "transitionCallback",
                    "description": "You can provide a custom function which runs on status transition of a record. You need to pass the function name, which may contain namespaces as well. If not passed, default behaviours will apply.",
                    "default": "",
                    "examples": [
                        "boardViewExtender.onStateTransition"
                    ]
                },
                "preventTransitions": {
                    "$id": "#/definitions/boardEntity/properties/preventTransitions",
                    "type": "boolean",
                    "title": "preventTransitions",
                    "description": "This defines whether drag and drop will be prevented. If not defined, it will default to false and no drag and drop will be possible",
                    "default": false,
                    "examples": [
                        true
                    ]
                },
                "fitLanesToScreenWidth": {
                    "$id": "#/definitions/boardEntity/properties/fitLanesToScreenWidth",
                    "type": "boolean",
                    "title": "fitLanesToScreenWidth",
                    "description": "Setting this to true enables dynamic lane widths, which try to fit all lanes into the page without horizontal scrolling. If not defined, it will default to false.",
                    "default": false,
                    "examples": [
                        true
                    ]
                },
                "hideCountOnLane": {
                    "$id": "#/definitions/boardEntity/properties/hideCountOnLane",
                    "type": "boolean",
                    "title": "hideCountOnLane",
                    "description": "Setting this to true hides the record counts in the lane headers. Defaults to false",
                    "default": false,
                    "examples": [
                        true
                    ]
                },
                "defaultOpenHandler": {
                    "$id": "#/definitions/boardEntity/properties/defaultOpenHandler",
                    "type": "string",
                    "title": "defaultOpenHandler",
                    "description": "Defines how the arrow button of a tile opens the record by default. Defaults to 'inline'",
                    "default": "inline",
                    "examples": [
                        "inline",
                        "sidebyside",
                        "modal",
                        "newwindow"
                    ]
                },
                "visibleLanes": {
                    "$id": "#/definitions/boardEntity/properties/visibleLanes",
                    "type": "array",
                    "title": "visibleLanes",
                    "description": "Defines which lane option values should be shown on the board. All are shown if none are set. Can be combined with hiddenLanes",
                    "default": "null",
                    "examples": [
                        [1, 2, 3]
                    ]
                },
                "hiddenLanes": {
                    "$id": "#/definitions/boardEntity/properties/hiddenLanes",
                    "type": "array",
                    "title": "hiddenLanes",
                    "description": "Defines which lane option values should be hidden on the board. All are shown if none are set. Can be combined with visibleLanes",
                    "default": "null",
                    "examples": [
                        [1, 2, 3]
                    ]
                },
                "persona": {
                    "$id": "#/definitions/boardEntity/properties/persona",
                    "type": "string",
                    "title": "persona",
                    "description": "Defines what is shown as persona on the tile. You can specify 'ownerid' for showing the owner's name. If available, it will even show the corresponding profile picture. Any other property will show an auto generated abbreviated label. Specifying null will hide the persona",
                    "default": "Primary display attribute of the corresponding entity",
                    "examples": [
                        null,
                        "ownerid",
                        "title"
                    ]
                },
                "emailSubscriptionsEnabled": {
                    "$id": "#/definitions/boardEntity/properties/emailSubscriptionsEnabled",
                    "type": "boolean",
                    "title": "emailSubscriptionsEnabled",
                    "description": "Set this to true for allowing users to optin to receiving notifications as emails as well. Configure emailSubscriptionsSender as well for specifying the sender of the notifications, otherwise the emails will have the users who should be notified as sender as well as receiver.",
                    "default": false,
                    "examples": [
                        true
                    ]
                },
                "emailNotificationsSender": {
                    "$id": "#/definitions/boardEntity/properties/emailNotificationsSender",
                    "type": "object",
                    "title": "emailNotificationsSender",
                    "description": "Defines the sender of email notifications when emailSubscriptionsEnabled is true and users subscribed with email opt-in. JSON representation of an EntityReference which will be used as sender of the created emails",
                    "default": null,
                    "examples": [
                        {"Id": "a79cb7fe-ff9e-405b-be68-71de7d0b1031", "LogicalName": "queue" }
                    ],
                    "required": [
                        "Id",
                        "LogicalName"
                    ],
                    "properties": {
                        "Id": {
                            "$id": "#/properties/emailNotificationsSender/properties/Id",
                            "type": "string",
                            "title": "Id",
                            "description": "Id of the sending record",
                            "default": null,
                            "examples": [
                                "a79cb7fe-ff9e-405b-be68-71de7d0b1031"
                            ]
                        },
                        "LogicalName": {
                            "$id": "#/properties/emailNotificationsSender/properties/LogicalName",
                            "type": "string",
                            "title": "LogicalName",
                            "description": "LogicalNameof the sending record",
                            "default": null,
                            "examples": [
                                "queue"
                            ]
                         }
                     }
                }
            }
        },
        "secondaryBoardEntity": {
            "allOf": [
                { "$ref": "#/definitions/boardEntity" },
                { 
                    "$id": "#secondaryBoardEntity",
                    "examples": [
                        {
                            "logicalName": "task",
                            "parentLookup": "regardingobjectid",
                            "swimLaneSource": "statuscode",
                            "subscriptionLookup": "oss_taskid",
                            "notificationLookup": "oss_taskid",
                            "transitionCallback": "boardViewExtender.onSecondaryStateTransition",
                            "defaultView": "All Tasks",
                            "preventTransitions": false,
                            "fitLanesToScreenWidth": false,
                            "hideCountOnLane": false,
                            "defaultOpenHandler": "inline",
                            "hiddenLanes": null,
                            "visibleLanes": null,
                            "visibleViews": ["My active accounts", "a79cb7fe-ff9e-405b-be68-71de7d0b1031"],
                            "hiddenViews": ["My active accounts", "a79cb7fe-ff9e-405b-be68-71de7d0b1031"]
                        }
                    ],
                    "required": [
                        "logicalName",
                        "parentLookup",
                        "swimLaneSource"
                    ],
                    "properties": {
                        "parentLookup": {
                            "$id": "#/definitions/secondaryBoardEntity/properties/parentLookup",
                            "type": "string",
                            "title": "parentLookup",
                            "description": "Name of the lookup over which secondary entity is connected to primary entity. Used for displaying secondary records with their matching primary record. Always needed.",
                            "default": "",
                            "examples": [
                                "regardingobjectid"
                            ]
                        },
                        "defaultView": {
                            "$id": "#/definitions/boardEntity/properties/defaultView",
                            "type": "string",
                            "title": "defaultView",
                            "description": "Provide a default view which will be selected initially. You can either pass the view name or the ID (without curly brackets). Case is ignored in all scenarios.",
                            "default": "First fetched view",
                            "examples": [
                                "All Cases",
                                "2B5F5A5D-2D23-4FE7-AA58-E77995368AE7"
                            ]
                        },
                        "visibleViews": {
                            "$id": "#/definitions/boardEntity/properties/visibleViews",
                            "type": "array",
                            "title": "visibleViews",
                            "description": "Defines which views should be shown on the board. All are shown if none are set. Can be combined with hiddenViews. Can be used with view names and view ids",
                            "default": "null",
                            "examples": [
                                ["My active accounts", "a79cb7fe-ff9e-405b-be68-71de7d0b1031"]
                            ]
                        },
                        "hiddenViews": {
                            "$id": "#/definitions/boardEntity/properties/hiddenViews",
                            "type": "array",
                            "title": "hiddenViews",
                            "description": "Defines which views should be hidden on the board. All are shown if none are set. Can be combined with visibleViews",
                            "default": "null",
                            "examples": [
                                ["My active accounts", "a79cb7fe-ff9e-405b-be68-71de7d0b1031"]
                            ]
                        }
                    }
                }
            ]
        }
    },
    "examples": [
        {
            "primaryEntity": {
                "logicalName": "incident",
                "swimLaneSource": "statuscode",
                "subscriptionLookup": "oss_incidentid",
                "notificationLookup": "oss_incidentid",
                "transitionCallback": "boardViewExtender.onStateTransition",
                "preventTransitions": false,
                "fitLanesToScreenWidth": false,
                "hideCountOnLane": false,
                "defaultOpenHandler": "inline"
            },
            "secondaryEntity": {
                "logicalName": "task",
                "parentLookup": "regardingobjectid",
                "swimLaneSource": "statuscode",
                "subscriptionLookup": "oss_taskid",
                "notificationLookup": "oss_taskid",
                "transitionCallback": "boardViewExtender.onSecondaryStateTransition",
                "defaultView": "All Tasks",
                "preventTransitions": false,
                "fitLanesToScreenWidth": false,
                "hideCountOnLane": false,
                "defaultOpenHandler": "inline"
            },
            "customScriptUrl": "/WebResources/oss_/D365BoardView/js/exampleExternalScript.js"
        }
    ],
    "required": [
        "primaryEntity"
    ],
    "properties": {
        "primaryEntity": { "$ref": "#/definitions/boardEntity" },
        "secondaryEntity": { "$ref": "#/definitions/secondaryBoardEntity" },
        "customScriptUrl": {
            "$id": "#/properties/customScriptUrl",
            "type": "string",
            "title": "customScriptUrl",
            "description": "When using custom logic such as transitionCallbacks, you need to provide the url to the web resource where your custom code can be found, so that it can be fetched on load.",
            "default": "",
            "examples": [
                "/WebResources/oss_/D365BoardView/js/exampleExternalScript.js"
            ]
        },
        "customStyleUrl": {
            "$id": "#/properties/customStyleUrl",
            "type": "string",
            "title": "customStyleUrl",
            "description": "Define url to a web resource with custom css for customizing some styling topics",
            "default": "",
            "examples": [
                "/WebResources/oss_/D365BoardView/css/exampleExternalScript.css"
            ]
        },
        "cachingEnabled": {
            "$id": "#/properties/cachingEnabled",
            "type": "boolean",
            "title": "cachingEnabled",
            "description": "Whether to cache metadata to speed up loading times. Should be enabled on prod and disabled on dev. Cached data is stored in session storage, so when closing the browser completely, cache will be cleared.",
            "default": false,
            "examples": [
                true
            ]
        },
        "defaultDisplayState": {
            "$id": "#/properties/defaultDisplayState",
            "type": "string",
            "title": "defaultDisplayState",
            "description": "Default display state to use when loading the board. Either 'simple' or 'advanced'",
            "default": "simple",
            "examples": [
                "simple", "advanced"
            ]
        }
    },
    "additionalProperties": false
}

Hint: You can compare your config json to this schema on a validator such as https://www.jsonschemavalidator.net/

Clone this wiki locally