Under maintenance

Heretto Help

Show Page Sections

Deploy API Filtering and Personalization

Note:

Audience-based filtering applies only to JSON Web Token (JWT) authentication. Simple API Keys cannot be restricted to specific audiences and always have full access to content across all audiences within their configured scope.

Audience-based filtering and personalization let a single sitemap or deployment return different content to different groups of users, so each request receives only the content meant for its audience.

An audience identifies a group of intended recipients for a portion of your content. You associate content with an audience by adding a data element with content-api-audience or content-api-default-audience attribute value to the main portal sitemap, pointing to a DITAVAL, or by defining named audiences for a deployment.

There are two places to define an audience, and they differ in scope:

Audiences defined in a sitemap

Associate a single sitemap with one or more DITAVAL files, each representing a different audience. See Define Audiences in a Sitemap.

Audiences defined in a deployment

Apply across an entire deployment and let you designate one audience as the default for the deployment. See Define Audiences in a Deployment.

Important:

Audiences can be configured in a sitemap, a deployment, or both. When both are configured, deployment audiences override sitemap audiences. Sitemap audiences are only used when no audiences are configured in the deployment.

To retrieve content for a specific audience, add the audience parameter to a request URL, for example, ?audience=private. For details on how to create such a request, see Define Parameters with Tokens. To learn how the requested audience interacts with the audiences claim in a JWT, see Deploy API Authentication.

Define Audiences in a Sitemap

Associate a map with an audience so its content is returned only to JWT-authenticated requests permitted for that audience.

This assigns an audience at the map level. To assign an audience to an entire deployment instead, see Define Audiences in a Deployment. The audience name you assign here is the value you'll reference later when configuring the audiences claim in a JWT (see Deploy API Authentication) or the audience request parameter (see Define Parameters with Tokens).

Every JWT request is matched to an audience. Here is a breakdown of possible scenarios.

  • Audience is mapped to the __default value when:

    • content-api-audience is used in the data element in your main portal sitemap, and no value attribute is specified. Example:

      <data href="../filters/private.ditaval" name="content-api-audience" value=""/>
    • content-api-default-audience is used in the data element in your main portal sitemap, regardless of whether the value attribute is specified. Examples:

      <data href="filter/public_only_filter.ditaval" name="content-api-default-audience" value=""/>
      <data href="filter/public_only_filter.ditaval" name="content-api-default-audience" value="general-audience"/>
    • No audience is specified in your main portal sitemap. In this case, no data element pointing to a DITAVAL is present in the sitemap.

  • A specific audience is used when:

    • content-api-audience is used in the data element in your main portal sitemap, and the value attribute is specified. Example:

      <data href="../filters/private.ditaval" name="content-api-audience" value="private"/>
  1. In Heretto CCMS, ensure that you are working in the master branch and go to your main portal sitemap.
  2. Right-click the main portal sitemap and select Edit Source.
  3. Add a data element inside the sitemeta element and, depending on your audience needs, specify attributes for the data element.

    Follow this structure:

    <data name="content-api-audience" href="ditaval_path" value="audience_name"/>

    Where:

    • ditaval_path is the path to the DITAVAL file in the CCMS. See href="../filters/private.ditaval" in the example below.

    • audience_name is the name you gave this audience. This name is used to configure Heretto Portal single sign-on (SSO) and the JSON Web Token (JWT) authentication for Heretto Deploy API. See value="private" in the example below.

    <data href="../filters/private.ditaval" name="content-api-audience" value="private"/>
  4. Optional: To define multiple audiences, add a data element per audience and define data element attributes as needed.
The map is now associated with the audience you specified, either __default or a named audience. Once this deployment uses JWT authentication, requests permitted for that audience can access the content in this map, subject to the audiences claim in the requesting JWT.
Important:

Audiences can be configured in a sitemap, a deployment, or both. When both are configured, deployment audiences override sitemap audiences. Sitemap audiences are only used when no audiences are configured in the deployment.

To configure Heretto Deploy API authentication with a Simple API Key or JSON Web Token (JWT), see Deploy API Authentication.

Define Audiences in a Deployment

Note:

This procedure explains how to configure a deployment. Configuring audiences in a deployment is a part of this process.

You can define audiences for entire deployments in Heretto CCMS. Deployments connect content in the CCMS with Heretto Portal environments or other delivery endpoints via Heretto Deploy API and enable you to publish content to the associated delivery endpoint. A portion of this configuration must be completed by the Heretto team.

