KMP PHP API Reference

WorkflowDefinitionsController extends AppController
in package

Application

WorkflowDefinitions Controller

Manages workflow definitions, visual designer, and versioning.

Constants

MOBILE_QUEUE_DEFAULT_PER_PAGE : int = 25
MOBILE_QUEUE_MAX_PER_PAGE : int = 50
VIEW_DATA_EVENT : string = 'KMP.plugins.callForViewData'
VIEW_PLUGIN_EVENT : string = 'KMP.plugins.callForViewCells'

Properties

$WorkflowDefinitions : WorkflowDefinitionsTable
$defaultTable : string|null
$isCsvRequest : bool
$pluginViewCells : array<string|int, mixed>
$pluginViewCellsEnabledForFragment : bool: Whether an intentionally fragment-style response still needs plugin view cells.
$engine : WorkflowEngineInterface
$versionManager : WorkflowVersionManagerInterface

Methods

__construct() : mixed: Constructor.
add() : Response|null|void: Form to create a new workflow definition.
appSettings() : void: Return JSON list of app settings for the workflow designer.
archive() : Response: Archive a workflow definition and keep its run history.
beforeFilter() : Response|null|void: Pre-action filter for application-wide processing.
beforeRender() : Response|null|void: Finalize view-only data after the action has run.
compareVersions() : Response|null|void: API: Compare two workflow versions and return their diff.
createDraft() : Response|null|void: API: Create a new draft version from the current published version.
delete() : Response: Delete an unused workflow definition.
designer() : Response|null|void: Visual workflow designer page.
index() : Response|null|void: List all workflow definitions.
initialize() : void: Initialize controller.
isCsvRequest() : bool: Check if current request is for CSV export.
loadVersion() : Response|null|void: API: Return a workflow version's definition as JSON.
migrateInstances() : Response|null|void: API: Migrate running instances to a specified version.
policyActions() : void: Return JSON list of public 'can*' methods for a given policy class.
policyClasses() : void: Return JSON list of entity policy classes in the system.
publish() : Response|null|void: API: Publish a draft workflow version.
registry() : Response|null|void: API: Return registry data for the designer palette.
save() : Response|null|void: API: Save a workflow definition and draft version.
switchView() : Response: Switch between mobile and desktop view modes.
toggleActive() : Response|null|void: API: Toggle a workflow definition's is_active flag.
updateMetadata() : Response: API: Update workflow definition metadata from the designer.
versions() : Response|null|void: Show version history for a workflow definition.
appSettingImageDataUri() : string|null: Resolve shared tenant branding for the online and cached mobile templates.
assertSafeContextUrl() : string: Ensure URL is same-origin relative path + query only.
authorizeCurrentUrl() : void: Authorize the current URL/action via Authorization component.
buildGridDataUrlFromPageContext() : string: Build grid-data URL preserving query string from page context.
consumeFlashForStream() : array<string, mixed>: Read flash from session and clear it for stream rendering.
enablePluginViewCellsForFragment() : void: Include route-matched plugin cells in an AJAX or other fragment response.
getPageContextUrl() : string|null: Posted page context URL (path + query), validated.
isGridOriginRequest() : bool: Whether POST originated from a grid index (stay on list).
matchesGridIndexPath() : bool: Whether page context path matches a grid index route pattern.
mobileQueuePagination() : array<string, int|bool>: Build shared pagination values for mobile actionable queues.
mobileQueuePaginationPayload() : array<string, int|bool>: Remove internal pagination values before sending the mobile JSON payload.
organizeViewCells() : array<string|int, mixed>: Organize view cells by type and display order.
renderDataverseTableRowElement() : string: Render a single Dataverse grid row element (Turbo Stream replace target HTML).
renderTurboCloseModal() : Response: Render turbo-stream: flash + replace table frame with lazy reload src.
renderTurboFlashOnly() : Response: Render turbo-stream flash messages without forcing a grid or frame reload.
renderTurboReloadFrame() : Response: Stream that reloads an edit turbo-frame (validation errors).
renderTurboRemoveGridRow() : Response: Render turbo-stream: flash + remove a grid row (no longer matches current filters).
renderTurboReplaceGridRow() : Response: Render turbo-stream: flash + replace a single grid row by DOM id.
wantsTurboStreamRequest() : bool: Whether the client expects a turbo-stream response.
withPageContextQuery() : T: Run a callback with query params from the posted page context URL.
actionLabel() : string: Convert a policy action name to a human-readable label.
buildServiceResultResponse() : Response: Build a flat JSON response from a ServiceResult.
formatValidationErrors() : string: Flatten Cake validation errors for JSON API responses.
getVersionManager() : WorkflowVersionManagerInterface: Get workflow version manager.
isEntityPolicy() : bool: Check whether a policy class belongs to an entity.
policyLabel() : string: Convert a policy class name to a human-readable label.

