External Form

The External Form functionality allows you to create a secure, public-facing form that non PPO users can use to submit records directly into your PPO instance.

This article covers:

• Use Cases 
• How to access the External Form Configuration page
• How to configure the External Form
• Important Considerations
• OTP Process
• Session Timeout & Re-Authentication
• Frequently Asked Questions

Use Cases

The External Form is designed to provide a secure and controlled method for capturing records by non PPO users.

Common use cases include allowing non PPO users to:

• Add Demand items
• Add Projects
• Add any project related entity records (i.e. Risks, Issues, Decisions etc)

How to Access the External Form Configuration page

To access the configuration page, hover over the Administration menu and select External Form Configuration. By default only the PPO Administrator user group will have access to configure the form.

How to configure the External Form

The External From Configuration page shows the following:

• Service Information: Contains a short description and the link to the External Form. This is an example of the link to the form: https://forms.ppolive.com/{instance} .  "{instance}" will be replaced with your PPO instance name.

• Enabled:  When this checkbox is checked (and the Entity has been selected), the External Form will be active and publicly visible using the URL mentioned above.
• Form Name:  Displayed at the top-left of the External Form page. For example "Demand Form"

• Include Header Image:  Enables uploading a header image. This is could be used to show a lifecycle, process image or any image relevant to the form being added.
• Header Image:  Upload the image that will appear below the Form Name.

• Entity:  Select the entity that the External Form will create records against.
• Categories to Exclude:  Once an entity is selected, its categories become available for exclusion. Excluded categories will not be displayed on the External Form. For example you can exclude all fields within the Management category.

• Fields to Exclude:  Allows you to hide specific fields from the External Form. Example is excluding Required End Date & Duration Estimate.

Customise External Field Captions:  Allows you to rename specific fields that will be visible on the External Form. This doesn't have an impact on the field name on PPO.

• Security:  OTP verification and optional IP/Domain whitelisting is available to ensure secure access to publicly exposed forms.

• Authentication Scheme:  OTP (One-Time Pin) authentication is supported. 
• Email Domain Whitelist:  Enter one domain per line. If populated, only non PPO users with email addresses from these domains will be able to receive an OTP. If left blank, any email address may be used. 
• IP Address Whitelist:  Enter one IP address or IP range per line. Only non PPO users connecting from these IP addresses will be able to access the External Form.

Important Considerations

• Only one entity can be linked to the External Form at a time.

• Updating the entity will immediately change the form visible to others.

• The URL remains the same even if the linked entity changes.

• If a field is removed from use, it will no longer appear on the External Form.

• For Data Field usage functionality, Fields that are used on the External Form doesn't show when using the Field Usage functionality.

• All active business rules apply to both the entity and the form.

OTP Process

The External Form uses OTP verification and optional IP/Domain whitelisting to ensure secure access to publicly exposed forms.  When you click on the link to access the form, the below is the process to authenticate:

(1) When you access the URL, you are prompted to capture your Email Address and to complete the Cloudflare Turnstile verification.  Once a valid email is entered, the Send OTP button becomes active. 

(2) You will receive an email from noreply@ppolive.com containing a One-Time Pin.

(3) Then enter the OTP to proceed.

(4) If the OTP expires, you will be prompted to request a new OTP.  The OTP is valid for 60 minutes.

(5) After successful verification, you will be redirected to the configured External Form and can capture the relevant information & Submit.

(6) Once the form is Submitted, the record is created in PPO:

Session Timeout & Re-Authentication

After successful OTP verification, you gain access to the External Form for the duration of their active browser session.

The following scenarios apply:

• If the browser tab is closed, the session ends.

• If the browser is refreshed after a prolonged period (more than 60 minutes) of inactivity, the session will expire.

• If the session times out due to inactivity, you will be redirected to the initial email capture screen.

• A new OTP will be required to regain access.

This ensures that access to the External Form remains secure and temporary.

Frequently Asked Questions

What happens if the OTP expires?

The OTP is valid for 60 minutes from the time it is issued.  If the OTP is not used within that period:

• The non PPO user will be prompted to request a new OTP.

• A new One-Time Pin will be sent to the same email address.

• The previous OTP becomes invalid.

What happens if the non PPO user enters the wrong OTP?

If an incorrect OTP is entered:

• They will be prompted to try again.

What happens if the non PPO user closes the browser after verification?

If the browser window or tab is closed:

• The authenticated session ends.

• They must repeat the OTP authentication process to access the form again.

What happens if the non PPO user refreshes the page?

If the page is refreshed during an active session:

• The session will remain active (provided it has not timed out).

• If the session has expired, you will be redirected to the OTP screen.

• If the session has not yet expired the session timeout is reset to 60 minutes.

Does submitting the form keep the session active?

Once the form is submitted and the record is created in PPO:

• The submission is complete.

• The page is refreshed which extends the session for another 60 minutes and you remain authenticated for a future submission.

• If they revisit the link later, they will need to request a new OTP.

What happens if the email domain is not whitelisted?

If an Email Domain Whitelist is configured and the non PPO user enters an email address that does not match an allowed domain:

• The application will indicate that the email address is not authorised to access the form.

• You will not be able to proceed.

What happens if the IP address is not whitelisted?

If an IP Address Whitelist is configured and the non PPO user attempts to access the form from a non-approved IP address:

• Access to the External Form URL will be blocked.

• The browser serves it's own internal HTTP Error 403 page.