This article is considered appropriate for administrators or workspace users with an advanced level of knowledge about submission portals. If you are a beginner or intermediate user, we recommend to read the following articles first:
For more information about suggested learning paths, see Introduction to Submission Portals: START HERE.
- The Purpose of Listing Steps
- Where to Find the Listing Step Configuration Options
- Standard Portal Experience for a Listing Step
- Configure a Listing Step
- Additional Articles
In a submission portal, a Listing Step is a type of Step that allows a portal user to complete the same form multiple times; each completion is captured as a separate record on the given form (which is linked to the Primary form of the submission portal).
This article will detail where to find and make changes to the configuration options for a Listing Step, as well as how changing each of these options affects the submission portal experience.
The Purpose of Listing Steps
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.
Listing Steps can be useful for other scenarios, and can be configured in different ways to increase their utility. Administrators can hide the completion status for a Listing Step, make the Step optional, prevent applicants from adding new records or submitting the Stage that the Listing Step is associated with, and hide the Listing Step completely if no records exist for that portal user.
These configuration options add flexibility and depth to a program’s use of Listing Steps to meet a wider variety of needs and offer administrators more control over their workflow.
Where to Find the Listing Step Configuration Options
In the Submission Portal Settings, the Listing Step configuration options can be found on the Step Description tab of the Step Settings page for the Listing Step which an administrator wishes to configure. (Note that these settings will not appear for Single Form Steps.)
To locate the configuration options for a Listing Step:
- 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.
- In the Portal Sections pane on the left side of the screen, select the Listing Step to be configured. (The Listing Steps vary from program to program and will most likely be different from the screenshot example below).
- Selecting a Listing 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.
- On the Step Description tab, confirm the Step Type near the top of the page.
- Scroll down towards the bottom of this page. The relevant configuration options are shown here.
NOTE: the options for Hide Add New Button? and Hide Submit Button on the Stage? will only appear if the first option Hide Completion Status? is checked, so the screen may look slightly different from this image at first.
Standard Portal Experience for a Listing Step
Understanding a standard submission portal experience for a Listing Step (without any configuration options enabled) is useful to provide a baseline for how each configuration option affects this experience. (If already familiar with Listing Steps and how they behave in a portal, feel free to skip this section and continue to Configure a Listing Step below.)
Once a portal user accesses their submission card in the submission portal, they will be taken to the Submissions Page, showing the current Stage they are on and any previous Stages they have completed. There is no clear indication of which Steps are Single Form and Listing Step types on this page, but in the image below, the Payments Step is a Listing Step.
The status will update from Action Required to Complete once the minimum number of listing items have been marked complete by a portal user. In addition, the Open button will change to Edit. Portal users will be able to edit their listing items until the Stage is submitted. (For information on how to hide the completion status for a Listing Step, see the section Configure a Listing Step → Hide Completion Status below.)
Selecting Open or Edit on a Single Form Step will take the user directly to the Form Page where they can enter information. However, doing so with a Listing Step will take a portal user to a Listing Page, where they will see a list of the items that have been added. Up to three fields from the form used in the Listing Step can be previewed as a column on this listing table. (Configuring these columns is not covered in this article; for more information on configuring these columns, see the article Customize the Listing Page.)
In the image below, three listing items have been added, and the portal user can identify each by previewing the Payment number, the Amount of the Payment, and the payment Status. The third item is marked as a Draft, indicating that it is in progress and not all required fields have been completed.
A portal user can view important information and perform actions on the Listing Page (image above):
A. Listing Page Messaging Text; this text can be edited.
- Editing the Listing Page text is not covered in this article; for more information on editing the text that appears at the top of a Listing Page, see the article Customize the Listing Page.
B. The number of minimum items required to complete this Step, the maximum allowed, and total completed.
- Changing this setting is not covered in this article; for more information on configuring the minimum and maximum number of listing items that can be added, see the article Customize the Listing Page.
C. Portal users can select the blue arrow buttons next to each column to order the items in ascending or descending order based on that column.
D. Portal users can select the green + New Item button to add a new item, which will create a new record on the associated form in Zengine.
- For information on how to hide the + New Item button, see the section Configure a Listing Step → Hide Add New Button below.
- Selecting + New Item will take the user to the Form Page, where they can fill in the fields and complete a new item/record.
After selecting + New Item, a portal user can view information and perform actions on the Form Page:
A. Step Form Messaging; this text can be edited.
- Changing the text that appears at the top of the Form Page is not covered in this article; for more information on changing the Step Form Messaging text, see the article Step Page Text.
B. Portal users can select Delete to delete this item. After doing so, it will no longer appear on the Listing Page.
- Preventing portal users from deleting listing items is not covered in this article; for more information on disabling the Delete button, see the article Prevent Portal Users from Deleting Listing Items.
C. Portal users can select Save Draft to save their progress before all required fields are filled in.
D. Portal users can select Mark Complete to save the item as complete once all required fields are filled in.
E. Portal users can select Close to return to the previous Listing Page.
Configure a Listing Step
The way a Listing Step behaves can be configured on the Step Description tab of the Step Settings page for a Listing Step.
Remember to select the blue Save all settings button in the lower right corner of the screen to save all changes to the Step when the configuration is complete.
Hide Completion Status
Selecting the checkbox next to Hide Completion Status? will remove the status Action Required or Complete next to the Listing Step on the Submission Page as shown in the example below.
NOTE: the Hide Add New Button? and Hide Submit Button on the Stage? options will only appear if Hide Completion Status? is enabled.
Hide Add New Button
Once the Hide Completion Status? option is enabled, selecting the checkbox next to Hide Add New Button? will remove the green + New Item button on the Listing Page.
In the image above, the + New Item button has been removed, preventing portal users from adding new items. (The red box in the image indicates where the + New Item button normally appears.) This can be useful if administrators will be completing these records in the workspace and wish the portal user to add or confirm information on each listing item, but not add new ones.
Hide Submit Button on the Stage
Once the Hide Completion Status? option is enabled, selecting the checkbox next to Hide Submit Button on the Stage? will remove the green Submit button on the Submissions Page.
In the image above, the Submit button for the Stage has been removed, preventing portal users from completing the Stage and advancing to the next one. (The red box in this image indicates where the Submit button would normally appear.) This can be useful if administrators want to control when a portal user progresses to the next Stage by changing the folder on their Primary form record manually.
Selecting the checkbox next to Make Optional? will make the Step optional for the portal user to complete before they are able to submit the Stage.
For more information on making Steps optional, see the article Making a Step Optional in the Submission Portal.
Hide if No Records Exist
If the checkbox next to Hide if No Records Exist? is selected, then the Listing Step will not appear to a portal user at all if no records exist that are linked to the portal user’s primary form.
In the image above, no Payments records exist for this portal user, so the Step is completely hidden. This can be useful if an administrator only needs a portal user to confirm information for records that have been pre-populated in the workspace, but some users may not need to confirm any information, and thus should not see this option at all if it is not required of them.
NOTE: Hiding the Listing Step if no records exist will prevent the user from submitting the Stage IF the Step is not made optional. Zengine will still understand that Listing Step should be required, even if it is hidden, and the Submit button will be grayed out and un-selectable. To prevent this, administrators should use this configuration option in conjunction with the Make Step Optional? Option as shown in the example below.
- Customize the Listing Page: change how the Listing Page looks and configure the number of allowable records a portal user can submit
- Submission Portal Key Concepts - Intermediate: Describes Listing Steps and form relationships at a conceptual level
- Step Page Text: Edit the text that appears at the top of the Step Form page in the submission portal.
- Make a Step View-Only: if a portal user should not be able to add OR edit items/records on a Listing Page
- Preventing Portal Users from Deleting Listing Items: if a portal user should not be able to delete items/records on a Listing Page
- Making a Step Optional in the Submission Portal: if a Listing Step should be optional for a portal user to complete before they are able to Submit a Stage