Controllers

Server and client interact with each other via several main controllers with the following methods and parameters. All DWKit controllers send uniform responses. Below is an example of a successful completion of an operation:

{
    item: {...some response object ...},
    success: true
}

or

{
    message: "Some operation complete",
    success: true
}

An example of an error response:

{
    message: "Some exception",
    details: "Stack trace",
    success: false
}

Keep in mind that some controllers (mainly DataController) can add additional info into response (server validation result for example).

UserInterfaceController

DWKit client side receives form layout via this controller. It also contains methods which transfer javascript files required to work with forms to the client.

The GetForm (route /ui/form/{name}) method

Returns layout forms. Input parameters:

  • name - form name
  • wrapResult - if true, JSON forms will be wrapped in an object of a {item:{form},success:true} type.
  • enableSecurity - if true, form will included information about the permissions for the current authorized user, connected to the form.

Returns a form description object serialized in JSON, which contains the following important fields:

{
    item: {
        name: "Form name",
        source: "JSON source (layout) of the form",
        permissions: [{form permission object}],
        mapping: {}
    },
    success: true
}
  • name - form name.
  • source - form layout stored and visualized in Form Builder.
  • permissions - permission connected to form with the indication of Permitted, Forbidden or Inherited.
  • mapping - object to convert attribute names of the form data object (see Mapping form and data) into Data Model attribute names. Is used automatically for modal child forms.

The GetFlow (route /ui/flow/{name}) method

Returns form bound to Business Flow.

Input parameters:

  • name - business flow name.
  • urlFilter - here the filter is transferred by which you can find a document. In most cases document ID is transferred.
  • forCopy - if true, the request comes from the form opened for copying.

Returned result is similar to the result which returns the GetForm method. I.e. we define which Form is to be opened by the name of Business flow.

The GetFormsBusinessCode (route /ui/form/businessobjects.js) method

Returns a Javascript file with all client user-defined actions code.

The GetLocalization (route /ui/localization.js) method

Returns a javascript file with localization constants.

The Login (route /ui/login) method

Returns a login form.

ConfigAPIController

The API (route /configapi) method

System method for saving/loading metadata from the admin panel to the server. This method does not accept parameters explicitly. All parameters transferred with request are transmitted in the DWKitRuntime.Metadata.ConfigAPI() function which processes all admin panel requests. We don to recommend to change this method.

DataController

This controller is used to interact with form data.

The GetData (route /data/get) method

