Deep-linking into portal forms

Deep-linking into portal forms allows you to directly navigate a user to a specific form in a Power Apps Portal or Power Pages via a URL, with specific parameters pre-filled based on the link. This is useful for scenarios where users are provided with a personalized link to a form, allowing them to quickly access and interact with the data without having to go through multiple navigation steps.

Steps to Implement Deep-Linking into Portal Forms

Here’s how you can implement deep-linking into portal forms in Power Pages (formerly Power Apps Portals), step by step.

Step 1: Understand the URL Structure of Portal Forms

When you create a form in Power Pages, it is typically linked to an entity in the Dataverse. The URL to access the form is typically structured as follows:

php-templateCopyEdithttps://<your-portal-name>.powerappsportals.com/<form-name>/

To enable deep-linking, you will extend this URL to include query parameters or path parameters that can pre-fill specific values in the form or pass context to the form.

For example:

https://yourportal.powerappsportals.com/contact-us/?first-name=John&last-name=Doe&email=john.doe@example.com

In the above example, the form at /contact-us/ is being deep-linked with pre-filled values for first-name, last-name, and email.

Step 2: Create a Form in Power Pages

You first need to ensure that you have created a form for the entity in Power Pages. Here’s a basic outline of the steps to create a form:

Create an Entity in Dataverse: Your form should correspond to an entity in Dataverse, such as Contact, Lead, Account, etc.
Create a Form for the Entity:
- Navigate to Power Pages or Power Apps Portals.
- Under Site Pages, create a new page or edit an existing page.
- Add a Form component.
- Link this form to an existing Dataverse Entity.
- Define which fields should be available and ensure that the form is published.

Step 3: Configure Query Parameters for Deep-Linking

When constructing the deep-link URL, you will use query parameters or custom route parameters to pass values into the form. These parameters are part of the URL and can be accessed on the page.

Query Parameters: These are standard URL parameters that are passed after the ? symbol in the URL. For example:
https://yourportal.powerappsportals.com/contact-us/?first-name=John&last-name=Doe&email=john.doe@example.com In this example, the query parameters first-name, last-name, and email are being passed.
Form Field Mapping: In the Power Pages form, ensure that the field names on the form match the query parameters in the URL. You can use JavaScript or Liquid templating to dynamically map these values to form fields when the page is loaded.

Step 4: Use JavaScript or Liquid to Pre-fill Form Fields

To pre-fill form fields with the values passed through the URL, you can use JavaScript or Liquid templating. These values can be extracted from the query string or URL path and used to populate form fields.

Using JavaScript to Pre-fill Form Fields

Here’s an example of how to use JavaScript to populate form fields based on URL parameters:

Access URL Parameters Using JavaScript:
window.addEventListener('DOMContentLoaded', function() { var urlParams = new URLSearchParams(window.location.search); var firstName = urlParams.get('first-name'); var lastName = urlParams.get('last-name'); var email = urlParams.get('email'); // Pre-fill form fields if parameters exist if (firstName) { document.getElementById('first-name-field').value = firstName; } if (lastName) { document.getElementById('last-name-field').value = lastName; } if (email) { document.getElementById('email-field').value = email; } }); In the example above:
- The script accesses the query parameters using the URLSearchParams API.
- It checks for parameters like first-name, last-name, and email, and pre-fills the corresponding form fields (first-name-field, last-name-field, and email-field).
Ensure the form field IDs are correct: In this JavaScript snippet, first-name-field, last-name-field, and email-field correspond to the IDs of the HTML elements where these values should be inserted. Ensure the form fields in Power Pages are assigned corresponding IDs for the script to work.

Using Liquid to Pre-fill Form Fields

Alternatively, you can use Liquid templating to inject the values into the form. Here’s an example using Liquid:

{% assign first_name = request.query['first-name'] %}
{% assign last_name = request.query['last-name'] %}
{% assign email = request.query['email'] %}

<form method="post" action="/submit-form">
  <label for="first-name">First Name</label>
  <input type="text" id="first-name" name="first-name" value="{{ first_name }}">

  <label for="last-name">Last Name</label>
  <input type="text" id="last-name" name="last-name" value="{{ last_name }}">

  <label for="email">Email</label>
  <input type="email" id="email" name="email" value="{{ email }}">

  <input type="submit" value="Submit">
</form>

In this case, Liquid pulls values from the query string and injects them into the form fields.

Step 5: Handle Form Submission

Once the form is pre-filled, the user can submit it. If you are using JavaScript to populate the fields, the form will submit as usual, just with the fields populated by the deep-link parameters.

If you’re using Liquid to populate the fields, you can ensure the form will properly handle the data when submitted, just as with any standard form.

Step 6: Test Deep-Linking

After implementing deep-linking, test the functionality thoroughly:

Test the URL format: Make sure the deep-link URL contains all the necessary query parameters.
Test form pre-population: Ensure that the correct data is pre-filled in the form when accessing the link.
Test form submission: After filling the form, make sure the submission works as expected, and the data is correctly stored in Dataverse.

Step 7: Security Considerations

While deep-linking into portal forms is useful, consider the following security measures:

Validate input: Always validate the data received via URL parameters to avoid injection attacks.
Limit query parameters: Only allow query parameters that are necessary for the form. Avoid including sensitive information in the URL.
Access control: Ensure that users can only access forms they are authorized to view, especially if you are deep-linking into a sensitive form.