Compart Launches DocBridge® Communication Suite
Market launch of the DocBridge® Communication Suite: New standards in flexibility and technology in customer communication management.
MoreURI Mapping – an Often Misunderstood Feature
URI mapping is an essential yet often misunderstood feature of the DocBridge® Communication Suite (DBCS). This guide aims to clarify its purpose, implementation, and the practical benefits it provides, particularly regarding resource portability and security.
When deploying DBCS using a Helm chart for Kubernetes, Docker Compose, or the DBCS installer, the good news is that you can generally rely on the default settings provided in these deployment methods. The installer automatically configures URI mapping, making manual changes typically unnecessary. However, it is still valuable to understand the underlying mechanisms and benefits – hence this guide.
Why URI Mapping?
The primary goal of URI mapping in DBCS is to ensure the portability of templates and resources across different environments – development, testing, and production – without requiring manual modifications. Typically, templates refer to other resources such as images, stylesheets, and fonts through URLs. These references need to be adaptable to various deployment scenarios.
How URI Mapping Works
When designing templates in DBCS, resources dragged into the document generate URLs with special protocols (e.g., resdir://, fonts://). These unusual protocols act as placeholders. At runtime, these placeholders dynamically resolve to actual, environment-specific paths or hostnames, thus maintaining resource portability.
For example, a URL placeholder like:
resdir://resource-directory/staticwould resolve to a full URL based on the specific environment, such as:
http://localhost:8080/resource-directory/staticTwo Core Components of URI Mapping
URI mapping in DBCS has two main components:
1. URI Placeholder Resolution:
Defined in the profile, URI placeholders like resdir:// are mapped to specific valid URLs at runtime. In local environments, manual setup is necessary, whereas Kubernetes deployments utilizing Helm charts automate this process.
2. Header Value Mapping:
This component is crucial for security, ensuring that requests to resources (like those hosted in Resource Director or Repository Manager) are authenticated and authorized. Instead of assigning broad permissions to the DocBridge Gear service, DBCS passes the OAuth token from the original request to subsequent resource requests. This ensures granular access control consistent with your security configurations.
Practical Implementation
The default URI mapping configuration (UriMapping.pro) included in the DBCS Helm chart provides out-of-the-box functionality for typical deployments. It handles both URI placeholder resolution and OAuth token header mapping automatically.
The OAuth token is mapped to the authorization header, ensuring that resources are fetched securely and respecting all configured access controls. Thus, resources such as templates, images, and stylesheets required for production or previews are securely retrieved using the user's credentials initiating the request.
Benefits of URI Mapping:
- Resource Portability: Templates and resources seamlessly transition between environments
- Enhanced Security: OAuth token-based resource fetching aligns with existing access controls
- Reduced Manual Effort: Automated placeholder resolution and secure access minimize manual configuration and maintenance
Recommended Deployment
For best results, utilize Helm charts or the DBCS installer to deploy into Kubernetes environments, leveraging the provided UriMapping.pro profile configuration without modification.
URI mapping, while initially appearing complex, significantly simplifies resource management across multiple deployment environments, ensuring consistency, security, and ease of use in DBCS.
For additional information or customized configurations, please contact the DBCS product support team.
