The Axinom Mosaic platform includes the Image Service that allows to upload and manage images. Set up the ingest functionality or the option to upload images from a pre-defined blob storage.

Set up Image Service

Introduction

By default, the Image Service is already set up to allow uploading and managing images. However, an extra setup is needed if you wish to use the Ingest functionality with images or programmatically upload images from a pre-defined blob storage using the RabbitMQ EnsureImageExists command.

To configure the required acquisition settings in the Management System, open your Management System UI in a web browser. From the home screen, navigate to Settings and find this section:

Settings
Figure 1. Image acquisition under Settings

Acquisition Profile

These settings define how the Image Service can acquire the source image files when they are referenced by a relative path during Ingest or when using the EnsureImageExists command processing.

Image acquisition profile defines the following properties:

Table 1. Properties common for every storage provider
Property Description

Title

A human-readable profile identifier

Storage Provider

The storage provider type

Root Path

An optional value that is used to define some sub-folder from which the images should be downloaded. If no value is specified, the images are acquired from the root storage location. If a value is specified, it must be a single folder name or a path, e.g folderName/anotherFolder. In this example, the images are acquired relatively to this folder.

Table 2. Azure Storage specific properties
Property Description

Storage Account Name

The username/account name

Storage Account Key

The corresponding password/access key for the storage account above.

Container Name

Which storage container to use. A Storage Account can have multiple Containers used for different purpose, e.g. source-images

Acquisition Profile / Azure
Figure 2. Example Acquisition Profile / Azure
Table 3. AWS specific properties
Property Description

Access Key Id

Access Key Id

Access Key

The corresponding password/access key.

Bucket name

Which bucket to use. Multiple buckets can be accessible with the same access key for different purpose

Region

AWS Region to use for data storage.

Acquisition Profile / AWS
Figure 3. Example Acquisition Profile / AWS
Tip
We recommend to create your storage using Mosaic Hosting Service. Alternatively, you can create storage using Microsoft Azure or AWS.

Webhooks

Image Upload Webhook

When uploading an image to the Image Service, there might be a need to validate image metadata to ensure that the image being uploaded conforms with any quality requirements.

For example, when uploading an image, there might be a requirement to ensure that the image has a minimal height and width, or only images of a specific format like png are allowed. The Image Service allows the administrators to implement this kind of validation through the image upload webhook.

Configuring image upload webhook

Image Service Settings
Figure 4. Image service settings

To configure the image upload webhook, click on the image upload webhook row in the webhooks list. This will navigate the user to Create Image Upload Webhook station.

Create Image Upload Webhook
Figure 5. Create image upload webhook

Provide a URL for the webhook and click on Proceed. This will create a secret for the webhook. Copy the webhook secret and store it in a secure manner. This secret is required to validate the authenticity of the request coming to the webhook as described in the Usage of image upload webhook section.

Image Upload Webhook Secret
Figure 6. Image upload webhook secret

Usage of image upload webhook

When an image is imported to Mosaic, either through the GraphQL API or through a RabbitMQ message, the Image Service will make an HTTP POST request to the URL configured as the image upload webhook. The payload of this request will have metadata related to the image (Refer to the request payload section.) that will allow the webhook implementor to build the required validation logic around it.

After the validation is completed, the webhook must return a response containing errors if there are any. (Refer to response payload section.) If any errors are present, the image upload will fail with the API returning the contents of the errors array as the reason.

Please refer to the Webhooks article on how to implement a webhook securely.

Image upload webhook request payload

The request payload of the image upload webhook contains the following.

Table 4. Image upload webhook request payload
Property Description Data Type

image_name

Original Image Name.

string

size

Size of the image in bytes.

number

width

Number of pixels wide.

number

height

Number of pixels high.

number

format

Name of the decoder used to compress image data. e.g. jpeg, png, webp, gif, svg

string

has_alpha

Boolean indicating the presence of an alpha transparency channel.

boolean

image_type

Type of Image as defined in the Image Service. e.g. MOVIE_COVER

string

Image upload webhook response payload

{
    errors: {
        message: string;
        code: string;
    }[];
}