In some situations it is required, or desirable, to modify the URL for an online resource. The most common situation where this occurs is when an institution offers a "proxy server" (aka "reverse proxies") which is used to proxy requests for e-resources in order that a user can access the e-resource with minimal authentication/authorisation issues (e.g. if the proxy server is granted IP authorisation to the resource, the user can access the resource from any location using the proxy server). For example a resource might have the URL: http://example.org. The proxied link for the same resource could be http://proxy.server.url/?url=http://example.org 

Another common situation where modification to a URL is required, is where the e-resource provider requires an institutional code to be added to a URL before it will respond to any requests to the URL. For example an e-resource might have the URL: http://example.org/?db=1234, but in order to successfully link to the resource using the subscription for a specific institution "ABCD" this URL would need to be modified to be: http://example.org/ABCD/?db=1234. Major database vendors such as EBSCO and Gale support institution specific URLs of this type.

In order to support such modified URLs, the Agreements app offers a system of templating which can be used to both:

• create Proxy server configurations, which modify all URLs across the system and;
• create platform level URL customizations, which modify all the URLs on a specific platform

Proxy server configuration is done via Settings → Local KB Admin → Proxy server settings. Proxy server configurations will apply to all URLs in the internal Knowledgebase by default, but specific platforms can be excluded from the Proxy server configuration, or from the platform record (accessed via the Agreements app). You can create multiple proxy server configurations if there are multiple proxy servers used (e.g. where a separate proxy server is used for resources licensed to Alumni).

Platform level URL customizations can be added to the platform record (accessed via the Agreements app). Each platform can have a single URL customization. 

URL customizations and proxy server configurations generate additional URLs to the URLs already stored in the system for the e-resource. If there are proxy server configurations and platform level URL customizations set, any URLs generated by a platform URL customization will also have the proxy server configuration applied (but not the reverse - the platform URL customization is never applied after the proxy configuration). So for example if a URL such as http://example.org/?db=1234 was modified to http://example.org/ABCD/?db=1234 by a platform URL customization, a proxy server configuration would produce the proxied version of the URL such as http://proxy.server.url/?http://example.org/ABCD/?db=1234. In this case four URLs would be available for the e-resource in total:

Original URL: http://example.org/?db=1234

Original URL proxied: http://proxy.server.url/?http://example.org/?db=1234

Customized URL: http://example.org/ABCD/?db=1234

Customized URL proxied: http://proxy.server.url/?http://example.org/ABCD/?db=1234

If there are multiple proxy server configurations, each additional configuration will result in an additional version of the Original and Customized URL modified for that proxy

Writing proxy server configurations and URL customizers

The templating system for modifying URLs works in the same way for both proxy server configurations and URL customizers. The templates can be used to do one or more of the following as required:

• Add text before the original URL
• Add text after the original URL
• Encode text with URL (aka 'percent') encoding
• Remove any protocol prefix from a URL
• Replace or remove text from the original URL
• Add a "local platform code" to a URL as defined on the platform record

Any text that is to be added around the original URL (such as a proxy server prefix or suffix) can just be typed as plain text, while any variables or helpers (which are functions which can be used for more complex modifications) need to be inside double curly brackets {{ }}. 

The variables supported by the templates currently are `inputURL` and `platformLocalCode`:

• The `inputURL` variable represents the URL to which the modifications specified in the template will apply and would usually appear in all templates
• The `platformLocalCode` variable is the local platform code (if any) for the platform where the resource is accessed. The local platform code is defined on the platform record in the Agreements application and would typically be used to store information such as a database code that needs to be added into a URL

The helpers supported by the templates currently are  `urlEncode`, `insertAfter`, `insertBefore`, `removeProtocol` and `replace` and are explained in detail below.

A simple addition of a prefix for a proxy server would be achieved using the following customization code:

http://url.prefix.com/{{ inputUrl }}

and a suffix addition would be achieved with

{{ inputUrl }}?some-suffix-text

and adding both a prefix and suffix is 

http://url.prefix.com/{{ inputUrl }}?some-suffix-text

Helper functions can be used inside the curly brackets. These work as follows:

urlEncode

{{ urlEncode inputUrl }}

Explanation: This helper encodes a URL (or other string) using percent encoding.

Example

Original URL: http://example.org

Template: http://proxy.url/?url={{ urlEncode inputUrl }}

Modified URL: http://proxy.url/?url=http%3A%2F%2Fexample.org

insertAfter

{{ insertAfter inputUrl "string-to-find" "string-to-insert" }}

Explanation: This helper inserts a string ("string-to-insert") after the first occurrence of a search string ("string-to-find") in the  URL

Example

Original URL: http://example.org

Template: {{ insertAfter inputUrl  "&authentication=ip" }}

Modified URL: http://example.org&authentication=ip

insertBefore

{{ insertBefore inputUrl "string-to-find" "string-to-insert" }}

Explanation: This helper inserts a string ("string-to-insert") before the first occurrence of a search string ("string-to-find") in the  URL

Example

Original URL: http://example.org/index/

Local platform code: ABCD

Template: {{ insertBefore inputUrl "/index" platformLocalCode }}

Modified URL: http://example.org/ABCD/index/

removeProtocol

{{ removeProtocol inputUrl }}

Explanation: This helper removes either "http://" or "https://" from the start of a URL

Example

Original URL: http://example.org

Template: https://proxy.url/?url={{ removeProtocol inputUrl }}

Modified URL: https://proxy.url/?url=example.org

replace

{{ replace inputUrl "string-to-find" "replacement-string" }}

Explanation: This helper replaces each occurrence of a specified string ("string-to-find") in the URL with a replacement string ("replacement-string")

Example

Original URL: http://example.org

Template: {{ replace inputUrl "org" "com" }}

Modified URL: http://example.com

Note that "replace" will replace all occurrences of the "string-to-find" that are found in the URL

Controlling the order in which changes are made

To control the order in which changes are made, parentheses can be used inside the curly brackets:

Example

Original URL: http://example.org/ebook/

Template: https://proxy.url/?url={{ ( replace ( removeProtocol inputUrl ) "/ebook/" "" ) }}

Modified URL: https://proxy.url/?url=example.org

In this example the "removeProtocol" happens before the "replace"

Example proxy server configuration templates

These examples are provided for guidance only.

EZProxy

Web page: https://help.oclc.org/Library_Management/EZproxy

Example template:

http://ezproxy.abclib.org:2048/login?url={{ inputUrl }}

WAM

Web page: https://csdirect.iii.com/tutorials/wam/index.html

Example template:

http://{{ insertBefore ( removeProtocol inputUrl ) "/" ".web.library.edu" }}

OpenAthens Redirector URLs

Web page: https://docs.openathens.net/display/public/MD/Redirector+link+generator

Example template:

https://go.openathens.net/redirector/athensdemo.net?url={{ encodeUrl inputUrl }}