Viewpoint service
Target audience:
This document is primarily intended for developers and architects seeking a comprehensive understanding of Viewpoint as a service. Coupled with a Postman collection and a Viewpoint environment, it serves as a complete resource to efficiently comprehend the functionality of the service.
Overview
What is Viewpoint?
Viewpoint is an enterprise-grade archiving solution, built on top of robust Azure services. Its secure and efficient architecture ensures scalability, catering to both small and large organizations.
Web GUI
In addition to the core Viewpoint REST API, an administrative web interface is available via Centerpoint. This GUI facilitates document search and viewing. However, for a streamlined experience, especially in CRM integrations, we recommend using the API instead of the GUI.
Architecture
Viewpoint leverages several Azure Platform as a Service (PaaS) components to deliver a scalable and secure solution. Please see the official Microsoft documentation for these services.
Azure PaaS services
- CosmosDB - Document database
- Storage - Contains services for storage of blobs/files, a basic queueing service and table service
- Key Vault - Secrets storage
- App Insights - Log and metrics storage
- App Service - Runtime for applications
Frontend - REST api
The above image shows the Viewpoint Cores services on a high level.
Backend - System & Maintenance services
The above image shows the Viewpoint System and Maintenance services on a high level.
Scalability and Elasticity
Viewpoint’s design is inherently scalable and elastic, drawing from the capabilities of its underlying Azure services. CosmosDB and App Service scale horizontally based on demand. Azure Storage also offers vast capacity, accommodating a wide range of scenarios. One of the key advantages is the ability to start small and scale progressively as your needs evolve.
Availability
Viewpoint is backed by enterprise-grade Azure PaaS services, with a standard Service Level Agreement (SLA) ensuring a high level of availability:
The availability of a Viewpoint service is the product of:
- CosmosDB - 99,99%
- Storage - 99,99%
- App Service - 99,95%
Viewpoint guarantees a service availability of 99.93% as part of its standard SLA. In addition to the robust foundation provided by Azure services, Viewpoint benefits from automated deployments, high test coverage, and continuous maintenance.
Disaster/recovery and backups
As the system is built on top of PaaS services like CosmosDB and Storage, it is covered by the disaster/recovery of these services. This does not however cover data loss due to some reason. In order to protect from data loss, the CosmosDB is backed up continously. Backup files are stored for 7 days and the retention period can be extended to 30 days. A CosmosDB database can be restored in hours, depending on the size of the backup.
Security
All data within Viewpoint is encrypted using industry-leading standards. Each document is encrypted with a unique key, which in turn is encrypted as a further protection. Additionally, the underlying database and storage account are encrypted natively by the Azure PaaS services.
Integration
Integrating with Viewpoint is straightforward, thanks to its easy-to-use REST API. The API supports all standard CRUD operations. Beyond the basic operations — upload, search, download, patch, and delete — the service offers enhanced functionality through “composed operations” that allow for seamless integration with external systems.
Authentication follows the OAuth protocol, utilizing Client ID and Client Secret for secure access. Clients are authorized with read/write capabilities, depending on their configuration.
API documentation
For detailed API information, visit the Swagger documentation:
Postman Collection
Postman is a powerful tool for exploring and understanding the APIs. The following Postman actions gives you a workflow overview.
Sensitive information have been abstracted to Variables and Params in the Postman collection below (for example {{ClientId}}, {{ClientSecret}}, {{baseUrl}}, :schema and more).
1. Authentication
2. Get Schemas
3. Upload
4. Search
5. Download
6. Delete
NuGet Package for Easier Integration
For .NET environments, Viewpoint provides a NuGet package that simplifies integration by handling authentication, error management, retry policies, and data modeling.
Find the NuGet package here:
Core Services
Access to Viewpoint’s core services is managed through its REST API, beginning with the “/auth/token” endpoint to retrieve an access token. This token must be included as a Bearer token in the Authorization header for all subsequent requests.
CRUD operations
Discover Schemas
/v1/document/schemasUpload Document
/v1/document/{schema}/{userid}/uploadSearch Documents
/v1/document/{schema}/{userid}/searchDownload Document
/v1/document/{schema}/{userid}/download/{documentId}Patch Document Metadata
/v1/document/{schema}/{userid}/{partitionKey}/{documentId}Delete document
/v1/document/{schema}/{userid}/{partitionKey}/{documentId}Composed operations
Viewpoint also supports combined operations for enhanced efficiency:
Search and Download
/v1/document/{schema}/{userid}/searchanddownload/{column}/{value}Search and Patch
/v1/document/{schema}/{userid}/searchandpatchSearch and Delete
/v1/document/{schema}/{userid}/searchanddelete/{column}/{value}These operations allow for quicker execution of multiple tasks in a single request, provided the search returns exactly one result.
Advanced Features
Appendices
Viewpoint allows multiple document blobs to be associated with a single database row. This is particularly useful in scenarios such as document signing processes where additional blobs (e.g., signed data) may be associated with a primary document.
Array Data
Viewpoint supports the storage of array data in database rows, which can be useful when searching for complex document content, such as lists or reports within a document.
Document blobs, document types
Viewpoint supports the storage of any document type. Simply specify the correct ContentType when uploading the document blob.
Additional Capabilities
Besides the regular features described above there are some extra services available at your convenience:
Metadata Validation and Debugging
The service includes endpoints for metadata validation, as well as debugging tools to simulate various error codes and test client error-handling mechanisms.
Metadata Export
An endpoint (/utils/getexportedmetadata/{pointInTime}) is available to get metadata that is exported during maintenance (if configured), allowing for robust document management.
Audit log Export
An endpoint (/utils/getauditlogs/{pointInTime}) is available to get the audit logs from the point in time of your interest. The audit logs are exported during maintenance and made available as zipped csv files for further analysis.
Authorization
Clients are granted access with specific rights (Read, Write, Admin) based on schema definitions. The Admin right is reserved for clients performing maintenance operations.
Schemas
The Schema defines the structure of your document metadata, specifying columns as strings, booleans, or arrays. Multiple Schemas can be defined in the system to cater to varying client requirements, including different authorization rules. Each Schema is tailored to your organizational needs.
Even though the CosmosDB is a document database and you can add metadata outside of the Schema, the Schema is used to enforce the quality of the metadata.
Besides validating the metadata the schema service can also:
- add default values to metadata
- enforce required fields when doing searches
- transform data when doing loading and saving of metadata (transform data to upper or lower case)
Clients integrating with Viewpoint can discover available Schemas via the /v1/document/schemas endpoint.
Retention policies
Each document in Viewpoint is subject to a defined retention policy, which dictates how long the document is stored. There are two types of retention policies:
- Direct: The retention period starts immediately upon document upload.
- On Signal: The retention period starts upon an external trigger by updating the RetentionStartDate.
Viewpoint automatically manages document lifecycle, deleting documents when their retention period expires while ensuring data remains recoverable during a configured grace period.
Another action (to bypass the retention policies) is just to delete the document.
Auditing
All endpoints in the system are audited. The audit log contains information like Operation, client ip address, timestamp, ClientId and more. These logs are good for analysis how the system is used. The logs are exported every night in the maintenance process and made available as zipped csv files to be used in tools like Excel and other tools for further analysis.