Novulo URL extensions plugin

Wiki
1

Generating Application URLs in Novulo

In the Novulo application, there are scenarios where generating an application URL (Host + FullPath) is necessary to construct links that point to specific records or pages within the system. For example:

  • Self-password reset service links
  • Emails containing links to service requests (e.g., novulo.com/admin.aspx?service={id})

Many times, these URLs are hardcoded into activity templates, content blocks, export definitions, or setting records. However, this method can be overcomplicated and inefficient for generating simple URLs. Having a dedicated function that dynamically returns the correct application URL simplifies the process by:

  • Avoiding dependencies on configurations that may not frequently change
  • Reducing complexity
  • Increasing maintainability

Additionally, the plugin provides Actions that can help with building URLs, which also include Query parameters and URL encodes these parameters (if necessary).

Plugin Configuration Requirements

Web.config Key

A key named NovuloUrlExtensions.BaseApplicationUrl should be added to the web.config file. This key will store the base application URL (e.g., https://www.novulo.com) for easy access by the function. The function will first try to retrieve the base URL from this configuration key.

SSO Configuration Check

A key named sso.overrideissuer can be used as a fallback if the web.config key is not present and the SSO (Single Sign-On) plugin is configured. If SSO is enabled, the URL configuration from SSO can be used.

Manual Reconstruction

If neither the web.config key nor the SSO configuration is available, the function will attempt to manually reconstruct the application URL from the current HTTP request using HttpUtils or similar utilities.

Summary of Configuration
  • Add the NovuloUrlExtensions.BaseApplicationUrl key to the web.config.
  • Add the sso.overrideissuer key to configure SSO as a fallback.
  • The two functions (getApplicationUrl and getApplicationUrlWithPath) will be part of a URL handler that ensures URLs are dynamically generated based on the configuration or reconstructed manually.

This approach improves flexibility, maintains consistency across different environments, and avoids over-reliance on static configurations that may become outdated or complex.

Available Functions

getApplicationUrl

This function returns only the base URL (e.g., https://www.novulo.com). It is useful when only the domain is needed. The function is of the TypeHandler type and returns a URL object.

getApplicationUrlWithPath

This function returns the full URL, including the application path (e.g., https://www.novulo.com/default.aspx). It is useful for generating direct links to specific pages or services. The function is of the TypeHandler type and returns a URL object.

Novulo Actions
BuildQueryStringAction

This action helps construct the query part of a URL, with the option to URL encode the query string or not.

Parameters

Name Data Type Usage
params List<Tuple<String,Mixed>> The key-value pairs to include in the query string.
url_encode_parameters boolean Optional: Indicates if the query part should be URL encoded (default: false).
url_encoding_to_use string Optional: Specifies encoding to use (default: UTF-8 when url_encode_parameters is true).
use_percent_encoding boolean Optional: Default is false. If true, spaces will be encoded as %20 instead of +.

Return Values

Name Data Type Usage
success boolean Indicates whether the action was successful.
error Message Describes the error, if success is false.
query string The generated URL query string based on the provided parameters.
BuildUrlAction

This action builds a complete URL (base URL + query string). It optionally URL encodes the query string and allows for easy management of query parameters.

Parameters

Name Data Type Usage
base_url string The base URL to which the query string will be appended. Can already contain query parameters.
params List<Tuple<String,Mixed>> Key-value pairs to be added to the query string.
overwrite_existing_query boolean Optional: If true, duplicate query parameters from params will overwrite existing parameters in base_url.
url_encode_parameters boolean Optional: Indicates if the query string should be URL encoded (default: false).
url_encoding_to_use string Optional: Specifies encoding to use (default: UTF-8 when url_encode_parameters is true).
use_percent_encoding boolean Optional: Default is false. If true, spaces will be encoded as %20 instead of +.

Return Values

Name Data Type Usage
success boolean Indicates whether the action was successful.
error Message Describes the error, if success is false.
url URL The complete URL with the query string appended (optionally URL encoded).
UrlEncode

This action URL encodes the provided value. It ensures that special characters in the string are encoded as per URL encoding rules.

Parameters

Name Data Type Usage
to_encode string The value to encode. Special characters like spaces, &, =, etc., will be encoded.
url_encoding_to_use string Optional: Specifies the encoding to use (default: UTF-8 when url_encode_parameters is true).
use_percent_encoding boolean Optional: Default is false. If true, spaces will be encoded as %20 instead of +.

Return Values

Name Data Type Usage
success boolean Indicates whether the action was successful.
error Message Describes the error, if success is false.
encoded string The URL-encoded value based on the input provided.
UrlDecode

This action decodes a previously URL-encoded value. It reverses the encoding process, returning the original input string.

Parameters

Name Data Type Usage
to_decode string The URL-encoded value to decode. This will return the original string.
url_encoding_to_use string Optional: Specifies the encoding to use (default: UTF-8).
use_percent_encoding boolean Optional: Default is false. If true, spaces encoded as %20 will be decoded correctly.

Return Values

Name Data Type Usage
success boolean Indicates whether the action was successful.
error Message Describes the error, if success is false.
decoded string The decoded value, which is the original string before encoding.
Explanation of `use_percent_encoding`

Encoding of Specific Characters:

When the use_percent_encoding is set to:
false → the used C# method is HttpUtility.UrlEncode
true → the used C# method is Uri.EscapeDataString

The way Uri.EscapeDataString and HttpUtility.UrlEncode encode certain characters differs, particularly when handling spaces and special characters.

Character Uri.EscapeDataString HttpUtility.UrlEncode
Space (" ") %20 +
Plus ("+") %2B %2B
Ampersand ("&") & %26
Equals ("=") = %3D
Hash ("#") %23 %23
Question mark ("?") ? %3F
Slash ("/") / %2F

Use Cases:

  • Uri.EscapeDataString:

    • Best used for encoding URL path segments or individual components where reserved characters (e.g., :, /, ?) must be preserved in their literal form.

  • HttpUtility.UrlEncode:

    • Commonly used for web form submissions or query strings where spaces are encoded as + and other characters are percent-encoded, making it more compatible with HTML forms and query parameters.

Examples of Encoding Differences:

Here are examples illustrating the differences between the two methods:

  • For a space (" "):

    • Uri.EscapeDataString("a b") → a%20b
    • HttpUtility.UrlEncode("a b") → a+b

  • For a plus sign ("+"):

    • Uri.EscapeDataString("a+b") → a%2Bb
    • HttpUtility.UrlEncode("a+b") → a%2Bb (same result here)