---
# System prepended metadata

title: API Extensions - Media Items

---

# API Extensions - Media Items

### Update File by Metadata & Locator

**Scenarios**:

- [x] Update a media item that doesn't exist
    - byLocator: `"Cannot read property 'id' of null"`
    - byMetadata: `"No candidate entities found for key: files_entity_caption,Global,hellooooooo. Please ensure your entity exists and the attribute used for the lookup is of type String"`
- [x] Update a media item that is archived
    - byLocator: updates the file as told. same does `updateFile`
    - byMetadata: updates the file as told. same does `updateFile`
- [x] Update a media item that is trashed
    - byLocator: `"Cannot read property 'id' of null"`
    - byMetadata: trashed files don't have metadata info, can't use mutation
- [x] Add extra languages (1 or 2) and fill in metadata fields on each
- [x] Update a file's entity type, fill in some fields, attach it to a title, update its parent and add it to a virtual folder when the file is unattached.
- [x] Update a file's entity type, fill in some fields, attach it to a title, update its parent and add it to a virtual folder when the file is already attached to a different title.
    - error: "Using a virtual folder from another title is not allowed." 
    - https://ateliere.atlassian.net/browse/CD-10860 - zypline issue
- [x] Update a file with an incompatible entity type
    - error: `"Can't use entityType with baseSubType 'image' for file with type 'caption'!"`
- [x] Add the file to a title when it's unasigned.
- [x] Update just the title when the file is attached to a different title
- [x] Update when multiple titles satisfy `titleMetadataLookup`
    - error: `"Multiple candidates found for key: api_extension_entity,Global,hello"`
- [x] Move the file from a virtual folder in a different virtual folder of the same title
- [x] Use a virtual folder that is part of a different title
    - error: `"Using a virtual folder from another title is not allowed."`
- [x] Update with a title that doesn't exist
    - error: `"No candidate entities found for key: api_extension_entity,Global,hellooooo"`
- [x] Update with a virtual folder that doesn't exist
    - error: `"No candidate entities found for virtualFolderName: test-auto2\n                and titleMetadataLookup: {\"entityTypeName\":\"api_extension_entity\",\"lookupField\":{\"name\":\"Global\",\"value\":\"hello\"}}"`
- [x] Update the parent when the file doesn't have a parent already set
- [x] Update the parent when the file already has a parent set
- [x] Update when multiple files satisfy the `parentMetadataLookup` 
    - error: `"Multiple candidates found for key: files_entity_caption,Global,hello"`

_______________

### Delete File by Metadata & Locator


**Scenarios**:

- [x] Delete a file that is not attached to any title

  - byLocator: ``{
    "data": {
        "deleteFileByLocator": {
            "filename": "CODA_Parcel1_1_minute-PRORES-1920-1080.mov",
            "status": "permanently_deleted",
            "locatorUrl": "s3://tf-s3-ownzones-arrakis/testautomation/uploads/CODA_Parcel1_1_minute-PRORES-1920-1080.mov"
        }
    }
}
   - byMetadata: ``{
    "data": {
        "deleteFileByMetadata": [
            {
                "filename": "CODA_Parcel4_1_minute-PRORES-1920-1080.mov",
                "status": "permanently_deleted"
            }
        ]
    }
}``

- [x] Delete a file that is attached to a title

   - byLocator:`` {
    "data": {
        "deleteFileByLocator": {
            "filename": "Matrix_Parcel3_1_minute-PRORES-1920-1080.mov",
            "status": "permanently_deleted",
            "locatorUrl": "s3://tf-s3-ownzones-arrakis/testautomation/uploads/Matrix_Parcel3_1_minute-PRORES-1920-1080.mov"
        }
    }
}
- byMetadata: ``{
    "data": {
        "deleteFileByMetadata": [
            {
                "filename": "TEST_Parcel1_1_minute-PRORES-1920-1080.mov",
                "status": "permanently_deleted"
            }
        ]
    }
}``


