Skip to main content
Kinetic Community

Submission Helper

The Submission Component contains methods to search or retrieve submissions within a bundle. Results are returned as a PaginatedList of Submission objects. The size of the submissions list is limited to the value of the "limit" parameter when calling one of the search methods, or the system default of 25 if not specified. The maximum number of submissions that can be retrieved in a single search call is 1000.

If the submissions component retrieved the number of submissions as indicated by the limit, there will be a value in thePaginatedList.nextPageToken property. A value indicates there are more submissions that matched the qualification. To retrieve the next page of submissions, the"nextPage" parameter must be added to the search parameters with the value returned in the PaginatedList.nextPageToken property.

Getting Started

Configuration

The submissions component is automatically added to the request object, and is available for use without having to do anything special in your bundle. The submissions component can be referenced using either JSTL expression language, or Java scriptlet code.

  • JSTL expression language:

    ${Submissions}
    
  • Java scriptlet

    <%
      com.kineticdata.core.web.bundles.BundleSubmissionComponent Submissions =
          (com.kineticdata.core.web.bundles.BundleSubmissionComponent)request
            .getAttribute("Submissions");
    %>

Usage

<%-- partials/sample.jsp --%>
<ul>
<c:forEach var="submission" items="${Submissions.searchByKapp(kapp)}">
  <li>${submission.id}</li>
</c:forEach>
</ul>

Methods

retrieve(String submissionId)
retrieve(java.util.UUID submissionId)

Returns a single submission using the id as the search key.

Submissions.retrieve("8eb7b7e6-bb05-11e5-9912-ba0be0483c18")    // Submission Object

searchByForm(com.kineticdata.core.models.Form form)
searchByForm(com.kineticdata.core.models.Form form, java.util.Map<String, String[]> parameters)

Returns a com.kineticdata.core.web.bundles.PaginatedList<com.kineticdata.core.models.Submission> list of submissions for a specific form. The parameters map be used to specify the search criteria.

java.util.Map<String,String[]> parameters = new java.util.Map<>();
// com.kineticdata.core.web.bundles.PaginatedList<com.kineticdata.core.models.Submission>
Submissions.searchByForm(form, parameters)

searchByKapp(com.kineticdata.core.models.Kapp kapp)
searchByKapp(com.kineticdata.core.models.Kapp kapp, java.util.Map<String, String[]> parameters)

Returns a com.kineticdata.core.web.bundles.PaginatedList<com.kineticdata.core.models.Submission> list of submissions for all forms within a specific kapp. The parameters map be used to specify the search criteria.

java.util.Map<String,String[]> parameters = new java.util.Map<>();
// com.kineticdata.core.web.bundles.PaginatedList<com.kineticdata.core.models.Submission>
Submissions.searchByKapp(kapp, parameters)

Search Parameters

The following search parameters can be included with any submission search:

  • coreState

    Restricts the result set where the submission coreState is one of the supplied values.

    Valid Values:

    • Draft
    • Submitted
    • Closed
  • timeline

    Restricts to submissions where the value of the field identified by this value falls within the date/time range provided by the values in the start and end parameters.

    The default value is createdAt.

    Valid values:

    • closedAt
    • createdAt
    • submittedAt
    • updatedAt
  • start

    Restricts to submissions where the value of the field identified by the timeline property is greater than this ISO8601 date/time value.
  • end

    Restricts to submissions where the value of the field identified by the timeline property is less than this ISO8601 date/time value.
  • direction

    Specifies how the submission results are sorted, based on the field value identified in the timeline property.

    The default value is DESC (descending).

    Valid Values:

    • ASC
    • DESC
  • limit

    Sets a hard limit on the number of submissions that will be returned. If more submissions exist than are returned in the result set, a pageToken will also be provided in the response that corresponds to the last submission returned.

    The default value is 25, and the maximum value is 1000.

  • pageToken

    Corresponds to the last submission returned with a limited result set. This value can be used for paginated results, where there are more submissions than the limit that match the search, to retrieve the next chunk of submissions that match the search parameter values.
  • q

    A custom qualification that can be constructed similar to a SQL where clause that allows building complex expressions using logical and relational operators against submission properties and field values.

    Operators:

      AND             Returns boolean true if and only if both expressions are true
                      Example:    expression1 AND expression2
    
      OR              Returns boolean true if at least one expression is true
                      Example:    expression1 OR expression1
    
      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"
    

    Expression 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")
    

    Submission Properties:

      closedBy        Username that closed the submission
    
      createdBy       Username that created the submission
    
      sessionToken    Used for anonymous submissions
    
      submittedBy     Username that submitted the submission
    
      updatedBy       Username that last updated the submission
    
      values          Any field that is implemented by the Form.
                      Example: the field named 'Approver' would be referred as:  values[Approver]
    

    Example Qualification:

      (values[Requested By] = "john.doe" OR values[Requested For] = "john.doe") 
          AND values[Status] IN ("Pending Assignment", "On Hold")
    

