Skip to main content
Kinetic Community

Submissions API Search Qualification Parameters

The submissions API allows searching by a variety of criteria to retrieve a list of submissions.  Some of this criteria is structured and may either be required or optional depending on the property it represents, and other criteria is unstructured and defined by the user requesting the data.

Some examples of the structured data would include:

  • Kapp Slug and/or Form Slug
  • Core State
  • Timeline
  • Date Range (Start / End)

 

Some examples of the unstructured data would include:

  • Submission Properties - closedBy, createdBy, sessionToken, submittedBy, updatedBy
  • Values - fields that are defined on the form

 

Each piece of structured data has a direct mapping to an associated search parameter.  The unstructured data must be constructed into a qualification using the Kinetic Query Language (KQL) syntax, and mapped to generic qualification parameter designated by the name "q".  The KQL qualification will end up being very similar to the "WHERE" clause in an SQL query.

 

Submission Properties

Properties from the submission that may be used as the key in KQL expressions:

  • closedBy
    • Username of the user that set the submission Core State to "Closed"
  • createdBy
    • Username of the user that created the submission
  • sessionToken
    • Used for anonymous submissions
  • submittedBy
    • Username of the user that set the submission Core State to "Submitted"
  • updatedBy
    • Username of the last user that updated the submission
  • values
    • Any field that is implemented by the Form.
    • Example: the field named 'Approver' would be referred as:  values[Approver]

 

KQL Operators 

Currently the following operators are available in KQL expressions.

  • AND
    • Returns boolean true if and only if both expressions are true
    • Example: expression1 AND expression2
  • OR
    • Returns boolean true if at least on expression is true
    • Example: expression1 OR expression2
  • IN
    • Returns boolean true if the key matches one of the list values
    • Example: key IN ("Value One", "Value Two", "Value Three")
  • =
    • Returns boolean true if the key is exactly equal to the value
    • Example: key = "Test Value"

 

KQL Expression Symbols

In addition to the operators, KQL expressions may also use these symbols.

  • null
    • Means "no value"
    • Example: key = null
  • (
    • Left parentheses for logic grouping, MUST be used with right parentheses
    • Example: (key = "Value 1" OR key = "Value 2")
  • )
    • Right parentheses for logic grouping, MUST be used with left parentheses
    • Example: (key = "Value 1" OR key = "Value 2")
  • ,
    • Comma for separating list items
    • Example: key IN ("Value 1", "Value 2")

 

 

Other parameters that don't affect the search criteria, but do have influence over the result set can also be added to limit the number of results.  Such parameters can be used to specify the page chunk, to determine the order, etc...  These parameters are all optional, and intelligent defaults will be used if they are omitted.

 

Parameter / Property Mappings

The following table shows the parameter mappings for both the structured and unstructured qualifications, as well as indicating whether the parameter is required or not.

Parameter Name Property Description Allowed Values / Example Required?
kappSlug Slug of the Kapp being searched Ex: catalog Yes
formSlug Slug of the Form being searched Ex: new-hire Only if searching by form.
type The form type to search Ex: Service No
coreState The submission "Core State" property. Draft, Submitted, or Closed No
timeline The timeline property to use for ordering the results. Default is the submission createdAt property. closedAt, createdAt, submittedAt, updatedAt No
direction The direction to order the results, based on the value of the 'timeline' property. Default is descending (DESC). ASC, DESC No
start The date/time to use that the submission 'timeline' property must be greater than or equal to. The format must be ISO8601 relative to UTC. 2016-03-01T06:00:00.000+00:00 No
end The date/time to use that the submission 'timeline' property must be less than or equal to. The format must be ISO8601 relative to UTC. 2016-04-01T05:59:59.999+00:00 No
limit Limits the number of results returned. The default is 25. The maximum is 1000. 25 No
pageToken The value to use as the offset for the page of submissions to return. The submission that matches this value will not be included in the results. i0im3k5h222m1kh7p0bats15588niopgiii No
q The unstructured, custom qualification parameter. Use this parameter to construct a KQL qualification that defines your desired query. (values[Requested For] = "john.doe" OR values[Requested By] = "john.doe") AND values[Required Approval] = "Yes" No