POST Query Form

Return a list of forms, filtered on the specified criteria, and which also satisfy the following conditions:

• active and non-test forms
• associated with the current portal

The result is ordered alphabetically by form name.

Request

HTTP request

POST https://<JM_SERVER>/workspaces/secure/api/v1/form/query

Request body

The POST request must contain a JSON structure describing the form query. To support multiple parameters, this API uses HTTP Content Type: application/json.

The set of query JSON attributes is listed below. All attributes are optional except where otherwise indicated.

Attribute	Description
fetchLimit	Integer (Default: 10000) Required. Specify the query fetch limit; that is, the maximum number of results returned. Values: In the range 1 - 10,000. Values greater than 10,000 are reduced to 10,000. Note: This attribute is used in conjunction with fetchOffset to determine which results are returned.
fetchOffset	Integer (Default: 0) Specify the query fetch offset. Note: This attribute is used in conjunction with fetchLimit to determine which results are returned.
filters	List A list of filters to query forms by. To learn more about filters, see Filter query results.

Supported filter criteria attributes

The following filter criteria attributes are supported for the Form API.

caution

If you specify an invalid filter criteria attribute, a 400 Bad Request HTTP status code is returned.

Attribute	Description
categoryName	String (single category) / List of Strings (multiple categories) Filter forms associated with one or more specified form category names. Supported operators: =, IN
clientCode	String Filter forms based on the specified client code. Supported operators: =, IN
description	String Filter forms based on the specified form description. Supported operators: =, LIKE
formCode	String Filter forms based on the specified form code. Supported operators: =, IN
formName	String Filter forms based on the specified form name. Supported operators: =, IN, LIKE
groupName	String (single group) / List of Strings (multiple groups) Filter forms associated with one or more specified form groups. Supported operators: =, IN

Response

If successful, this operation returns a response with a HTTP 200 OK status code.

Error messages

Error key	Error	HTTP status code
illegalArgument	Unsupported criteria attribute: <ATTRIBUTE> Unsupported operator for attribute '<ATTRIBUTE>': <OPERATOR> For input string: <STRING> Please see Error Log ID {number}	400 Bad Request
internalError	Please see Error Log ID {number}	500 Internal Server Error
unableToResolvePortal	Unable to resolve portal from request	400 Bad Request

Error responses

HTTP status code	Description
400 Bad Request	Bad request or request parameter. Check error message for details.
404 Not Found	Ensure the URL endpoint is entered correctly.
500 Internal Server Error	Exception occurred in form query. Contact administrator.

Example

Complex queries can be created by joining multiple criteria using "AND" or "OR" operators. For examples of how to define these queries, see Filter query results.

Ensure you specify Content-Type: application/json.

Example request 1

POST /workspaces/secure/api/v1/form/query HTTP/1.1
Host: https://transact.workspaces.com
Content-Type: application/json

{
    "fetchLimit": 100,
    "filters": [
        {
            "criteria": [
                "formName like 'loan'",
                "categoryName = 'Loan applications'",
                "groupName = 'Job Applicants'"
            ]
        }, {
            "criteria": [
                "formName like 'with attachments'"
            ]
        }
    ]
}

Example request 2

POST /workspaces/secure/api/v1/form/query HTTP/1.1
Host: https://transact.workspaces.com
Content-Type: application/json

{
    "fetchLimit": 100,
    "filters": [
        {
            "criteria": [
                "formName like {0}",
                "categoryName = {1}",
                "groupName = {2}"
            ],
            "params": [
                "loan",
                "Loan Applications",
                "Job Applications"
            ],
            "operator": "AND"
        }, {
            "criteria": [
                "formName like 'with attachments'"
            ]
        }
    ]
}

Example successful response

{
    "fetchLimit": 100,
    "fetchOffset": 0,
    "durationMs": 32,
    "result": [
        {
            "clientCode": "workspace",
            "categoryName": [
                "Loan applications"
            ],
            "currentVersion": "1",
            "description": "Loan application with attachments",
            "formCode": "loanapplicationwitha",
            "formName": "Loan application with attachments",

            "groupName": [
                "Job Applicants"
            ],
            "saveChallenge": false,
            "space": [
                {
                    "formUrl": "https://transact.avoka-transact.com/web-plugin/servlet/SmartForm.html?formCode=loanapplicationwitha",
                    "name": "Web Plug-in",
                    "anonAccess": false,
                    "authAccess": false
                },
                {
                    "formUrl": "https://transact.avoka-transact.com/workspace/servlet/SmartForm.html?formCode=loanapplicationwitha",
                    "name": "Work Space",
                    "anonAccess": true,
                    "authAccess": true
                },
                {
                    "formUrl": "https://transact.avoka-transact.com/workspaces/servlet/SmartForm.html?formCode=loanapplicationwitha",
                    "name": "Work Spaces",
                    "anonAccess": false,
                    "authAccess": true
                }
            ]
        }
    ]
}