Customer Knowledge Base
Customer Knowledge Base
Breadcrumbs

Custom Header Handling for HCMS and OC Image Service

1. Overview

This Knowledge Base describes how HCMS and OC Image Service handle custom HTTP response headers. It clarifies which headers are provided by default and how they differ across metadata and file‑delivery endpoints.

HCMS guarantees:

  • All entity endpoints include an ETag derived from the asset CCN (including dependent assets).

  • All raw content (file delivery) endpoints include:

    • ETag based on the storage item hash

    • Last-Modified based on the storage item timestamp

Any enhancements beyond this (for example, additional custom headers) require a formal feature request.

2. Symptoms

  • Last‑Modified missing on endpoints that serve metadata rather than file content.

  • Custom feature-based header (for example, Edge‑Cache_Tag) not included in responses.

  • Differences between OC Image Service headers and HCMS headers.

  • ETag present but derived differently than expected.

3. Common Causes

  • Entity endpoints are not expected to return Last‑Modified; by design they only provide ETag from the asset CCN.

  • Raw content endpoints return both ETag and Last‑Modified only when the requested resource is a storage item.

  • The required feature does not exist on the asset.

  • The bundle used does not include additional custom header logic.

  • Expectations mix HCMS behavior with OC Image Service behavior. 

4. Diagnostics

4.1 Customer/Partner

  • Confirm whether the URL refers to:

    • Entity endpoint (returns metadata → ETag only)

    • Raw content endpoint (returns files → ETag + Last‑Modified)

  • Verify that the asset contains the required feature key for custom headers.

  • Ensure the correct bundle build is deployed.

  • Check that intermediate systems (CDN, proxies) do not strip headers

4.2 Infra/DevOps

  • Validate that the updated OC/HCMS bundle is deployed on all nodes.

  • Confirm caching layers preserve upstream headers.

  • Verify request routing reaches the intended service (HCMS vs. OC).

4.3 censhare Support

  • Confirm the endpoint type and expected header behavior.

  • Verify storage item metadata (hash, timestamps).

  • Validate feature structure for any custom header functionality.

5. Mitigation

  • For entity endpoints:
    ETag only is expected; Last‑Modified is not applicable.

  • For raw content endpoints:
    Last‑Modified and ETag must come from the storage item, and issues typically relate to metadata configuration or caching layers.

  • For custom headers:
    Ensure features are present and supported by the bundle in use.

  • For new behavior requests:
    Submit via the feature request channel.

6. Best Practices

  • Use storage items for all file-delivery use cases requiring standard HTTP caching headers.

  • Ensure CDN logic aligns with HCMS’s standard header behavior.

  • Use well-structured asset features for any custom header mappings.

7. When to Contact Support

  • Entity endpoints fail to include an ETag.

  • Raw content endpoints fail to include Last‑Modified or storage-item-based ETag.

  • The custom feature is present but the corresponding header is not returned.

  • A new build or feature extension is required.

8. Information Required

  • Exact endpoint URL and whether it’s entity or raw content.

  • Full raw response headers.

  • Asset ID and feature metadata involved.

  • Bundle version deployed.

  • Expected vs. observed header behavior.