- [x] Delete a file that is attached to a title and it is Archived

  - byLocator:``{
    "data": {
        "deleteFileByLocator": {
            "filename": "Parcel21_1_minute-PRORES-1920-1080.mov",
            "status": "permanently_deleted",
            "locatorUrl": "s3://tf-s3-ownzones-arrakis/testautomation/uploads/Parcel21_1_minute-PRORES-1920-1080.mov"
        }
    }
}``
   - byMetadata: ``{
    "data": {
        "deleteFileByMetadata": [
            {
                "filename": "Matrix_Parcel3_1_minute-PRORES-1920-1080.mov",
                "status": "permanently_deleted"
            }
        ]
    }
}``
 
 - [x] Delete a media item that doesn't exist
   - byLocator: ``{
    "errors": [
        {
            "message": "Cannot read property 'id' of null"
        }
    ],
    "data": {
        "deleteFileByLocator": null
    }
}``
   
   - byMetadata: ``{
    "data": {
        "deleteFileByMetadata": []
    }
}``


 - [x] Delete a media that is "Trashed"
     - byLocator:`` {
    "errors": [
        {
            "message": "Cannot read property 'id' of null"
        }
    ],
    "data": {
        "deleteFileByLocator": null
    }
}``

   - byMetadata:`` {
    "data": {
        "deleteFileByMetadata": []
    }
}``
  
  
  - [x] Delete a media with "physicalDelete": false
  
    - byLocator: ``{
    "data": {
        "deleteFileByLocator": {
            "filename": "TEST_Parcel1_1_minute-PRORES-1920-1080.mov",
            "status": "trashed",
            "locatorUrl": "s3://tf-s3-ownzones-arrakis/testautomation/uploads/TEST_Parcel1_1_minute-PRORES-1920-1080.mov"
        }
    }
}``
    
  - byMetadata: ``{
    "data": {
        "deleteFileByMetadata": [
            {
                "filename": "TEST_Parcel1_1_minute-PRORES-1920-1080.mov",
                "status": "trashed"
            }
        ]
    }
}``
 
 
 - [x] Delete a media with an invalid "key"
  
  - byLocator: ``{
    "errors": [
        {
            "message": "Cannot read property 'id' of null"
        }
    ],
    "data": {
        "deleteFileByLocator": null
    }
}``
  
  
  
     
  - [x] Delete a media with an invalid "url"
    - ByLocator: ``{
    "errors": [
        {
            "message": "Cannot read property 'id' of null"
        }
    ],
    "data": {
        "deleteFileByLocator": null
    }
}``

  

