Skip to main content

Introducing Formengine - The New Formbuilder, try for FREE formengine.io.

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, the form will include information about 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 do not recommend changing 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. Because components with server pagination are independent of 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.
  • forCopy - if true, the request comes from the form opened for copying.

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

{
    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.