How Content is Passed to Deploy API

Once content is finalized in Heretto CCMS, it moves to the Deploy API through deployments.

Deployments are essential configuration elements that determine which content is published, where it's published, and under what conditions. Deployments connect specific content in the CCMS with appropriate delivery endpoints such as Heretto Portal or other delivery endpoints.

Deploy API supports two deployment types:

Active Sync

Automatically and continually publishes content updates from the CCMS to delivery endpoints. As content creators make changes in the CCMS, their updates are rapidly integrated into the associated deployment and published to a delivery endpoint.

Active sync is valuable for preview environments where teams need to see work-in-progress content. Due to its immediate nature and the risk of publishing work-in-progress content, active sync is not available for production portal environments.

Manual Deploy

Requires deliberate user action to initiate the publishing process. Content updates remain in the CCMS until a user manually publishes a deployment. This deployment type gives teams control over when updates are released, enabling them to work on substantial content updates.

Manual deploy is available for all portal environments. It is the standard configuration for publishing official content versions.

How Content Becomes a Deployment

Once content is passed from Heretto CCMS through a deployment to Deploy API, it is processed into a final output and served to the Heretto Portal or other delivery endpoints.

Processing a deployment involves evaluating raw DITA content and associated assets and converting them into a final output used to serve the content to its final delivery endpoint for end-user consumption. All deployment processing starts in Heretto CCMS with the deployment configuration and a DITA map (sitemap). At a high level, the following happens during a deployment processing:

• Deployment instructions indicate the audiences and the locales (target languages) that are included.

• The map defines the scope of the deployment.

• All content files for a tenant are located and made available.

• All source content is processed into a normalized structure with all necessary information for output.

  This process involves steps such as: evaluating document metadata, including or excluding review markup, processing conditional sets, processing keyrefs and xrefs, link correction, and processing tables and figures.

At this point, there is an ephemeral in-memory representation of the full set of content in an intermediate state that is nearly final. The content is ready to be rapidly transformed into a final output format, like HTML. This process of building a content set in its nearly final state is used by both active sync and manual deploy deployments. How the two deployment types use this process varies, as described below.

Active Sync Processing

With an active sync deployment, the process is always on, hosting the content in its nearly final state. The content in this case is hosted within Deploy API.

There are two reasons it works this way. The content can be quickly returned in the final format to serve content requests. Additionally, the intermediate in-memory state is ideal for quickly integrating content changes from the CCMS.

The primary benefit of this structure is the rapid integration of new content. That benefit comes with some expense:

• The representation is ephemeral and must be reprocessed at restart

• All content must fit in memory

• An error in content can impact the APIs ability to respond to content requests

• Auto scaling the API is slow because of the initial processing duration

Manual Deploy Processing

With a manual deployment, the process of building the set of content in its nearly final state happens outside of Deploy API. When deployment publishing is triggered, a publishing job is initiated that performs the processing. At the end of processing the content, a snapshot is generated. The snapshot includes: all the files used for processing, an immutable database with all content in its final form, and search indexes. Upon completion of processing and storage, the Deploy API switches to serving content from the new immutable database.

There are multiple benefits to this mode of operation:

• All content processing happens outside of the production API, reducing the risk that a content error makes the API unavailable

• Rapid auto scaling because all content is pre-processed

• The code base for serving content is 90% smaller, leaving less surface area for issues

• Highly efficient memory and content serving for a great experience

• Content no longer needs to fit directly into memory, greatly increasing safety

The main tradeoff of manual deployments is that content updates take longer to become available, as the processing job must finish before new content is deployed.