Example Usage

For easier use, it is recommended to write a SubmissionHelper.jspf to wrap BundleSubmissionComponent calls into domain-specific methods, and then call this helper from the partial JSP that is rendering the submission information. One such example is shown below to retrieve the most recent closed submissions form the user making the request.

SubmissionHelper.jspf

<%!
    <%@page import="com.kineticdata.core.authentication.Identity"%>
    <%@page import="com.kineticdata.core.bundles.TimeHelper"%>
    <%@page import="com.kineticdata.core.models.Kapp"%>
    <%@page import="com.kineticdata.core.models.Submission"%>
    <%@page import="com.kineticdata.core.web.bundles.BundleSubmissionComponent"%>
    <%@page import="com.kineticdata.core.web.bundles.PaginatedList"%>
    <%@page import="java.util.Map"%>

    public static class SubmissionHelper {
        private final HttpServletRequest request;
        private final BundleSubmissionComponent submissionComponent;
        private final Kapp kapp;
        private final Identity identity;

        public SubmissionHelper(HttpServletRequest request) {
            this.request = request;
            this.submissionComponent = (BundleSubmissionComponent)request.getAttribute("Submissions");
            this.kapp = (Kapp)request.getAttribute("kapp");
            this.identity = (Identity)request.getAttribute("identity");
        }

        /**
         * Retrieve the first page of closed submissions that were submitted by the current user
         * during the last 30 days.
         */
        public PaginatedList<Submission> retrieveRecentClosed() {
            return retrieveRecentClosed(null);
        }

        /**
         * Retrieve a page of closed submissions that were submitted by the current user
         * during the last 30 days.
         */
        public PaginatedList<Submission> retrieveRecentClosed(String nextPageToken) {
            // Setup the search parameter map.
            Map<String,String[]> parameters = new Map<>();
            // Closed submissions
            parameters.put("coreState", new String[]{ "Closed" });
            // Last 30 days, latest returned first
            parameters.put("timeline", new String[]{ "closedAt" });
            // Now
            parameters.put("end", new String[]{ Time.format(new Date()) });
            // 30 days prior
            parameters.put("start", new String[]{ Time.format(Time.add(new Date(), -30, "days", "Etc/GMT")) });
            // Latest submission will be returned first
            parameters.put("direction", new String[]{ "DESC" });  // not necessary as this is the default
            // Paginate the results
            parameters.put("limit", new String[]{ "50" });
            // Custom query parameter - search the submissions where the submittedBy field is the current user
            if (identity.isAuthenticated()) {
                parameters.put("q", new String[]{ "submittedBy = \"" + identity.getUsername() + "\"" });
            } else {
                parameters.put("q", new String[]{ "submittedBy = \"" + identity.getSessionToken() + "\"" });
            }
            // If the next page token is present, get the results starting at the specified token value
            if (nextPageToken != null) {
                parameters.put("nextPageToken", new String[]{ nextPageToken });
            }

            // Return the results of the search
            return submissionComponent.searchByKapp(kapp, parameters);
        }
    }
%>

Partial JSP calling SubmissionHelper.jspf

<c:forEach var="submission" items="${SubmissionHelper.retrieveRecentClosed()}>
    ...
</c:forEach>

Related