MOBILE_QUEUE_DEFAULT_PER_PAGE


    public
        int
    MOBILE_QUEUE_DEFAULT_PER_PAGE
    = 25

Shared default page size for mobile actionable queues.

MOBILE_QUEUE_MAX_PER_PAGE


    public
        int
    MOBILE_QUEUE_MAX_PER_PAGE
    = 50

Shared maximum page size for mobile actionable queues.

VIEW_DATA_EVENT


    public
        string
    VIEW_DATA_EVENT
    = 'KMP.plugins.callForViewData'

Event for plugin view data enhancement

VIEW_PLUGIN_EVENT


    public
        string
    VIEW_PLUGIN_EVENT
    = 'KMP.plugins.callForViewCells'

Event for plugin view cell registration

$WorkflowDefinitions


        public
            WorkflowDefinitionsTable
    $WorkflowDefinitions

$defaultTable


        protected
            string|null
    $defaultTable
     = 'WorkflowDefinitions'

$isCsvRequest


        protected
            bool
    $isCsvRequest
     = false

Whether current request is for CSV export (.csv extension)

$pluginViewCells


        protected
            array<string|int, mixed>
    $pluginViewCells
     = []

View cells from plugins for current request

$pluginViewCellsEnabledForFragment

Whether an intentionally fragment-style response still needs plugin view cells.


        protected
            bool
    $pluginViewCellsEnabledForFragment
     = false

$engine


        private
            WorkflowEngineInterface
    $engine

$versionManager


        private
            WorkflowVersionManagerInterface
    $versionManager

__construct()

Constructor.


    public
                    __construct(ServerRequest $request, WorkflowEngineInterface $engine, WorkflowVersionManagerInterface $versionManager[, ComponentRegistry|null $components = null ]) : mixed

Parameters

$request : ServerRequest: Request instance
$engine : WorkflowEngineInterface: Workflow engine
$versionManager : WorkflowVersionManagerInterface: Version manager
$components : ComponentRegistry|null = null: Component registry

add()

Form to create a new workflow definition.


    public
                    add() : Response|null|void

Return values

Response|null|void

appSettings()

Return JSON list of app settings for the workflow designer.


    public
                    appSettings() : void

archive()

Archive a workflow definition and keep its run history.


    public
                    archive(int $id) : Response

Parameters

$id : int: Workflow definition ID

Return values

Response

beforeFilter()

Pre-action filter for application-wide processing.


    public
                    beforeFilter(EventInterface $event) : Response|null|void

Handles: plugin validation, navigation history, view cell loading, and Turbo Frame detection.

Parameters

$event : EventInterface: The beforeFilter event

Return values

Response|null|void

beforeRender()

Finalize view-only data after the action has run.


    public
                    beforeRender(EventInterface<string|int, Controller> $event) : Response|null|void

Deferring view cells prevents redirect-only requests from executing badge callbacks.

Parameters

$event : EventInterface<string|int, Controller>: Event.

Return values

Response|null|void

compareVersions()

API: Compare two workflow versions and return their diff.


    public
                    compareVersions() : Response|null|void

Return values

Response|null|void

createDraft()

API: Create a new draft version from the current published version.


    public
                    createDraft() : Response|null|void

Return values

Response|null|void

delete()

Delete an unused workflow definition.


    public
                    delete(int $id) : Response

Parameters

$id : int: Workflow definition ID

Return values

Response

designer()

Visual workflow designer page.


    public
                    designer([int|null $id = null ]) : Response|null|void

Parameters

$id : int|null = null: Workflow definition ID

Return values

Response|null|void

index()

List all workflow definitions.


    public
                    index() : Response|null|void

Return values

Response|null|void

initialize()

Initialize controller.


    public
                    initialize() : void

isCsvRequest()

Check if current request is for CSV export.


    public
                    isCsvRequest() : bool

Return values

bool

loadVersion()

API: Return a workflow version's definition as JSON.


    public
                    loadVersion(int $versionId) : Response|null|void

Parameters

$versionId : int: Version ID

Return values

Response|null|void

migrateInstances()

API: Migrate running instances to a specified version.


    public
                    migrateInstances() : Response|null|void

Return values

Response|null|void

policyActions()

