Under maintenance

Heretto Help

Show Page Sections

Deployments

A deployment is a configuration in Heretto CCMS that defines which main sitemap is published to which Heretto Portal environment or other delivery endpoint such as a website, application, device, or machine. Deployments carry information like deployment type, audience, locales (or target languages), or metadata. They enable you to publish content from the CCMS to your delivery endpoints.

There are two types of deployments: active sync and manual.

Active Sync Deployments

A deployment type that automatically publishes content updates to a Heretto Portal environment or other delivery endpoints. With active sync, content updates made in a topic or map are visible in an associated delivery endpoint automatically and instantaneously. This deployment type is particularly useful to preview work-in-progress content in a non-production delivery endpoint. Active sync deployments can be configured only for non-production delivery endpoints.

Manual Deployments

A deployment type that requires publishing to be triggered manually in Heretto CCMS. With manual deploy, content updates made in topics and maps are not visible in an associated Heretto Portal or other delivery endpoints until that deployment is manually published. This deployment type enables you to control when content updates are visible in your delivery endpoint. This deployment type is particularly useful to publish your final content to a production delivery endpoint in a controlled manner. Manual deployments can be configured for any delivery endpoint.

Apart from deployment type, each deployment contains a number of settings including the ones that define which content and in which languages gets published through it, which audiences are included, or which metadata is included.

Deployments Operation and Guidelines

Before you start using deployments, familiarize yourself with important facts and guidelines about working with it.

  • Deployments are used to publish content in Heretto CCMS with Deploy API to an endpoint like Heretto Portal or a third-party endpoint, like a device or machine. A deployment is a configuration in the CCMS that defines which sitemap is published to which endpoint. Deployments carry information like the deployment type, audience(s), locales (target languages), or metadata.

  • Content published through a deployment must be organized into a sitemap, a specialized DITA map that lives in Heretto CCMS. It can contain other sitemaps, maps, bookmaps, topics, and other files. It can also contain elements that enable you to organize and present all components of your content. For example, sitesection, topichead, and topicgroup.

  • When configuring publishing through a deployment, you may want to configure audiences. An audience is any group of viewers that you want to filter content for. Filtering content means that you want to show only some content for one or more audiences, or that you want to ensure that a specific audience cannot see some portion of the content.

  • 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.

  • Each deployment must have a sitemap associated with it. One deployment can use only one sitemap. One sitemap can be used in multiple deployments.

  • 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.

  • Deployments include a metadata governance component that enables you to control which metadata should be delivered with content to a delivery endpoint. For details, see Metadata Governance in Heretto Portal.

  • Deployments is where you can manage Heretto Portal automatic redirects. 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 details, see Portal Redirects Overview.

  • You cannot publish content through a deployment from a release. You can, however, branch a release and publish through a deployment from that branch.

  • Deployments do not warn about validation issues in your content. Use the preflight check or Quality Report to validate your content before publishing it to portal. For details, see Preflight Check or Quality Report.

Configure Audiences in a Sitemap

When configuring publishing through a deployment, you may want to configure audiences. An audience is any group of viewers that you want to filter content for. Filtering content means that you want to show only some content for one or more audiences, or that you want to ensure that a specific audience cannot see some portion of the content.

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.

Depending on how you configure audiences in your main portal sitemap, audiences are mapped to the __default value or specific, named audience(s) when publishing to Heretto Portal or third-party endpoints like machines or devices.

  • 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 one or more audiences, either __default or one or more named audiences.

Configure Deployments

Deployments are configured in Heretto CCMS. They 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 Configure 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.