- [x] Delete a media with an invalid "type"
  - byLocator: `Variable "$_v1_fileLocator" got invalid value { key: "testautomation/uploads/TEST_Parcel1_1_minute-PRORES-1920-1080.mov", url: "s3:/tf-s3-ownzones-arrakis/testautomation/uploads/TEST_Parcel1_1_minute-PRORES-1920-1080.mov", type: "3FileLocator", bucket: "tf-s3-ownzones-arrakis"
}; Expected type FileLocatorInput. 
Invalid value "3FileLocator" at "value.type": Expected type FileLocatorType. Did you mean S3FileLocator, FsFileLocator, HttpFileLocator, or TransferFileLocator?``


- [x] Delete a media with an invalid "bucket"
  - ByLocator: ``{
    "errors": [
        {
            "message": "Cannot read property 'id' of null"
        }
    ],
    "data": {
        "deleteFileByLocator": null
    }
}``


_______________

### Tag/Untag

**Scenarios**:

- **bulkUpdateFilesByMetadata**

- [x] Add a tag that matches the file type
    - update: error "column \"values\" does not exist" - with @nick
    - tag is added but query returns `"filename": null`, and `"designation": null`. same does `bulkUpsertFiles`  
- [x] Pass an entityTypeName that doesn't exist or it's not set on any file
    - error: "Cannot read property 'baseEntities' of undefined" - to recheck after bugfix
    - new error: "No candidate entities found for key: dasdas,Global,hi. Please ensure your entity exists and the attribute used for the lookup is of type String"
- [x] Update multiple files with different tags
- [x] Update a file with a tag that doesn't exist
    - https://ateliere.atlassian.net/browse/CD-10864
- [ ] Update the same file with multiple tags
    - ads just one. same does `bulkUpsertFiles` 
    - should error for duplicate entries - recheck after deploy
- [x] Add a tag that doesn't match the file type
    - adds it anyway but marks with Invalid Tag! - same after merge with master, same on bulkUpsertFiles
- [x] Update both tag and entity type


- **createFileFileDesignationEdgeByMetadata** & **createFileFileDesignationEdgeByLocator**

- [x] Pass entityName empty or non existing
    - `"No candidate entities found for key: bgbfgfhg,Global,hi. Please ensure your entity exists and the attribute used for the lookup is of type String"`
- [x] Add a tag that matches the file type
    - tag is added but query returns "designation": null in fileDesignations.edges. [zypline issue]
    - won't delete already existing tags, will just add another one
- [x] Update a file with a tag that doesn’t exist
    -  `"FileDesignation with name: designationsFeaturessss was not found on organization: c8b2d689-90b5-4a81-8dfc-5ae0aff74f1e!"`
- [x] Add a tag that doesn't match the file type
    - adds it anyway but marks with Invalid Tag!


- **deleteFileFileDesignationEdgeByMetadata** & **deleteFileFileDesignationEdgeByLocator**

- [x] Remove a tag that is not on the file but exists
    - byMetadata: `"Error: The specified FileFileDesignation was not found."`
    - byLocator: `"Error: The specified FileFileDesignation was not found."`
- [x] Remove a tag that doesn't exist
    - byMetadata: `"FileDesignation with name: designationsFeaturess was not found on organization: c8b2d689-90b5-4a81-8dfc-5ae0aff74f1e!"`
    - byLocator: `"FileDesignation with name: designationsFeaturess was not found on organization: c8b2d689-90b5-4a81-8dfc-5ae0aff74f1e!"`
- [x] Remove a tag when the file has only one tag
- [x] Remove a tag when the file has multiple tags
- [x] Remove a tag then remove it again
    - `"Error: The specified FileFileDesignation was not found."`
- [x] Remove an invalid tag (add an invalid tag first)
- [x] Remove a tag from multiple files (byMetadata only)


_______________

### Archive File by Metadata & Locator

**Scenarios**:

- [x] Archive a media item that is unasigned
     - byMetadata: ``{
    "data": {
        "archiveFileByMetadata": [
            {
                "filename": "Chloe_api_extensions.mov",
                "properties": {
                    "status": null,
                    "type": null
                },
                "archiveWorkflow": {
                    "status": "pending"
                },
                "status": "archive_started"
            }
        ]
    }
}``
     - byLocator: ``{
    "data": {
        "archiveFileByLocator": {
            "filename": "Chloe_api_extensions_child.scc",
            "properties": null,
            "archiveWorkflow": {
                "status": "pending"
            },
            "status": "archive_started",
            "storageClass": null
        }
    }
}``

- [x] Archive a media item assigned to a title
     - byMetadata: 
   `` "data": {
        "archiveFileByMetadata": [
            {
                "filename": "TEST_Parcel1_1_minute-PRORES-1920-1080.mov",
                "properties": {
                    "status": null,
                    "type": null
                },
                "archiveWorkflow": {
                    "status": "pending"
                },
                "status": "archive_started"
            }
        ]
    }
}``
    
   - byLocator:`` {
    "data": {
        "archiveFileByLocator": {
            "filename": "Chloe_api_extensions.mov_0.jpg",
            "properties": {
                "status": null,
                "type": null
            },
            "archiveWorkflow": {
                "status": "pending"
            },
            "status": "archive_started",
            "storageClass": null
        }
    }
}``
      
- [x] Archive a media item of different types: .mov, ,jpg, .srt etc.
   
   - byMetadata:``{
    "data": {
        "archiveFileByMetadata": [
            {
                "filename": "Chloe_api_extensions.srt",
                "properties": null,
                "archiveWorkflow": {
                    "status": "pending"
                },
                "status": "archive_started"
            }
        ]
    }
}`