Return JSON list of public 'can*' methods for a given policy class.


    public
                    policyActions() : void

policyClasses()

Return JSON list of entity policy classes in the system.


    public
                    policyClasses() : void

publish()

API: Publish a draft workflow version.


    public
                    publish() : Response|null|void

Return values

Response|null|void

registry()

API: Return registry data for the designer palette.


    public
                    registry() : Response|null|void

Return values

Response|null|void

save()

API: Save a workflow definition and draft version.


    public
                    save() : Response|null|void

Return values

Response|null|void

switchView()

Switch between mobile and desktop view modes.


    public
                    switchView() : Response

Stores preference in session and redirects to appropriate interface. Mobile redirects to viewMobileCard, desktop to profile.

Return values

Response —

Redirect response

toggleActive()

API: Toggle a workflow definition's is_active flag.


    public
                    toggleActive(int $id) : Response|null|void

Parameters

$id : int: Workflow definition ID

Return values

Response|null|void

updateMetadata()

API: Update workflow definition metadata from the designer.


    public
                    updateMetadata(int $id) : Response

Parameters

$id : int: Workflow definition ID

Return values

Response

versions()

Show version history for a workflow definition.


    public
                    versions(int $definitionId) : Response|null|void

Parameters

$definitionId : int: Workflow definition ID

Return values

Response|null|void

appSettingImageDataUri()

Resolve shared tenant branding for the online and cached mobile templates.


    protected
                    appSettingImageDataUri(string $settingName) : string|null

Parameters

$settingName : string

Return values

string|null

assertSafeContextUrl()

Ensure URL is same-origin relative path + query only.


    protected
                    assertSafeContextUrl(string $url) : string

Parameters

$url : string

Return values

string

authorizeCurrentUrl()

Authorize the current URL/action via Authorization component.


    protected
                    authorizeCurrentUrl() : void

buildGridDataUrlFromPageContext()

Build grid-data URL preserving query string from page context.


    protected
                    buildGridDataUrlFromPageContext(string|null $pageContextUrl, array<string, mixed> $gridDataRoute) : string

Parameters

$pageContextUrl : string|null
$gridDataRoute : array<string, mixed>: Cake URL array for gridData action

Return values

string

consumeFlashForStream()

Read flash from session and clear it for stream rendering.


    protected
                    consumeFlashForStream() : array<string, mixed>

Return values

array<string, mixed>

enablePluginViewCellsForFragment()

Include route-matched plugin cells in an AJAX or other fragment response.


    protected
                    enablePluginViewCellsForFragment() : void

getPageContextUrl()

Posted page context URL (path + query), validated.


    protected
                    getPageContextUrl() : string|null

Return values

string|null

isGridOriginRequest()

Whether POST originated from a grid index (stay on list).


    protected
                    isGridOriginRequest(string|null $pageContextUrl) : bool

Parameters

$pageContextUrl : string|null

Return values

bool

matchesGridIndexPath()

Whether page context path matches a grid index route pattern.


    protected
                    matchesGridIndexPath(string|null $pageContextUrl, string $pathRegex) : bool

Parameters

$pageContextUrl : string|null
$pathRegex : string

Return values

bool

mobileQueuePagination()

Build shared pagination values for mobile actionable queues.


    protected
                    mobileQueuePagination(int $total) : array<string, int|bool>

Parameters

$total : int: Total actionable records

Return values

array<string, int|bool>

mobileQueuePaginationPayload()

Remove internal pagination values before sending the mobile JSON payload.


    protected
                    mobileQueuePaginationPayload(array<string, int|bool> $pagination) : array<string, int|bool>

Parameters

$pagination : array<string, int|bool>: Pagination data

Return values

array<string, int|bool>

organizeViewCells()

Organize view cells by type and display order.


    protected
                    organizeViewCells(array<string|int, mixed> $viewCells) : array<string|int, mixed>

Unused - view cells organized in ViewCellRegistry

Parameters

$viewCells : array<string|int, mixed>: Flat array of view cell configurations

Return values

array<string|int, mixed> —

Organized array grouped by type and sorted by order

renderDataverseTableRowElement()

Render a single Dataverse grid row element (Turbo Stream replace target HTML).


    protected
                    renderDataverseTableRowElement(array<string, mixed> $vars) : string

Parameters

$vars : array<string, mixed>: Element variables

Return values

string

renderTurboCloseModal()

Render turbo-stream: flash + replace table frame with lazy reload src.


    protected
                    renderTurboCloseModal(string $refreshFrame, array<string, mixed> $gridDataRoute[, string|null $pageContextUrl = null ][, array<string|int, mixed>|null $flashMessages = null ]) : Response

