Catalogue Updates
User Guide - Catalogue Updates
This guide explains how to update the commercial catalogue offer, known as “Despliegue de oferta” in the MasStack Admin frontend.
Overview
The catalogue update process allows updating the commercial offer available in our database.
This is necessary so that changes made by the Commercial Offer team (OFC) are reflected in our public API.
This operation is typically performed by:
- An internal mas-catalogue cronjob that runs daily at 04:00 AM (TZ=Europe/Madrid)
- The Commercial Offer team (OFC)
- The mas-catalogue team
plaintext
This process may cause latencies in the public API response time or even temporary unavailability in the worst case.
Therefore, it should be performed during off-peak hours and with caution.Access Points
You can access the catalogue offer deployments through the MasStack Admin Web interface, depending on the environment:
Prerequisites
- Permissions: There are two permissions needed for managing catalogue updates, according to the following table:
| Operation | Permission | Included in roles |
|---|---|---|
| Request a new catalogue update | catalogue.designer.write | catalogue-admin catalogue-designer-writer |
| See catalogue updates history | catalogue.designer.read | catalogue-admin catalogue-designer-writer catalogue-designer-reader |
- No other catalogue-update process should be running concurrently. The system does not support parallel updates.
How to Perform a Catalogue Update
- Access the Admin Dashboard for your target environment (STA or PROD) using the links above
- Verify Prerequisites: Otherwise, you won’t be able to trigger an update
- Trigger the Update through the Admin UI interface
- Monitor the Status: The update process goes through several phases
Understanding Update Status
The catalogue update can show the following statuses:
| Description | V2 Status | V3 Status |
|---|---|---|
| The update is currently running | IN_PROGRESS | RUNNING |
| The update failed (check error details in the dashboard) | ERROR | FAILED |
| The update completed successfully | FINISHED_OK | COMPLETED |
What Happens During an Update
The update process involves:
- Data Composition: Gathering offer data from Oracle, GCP buckets, and PostgreSQL
- Validation: Running integrity checks in an isolated database
- Export: Creating a catalogue dump file if validations pass
- Distribution: Uploading the dump to GCP storage
- Reload: Each service instance loads the new catalogue dump
- Cache Refresh: Clearing cached data to reflect the new commercial offer
- Completion: Marking the update as finished
plaintext
The process is designed to minimize downtime, but some latency may be experienced during the reload phase.Version Differences
| Aspect | v2 | v3 |
|---|---|---|
| API Endpoint | /orgs/{org_id}/designer/catalogue_updates | /orgs/{org_id}/updates |
| Status Values | IN_PROGRESS / ERROR / FINISHED_OK | RUNNING / FAILED / COMPLETED |
| Additional Steps | Direct cache flush | Data migration to PostgreSQL before cache flush |
plaintext
For v3, the update process includes an additional migration phase where data is synchronized to PostgreSQL database.
This is transparent to users but may take slightly longer than v2.Troubleshooting
If an update fails:
- Check the error details in the Admin dashboard
- Ensure no concurrent updates were attempted
- Check service logs for detailed error messages
- Contact mas-catalogue team if the issue persists
Additional Information
For technical details about the update architecture and event flow, see ADR-004: Catalogue Updates V3 Architecture.