Mosaic products documentation: Concepts, API Reference, Technical articles, How-to, Downloads and tools

Release Notes

The list below shows the latest releases and the respective features/improvements to Axinom Mosaic.

R99 (June 25, 2024)

New in this release

Libraries

  • @axinom/mosaic-ui: It is now possible to unselect items after the "select all" option was used. The checkboxes on the data rows will get enabled, once the data is exhausted (meaning there are no more pages to load). If the list is not exhausted yet, the checkboxes will stay disabled as in this case actions are expected to be performed on the whole list (including potentially unloaded items). Once the list is exhausted, the selection event will switch to a mode where it will enumerate the individual selected items to perform the action on.

    The Explorer component uses that mode by default, whenever enableSelectAll is set to true. For List components the behavior can be enabled by setting the enableSelectAllDeselect to true.

Managed Services

  • Video Service: Videos can now be deleted. To delete a video, the user role or service account that is used must have Videos: Edit AND Videos: Delete permission, or just Admin permission for the Video Service.

    • Deletion can be done via the UI (from the video details station or the video explorer station) or directly via the GraphQL API (deleteVideo and startVideosDeletion mutations).

    • You can also send a DeleteVideo command. If the video was found and was successfully deleted a DeleteVideoFinished event will be sent that you can subscribe to. If the video deletion failed a DeleteVideoFailed event will be sent. If an attempt to delete a video is made, but this video does not exist (anymore) the operation will still succeed, but no events will be sent.

Customizable Services

  • Media Messages: We’ve extended the doc types on the message payloads defined in the media-messages library to include information about the used aggregate-id and type. This will make it easier for consumers and producers of the messages to understand the values expected for each message. #315

  • Media Service: Fixed an issue with genre localizations not always being synchronized correctly #310

  • Media Service: Fixed an issue where the TV show genres station was not rendering successfully when the genre list was empty. #311

R98 (June 6, 2024)

New in this release

General

Media Template Bootstrapping

With this release we’re introducing a new, improved way to bootstrap custom solutions based on our media template. This process is powered by the Mosaic CLI and will guide users through the setup process, allowing to customize the experience to their needs. We’re planning to add further improvements to this process in the future, so stay tuned for more updates.

Mosaic Create CLI command

If you’re new and want to setup a new custom solution, please follow the instructions documented in the getting started section on the media template introduction docs.

If you want to learn more about the command and it’s options check out the mosaic-cli documentation.

Postgres 16.2

We now support Postgres v16.2 as the database version for Media Template. Please follow the below steps to migrate your existing local environment to the new version (your data will be preserved):

  1. Make sure your media-template repository is up to date with the latest changes. Especially the changes from this PR

  2. Run yarn run env-cmd --silent -f .env ts-node scripts/create-data-dump.ts from Media Template root.

  3. Run yarn infra:down

  4. Delete the Docker volume related to Postgres (docker volume rm infra_postgres_data)

  5. Run yarn infra:up --build

  6. Run yarn db:reset

  7. Run yarn run env-cmd --silent -f .env ts-node scripts/import-pg-dump.ts from Media Template root.

Libraries

  • @axinom/mosaic-cli: Fixing some commands that were not crrectly returing a non-zero exit code in case there was an error. This will make it easier to use the CLI in automated scripts.

  • @axinom/mosaic-message-bus: We have made adjustments to the @axinom/mosaic-message-bus library to create the delay queues of Quorum type instead of Classic type. This will ensure the messages in those queues will have higher reliability and fault tolerance.

    However it’s not possible to simply change the type of a RabbitMQ queue from Classic to Quorum. Therefore, we’ve changed the name of the delay queues from delay:10sec, delay:30sec to delay:10s, delay:30s. After upgrading to the latest message-bus library, the services will start using the newly named queues, and the older queues will remain unused/unconsumed.

    The services will not need any changes, however the remaining unused queues (delay:10sec, delay:30sec) can be deleted via the RabbitMQ Management UI.

