Main Article Collection
Contents
- Overview
- Stages: Part 2 - Required and External Stages
- Folders: Part 2
- Step Types & Form Relationships
- Activities to Support These Concepts
Overview
The Submission Portal is a major feature of Zengine that is crucial to the functioning of grant, scholarship, and a range of other programs. The core concepts involved in understanding how a submission portal works with the data in a Zengine workspace is discussed in the article Submission Portal Key Concepts: Beginner. This article will explain more complex concepts, appropriate for an administrator with an intermediate-level understanding of submission portals, that are nonetheless critical for building and managing a program’s submission portal(s). These concepts include different Step types, a more detailed explanation of how folders on a submission portal’s Primary form control Stage access, and how form relationships contribute to the structure of the portal user’s experience.
If already familiar with configuring submission portals, or are interested in finding how to make a specific change to a submission portal, please see the article Introduction to Submission Portals: START HERE (where a recommended article reading order, based on an individual’s experience and familiarity with Zengine, can be found) or Submission Portal Settings.
Stages: Part 2 - Required and External Stages
There is one more layer of complexity to how Stages, Steps, and Folders work together in a submission portal beyond what was discussed in the Submission Portal Key Concepts: Beginner article. Two different types of Stages exist: Required and External. Understanding these different types of Stages is important for structuring the submission portal and workflow.
Required Stages are Stages in which an applicant or portal user is required to submit information or perform a similar action before they can progress to the next program stage or milestone. A typical Required Stage may be an Application Intake Stage in which a portal user must complete one or more forms as part of their application package, or an Award Stage if a portal user is required to accept an award and provide payment details, for example, in the submission portal upon receiving their award.
Importantly, once an applicant or portal user has completed all required Steps in a Required Stage, submitting that Stage will automatically advance them to the next Stage in the process by changing the folder status on that portal user’s Primary form.
When a stage is completed by an administrator instead of a portal user, the stage is called an External Stage. External stages do not require portal users to complete any actions, and the portal user cannot advance to the next program stage or milestone on their own. One External Stage in a typical program might be called Under Review, in which administrators and reviewers assess application packages, determine awards, and actually create award packages for awardees. When administrators have finished going through all submitted application packages, they will manually change the folders of different Primary form records to Awarded or Not Awarded, which will send these applicants to different Stages in the submission portal.
There are a few other things that are useful to keep in mind regarding Required and External Stages:
- Steps (and associated Forms) can generally only be added to Required Stages, and at least one Step must be included in a Required Stage.
- There is one exception to this rule, but it’s rare, and not relevant to this article.
- Required Stages can only be associated with one folder on the primary form. However, External Stages can be associated with more than one folder. This can be useful if, for example, an application package must undergo multiple rounds of review: a stage called Under Review can be associated with folders labeled Review Round 1 and Review Round 2, and if an administrator promotes that application package to the second review round, the applicant will remain in the Under Review stage and will not be notified of any review status changes.
- Required and External Stages are often paired together in a submission portal workflow. For example, a Required Stage called Application Intake is frequently followed by an External Stage called Under Review that allows administrators to evaluate application packages and determine awards at their own pace. Similarly, an Award Acceptance Required Stage may be followed by an Award Acceptance Submitted External Stage, so administrators can review the award confirmation details that have been submitted by a portal user before advancing them to the next stage.
Folders: Part 2
Primary Form Folder Examples
As discussed in the article Submission Portal Key Concepts: Beginner, folders on the Primary form control which Stage an applicant or portal user has access to. The name of the current Stage will be indicated on the Submission Card on the Homepage of the submission portal.
To enable a submission portal to function properly, folders need to be created when setting up the Primary form. Those folders must then be associated with a specific Stage when building a submission portal.
Folders on a Primary form, and the Stages they are associated with, will vary depending on a program’s workflow, but could include:
At a minimum, an In Progress folder and a Submitted folder need to be set up on a program’s primary form for the submission portal to function properly. (For information on adding, deleting, or editing folders on a form, see the article Form Builder Overview → Form Settings → Folder Settings (section). For more information about Primary form requirements, see Building a Submission Portal.)
Manual Folder Movements
When a portal user completes all necessary steps associated with a Required Stage and submits that Stage, the submission portal will automatically change the folder on the Primary form to the one associated with the next Stage. The portal user will then gain access to that subsequent Stage, if it is a Required Stage; if it is an External Stage, the portal user must wait for administrator action to advance to the next Required Stage.
However, an administrator can manually change the folder of a record in the administrative portal (for more information, see the article Viewing, Editing, and Moving Records → Moving Records (section)). If an administrator changes the folder of a record to one associated with an earlier stage in the process, for example, the portal user can edit their information and re-submit (even if it was previously submitted). Conversely, if an administrator changes the folder to one associated with a later stage, the portal will be able to access that later stage (even if earlier stages were not completed).
--- IMPORTANT ---
If the folder of the Primary Form record is changed to one that is not associated with any stage in the submission portal, this card will show Stage Unspecified in red text, and the end-user will be unable to access any stages.
Folders and Other Forms
Folders CAN be set up on other forms, but these will not affect the function of the submission portal. For example, folders can be set up on other forms to:
- Trigger auto-emails
- For internal tracking of completion or review status
- Review feedback forms require three folders to track review completion status in a Review Portal
Step Types & Form Relationships
Four different types of Steps exist in a submission portal: Primary, Requests, Single Form, and Listing. Understanding the difference between Step types is important for creating a submission portal experience that suits a program’s requirements.
Primary Step
A Primary Step type is a Step associated with the Primary form. This Step must be associated with the first Stage in a submission portal, and is typically the first Step a portal user will complete. Because this Step is determined when a submission portal is first created, it cannot be changed without rebuilding a submission portal.
Request Step
A Request Step is a special kind of Step that uses a submission portal’s Request feature. This is a useful feature that allows a portal user to involve outside collaborators; a typical use for this feature is to allow a third party to submit a blind letter of recommendation on behalf of an applicant, without needing to access the submission portal directly.
The remainder of this section focuses on a discussion of Single Form and Listing Steps. For more information on using and configuring Request Steps, see the article Requests.
Single Form and Listing Steps
A Single Form Step type means that a portal user will only fill out a single form associated with that Step. In the Zengine workspace, this action will create only one record on that form. Conversely, a Listing Step type allows a portal user to fill out the same form multiple times, creating more than one record, for that Step. This distinction can provide a great deal of flexibility when it comes to meeting a program’s workflow requirements.
As one example, a Listing Step may be ideal if, as part of an application process to a scholarship program, an applicant is asked to submit information about other scholarships they have applied for. Because the number of other scholarships will vary from applicant to applicant, estimating the number of fields to collect this information on a single form is difficult. A Listing Step solves this problem by allowing an applicant to complete as many records as they need to, with each completion representing a different scholarship to which the applicant has already applied.
Whether a Step is configured as a Single Form or Listing Step cannot be configured by a submission portal setting. Instead, it is determined by the form relationship between the Primary form and the form associated with the Step in question.
Form Relationships
The relationship between linked forms in a submission portal, and for Zengine in general, is frequently referred to as parent and child records. These can be characterized as a one-to-one relationship (i.e., only one child form record can be linked to a parent form record) or a one-to-many relationship (i.e., many child form records can be linked to a single parent form record).
A one-to-one relationship between the Primary form (parent) and a linked secondary form (child), when associated with a Step in the Submission Portal, will create a Single Form Step Type, meaning that the applicant (portal user) can only fill out a form once as part of a Stage.
Conversely, a one-to-many relationship between the Primary form and a linked child form will create a Listing Step Type in the Submission Portal, allowing the portal user to create more than one record on the associated form for each Primary form record.
Configuring the relationship between two linked forms is done by editing a Linked Form field on a form directly in the Zengine workspace. For more information on using and configuring Linked Fields, see the article Linking Forms.
For more information on the submission portal experience for Listing Steps, as well as how to configure the appearance and behavior of Listing Steps, see the articles Configure Listing Steps and Customize the Listing Page.
Typically, for a submission portal to function properly, the following form relationships should be observed:
- User form to Profile form: one-to-one
- Profile Form to Primary form: one-to-one if each applicant or end-user can only submit one application package once, or one-to-many if an applicant or end-user can create and submit multiple application packages.
- Primary form to Secondary forms: this can vary. For example, if an applicant must submit information to accept an award, but only one award, the relationship between an Application (Primary) form and the Award form (secondary) should be one-to-one. However, if multiple awards can be given for a single application, this relationship should be one-to-many.
For more information on the forms and form relationships needed to set up a submission portal, see the article Building a Submission Portal.
The following article provides more information about form relationships:
To learn more about linking forms and Linked Fields:
Activities to Support These Concepts
Knowing how to identify whether a Step is Required or External in an existing submission portal is useful for an administrator, as is identifying whether a Step is a Single Form, Listing, or other Step type. The activities below will help locate this information.
Once these activities have been completed, continue learning about submission portals by returning to the article Introduction to Submission Portals: START HERE and explore how to change submission portal settings that are appropriate for an administrator with Intermediate- or Advanced-level knowledge about submission portals. You can also explore the article Submission Portal Settings or begin building your own submission portal (Building a Submission Portal).
Navigating to Submission Portal Settings
Begin by navigating to the Settings for a submission portal.
- Logged into a program as an administrator, navigate to the Settings & Tools section by selecting the cog wheel icon in the top navigation bar.
- Select the Submission Portal tile from the Plugin Settings section.
- Select the Edit button to the appropriate submission portal.
Note: if no submission portals are listed on this screen, a basic submission portal must be built to continue with this activity. Please see the article Building a Submission Portal.
Identifying Required and External Stages
From the Submission Portal Settings, an administrator can easily identify which Stages are Required Stages and which are External Stages.
- Upon entering the Submission Portal Settings, administrators will see a pane on the left side of any screen called Portal Sections. This pane will show a linear list of the Stages and Steps a portal user will progress through over the full course of a program workflow. The image below shows an example of this pane. (The Stages and Steps are listed under Submissions.)
- Identify the Stages:
Required Stages will have Steps associated with them, while External Stages do not. In the example above, the Stages Application Stage, Awarded, and Program Outcomes are Required Stages, as these have one or more Steps listed underneath them that portal users must complete to progress.
External Stages do not have any Steps listed underneath them. In the example above, the Stages Full Application Under Review, Not Awarded, Reporting, and Completed Process are External Stages.
- Selecting the Stage name in this Portal Sections list will bring up the Stage Settings page in the main part of the screen. This provides another way to differentiate between Stage types, as the Stage Settings configuration options are much more robust for Required Stages than they are for External Stages.
Submission Portal Stage Settings page for a Required Stage.
Submission Portal Stage Settings page for an External Stage.
Identifying the Step Type
Administrators can also easily verify the Step type from anywhere in the Submission Portal Settings.
- In the Portal Sections pane on the left side of the screen, select the link for the Step that you wish to view. (Steps are associated with a Stage, and are shown on the Portal Sections pane as indented further to the right.) Multiple Steps are highlighted in the example image below to show there may be more than one to choose from.
2. Selecting a Step in the Portal Sections panel will change the contents of the right panel and display the Step Settings.
- If not already showing, select the Step Description tab at the top of the Step Settings page.
- The Step type (Primary, Single Form, Listing, or Request) will appear near the top of the Step Description tab, next to Step Type.