Overview

The Headless Server is able to retrieve links for content objects like pages, articles or pictures, that are generated by a remote system, like a CAE. These links can be used by a client to link to that remote content.

Figure 4.1. Remote Links

A request is executed from the Headless Server to a configured remote handler in a CAE with a list of content IDs together with optional properties (site, context). The handler generates corresponding links and returns them to the Headless Server.

GraphQL Schema

In the GraphQL schema, the remoteLink property is defined on type CollectionItem:

interface CollectionItem {
  remoteLink(siteId:String, context:String): String
}

All types that inherit from CMLinkable or implement CollectionItem can access this field. For example, the following query retrieves a remote link for an article:

{
  content {
    article(id: "7456") {
      remoteLink
    }
  }
}

The query fragment in the GraphQL schema to retrieve a remoteLink contains the contentId implicitly via the RemoteLinkDataFetcher. Additionally, the following parameters can be set:

The following example retrieves an article within a site and a specific context:

{
  content {
    article(id: "7456") {
      remoteLink(siteId:"abffe57734feeee", context: "7950")
    }
  }
}

A typical use case is the retrieval of a page content object:

query getPageById($pageId: String!, $siteId: String) {
  content {
    page(id: $pageId) {
      title
      remoteLink(siteId: $siteId)
      pictures {
        title
        remoteLink(siteId: $siteId)
      }
    }
  }
}

Caution

Please note, that links for commerce objects currently cannot be resolved. For technical reasons it is nonetheless possible to use the remoteLink fragment for commerce object already. A query for remote links for commerce object will always resolve to a null object!

Batch loading mechanism and caching

In order to achieve a reasonable performance when resolving remote links, the Headless Server uses a so called batch loader, which is able to resolve all remote links with only one remote request to the CAE per query level and caches the results (time based eviction).

Configuration

The following configuration options are available, see Section 3.3.4, “Remote Service Adapter Properties” in Deployment Manual for details:

CAE Handler

The CAE UrlHandler handles requests to /internal/service/url and generates links using the CAE link building mechanisms.

As the remote handler for link building is configurable, a custom service can be set up, that handles requests with the given parameters and returns URLs in json format with entities of type UrlServiceResponse.

Deployment

It is assumed that the remote system, that is the CAE, is located in the same trusted network as the Headless Server and so the systems communicate via HTTP. If communication should be established via HTTPS, security configuration needs to be applied to the servers accordingly.

The handler path of the UrlHandler /internal/service/url needs to be configured if required for preview and live environments (for example, traefik, rewrite rules).

Development

For debugging SSL connections, the option caas.remote.httpClientConfig.trustAllSslCertificates can be set to true. This should only be done in a development environment.