The package @axinom/mosaic-managed-workflow-integration provides types and helpers for integrating with Axinom Mosaic Managed Workflows.

@axinom/mosaic-managed-workflow-integration

This package provides types and helpers for integrating with Axinom Mosaic Managed Workflows.

Channel Workflow Integration

To integrate with the Channel Pilet, this library provides interfaces and helpers for easier integration with the following features:

  • Fast Providers

  • Route Resolvers

FAST Providers

The Channel Pilet registers a FAST provider, which enables customizable service workflows to add registrations for entities they want to be supported by the Channel service for playlist management. This is achieved through the provider registration feature provided by @axinom/mosaic-portal. For more details on providers and their usage, please refer to the Providers section in the @axinom/mosaic-portal documentation.

The integration library contains the necessary types for FAST provider registration using the @axinom/mosaic-portal library.

Here’s an example of how to register a FAST provider for the Trailer entity:

// in Pilet registration function
export function register(app: PiletApi): void {

    app.addProvider('fast-provider', {
        type: 'Trailer',
        label: 'Trailer',
        selectionComponent: ({ onSelected, onClose }) => {
            // Add your custom selection component here
            // (e.g. reusing an already existing select explorer)
            const items: ProgramEntity[] = [
            { title: 'One', videoId: '1', entityId: '1' },
            { title: 'Two', videoId: '2', entityId: '2' },
            ];

            return (
            <>
                <ul>
                {items.map((item) => (
                    <li key={item.entityId}>
                    <button onClick={() => onSelected([item])}>{item.title}</button>
                    </li>
                ))}
                </ul>
                <button onClick={onClose}>Close</button>
            </>
            );
        },
        detailsResolver: ({ entityId }) => `/trailer/${entityId}`,
    });

  // ...
}

In the Pilet registration function, use the app.addProvider method to register a FAST provider. Provide the necessary configuration, such as the provider type, label, selection component, and details resolver. The selection component allows you to create a custom component for selecting entities, while the details resolver specifies the route for navigating to the details station of the selected entity.

Route Resolvers

The Channel Pilet registers route resolvers for some of its stations, allowing other Pilets to navigate to those specific channel stations. These route resolvers are intended for use in other Pilets within your application.

Route resolvers are an important feature provided by the @axinom/mosaic-portal library. For more details about route resolvers, refer to the Route Resolvers section in the @axinom/mosaic-portal documentation.

This library, @axinom/mosaic-managed-workflow-integration, provides the ChannelStationNames enum, which contains the names of the Channel stations for which route resolvers are registered. Additionally, it defines types for the route’s dynamicSegments, which are required to retrieve the route using the resolveRoute method.

Here’s an example of how to use the resolveRoute method to retrieve the route for the ChannelDetails station:

import { ChannelStationNames } from '@axinom/mosaic-managed-workflow-integration';

const channelDetailsRoute = app.resolveRoute(ChannelStationNames.ChannelDetails, `'123'`);

React.history.push(channelDetailsRoute);

By using the resolveRoute method and passing the appropriate station name from the ChannelStationNames enum, you can retrieve the route for a specific station.

Image Workflow Integration

The Integration library provides helper methods and types for integrating image service extensions into customizable service workflows. These extensions include components for image cover, preview, explorer, and selection fields.

To use the Image service extensions in your app and bind them to the context with Piral shared data and extensions, follow these steps:

  1. Import the necessary types and helper methods into your app:

    import {
      bindImageExtensions,
      extensionDefaultValue,
      ImageExtensions,
      setGetThumbnailAndStateRenderer,
    } from '@axinom/mosaic-managed-workflow-integration';
  2. When defining the extension context, include the ImageExtensions type:

    export type Extensions = ImageExtensions & {
      // other extension types
    }
    
    export const ExtensionsContext = React.createContext<Extensions>({
      ImageCover: extensionDefaultValue,
      ImagePreview: extensionDefaultValue,
      ImageSelectExplorer: extensionDefaultValue,
      ImageSelectField: extensionDefaultValue,
      // other extensions
    });
  3. Bind the image service extensions to your app’s context using the bindImageExtensions method:

    export const bindExtensions = (app: PiletApi): Extensions => {
      setGetThumbnailAndStateRenderer(app);
    
      /** Image Extensions */
      const { ImageCover, ImagePreview, ImageSelectExplorer, ImageSelectField } =
        bindImageExtensions(app);
    
      return {
        ImageCover,
        ImagePreview,
        ImageSelectExplorer,
        ImageSelectField,
        // other extensions
      };
    };

The bindExtensions function is called when registering your Pilet and returns an object containing all the external extensions that can be used as the value for the ExtensionsContext.Provider value.

Additionally, the library provides the setGetThumbnailAndStateRenderer method. This method sets the getThumbnailAndStateRenderer function for the thumbnail renderer, which can be called and used in your app. For example, you can use it to render an explorer column with thumbnails and state.