Managed Services

  • Image Service: Images can now be deleted. To delete an image, the user or token that is used must have Images: Edit AND Images: Delete permission, or just Admin permission for the Image Service.

    • Deletion can be done via UI (from Image Details station or Images Explorer station) or directly via the GraphQL API (deleteImage and startImagesDeletion mutations),

    • You can also send a DeleteImage command. If the image was found and and successfully deleted a DeleteImageFinished event will be sent that you can subscribe to. If the image deletion failed a DeleteImageFailed event will be sent. If an attempt to delete an image is made, but this image does not exist - not found - the operation will still succeed, but no events will be sent.

  • Image Service: Fixed an issue that prevented the Altair client to work correctly.

  • Localization Service: Fixed an issue with the validation of language tags in Localization settings.

  • Localization Service: Fixed a racing condition where localization values created immediately after the source entity registration were sometimes not saved correctly.

Customizable Services

  • Media Service: We improved the ingest process to be more resilient on large ingests, able to handle more entities at once, improved the progress reporting, and have improved error handling. (#291, #293, and #295)

  • Media Service: Messages the service uses to send to itself (e.g. during ingest) are now directly stored in the inbox table and won’t do a detour over the RMQ anymore (#292)

  • Media Service: We updated the version of the Altair package (#303)

  • Media Service: We updated the version of the pg-transactional-outbox package (#307)

R96 (May 6, 2024)

Breaking Changes

Removed APIs

We now have removed the deprecated events from the ID Service:

  • UserDeleted

  • UserRoleDeleted

  • ServiceAccountDeleted

Please refer to Planned Deprecations page to see the new events you may use instead.

New in this release

Libraries

  • @axinom/mosaic-cli: A new CLI command mosaic service purge-permissions is introduced, which can be used to purge permissions from ID Service for a given Mosaic Service. More info can be found in the @axinom/mosaic-cli documentation.

  • @axinom/mosaic-ui: We introduced a new Tabs component. This component can be used to structure the fields on detail pages. To find more about the control and some general things to keep in mind when designing workflows using this component, check out the Storybook.

Managed Services

  • Video Service: The video-select-field microfrontend extension now has a new optional property predefinedFilterValues that can be used to specify additional filters that should be applied to the list of videos that users can pick from.

  • Video Service: The preview station now contains an optional video player allowing to preview videos directly in the management system. This feature can be configured in the video service settings on the admin portal.

  • Hosting Service: Hosting Service now supports assigning custom DNS labels to services hosted by it that makes it possible to have more predictable URLs for the deployed services. You can find the new field in the details station of your customizable service. Please note that the custom DNS labels are globally unique, and therefore will be assigned on a first-used basis.

    Custom DNS Label
  • Management System Service: Added an option to replace the welcome message on the home screen as well as the logo on the top right of the management system shell with a custom component. To find out how, check out the documentation

Customizable Services

  • Media Service: We updated the piral package to version 1.5.2, which matches the version the Mosaic Portal is using. This update should not have any impact on the existing services, but it is recommended to update the piral package in your services to the latest version to avoid any potential issues. (#287 & #288)

  • Media Service: We added a new environment variable IS_LOCALIZATION_ENABLED to the media workflow package. This variable will affect whether the localization sub stations on the entity details will be shown or not. (#284)

  • Media Service: We removed the unnecessary permission check for the events the service receives as answer for the LocalizeEntity command which complicated the process when trying to setup the service from the scratch. (#277)

  • Media Service: Message handlers in the media service are using a database clients with the owner permissions to be able to change also those values that cannot be changed via the login database role. The field names in the handler suggested incorrectly, that the database login pool is used in message handler. We changed the argument names to "ownerClient" to avoid confusion. (#278)

R94 (April 10, 2024)

New in this release

General

With this release we’re launching our new Localization Service! 🎉

Localization Tile

This service enables you to manage the different localizations of the metadata of your entities and ultimately shipping them to your users. To learn more about the service check out its documentation here.

We integrated support for it into the Media and Catalog Service (more details below), but the service is not limited to these services. If you want to use it in your custom service, please check out the this article that explains how to extend your entities with localizations.

Localization Details

Libraries

  • @axinom/mosaic-ui: Fixed an issue with the Dynamic Data List, where changes to the position of an item using the text input were not applied correctly.

  • @axinom/mosaic-ui: Explorers in selection mode now reset their selection when the filters are changed.

Managed Services

  • Hosting Service: When storage credentials are regenerated through the Admin Portal, the Hosting Service now emits an event ObjectStorageCredentialsRegenerated. Interested services can listen to this event and update any stored management tokens etc. using Hosting Service GraphQL API to keep the storage credentials up-to date.

  • Hosting Service: Now the services deployed via the Hosting Service will receive a performance boost during executing DB Queries that uses ILIKE statement (such as when using filter queries for text fields) since they are able to use existing GIN INDEXes for improving query performance when Row Level Security is enabled. This is achieved by automatically marking the pg_catalog.texticlike function as LEAKPROOF.

  • Hosting Service: The Mosaic Hosting Service no longer grants the policymaker role to RMQ Users it generates and instead will grant the management role. If you require specific policies to be configured for your RMQ vhosts, please get in touch with our support team, so we can help you out.

Customizable Services

  • Media & Catalog Service: We added localization support for all publishable entities (Movie, TV Show, Season, Episode, Collection, Movie Genre, TV Show Genre).

    We changed the Catalog Service by moving localizable properties into a separate related table, e.g. title, description, and synopsis are no longer part of the movie table, but are moved to movie_localizations related table. The GraphQL API remains unchanged, as dedicated views are implemented to expose localizable properties on the level of parent entity.

    Localization is an optional feature in the Media Service and can be enabled/disabled using the LOCALIZATION_IS_ENABLED environment variable. When disabled, entity definitions and changes from the Media Service will not be synced with the Localization Service, and only base values will be published instead of base values and localizations.

    Note
    In order for localizations to be enabled, the Localization Service must be enabled on the environment and the LOCALIZATION_IS_ENABLED environment variable needs to be set to true.

    After these changes are applied to an existing media-template repository and there is an intention to enable localizations, the following migration steps must be done:

    • The existing media-service service account must be adjusted to include "Source Entities: Edit!, "Entity Definitions: Edit", "Localized Entities: Edit", and "Localized Entities: Review" permissions of the Localization Service. For a local development, this can be done by running yarn setup` script to (re)create the service account.

    • Once the Localization Service is enabled in both Admin Portal and Media Service (via the LOCALIZATION_IS_ENABLED env var) and successfully launched, the previously existing entities can be migrated to become localizable using a dedicated migration script located at services\media\service\src\_manual-repair-scripts\register-localization-sources.ts

    The majority of the changes were added via PR #160. The support for ingesting localized values was added with PR #211

  • Media Service: We added a refetch configuration to the mutations on the detail stations to make sure the form data also updates correctly when the save is performed by an action that does not navigate the user away from the page. (#269)

  • Media Service: We adjusted the titles of some Explorer stations to be more consistent (#267)

  • Media, Catalog, Entitlement, Vod-to-Live Service: The services were updated to use the latest service-common library, specifically now we use the updated setupMonitoring method of this library that will ensure if there will be any errors of a single metric during its collection, the other successfully collected metrics will be available in the registry. Instead an error log will be generated to be investigated separately. (#263)

R93 (March 25, 2024)

New in this release

General

With this release we’re introducing a new pattern on how the media, catalog and entitlement service handle messages. The services are now using a Transactional Inbox/Outbox pattern. The classical way of processing messages is in general still supported, but we encourage the use of the new pattern to get a more reliable and consistent message processing. We have a more detailed explanation of the pattern in the Messaging documentation, but here are the sections that describe the general idea:

Transactional Outbox
In Mosaic, the transactional outbox pattern is utilized for reliable message sending from one service to itself or other external systems. When a service needs to publish an event or command, it first writes the message details to its outbox table within the same database transaction as the business logic. This ensures the message’s atomicity and durability together with the associated business data. The message publisher of that service polls then this outbox table and sends the messages via the actual RabbitMQ messaging broker.

Transactional Inbox
On the receiving end, services in Mosaic employ the transactional inbox pattern to process incoming messages reliably and efficiently. Messages are retrieved from the RabbitMQ queue and stored exactly once in the inbox database table. The associated business logic is then executed within the same database transaction that marks the inbox message as processed. This guarantees that the message is processed exactly once, even in the event of failures or system restarts.

The very changes to the three services on the media template can be seen on PR #219.

Libraries

  • @axinom/mosaic-ui: The UI library will now be smarter about the <style/> elements it injects into the DOM. A UI library instance will only add the styles if they were not already added by another instance. Different versions of the library will still define styles that differ individually. This change makes the DOM more lightweiht and improves the developer experience when trying to tweak styles on the fly using the browser’s developer tools.

  • @axinom/mosaic-portal: When pressing the save button in the management system, the application will not create another entry in the browser history. This will make it easier to navigate back to the previous page after saving a form.

  • @axinom/mosaic-service-common: The service-common library now includes an express handler to add the Axinom Mosaic favicon.ico to express applications. This can be done via app.use(mosaicFavicon);

  • @axinom/mosaic-service-common: The assertError helper function is deprecated in favor of a new ensureError helper function.

    Before After
    import { assertError} from '@axinom/mosaic-service-common';
    
    try {
       // code that has a potential to throw errors
    } catch(error) {
       assertError(error);
       // your error handling
    }
    import { ensureError } from '@axinom/mosaic-service-common';
    
    try {
       // code that has a potential to throw errors
    } catch(e) {
       const error = ensureError(error);
       // your error handling
    }

    The main reason for this change is, that the code in the 'Before' example would throw from within the catch block, in case the caught error was not an instance of an Error class. And this is likely not the behavior the developer intended. With ensureError, if something that is not an instance of an Error is thrown - it is wrapped into the new MosaicError object and returned instead. The developer can then decide to handle the error or throw it further.

Managed Services

  • Video Service: The Video Service message handlers for bulk archiving and bulk unarchiving videos send out an ArchiveVideosFailedEvent and UnarchiveVideosFailedEvent message in case the (un)archiving fails. The import custom videos message handler will now send an ImportCustomVideoFinishedEvent message when the import is successfully done and an ImportCustomVideoFailedEvent in case the import fails.

  • Image Service: When the ArchiveImagesCommand or the UnarchiveImagesCommand Image Service fails to handle the archive/unarchive message they send out the corresponding ArchiveImagesFailedEvent and UnarchiveImagesFailedEvent messages.

Customizable Services

  • Entitlement Service: Maxmind has introduced a daily download limit for their GEO IP databases. If your entitlement service is deployed in a scalable way or deployed/restarted often that limit can be exceeded. To avoid this limit Maxmind suggests downloading their database with your license key to some shared repository or setting up a proxy cache from where your services download the database.

    You can set the URL of such a proxy in the environment variable GEOLITE2_DOWNLOAD_URL for your Entitlement Service. #261

  • Entitlement Service: We bumped the geoip-country package version to fixed a bug that caused entitlement-service to crash shortly after start-up. This was caused due to a change in the MaxMind API and the library which accesses the API to fetch the geoip-country list not being updated to handle the changed API. #256

R92 (March 13, 2024)

New in this release

General

  • This release implements a few improvements around the way how data is saved in the management system workflows. You can find a more detailed description of concept for saving in the Saving article.

  • The management system browser tab title now dynamically adapts to the page that is currently open. This makes it easier to distinguish between different tabs when you have multiple tabs open in the same browser window.
    Out of the box it will use the title that is being set on the PageHeader component of the station. Stations can also set a custom page title by using the setTitle method on the PiralAPI object. To make it not conflict with a potential PageHeader, the automatic setting of the page title by the PageHeader can be disabled by setting setTabTitle to false.
    To enable that feature for your custom workflows you need to update the UI library to the latest version.

  • We improved the user experience when configuring profiles on video and image service that are using storages coming from the hosting service. If you have hosting service storages already enabled, you can directly pick the container from the containers available on your storage. If you have not enabled the hosting service storages yet, the UI will guide you through the process of enabling them. To find out more, check out the hosting service documentation.

Libraries

  • @axinom/mosaic-ui: The FormStation components will now add an asterisk to the page title, if the form has unsaved changes, making it easier to understand whether a from is dirty or not. This will also be reflected in the browser tab title.

  • @axinom/mosaic-ui: Added a toast notification when a form was saved successfully. This will help users to better understand when a saving operation was happening, e.g. when navigating away from a dirty form.

  • @axinom/mosaic-ui: Added a new FormGrid component. This can be used to replicate the styles applied to the children of the FormStation.

  • @axinom/mosaic-graphql-common: We’ve added a new Express middleware forwardToGraphiQl, which will redirect browsers requesting the / as well as /graphql route of a service to the /graphiql endpoint. This will make it easier to access the GraphiQL interface of a service. We added this middleware to all our managed services as well as the services in the media template (see #250).

Managed Services

  • Management System Service: We tweaked the look and feel of the save indicator to make it more clear what the state of the from and saving process is.

  • Management System Service: We changed the favicon of the Management system to the Mosaic logo.

  • Image Service: Previously, if you would request an image of a specific width and height from the /transform` API, and these values exceeded the size of an original image the returned image would have been up-scaled. This is no longer happening. If at least one of the requested dimensions is greater than the same dimension of the original image, the returned image will be transformed to match the aspect ratio of the requested dimensions, but will not exceed the original image. If upscaling was previously expected to happen by the image service, it should not be handled by other means. E.g. browsers built-in upscaling mechanisms.

  • Image Service: Adding the image transformation base url to the image details station making it easier obtainable for users of the management system.

  • Image Service: If an image with a name that is longer then 100 characters is uploaded or imported using the EnsureImageExits message, the image service will now truncate the image title to 100 characters instead of failing the import.

  • Image Service: Fixed an issue with the preview of the image transformation in the focal point stations for images that have the default focal point set.

  • Hosting Service: The Mosaic Hosting Service now grants the policymaker role to all RMQ Users it generates. This shall offer greater control over defining message policies such as setting Message TTL, Max length, etc. via the RMQ Management Portal for the user.

Customizable Services

  • Media Template: We discovered that some services are missing their required deps in the package.json. Since we are in a monorepo, these deps were supplied by other services, and therefore everything appears to work well. But when we try to build a service in isolation, the missing deps would produce build errors. We added the missing dependencies to all services in PR #246.

R91 (February 28, 2024)

New in this release

General

We’ve now introduced a strongly typed eventKey property in GraphQL Subscriptions that generates payloads for event changes in our Managed Services. If you happen to consume such subscriptions in your custom services, you may now use the eventKey field over the event field to have better type safety and to avoid any potential issues in the future.

▶ Details

An example difference in payload formats before and after:

Old New
type VideoSubscriptionPayload {
  id: UUID!
  video: Video
  event: String
}
type VideoSubscriptionPayload {
  id: UUID!
  video: Video
  event: String @deprecated(reason: "Use 'eventKey' instead.")
  eventKey: VideoSubscriptionEventKey
}

enum VideoSubscriptionEventKey {
  CUE_POINT_CREATED
  CUE_POINT_CHANGED
  CUE_POINT_DELETED
  VIDEO_CREATED
  VIDEO_CHANGED
  VIDEO_DELETED
  VIDEO_TAG_CREATED
  VIDEO_TAG_CHANGED
  VIDEO_TAG_DELETED
}

Libraries

  • @axinom/mosaic-id-guard: When a custom-service is configured to use a specific tenant/environment but receives a JWT that was issued to a different tenant/environment, the displayed error message will contain better instructions to troubleshoot the issue.

  • @axinom/mosaic-ui: Live suggestion styles are adjusted to have better padding.

  • @axinom/mosaic-ui: Added new icon for In Progress.

Managed Services

  • Identity Service: A bug was fixed when the UserRoleAssignmentChanged event was fired for a User Role that was removed from a User, the correct User Role information was not included in the event payload. Now the payload includes the correct User Role name and ID.

  • Hosting Service: A bug was fixed when a Custom Service was redeployed with a changed DNS label (via the DNS-port-mappings in the deployment-manifest YAML), the new label was not pointing to the service port.

  • Video Service: The Cue Points station was updated by removing the "Row Number" column from the Cue Points to avoid any confusion regarding the ordering. The Cue Points are always ordered by the Timestamp.

Customizable Services

  • Media Messages: The media-messages library was updated and the corresponding services (Media, Catalog & Entitlement) were aligned to now use the updated GraphQL Subscription payload format where the eventKey strongly typed property is favoured over the now deprecated event property. See more details in this PR (#235).

  • Media Service: Improved the look & feel of the workflows which contained the "Archive" & "Delete" actions to be more consistent with the remaining actions by removing the icon and only having the label.

R90 (February 12, 2024)

Breaking Changes

Deprecations

The format of GraphQL errors returned by Mosaic services has changed to conform with GraphQL standards. Deprecated properties are timestamp, code, and details. For backward compatibility, the old properties are still returned, but they will be removed in the future. For more details, see the Planned Deprecations page.

▶ Details

How to access these properties with new format:

Deprecated New

error.timestamp

error.extensions.timestamp

error.code

error.extensions.exception.code

error.details.someDetailsProperty

error.extensions.someDetailsProperty

Old New
{
  "errors": [
    {
      "message": "Access Token is not provided",
      "path": [
        "playbackVideo"
      ],
      "timestamp": "2023-08-23T04:38:06.435Z",
      "code": "ACCESS_TOKEN_REQUIRED",
      "details": {
        "someDetailsProperty": "property value"
      }
    }
  ],
  "data": null
}
{
  "errors": [
    {
      "message": "Access Token is not provided",
      "path": [
        "playbackVideo"
      ],
      "extensions": {
        "someDetailsProperty": "property value",
		    "timestamp": "2023-08-23T04:38:06.435Z",
        "exception": {
		      "code": "ACCESS_TOKEN_REQUIRED"
        }
      },
    }
  ],
  "data": null
}

Removed APIs

  • With this release we removed backwards compatibility on our Video Service for the deprecated APIs that still used the Encoding Service name.

  • We also dropped support for the following properties on Video service: drmKeyIds, qualityLevels, durationInSeconds on Videos. bandwidthInBps and initialFile on VideoStreams.

  • We removed the NodeId based fields from the graphql schemas of all managed services.

Please refer to the Planned Deprecations page for more information.

New in this release

Libraries

  • @axinom/mosaic-cli: A new CLI command mosaic service sync-permissions is introduced, which can be used to synchronize permissions with ID Service for a given Mosaic Service by giving a permissions.json file. More info can be found in the Documentation of the CLI package.

  • @axinom/mosaic-id-guard: Now the AxGuard plugin generates a permission-definition.json file that serializes the permission-definition of the service. This can be helpful when you need to perform out-of-band permission synchronization to the Mosaic ID Service before the service is started.

    See this PR (#223) & Library Documentation for the change required on the custom-service. The generated file can be used by the new mosaic service sync-permissions command of the Mosaic CLI (see above) to seed the permissions into the ID service.

  • @axinom/mosaic-portal: Changed the link to the /about page on the side panel footer to now show the portal version anymore to avoid confusions. The footer still links to the /about page. The full list of versions of all components running on the management system can be found there.

  • @axinom/mosaic-ui: Changed the ImageLoader component, to not do requests to ./undefined if the imgSrc is not defined.

  • @axinom/mosaic-service-common: Removed deprecated error handling classes in favour of MosaicError.

Managed Services

  • Identity Service: Now when a customizable-service synchronizes the permissions to the Identity Service, the system-defined Administrator role of the corresponding environment will be immediately updated with the changed permissions. Previously this happened only when a Management Super Admin would sign-in to the management system. This new change will keep the Administrator role up to date in a more timely manner.

  • Hosting Service: The Pilet Artifacts Explorer now shows most recently updated pilets first.

  • Image Service: New property image_type added to the Image Upload Webhook request payload.

  • Channel Service: Fixed an issue where the publish validations for channels and playlists would include the publish hash even if there were errors. The publish hash is now correctly null when any validation reported an error.

  • Monetization Grants Service: Fixed an issue where the publish validations for claim sets would include the publish hash even if there were errors. The publish hash is now correctly null when any validation reported an error.

  • Subscription Monetization Service: Fixed an issue where the publish validations for subscription plans would include the publish hash even if there were errors. The publish hash is now correctly null when any validation reported an error.

Customizable Services

  • Media, Catalog and Entitlement Service: Added pg lock timeout config on Postgres PoolConfig level. This setting helps to resolve deadlock situations when two competing transactions wait for each other to release their locks. This can happen when a client runs multiple mutations within a single GraphQL request or with other database related work. (#207)

Documentation

We’re now publishing the TypeDocs for our libraries at https://mosaic-typedocs.axinom.net/. This will allow you to see the TypeScript type definitions of our libraries in a more user-friendly way.

More release notes can be found here.