Forms and paging grids receive data via this method. Input parameters:

  • name - form name
  • propertyName - you should specify property name (as a rule it's a component collection), which is required in paging requests. It's a non-required field in all other cases.
  • urlFilter - part of the url, responsible for the filter. It can be represented in the following formats:
    • hostname/form/FormName/FilterActionName/ - name of a server user-defined action - filter.
    • or hostname/form/FormName/90fb3531-808f-43d9-be92-d3c5e8b70ebd/ - value of the primary key of an opened record.
    • or hostname/form/FormName/[{term:"like",column:"Name",value:"Document"},{term:">=",column:"Amount",value:10}] - value of a filter by columns, serialized in JSON. This expression means Name LIKE ('%Document%') AND Amount >= 10.
  • options - a serialized object-parameter transmitted to the server Filter.
  • filter - a filter serialized in JSON, sent by a grid with server pagination, for example, [{term:"like",column:"Name",value:"Document"},{term:">=",column:"Amount",value:10}]
  • paging - a request of a data page, serialized in JSON, sent by a grid with server pagination, for example, {startIndex:20,pageSize:10}
  • sort - sorting serialized in JSON, sent by a grid with server pagination, for example, [{Column:"Name",Order:"ASC"},{Column:"Amount",Order:"DESC"]
  • forCopy - if true, the request comes from the form opened for copying.

This method returns data to be displayed in the form or data for a collection component with server pagination. Components with server pagination request data separately from the rest of the form. As far as components with server pagination are independent from each other, each component requests data only for itself. Let's look at the form in the following example. This form does not contain components with server pagination, that's why one request is enough to get data it needs.

{
    success: true,
    item : {
        ...
        amount: 111,
        comment: null,
        Id: '90fb3531-808f-43d9-be92-d3c5e8b70ebd',
        __id: '90fb3531-808f-43d9-be92-d3c5e8b70ebd',
        gridHistory: [
            {
                ...
                command: 'Approve',
                to: 'Accounting review',
                Id: 'cd8ebe54-2a33-4b3a-b318-0bbc1d13af87',
                from: 'BigBoss signing',
                __id: 'cd8ebe54-2a33-4b3a-b318-0bbc1d13af87'
                ...
            },
            {
                ...
                command: 'SetState',
                to: 'Manager signing',
                Id: 'f47d6f0e-81a2-4fbd-b6e2-8083b518e547',
                from: 'Vacation request created',
                __id: 'f47d6f0e-81a2-4fbd-b6e2-8083b518e547'
                ...
            },
        ]
        ...
    }
}

This form contains only one grid with server pagination, that's why responses to its requests will look like this:

{
    success: true,
    item : {
        __grid_totalcount: 2,
        grid: [
            {
                amount: 100,
                comment: null,
                Id: "90fb3531-808f-43d9-be92-d3c5e8b70ebd",
                name: "Name1",
                State: "RequestApproved",
                __id: "90fb3531-808f-43d9-be92-d3c5e8b70ebd"
            ...
            },
            {
                amount: 200,
                comment: "Test comment",
                Id: "cd8ebe54-2a33-4b3a-b318-0bbc1d13af87",
                name: "Name2",
                State: "AccountingReview",
                __id: "cd8ebe54-2a33-4b3a-b318-0bbc1d13af87"
            ...
            }
        ]
    }
}

The ChangeData (route /data/change) method

Changes the form data. Input parameters are:

  • name - form name.
  • data - changed form data. The data format is identical to the data returned by the GetData method.

Returns a success or error response.

Success response will have additional properties:

{
    success: true,
    item: {form data object}
    result: {the global state of the client application change object},
    message: "some additional message"
}

Fail response will have additional properties:

{
    success: false,
    message: "some error message",
    details: "error stacktrace",
    result: {the global state of the client application change object},
    validationResult: {server validation errors object}
}

The DeleteData (route /data/delete) method

Is used to delete data from the entire form or rows from the grid with server pagination. Input parameters are:

  • name - name of a form.
  • propertyName - control - name of a form control, specified in case you delete not the data from the entire form, but the lines from the grid with server pagination.
  • data - a list of IDs of deleted records, serialized in JSON.

Returns a success or error response.

Success response will have additional properties:

{
    success: true,
    result: {the global state of the client application change object},
    message: "some additional message"
}

Fail response will have additional properties:

{
    success: false,
    message: "some error message",
    details: "error stacktrace",
    result: {the global state of the client application change object},
    validationResult: {server validation errors object}
}

The GetDictionary (route /data/dictionary) method

Returns the data for the component of Dictionary or Tree picker type. Input parameters are:

  • name - name of the Data model specified in the settings of the component.
  • sort - sorting serialized in JSON, for example [{Column:"Name",Order:"ASC"},{Column:"Amount",Order:"DESC"}].
  • columns - a serialized list of columns, from which an output value is formed, for example ["Name","Amount"].
  • paging - request of a data page, serialized in JSON, sent by a grid with server pagination, for example, {startIndex:20,pageSize:10}.
  • filter - a filter serialized in JSON, for example, [{term:"like",column:"Name",value:"Document"},{term:">=",column:"Amount",value:10}].
  • parent - attribute name by which hierarchy is built in the Tree picker component.

Returns a dictionary of values. There will be the following component response for Dictionary:

{
    success: true,
    item : [
        {key:"cd8ebe54-2a33-4b3a-b318-0bbc1d13af87", value: "Name1 100" },
        {key:"90fb3531-808f-43d9-be92-d3c5e8b70ebd", value: "Name2 200" }
    ]

There will be the following component response for Tree picker:

{
    success: true,
    item : [
        {key:"cd8ebe54-2a33-4b3a-b318-0bbc1d13af87", name: "Name1 100", parent:"90fb3531-808f-43d9-be92-d3c5e8b70ebd", HasChild: false},
        {key:"90fb3531-808f-43d9-be92-d3c5e8b70ebd", name: "Name2 200", parent:null, HasChild: true}
    ]

The UploadFile (route /data/upload) method

Method by which DWKit uploads files.

The DownloadFile (route /data/download/{token}) method

Method by which DWKit downloads files. token - file ID.

WorkflowController

This controller is used to control workflow processes.

The DesignerAPI (route /workflow/designerapi) method

Enables proper functioning of the Workflow Designer.

The GetData (route /workflow/get) method

Returns a list of commands and states available for a document. Input parameters are:

  • name - name of a form
  • urlFilter - part of the url, responsible for the filter. It can be represented in the following formats:

    • hostname/form/FormName/FilterActionName/ - name of a server user-defined action - filter
    • or hostname/form/FormName/90fb3531-808f-43d9-be92-d3c5e8b70ebd/ - value of the primary key of an opened record.
    • or hostname/form/FormName/[{term:"like",column:"Name",value:"Document"},{term:">=",column:"Amount",value:10}] - value of a filter by columns, serialized in JSON. This expression means Name LIKE ('%Document%') AND Amount >= 10.

    DWKit finds a requested document, finds a corresponding Workflow Process and returns a list of commands and states available for setting.

  • forCopy - if true, the request comes from the form opened for copying.
{
    success: true,
    item : {
        commands : [
            {
                Value:"CommandSystemName",
                Text:"Command name",
                Scheme:"WorkflowSchemeName",
                Type:1,
                Form: {Name: "CommandFormName"}
            },
            {...}
        ],
        states : [{Value:"StateSystemName", Text:"State name"},{...}]
    }
}

For more details, refer to the sections on commands and states.

The ExecuteCommand (route /workflow/execute) method

Executes a command. Input parameters are:

  • name - name of a form.
  • id - id of a document.
  • command - name of the command to be executed.
  • data - data collected from a Command form.

Returns a success or error response.

The SetState (route /workflow/set) method

Sets a state. Input parameters are:

  • name - form name.
  • id - document ID.
  • state - name of the state to be set.

Returns a success or error response.

CodeActionController

This controller is used to launch server Actions.

The Execute (route /actions/execute) method

Launches server Action. Input parameters are:

  • name - name of server Action to be launched.
  • request - object which will be transferred to server Action.

Learn more about calling and returning server Action here.

IntegrationAPIController

Implements DWKit integration API. Learn more about integration API here.

ExternalController

Required for support authorization using Identity Server. Learn more about Identity Server and OpenId here.