Ingest Workflow

Setup

When ingesting files in Connect, you must first configure the following:

• Bucket(s)
• A title structure with a title metadata schema
• A metadata schema
• Media item entity types
• A media descriptive metadata schema
• A virtual asset entity type
• A virtual asset metadata schema
• A media JSON payload

For more information on configuration, see Configuring a Media Item Entity Type.

Workflow

Consider the following scenario:

Your own media management system has sent you a JSON file like the following example. The intention is to integrate this media into Connect. To achieve this, we need to first check if that media item has already been ingested in Connect. If that's the case, we will keep using it. If not, we will create a virtual asset entity for that file that will contain some of the information parsed from the JSON file.

1. Getting Media Items

We need to make sure we work with a media item that has been ingested in Connect. As such, we will use a search query by name and ingest status. To check if the media item exists in Connect with the ingest completed status, use the following query:

Query

query fileByMetadata($metadataLookup: MetadataLookupInput) {
    fileByMetadata(metadataLookup: $metadataLookup) {
        filename
        status
        entityType {
            name
        }
        customFields {
            locale
            values {
                id
                value
            }
        }
        fileDesignations {
            edges {
                node {
                    name
                }
            }
        }
    }
}

Variables

{
    "metadataLookup": {
        "entityTypeName": "Media container type",
        "lookupField": {
            "name": "External ID",
            "value": "External ID e9fcf238"
        }
    }
}

You will get the following response:

Response

{
    "data": {
        "fileByMetadata": [
            {
                "filename": "External_movie_UHD.mov",
                "status": "ingest_completed",
                "entityType": {
                    "name": "Media container type"
                },
                "customFields": [
                    {
                        "locale": "af-ZA",
                        "values": [
                            {
                                "id": "0ba3e300-3241-4f9a-846f-ea330dd266d6",
                                "value": "External ID e9fcf238"
                            },
                            {
                                "id": "91917564-b9a7-4aa2-b503-60a665b12383",
                                "value": false
                            }
                        ]
                    }
                ],
                "fileDesignations": {
                    "edges": [
                        {
                            "node": {
                                "name": "Episode_HD"
                            }
                        }
                    ]
                }
            }
        ]
    }
}

2. Creating Media Items

If the query does not return a result, you must use the following mutation to create the virtual asset. For more information about virtual assets, see the Glossary.

Note: When ingesting a media item, you must first upload it in S3. The media item entity object is automatically created in Connect.

Mutation

mutation createVirtualAsset($input: VirtualAssetInput!) {
  createVirtualAsset(input: $input) {
    id
    name
    organizationId
    entityTypeId
    fileId
    customFields {
      locale
      values{
        value
        attributeId
      }
    }
  }
}

Variables

{
  "input": {
    "name":"Placeholder_MovieName",
    "titleId":"dcbaf148-6f24-4c92-9862-3ecdf4ae183e",
    "entityTypeId":"9312cfed-1fde-4450-adff-202298476594",
    "customFields": [
      {
        "values": {
          "attributeId": "c8b40676-16cd-4b75-ba69-420bf976d755", 
          "value": "MovieName"
        }
      },
      {
        "values": {
          "attributeId": "e1ad4149-dceb-486b-b402-ce1d6f56fb63", 
          "value": "unknown"
        }
      }
    ]
  }
}

You will get the following response:

Response

{
  "data": {
    "createVirtualAsset": {
      "id": "3854e0c1-d3c3-4be9-a32a-5c69c5e3cc0f",
      "name": "Placeholder_MovieName",
      "organizationId": "73dbbfa1-3839-452e-99cf-6274cecfdfaa",
      "entityTypeId": "9312cfed-1fde-4450-adff-202298476594",
      "fileId": null,
      "customFields": [
        {
          "locale": null,
          "values": [
            {
              "value": "MovieName",
              "attributeId": "c8b40676-16cd-4b75-ba69-420bf976d755"
            },
            {
              "value": "unknown",
              "attributeId": "e1ad4149-dceb-486b-b402-ce1d6f56fb63"
            }
          ]
        }
      ]
    }
  }
}

After the virtual asset has been created, we can use part of the JSON information to update the following metadata fields:

• File Name -> items.AssetBasicData.FileName (from the JSON file)
• Physical location -> items.CorrelationId + items.VendorPrimaryGroup

Mutation

mutation updateVirtualAsset($virtualAssetId: ID!, $virtualAssetInput: VirtualAssetInput) {
  updateVirtualAsset(id: $virtualAssetId, input: $virtualAssetInput) {
    id
    name
    organizationId
    entityTypeId
    fileId
    customFields {
      locale
      values{
        value
        attributeId
      }
    }
  }
}

Variables

{
    "virtualAssetId": "3854e0c1-d3c3-4be9-a32a-5c69c5e3cc0f",
    "virtualAssetInput": {
        "customFields": [
            {
                "locale": null,
                "values": [
                    {
                        "attributeId": "e1ad4149-dceb-486b-b402-ce1d6f56fb63",
                        "value": "s3://physical_location_bucket/physical_location_key/movie.mp4"
          },
                    {
                        "attributeId": "c8b40676-16cd-4b75-ba69-420bf976d755",
                        "value": "New Movie Name"
                    }
                ]
            }
        ]
    }
}

Response

{
  "data": {
    "updateVirtualAsset": {
      "id": "3854e0c1-d3c3-4be9-a32a-5c69c5e3cc0f",
      "name": "Placeholder_MovieName",
      "organizationId": "73dbbfa1-3839-452e-99cf-6274cecfdfaa",
      "entityTypeId": "9312cfed-1fde-4450-adff-202298476594",
      "fileId": null,
      "customFields": [
        {
          "locale": null,
          "values": [
            {
              "value": "New Movie Name",
              "attributeId": "c8b40676-16cd-4b75-ba69-420bf976d755"
            },
            {
              "value": "s3://physical_location_bucket/physical_location_key/movie.mp4",
              "attributeId": "e1ad4149-dceb-486b-b402-ce1d6f56fb63"
            }
          ]
        }
      ]
    }
  }
}

3. Updating Media Items

If the query returns a media item, it exists. You can set the media item entity type using the following mutation:

Mutation

mutation updateFile($input: FileInput, $id: ID!) {
    updateFile(id: $id, input: $input) {
        id
        status
        entityType {
            name
        }
        customFields {
            locale
            values {
                id
                value
            }
        }
    }
}

Variables

{
    "id": "9a5c2653-d988-44a2-b042-3511a97c24ad",
  "input": {
    "entityTypeId": "e1e335c0-b24b-442f-8bba-cd4ac1af6921",
    "language": "en_GB",
    "titleId": "62223f00-1487-481d-9083-4a945e9a2b6c",
    "customFields": {
      "values": {
        "attributeId": "723310c3-d0c0-494e-97f3-70a6b195dc0f",
        "value": "Original File Name"
      }
    }
  }
}

Response

{
  "data": {
    "updateFile": {
      "id": "9a5c2653-d988-44a2-b042-3511a97c24ad",
      "status": "ingest_completed",
      "entityType": {
        "name": "video media"
      },
      "customFields": [
        {
          "locale": null,
          "values": [
            {
              "id": "7810085a-fb45-43ca-b737-0e51b6de6701",
              "value": "Original File Name"
            }
          ]
        }
      ]
    }
  }
}

You can now use this information about the media item to a third party tool of your choice.