To complete this procedure, you must be assigned the Administrator role in Heretto CCMS.

  1. In the top-left corner, click the Main Menu and go to Deployments.
  2. In the top-right corner of the Deployments interface, click New Deployment.
  3. In the Create Deployment window, provide these details:
    Create Deployment Window
    1. In the Deployment Type section, select deployment type: Manual Deployment or Active Sync Deployment.

      Manual deployment can be configured for any delivery environment: preview, staging, and production. Active sync deployments can be configured only for non-production delivery environment.

    2. In the General Configuration section, provide the name of the deployment.
      Note:

      We recommend including the name of the branch and portal environment or a different delivery endpoint in the deployment name. For example, when your deployment is to publish content from the production branch to the staging portal environment, your deployment name could be Production branch & Staging portal. This ensures that anyone can understand how each deployment is configured.

    3. Add a sitemap by clicking Add file and navigating to the sitemap you want to publish through this deployment.
      Tip:

      To add a sitemap from a specific branch, click Add file and from the branching drop-down in the top-left corner, switch to that branch. Once a sitemap is added to a deployment and changes are saved, it cannot be replaced by a different sitemap. Instead, a new deployment must be configured.

    4. Select which locales (target languages) you want to publish with this deployment.

      The list of locales shows all locales available in the CCMS. If you do not see a locale listed, it likely means that your content hasn't been translated to the language or that the translation hasn't been uploaded to the CCMS.

    5. In the Audiences section, add one or more audiences by clicking Add audiences and navigating to the DITAVAL file you want to use in this deployment. If you want an audience to be the default audience, select the Default check box.
      Important:

      Skip this step if your audiences are configured in the sitemap.

      Audiences can be configured in a sitemap, a deployment, or both. When both are configured, deployment audiences override sitemap audiences. Sitemap audiences are only used when no audiences are configured in the deployment.

      For details on how to configure audiences in a sitemap, see Define Audiences in a Sitemap.

      For details on DITAVAL files, see Conditional Processing Overview and DITAVALs.

    6. In the Metadata Governance section, configure which metadata should be included in this deployment.

      For more information about metadata, see Metadata Governance in Heretto CCMS and Metadata Governance in Heretto Portal.

    7. Optional: Heretto Portal only: In the Portal Content Automatic Redirects section, decide if you want to disable automatic redirects in this deployment.
      Automatic redirects are available only for manual deployments configured to publish to a Heretto Portal environment. By default, automatic redirects are enabled and we recommend keeping them enabled. For more information, see Portal Redirects Overview.
  4. Click Save.
  5. From the Deployments interface, copy the deployment ID generated for your deployment and pass it to your Customer Success Manager, along with these details:
    • Share URL to the sitemap you added to this deployment

    • The name of the branch that contains the sitemap

    • The Heretto Portal environment or third-party delivery endpoint the deployment should be connected to

Once the Heretto team completes the configuration on their side, the configuration of the deployment is complete. Users assigned the Administrator role in the CCMS can modify most aspects of the deployment with the exception of the sitemap it uses. To use a different sitemap in a deployment, a new deployment must be configured.

Define Parameters with Tokens

Add the audience parameter to a Heretto Deploy API request URL to specify which audience the returned content belongs to.

The audience parameter has an effect only on maps whose content has been associated with an audience via a DITAVAL, as described in Define Audiences in a Sitemap and Define Audiences in a Deployment. Add it to the link alongside the token used for authentication. The token parameter supports every Deploy API endpoint. For more information about how the audience parameter interacts with the audiences claim in a JSON Web Token (JWT), see Deploy API Authentication.

This example shows a link to unfiltered content, using the content endpoint. The link does not include the audience parameter.

https://{organizationId}.deploy.heretto.com/v4/deployments/{deploymentIdentifier}/content?for-path={path}&token={JWT}
This example shows a link to filtered content. The link includes the audience parameter. The audience parameter applies only to requests authenticated with a JWT.
https://{organizationId}.deploy.heretto.com/v4/deployments/{deploymentIdentifier}/content?for-path={path}&token={JWT}&audience={audience_name}

Where:

  • {organizationId} is the identifier for your organization. See Obtain Parameter Values for Endpoint URLs.

  • {deploymentIdentifier} is the identifier for the deployment you're calling. See Obtain Parameter Values for Endpoint URLs.

  • {endpoint} is an endpoint of your choice, such as content (shown above) or structure. See Deploy API Endpoint Specification at Heretto Deploy API.

  • {path} is the href value returned by the structure endpoint, for the content you want to retrieve.

  • {JWT} is the signed JSON Web Token (JWT) used to authenticate the request. See Create a JWT.

  • {audience_name} is the audience name set in the value attribute of a content-api-audience data element in the sitemap. See Define Audiences in a Sitemap.