Parameters

$refreshFrame : string
$gridDataRoute : array<string, mixed>
$pageContextUrl : string|null = null
$flashMessages : array<string|int, mixed>|null = null

Return values

Response

renderTurboFlashOnly()

Render turbo-stream flash messages without forcing a grid or frame reload.


    protected
                    renderTurboFlashOnly([array<string|int, mixed>|null $flashMessages = null ]) : Response

Parameters

$flashMessages : array<string|int, mixed>|null = null

Return values

Response

renderTurboReloadFrame()

Stream that reloads an edit turbo-frame (validation errors).


    protected
                    renderTurboReloadFrame(string $frameId, string $frameSrc[, array<string|int, mixed>|null $flashMessages = null ]) : Response

Parameters

$frameId : string
$frameSrc : string
$flashMessages : array<string|int, mixed>|null = null

Return values

Response

renderTurboRemoveGridRow()

Render turbo-stream: flash + remove a grid row (no longer matches current filters).


    protected
                    renderTurboRemoveGridRow(string $rowDomId[, array<string|int, mixed>|null $flashMessages = null ]) : Response

Parameters

$rowDomId : string
$flashMessages : array<string|int, mixed>|null = null

Return values

Response

renderTurboReplaceGridRow()

Render turbo-stream: flash + replace a single grid row by DOM id.


    protected
                    renderTurboReplaceGridRow(string $rowDomId, string $rowHtml[, array<string|int, mixed>|null $flashMessages = null ]) : Response

Parameters

$rowDomId : string
$rowHtml : string
$flashMessages : array<string|int, mixed>|null = null

Return values

Response

wantsTurboStreamRequest()

Whether the client expects a turbo-stream response.


    protected
                    wantsTurboStreamRequest() : bool

Return values

bool

withPageContextQuery()

Run a callback with query params from the posted page context URL.


    protected
                    withPageContextQuery(string|null $pageContextUrl, callable(): T $callback) : T

Parameters

$pageContextUrl : string|null
$callback : callable(): T

Return values

actionLabel()

Convert a policy action name to a human-readable label.


    private
                    actionLabel(string $action) : string

Parameters

$action : string: Action method name

Return values

string

buildServiceResultResponse()

Build a flat JSON response from a ServiceResult.


    private
                    buildServiceResultResponse(ServiceResult $result) : Response

Parameters

$result : ServiceResult

Return values

Response

formatValidationErrors()

Flatten Cake validation errors for JSON API responses.


    private
                    formatValidationErrors(array<string, mixed> $errors) : string

Parameters

$errors : array<string, mixed>: Entity validation/rule errors

Return values

string

getVersionManager()

Get workflow version manager.


    private
                    getVersionManager() : WorkflowVersionManagerInterface

Return values

WorkflowVersionManagerInterface

isEntityPolicy()

Check whether a policy class belongs to an entity.


    private
                    isEntityPolicy(string $className) : bool

Parameters

$className : string: Class name

Return values

bool

policyLabel()

Convert a policy class name to a human-readable label.


    private
                    policyLabel(string $className) : string

Parameters

$className : string: Class name

Return values

string

WorkflowDefinitionsController extends AppController in package Application

Table of Contents

Constants

Properties

Methods

Constants

MOBILE_QUEUE_DEFAULT_PER_PAGE

MOBILE_QUEUE_MAX_PER_PAGE

VIEW_DATA_EVENT

VIEW_PLUGIN_EVENT

Properties

$WorkflowDefinitions

$defaultTable

$isCsvRequest

$pluginViewCells

$pluginViewCellsEnabledForFragment

$engine

$versionManager

Methods

__construct()

Parameters

add()

Return values

appSettings()

archive()

Parameters

Return values

beforeFilter()

Parameters

Return values

beforeRender()

Parameters

Return values

compareVersions()

Return values

createDraft()

Return values

delete()

Parameters

Return values

designer()

Parameters

Return values

index()

Return values

initialize()

isCsvRequest()

Return values

loadVersion()

Parameters

Return values

migrateInstances()

Return values

policyActions()

policyClasses()

publish()

Return values

registry()

Return values

save()

Return values

switchView()

Return values

toggleActive()

Parameters

Return values

updateMetadata()

Parameters

Return values

versions()

Parameters

Return values

appSettingImageDataUri()

Parameters

Return values

assertSafeContextUrl()

Parameters

Tags

Return values

authorizeCurrentUrl()

WorkflowDefinitionsController extends AppController
in package

Application