This chapter is to aid you in configuring a shared form URL for an integration. This assumes you have the technical expertise necessary to create a shared form URL integration. There are several programming and security concepts that must be understood to properly utilize integrations, including URL parameterization, URL encoding, and cryptographic hashing.
To create a shared form URL for an integration, follow these steps:
- Configure an integration for the form that has a token available. See Configuring Unity Form Integrations for more information.
-
Generate a shared form URL for a form using the Forms Designer. Be sure to select Use Integration and select the correct integration that is configured. See Sharing Forms for more information.
Note:
It is recommended to use an encrypted connection when configuring a shared form URL with an integration.
-
Create a parameter string for fields to be pre-populated in the format:
&ufprefieldid1=value&ufprefieldid2=value&ufprefieldid3=value
The URL string should contain the ‘&' in the beginning, as the server expects that format when it reconstructs the string.
When creating the URL to calculate the hash, the constant ufpre should be attached to the beginning of every field ID. This is so that it will be easy to identify the fields that will be pre-populated from the URL string. The field IDs on the form do not need to be changed.
Escape only the ID and value portion of the URL. Do not escape the entire string at once, but just the individual parameters one by one. Escaping the entire URL string would also escape the ‘&' and '=' characters used to append the field ID and value pairs on to the URL. Do not escape the '&' and '=' characters.
- Parse the URL escaped parameter string into UTF-8 format.
-
Ensure the token is a base64 string. The token should already be a base64 string by default.
Note:
Do not share the token with anyone. The hashing will be secure only as long as the token is kept as secure as possible.
-
Calculate the hash of the URL string, which was parsed into UTF-8 format, using the HMAC method and SHA256 algorithm with the token as the secret.
Note:
Using C# to generate the hash is more secure when compared to JavaScript.
Note:Hash values are case sensitive and should match the case of keyword values associated with the form.
- Convert the calculated hash into base64 string and append it to the URL, escaping the base64 string.
-
Paste the URL Encoded String value into the shared form URL and add the generated hash so that the shared form URL looks similar to the following:
http://<localhost>/<webserver>/Unityform.aspx?d1=<encrypted configurationparameters>&ufprefieldid1=value&ufprefieldid2=value&ufprefieldid3=value&ufprehash=<generatedHash>
- When you click on the generated link, the form should open with the values for the given fields populated.