Basic concepts

This page explains some of the basic concepts that pertain to the usage of the Xillio Link Redirector.

We assume some general knowledge on basic networking concepts, like Domain names, IP-addresses, and HTTP Requests.

Documents

Throughout this documentation the word 'document' is being used. This refers to more than just images, excel-sheets, and PDF's. It can also a mean page of a website, a video, or a response from an API. Think of a document as anything that is being referenced to by a URL (Uniform Resource Locator).

Source & Target Systems

Within the context of migrations, the terms source- and target-system are used to refer to the system that is currently being used and the system that will be migrated towards. Usually there is a one-to-one relation between source- and target system, but in more complex migrations there might be multiple sources or targets.

Migrations

When the Professional Services team of Xillio is migrating documents, they will keep a list of all the migrated documents. This list will include IDs of the documents in the source-system and the new IDs it gained in the target-system.

This combination of source ID and target ID is what makes up a 'migration' for the Xillio Link Redirector. Based on these migrations the Xillio Link Redirector can map documents between the two systems.

Redirect

When we are talking about a redirect for the Xillio Link Redirector, we mean that a user makes a request to the Xillio Link Redirector and we reply with the actual location of the document. With this location, the browser (or other software) usually automatically performs this request and fetches the document at that specific location. This new request originates from the users machine, so the Xillio Link Redirector never performs this request itself.

sequenceDiagram
    User->>+XLR: http-get: docs.network.com/document/:docId
    XLR-->>-User: redirect: new.network.com/:docId
    User-->>+Server: http-get: new.network.com/:docId
    Server->>-User: Response

Proxy

Next to redirecting, we also allow for proxying requests. The Xillio Link Redirector still takes the incoming user request and will look for the location the request should be going. But instead of replying with a redirect, the Xillio Link Redirector itself will perform the request and reply to the user with the response. Therefore, this new request originates from the machine on which the Xillio Link Redirector is running.

sequenceDiagram
    User->>+XLR: http-get: docs.network.com/document/:docId
    XLR-->>+Server: http-get: new.network.com/:docId
    Server-->>XLR: Proxied response
    XLR->>-User: Response

Rules

The Xillio Link Redirector can be configured by defining rules. There are two types of rules; a Rewrite and Lookup rule. They describe the behavior of incoming requests and will modify the request accordingly. Each rule has the option to be configured as either a Redirect or a Proxy request.

Rewrite rule

A rewrite rule is the simplest of the rules and only changes the incoming URL to a new location. There is no additional logic except for the rebuilding of the URL.

An example of a simple rewrite rule is:

{
    "type": "rewrite",
    "pattern": "/document/:folder/:docId",
    "destination": "https://example.com/:folder/:docId",
    "redirect": true
}

In this example you can see that it is possible to filter some URLs (only those starting with /document) and rebuilding the destination URL with parts of the original URL.

For example the URL http://docs.network.com/document/photos/123 will be rewritten to https://example.com/photos/123.

graph TD
    A[Request] -->|GET: docs.network.com/document/photos/123| B(Rewrite)
    B --> C[https://example.com/photos/123]

By specifying parameters using the :-character, we can reuse these parts of the URL.

Lookup rule

The Lookup rule allows the usage of the Migrations and will look for the :id parameter in the url-pattern. This ID will be used to do a lookup in a database (managed by our migration-endpoints). When the ID gives a match, the destination-field will be build, with :id now being the mapped ID of our document (Migration.migratedId).

If no migration was found the fallback-field will be used, if present. This fallback is optional and if it was not set the Xillio Link Redirector will return with an error object.

{
    "type": "lookup",
    "pattern": "/document/:folder/:docId",
    "connector": "filenet",
    "destination": "https://new.filenet.com/:folder/:docId",
    "fallback": "https://old.filenet.com/documents/:docId",
    "redirect": true
}

To illustrate this behavior we have to following schematic:

graph TD
    A[Request] -->|GET: docs.network.com/document/photos/123| B(Lookup)
    B --> C{Is Migrated?}
    C -->|Yes| D[https://new.filenet.com/photos/456]
    C -->|No| E[https://old.filenet.com/documents/123]

This assumes that we would have a migration that maps ID 123 to 456.

Path Patterns

Live Pattern Tester

Use this tester to try URL's against a pattern.

PathPatternDestination

Matches:No

Destination:

Pathname matching

Static paths

Patterns can contain static segments of a path. Static segments are matched exactly against the pathname.

For example: /photos, and /photos/cats/cute-cat.png

Unnamed parameters

It is possible to use Regular Expressions to match parts of the path.

For example:

• /(.*), matches everything after the first slash.
• /(\d+), matches only digits.
• /(\d+)-(\d+), matches two digits separated by a hyphen.
• /photos/(cats|dogs)/(.*), matches all paths that start with /photos and have a subpath that starts with cats or dogs.
• /photos/(.*).png, matches all paths that start with /photos and end with .png.

Named parameters

In order to create the destination URL, named parameters were introduced. These parameters are specified in the pattern with a colon (:) and function as variables.

These parameters can be used to assemble the destination URL, reusing parts of the original URL. It is possible to combine the regular expression syntax with the named parameters to get even more control over the URL.

For example:

• /photos/:animal/:file matches /photos/cats/cute-cat.png and will store cats and cute-cat.png in the parameters.
• /photos/:animal(cats|dogs)/:file matches /photos/cats/cute-cat.png, but not /photos/koala/cute-koala.png.

Additional examples

URL / Pattern	/blog	/blog/1	/blog/:id	/blog/:id(\\d+)	/blog/(.*)
/blog	Yes	No	No	No	Yes
/blog/1	No	Yes	Yes	Yes	Yes
/blog/1234	No	No	Yes	Yes	Yes
/blog/a	No	No	Yes	No	Yes
/blog/abcd	No	No	Yes	No	Yes

Query matching

Sometimes the information that should be matched or gathered is in the query string of the URL. This is the part in the URL after the question mark (?). For example, in the path /photos/cats/cute-cat.png?version=1.2 the query string is version=1.2.

It is possible to match parts of the query string (unordered) by extending the pattern. To check if the version of the image is equal to 1.2, the pattern /(.*) ??version=1.2 can be used.

Additionally, it is possible to use named parameters to match parts of the query string, like ??version=:version.