By following these steps, you can seamlessly integrate image service extensions into your customizable service workflows.

Localization Workflow Integration

To integrate with the Localization Pilet, this library provides types and helper functions for generating routes to the embedded localization stations.

The library includes the registerLocalizationEntryPoints function for embedded route registration. This function needs to be called in the Pilet registration function as shown below:

  import { registerLocalizationEntryPoints } from '@axinom/mosaic-managed-workflow-integration';

  // Generate entry points to embedded localization stations
  registerLocalizationEntryPoints(
    [
      {
        root: routes.channelDetails,
        entityIdParam: 'channelId',
        entityType: 'channel',
      },
    ],
    app,
  );

By using registerLocalizationEntryPoints, you will register localization pages with the specified root path, such as 'channel/:channelId', and additional localization-specific route segments.

This registration will generate the following routes:

  • channel/:channelId/localization - Localization locale explorer station for the channel entity.

  • channel/:channelId/localization/:locale - localizationSourceId: Localization details station for the channel entity.

You can later access the registered routes using the getLocalizationEntryPoint method. This allows you to add links to the entities' details pages. Here’s an example:

import { getLocalizationEntryPoint } from '@axinom/mosaic-managed-workflow-integration';

// ...
const localizationPath = getLocalizationEntryPoint('channel');

// use it when navigating to the localization station
history.push(localizationPath.replace(':channelId', '123'));

In the example above, the getLocalizationEntryPoint method is used to retrieve the route, which is then added to the details station actions under the "Localizations" action:

channel details station

Clicking on the "Localizations" action will lead to the generated locale station, listing all available locales for the channel entity:

localization locale explorer

Selecting any of the locales from the locale station will further lead to the localization details station under the generated path:

localization details station

Video Workflow Integration

Extensions

The Integration library provides helper methods and types for integrating video service extensions into customizable service workflows. These extensions include components for video selection explorer and video selection field.

To use the Video service extensions in your app and bind them to the context with Piral shared data and extensions, follow these steps:

  1. Import the necessary types and helper methods into your app:

    import {
      bindVideoExtensions,
      extensionDefaultValue,
      VideoExtensions,
      setGetVideoCuePointsData,
    } from '@axinom/mosaic-managed-workflow-integration';
  2. When defining the extension context, include the VideoExtensions type:

    export type Extensions = VideoExtensions & {
      // other extension types
    }
    
    export const ExtensionsContext = React.createContext<Extensions>({
      VideoSelectExplorer: extensionDefaultValue,
      VideoSelectField: extensionDefaultValue,
      // other extensions
    });
  3. Bind the video service extensions to your app’s context using the bindVideoExtensions method:

    export const bindExtensions = (app: PiletApi): Extensions => {
      setGetVideoCuePointsData(app);
    
      /** Video Extensions */
      const { VideoSelectExplorer, VideoSelectField } = bindVideoExtensions(app);
    
      return {
        VideoSelectExplorer,
        VideoSelectField,
        // other extensions
      };
    };

The bindExtensions function is called when registering your Pilet and returns an object containing all the external extensions that can be used as the value for the ExtensionsContext.Provider value.

Additionally, the library provides the setGetVideoCuePointsData method, which allows you to fetch cue points data for videos in your app. This method internally utilizes the app.getData method from Piral, and it sets the getVideoCuePointsData function for retrieving the cue points data.

By calling the getVideoCuePointsData function, you can easily retrieve the cue points data associated with a video. This data can then be used in your app to implement features such as navigating to specific points in the video or displaying additional information at specific cue points.

By following these steps, you can seamlessly integrate video service extensions into your customizable service workflows.

Route Resolver

The Video Pilet registers route resolvers for some of its stations, allowing other Pilets to navigate to those specific video stations. These route resolvers are intended for use in other Pilets within your application.

The @axinom/mosaic-managed-workflow-integration library provides the VideoStationNames enum, which contains the names of the video stations for which route resolvers are registered. You can use these names to retrieve the routes for specific video stations using the resolveRoute method.

Here’s an example of how to use the resolveRoute method to retrieve the route for a video station:

import { VideoStationNames } from '@axinom/mosaic-managed-workflow-integration';

// ...

const navigateToVideoDetails = (videoId: string) => {
  const videoDetailsRoute = app.resolveRoute(VideoStationNames.VideoDetails, '123');
  React.history.push(videoDetailsRoute);
};

By calling the resolveRoute method with the appropriate station name from the VideoStationNames enum and any required dynamic segments (e.g., '123' in the example), you can retrieve the route for the desired video station. Then, you can navigate to that route using your preferred navigation method (React.history.push in the example).

By utilizing the registered route resolvers, you can facilitate seamless navigation to specific video stations provided by the Video Pilet within your application.