Import Assets
Table of Contents
Overview
The import service automates the process of importing assets to Codex. This eliminates the need for manual data asset and ensures consistent adherence to our specified schema.
JSON Schema
Prior to usage, it's essential to understand the JSON schema that defines the structure of the assets to be imported. The schema serves as a blueprint for creating valid JSON entries. Below is an example of the expected schema:
[
{
"id": "string",
"title": "string",
"caption": "string",
"alt": "string",
"author": "string",
"source": "string",
"provider": "string",
"copyright ": "string",
"tags": ["string"],
"fileUrl": "string",
"folderId": "string",
"createdAt": "utc datetime",
"createdBy": "string",
"updatedAt": "utc datetime",
"updatedBy": "string",
"expiresAt": "utc datetime",
"attrs": {
"attributeName": "attributeValue"
}
},
// more asset objects...
]
JSON Schema Explanation
Here's an example asset object:
{
"id": "100",
"title": "Tile14",
"caption": "Caption 1",
"alt": "Alt text 1",
"author": "Author 1",
"source": "Source 1",
"copyright ": "Copyright 1",
"provider": "Provider 1",
"tags": ["Tag 1", "Tag 2", "Tag 3"],
"fileUrl": "https://codex-dev.codexcdn.net/assets/aswNcbIDFvNKT4PZz.png",
"folderId": null,
"expiresAt": "2024-04-04T00:00:00Z"
}
JSON Schema Explanation
The JSON schema provided outlines the structure of the assets to be imported using codex. Let's break down the fields present in the schema:
id (string)
External unique identifier provided by the client. Used to uniquely identify the asset within your system. Created assets' Id will be stored in Codex as their externalId.
It's required for inserting and updating assets.
fileUrl (string)
The URL to the file of the asset.
It's required for inserting assets.
title (string)
The title of the asset.
caption (string)
A brief description or caption for the asset.
alt (string)
Alternative text for the asset.
author (string)
The author of the asset.
Source (string)
The source of the asset.
caption (string)
A brief description or caption for the asset.
provider (string)
The provider of the asset.
copyright (string)
The copyright of the asset.
tags (List of strings)
A string list of tags associated with the asset.
folderId (string)
Codex Folder Id: Assign the asset to a Codex folder by providing its Id. Set to null, or not be set at all if you want to associate the asset with no folder.
createdAt (datetime)
The creation DateTime of the asset, in UTC time zone. If not provided, a default value will be assigned.
updatedAt (datetime)
The last update DateTime of the asset, in UTC time zone. If not provided, a default value will be assigned.
createdBy (string)
The User ID or API Key ID as it is in Codex. If not provided, a default value will be assigned.
updatedBy (string)
The User ID or API Key ID as it is in Codex that made the last update to the entry. If not provided, a default value will be assigned
expiresAt (datetime)
The expiration DateTime of the asset, in UTC time zone.
attrs (dictionary<string, object>)
A dictionary of attribute-value pairs associated with the asset.
Each entry consists of:
- Key (string): The name of the attribute.
- Value (object): The value associated with the attribute.
Usage
The whole process of importing assets involves updating existing assets, and inserting new assets based on their external IDs. Here are the steps:
Begin by preparing a JSON file containing an array of asset objects following the specified JSON structure.
The service will then process these assets using the provided data.
Image retrieval from the FileUrl object and subsequent uploading to Codex will be handled seamlessly by the service.
Finally, the service securely stores all metadata alongside the files in Codex.
Note: To efficiently manage potential high-volume downloads, consider utilizing a Content Delivery Network (CDN)or ensure that your storage infrastructure can efficiently handle high-volume downloads.
Inserting an Asset
When inserting an asset, id and fileUrl are the only required fields and other fields are optional.
Here's an example:
[
{
"id": "1",
"fileUrl":"https://codex-dev.codexcdn.net/assets/aswNcbIDFvNKT4PZz.png"
}
]
or
[
{
"id": "2",
"title": "Tile",
"caption": "Caption",
"copyright": "Copyright",
"alt": "Alt text",
"author": "Author",
"source": "Source",
"provider": "Provider",
"tags": ["Tag 1", "Tag 2", "Tag 3"],
"fileUrl":"https://codex-dev.codexcdn.net/assets/aswNcbIDFvNKT4PZz.png",
"folderId": null,
"expiresAt": "2024-04-04T00:00:00Z"
}
]
Updating an Asset
For updating an asset, you must provide a valid id (asset external ID) that corresponds to an existing asset in the codex.
Here's an example:
[
{
"id": "1"
},
{
"id": "2",
"title": "Tile",
"caption": "Caption",
"copyright": "Copyright",
"alt": "Alt text",
"author": "Author",
"aource": "Source",
"provider": "Provider",
"tags": ["Tag 1", "Tag 2", "Tag 3"],
"expiresAt": "2024-04-04T00:00:00Z"
}
]
Validation
During the import process, various validations and exceptions related to the provided asset objects may occur. Here are some common scenarios:
Asset External ID(
id) Validation: -- If the imported asset's ID is missing or empty: Message: Asset Id is required. Description: This error occurs if the ID is missing, empty, or consists only of whitespace characters.File URL(
fileUrl) Validation: -- If a file URL is missing for an asset that is being inserted: Message: File url is required. Description:This error occurs when an asset object is missing thefileUrlfield entirely.
-- If a file URL is invalid:
Message: File url is invalid.
Description: This error occurs when the fileUrl provided in an asset object is not a valid URL. A valid URL should include the scheme (protocol) like http:// or https://, followed by the domain name and the path to the file.
- Validation of the extracted file from URL: -- If a file is empty: Message: The file [FileName] is empty. Description: This error occurs when the downloaded file from the provided URL is found to be empty.
-- If a file exceeds the size limit: Message: File [FileName] exceeds 100 MB limit size. Description: This error occurs when the downloaded file from the provided URL exceeds the maximum allowed size of 100 MB.
-- If a file extension is not supported: Message: This type [Extension] of file is not supported. Description: This error occurs when the file extension of the downloaded file is not among the supported file types. Supported file types include but are not limited to various image, graphics, document, audio, and data formats.
Uploading Failure Handling: -- If uploading the file to the storage service fails: Message: Uploading file [FileName] has failed. Description: This error occurs if the attempt to upload the downloaded file to the storage service fails, which could happen due to reasons like network issues or storage configuration problems.
Codex FolderId Validation: -- If a provided Codex folderId is invalid: Message: Folder id is invalid. Description: When the provided FolderId is not a valid Codex folder identifier. Make sure to create the folder in Codex first or use null for no folder association.
Logging
During the asset import process, you will receive various logging messages to keep you informed about the progress and any issues encountere, including:
| Message | Description |
|---|---|
Downloading assets: | Assets downloaded from provided URLs. |
X% of assets preprocessed: | Update on processed assets percentage. |
Assets processed: | All imported assets processed. |
Import Success [count]: | Number of successfully imported assets. |
Import Failures [count]: | Number of failed imports. |
Created [count]: | Number of new assets created. |
Updated [count]: | Number of updated existing assets. |
Task completed: | Confirms the completion of the import task. |
Task failed: | Logs the failure of the import task. |
Asset [Id] is invalid [error message] | Alert for specific asset with validation errors. |