Variables in hyperlinks

OL Connect provides an easy way to add a hyperlink to your documents. In some scenarios this link requires variable information, for example to navigate the recipient to a personalized landing page based on a unique ID. This can be achieved by adding a so called query parameter to the URL. This article explains how to insert a static hyperlink and shows how to add variable information to it through a simple script.

Static hyperlink

Let’s start by creating a basic static link: a URL that points to a specific web page.

To create a static link:

  1. Select some text in your document
  2. Right click the selection. The contextual menu appears. Choose: Hyperlink > Insert…
  3. Enter the desired URL and click Finish.

In the above example, https://www.example.com/invoices/ is the static link. When a user clicks on the text “View your document online” it triggers the browser to open and visit the specified link.

Underwater the selected text is now surrounded by an <a> element (hyperlink) where the link is stored in the href attribute. This looks like this:

<a href="https://www.example.com/invoices/">View your document online</a>

Adding variable information

Now, let’s move on to adding a dynamic component using a query parameter. Query parameters are added to a URL, usually in the form of key-value pairs. Here are some examples:

  • https://www.example.com/invoices/?document=9ffd7b7d-3cc5-4c89-b34b-89230d9d0764
  • https://olresourcecenter.uplandsoftware.com?salutation=Hello Peter,

In the first example, document is the key and what follows after ‘=’ is the value of the query parameter.

To add a query parameter to the link we need a script.

Preparing the element

Before creating the script:

  1. Place the text cursor inside the text with the link.
  2. In the Attributes panel, enter purl in the ID field. This assigns an ID to the hyperlink which allows a script to identify the element.
  3. Click the label of the ID field to create a new script for this element.

The Edit Script dialog appears. The script’s Selector is set to ‘#purl’.

The script

Now copy-paste our sample script in the Edit Script dialog. It consists of four lines:

  1. The first line retrieves the value of the href attribute of the hyperlink. In our example, this value is https://www.example.com/invoices/.
  2. The next line assigns the value from the documentId data field to a variable, ensuring proper encoding using the JavaScript encodeURIComponent() function.
  3. Next, the URL, parameter, and value are concatenated using the backtick approach (Template literal). The URL and query parameter are separated by a question mark.
  4. The last line updates the href attribute of the link with the new value.
let url = results.attr('href')
let documentId = encodeURIComponent( record.fields.documentId )

let purl = `${url}?document=${documentId}`;

results.attr('href', purl)

Path parameters versus Query parameters

Depending on the receiving backend, you may prefer to use path parameters instead of query parameters. Path parameters typically refer to a particular REST API resource. The path parameter is separated from the URL by a ‘/’. If combined with any query parameter(s), path parameters come before the question mark (?).

This URL with a query parameter targets a specific invoice:

https://www.example.com/invoices/?document=9ffd7b7d-3cc5-4c89-b34b-89230d9d0

The following URL targets the same resource, but now uses a path parameter:

https://www.example.com/invoices/9ffd7b7d-3cc5-4c89-b34b-89230d9d076

The following script shows a way to construct such a dynamic path. To keep it simple, we skipped reading the current href value and wrote the full URL in the code. 

let documentId = encodeURIComponent( record.fields.documentId )
let purl = `https://www.example.com/invoices/${documentId}`;
results.attr('href', purl)