{
    "data": {
        "archiveFileByMetadata": [
            {
                "filename": "image_api_extensions.jpg",
                "properties": {
                    "status": null,
                    "type": null
                },
                "archiveWorkflow": {
                    "status": "pending"
                },
                "status": "archive_started"
            }
        ]
    }
}``

   
  - byLocator: ``{
    "data": {
        "archiveFileByLocator": {
            "filename": "test-auto-17-5440-4652-890f-7a9c4c612b43_j2k__video.mxf",
            "properties": {
                "status": null,
                "type": null
            },
            "archiveWorkflow": {
                "status": "pending"
            },
            "status": "archive_started",
            "storageClass": "GLACIER"
        }
    }
}``
 
 - [x] Archive a media item from a different organisation
   - byMetadata: to retest after deploy
   
   - byLocator:`` {
    "errors": [
        {
            "message": "The file with the id:'a33ff0d4-7f62-407a-82ae-446b37853623' was not found."
        }
    ],
    "data": {
        "archiveFileByLocator": null
    }
}``

 - [x] Archive a media item which doesn't exist in Connect 
   - byMetadata: to retest after deploy
   
   - byLocator: ``{
    "errors": [
        {
            "message": "Cannot read property 'id' of null"
        }
    ],
    "data": {
        "archiveFileByLocator": null
    }
}``
   
 - [x] Archive a media item which is already in archived status
   - ByMetadata: https://ateliere.atlassian.net/browse/CD-10867
   -  byLocator: 
  same behaviour as above
  
  
  
  _______________

### Restore Archived File by Metadata & Locator

**Scenarios**:

- [x] Restore a media item that is unasigned
    - byMetadata:``{
    "data": {
        "restoreArchivedFileByMetadata": [
            {
                "filename": "Chloe_api_extensions.mov",
                "properties": {
                    "status": null,
                    "type": null
                },
                "archiveWorkflow": {
                    "status": "completed"
                },
                "status": "restore_started",
                "storageClass": "GLACIER"
            }
        ]
    }
}``
    
   
    - byLocator:

- [x] Restore a media item that is assigned to a title
    - byMetadata:
   
    - byLocator:

 - [x] Restore a media item of different types: .mov, ,jpg, .srt etc.
 
   - byMetadata:
   
    - byLocator:

- [x] Restore a media item from a different organisation
   - byMetadata:`"message": "Cannot read property 'id' of null"`
   
   - byLocator:`"message": "Cannot read property 'id' of null"`
 
 - [x] Restore a media item which doesn't exist in Connect 
   - byMetadata: ``"message": "Cannot read property 'id' of null"``
   
   - byLocator: `"message": "Cannot read property 'id' of null"``

- [x] Restore a media item which is not archived
   - byMetadata: ``"message": "The file with the id:'4c01f371-621e-4f84-9a27-b1cff24ea954' is not archived."``
   
   - byLocator: ` "message": "The file with the id:'d55b90f2-0b12-4ab0-b58e-f2404d487778' is not archived."`
   
- [x] Restore a media by its "restoreType": "Expedited(1-5 minutes)"

  - byMetadata:
   
  - byLocator: 

- [x] Restore a media by its "restoreType": "Bulk(5-12h)"
   - byMetadata:
   
   - byLocator: 


- [x] Restore a media by its "restoreType": "Standard(3-5h)"

  - byMetadata:
   
  - byLocator: 



_______________

### Restore File from Trash by Locator

**Scenarios**:

- [x] Restore a trashed file
- [x] Restore a media item that doesn't exist
    - `"Cannot read property 'id' of null"`
- [x] Restore a file that is not trashed
    - will reingest the file. same does current mutation `restoreFileFromTrash`
    - try this with an Archived file

----------------

### Read file

 - [x] Have multiple files that match the query and make sure all of them are returned (in different statuses: ingest completed, restore started, archived)
`{
    "data": {
        "fileByMetadata": [
            {
                "filename": "bug_jobs.png",
                "status": "ingest_completed",
                "entityType": {
                    "name": "files_entity_image"
                },
                "customFields": [
                    {
                        "locale": null,
                        "values": [
                            {
                                "id": "9cc3a086-9a54-4427-89aa-ee888257be38",
                                "value": "hi"
                            }
                        ]
                    },
                    {
                        "locale": "en-US",
                        "values": [
                            {
                                "id": "22a386a7-891b-4ebd-9662-408690415591",
                                "value": "get query"
                            },
                            {
                                "id": "fe376509-ea88-477e-9113-9c21cdecd849",
                                "value": false
                            }
                        ]
                    }
                ]
            },
            {
                "filename": "image_api_extensions.jpg",
                "status": "restore_started",
                "entityType": {
                    "name": "files_entity_image"
                },
                "customFields": [
                    {
                        "locale": null,
                        "values": [
                            {
                                "id": "b8617383-702c-402e-b8d0-215352ba6635",
                                "value": "hello"
                            }
                        ]
                    },
                    {
                        "locale": "en-US",
                        "values": [
                            {
                                "id": "80b4a19d-014d-4214-8664-aa863fa2ae53",
                                "value": false
                            },
                            {
                                "id": "f42887f6-101b-4f01-b912-0cc40fb72dee",
                                "value": "get query"
                            }
                        ]
                    }
                ]
            },
            {
                "filename": "Chloe_api_extensions.mov_0.jpg",
                "status": "ingest_completed",
                "entityType": {
                    "name": "files_entity_image"
                },
                "customFields": [
                    {
                        "locale": "en-US",
                        "values": [
                            {
                                "id": "b19ac5c8-a62f-4a16-9cb0-f5d8f7c8a00a",
                                "value": false
                            },
                            {
                                "id": "7a50a36c-14a9-4c10-bc4c-ddf684e8f564",
                                "value": "get query"
                            }
                        ]
                    }
                ]
            },
            {
                "filename": "searchservice-002.png",
                "status": "restore_started",
                "entityType": {
                    "name": "files_entity_image"
                },
                "customFields": [
                    {
                        "locale": "en-US",
                        "values": [
                            {
                                "id": "664734c1-62f3-4102-abf6-a9294497ed07",
                                "value": false
                            },
                            {
                                "id": "93577d48-fade-47af-9eeb-8011b05b0409",
                                "value": "get query"
                            }
                        ]
                    }
                ]
            },
            {
                "filename": "test-auto_automation_1635874492523.jpg",
                "status": "archived",
                "entityType": {
                    "name": "files_entity_image"
                },
                "customFields": [
                    {
                        "locale": "en-US",
                        "values": [
                            {
                                "id": "8d36a513-93e1-4095-a4a6-9b62fe2c9f50",
                                "value": "get query"
                            },
                            {
                                "id": "cfc39736-f0cf-4e0d-9dcf-0515dc6e9769",
                                "value": false
                            }
                        ]
                    }
                ]
            }
        ]
    }
}`




 - [x] Test single file can be returned
 
 
 - [x] No files are returned when none match the query
 
 `  "message": "No candidate entities found for key: raluca api test,String,1000. Please ensure your entity exists and the attribute used for the lookup is of type String"`
