DocumentationDynamic Media Image Production System API

searchAssetsByMetadata

Last update: Tue Mar 08 2022 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Developer
  • Admin

Searches the metadata index repository for the given search terms. Returns asset data like the searchAssets method.

While searchAssetsByMetadata lets you search against User-Defined Metadata Fields, those fields are not returned if they are specified in the responseMetadataArray. To illustrate this point, the following code example:

<ns:responseMetadataArray>
 <ns:items>custom_attributes.x</ns:items>
</ns:responseMetadataArray>

returns a null value:

<items>
 <name>custom_attributes.x</name>
 <value>null</value>
</items>

To work around this issue, you can use the fieldHandles of the assets that are returned from the search to run getAssets (see also getAssets). This method gets the User-Defined Fields values for the assets in question. Use the following syntax example to search against User-Defined Metadata Fields:

<ns:metadataConditionArray>
 <ns:items>
  <ns:fieldHandle>custom_attributes.[UDF Field Name]</ns:fieldHandle>
  <ns:op>[Conditional]</ns:op>
  <ns:value>[Value]</ns:value>
 </ns:items>
</ns:metadataConditionArray>

Authorized User Types

  • IpsUser
  • IpsAdmin
  • IpsCompanyAdmin
  • ImagePortalAdmin
  • ImagePortalUser
  • ImagePortalContrib
  • ImagePortalContribUser

Parameters

Input (searchAssetsByMetadataParam)

Name
Type
Required
Description
companyHandle
xsd:string
Yes
The handle to the company.
Filter
type:SearchFilter
No

Filters that help you define search criteria.

See SearchFilter.

metadataConditionArray
type:MetadataConditionArray
No
Conditions that define search criteria. See below for additional information.
responseMetadataArray
type:StringArray
No
Additional fields you want to have populated on the response in the asset summary. The fields must be specified in the normalized format.
recordsPerPage
xsd:int
No
The number of assets returned by the response. The default value is 1000.
resultsPage
xsd:int
No
Specifies the page of results to return, based on recordsPerPage page size.
sortBy
xsd:string
No
Sort by selected asset field.
sortDirection
xsd:string
No
Choice of sort direction. Ascending is default.

Output (searchAssetsByMetadataReturn)

Name
Type
Required
Description
totalRows
xsd:int
No
Number of matches.
assetArray
types:AssetArray
No
Array of assets returned by the search.

metadataConditionArray Details

Item Structure

metadataConditionArray structure is as follows:

<ns1:items>
   <ns:fieldHandle>field_handle</ns:fieldHandle>
   <ns:op>operator</ns:op>
   <ns:value>comparison_value</ns:value>
</ms1:items>

Values

field_handle is the metadata search key. It can contain dot notation. Possible values include:

  • asset_id (without prefix)

  • name

  • folder_path

  • type

  • file_name

  • description

  • comment

  • user_data

  • sku

  • modified_at

  • modified_by

  • created_at (same as modified_at (Date in the form: Fri Jul 25 2014 22:13:45 GMT-0500 (CDT))

  • created_by

Allowed Operators

The operator defines how to compare the value and include:

  • Equals
  • NotEquals
  • Contains
  • NotContains
  • StartsWith
  • EndsWith

The comparison_value is the term to search for.

Examples

This code sample performs a search with the following metadata criteria:

  • name field contains 1000801.

  • dc.rights field equals Per Jessen Schmidt.

Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.scene7.com/IpsApi/xsd"
xmlns:ns="http://www.scene7.com/IpsApi/xsd/2010-01-31">
   <soapenv:Header>
      <xsd:authHeader>
          <xsd:user>user@adobe.com</xsd:user>
          <xsd:password>topSecret</xsd:password>
      </xsd:authHeader>
   </soapenv:Header>
   <soapenv:Body>
      <ns:searchAssetsByMetadataParam>
         <ns:companyHandle>c|656</ns:companyHandle>
         <ns:metadataConditionArray>
            <ns:items>
               <ns:fieldHandle>name</ns:fieldHandle>
               <ns:op>Contains</ns:op>
               <ns:value>1000801</ns:value>
            </ns:items>
            <ns:items>
               <ns:fieldHandle>dc.rights</ns:fieldHandle>
               <ns:op>Equals</ns:op>
               <ns:value>Per Jessen Schmidt</ns:value>
            </ns:items>
         </ns:metadataConditionArray>
         <ns:responseMetadataArray>
            <ns:items>dc.subject</ns:items>
            <ns:items>xmp.CreatorTool</ns:items>
         </ns:responseMetadataArray>
      </ns:searchAssetsByMetadataParam>
   </soapenv:Body>
</soapenv:Envelope>

Response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <searchAssetsByMetadataReturn xmlns="http://www.scene7.com/IpsApi/xsd/2010-01-31">
         <totalRows>1</totalRows>
         <assetSummaryArray>
            <items>
               <assetHandle>a|885289</assetHandle>
               <type>Image</type>
               <name>test9-1000801</name>
               <folder>Extroscope/Test subfolders/</folder>
               <filename>test9-1000801.jpg</filename>
               <created>2009-11-19T07:21:24.252-08:00</created>
               <createUser>pschmidt@adobe.com</createUser>
               <lastModified>2009-11-19T07:21:25.487-08:00</lastModified>
               <lastModifyUser>pschmidt@adobe.com</lastModifyUser>
               <metadataArray>
                  <items>
                     <name>dc.subject</name>
                     <value>[San Fransico, USA</value>
                  </items>
                  <items>
                     <name>xmp.CreatorTool</name>
                     <value>Ver.1.0</value>
                  </items>
               </metadataArray>
            </items>
         </assetSummaryArray>
      </searchAssetsByMetadataReturn>
   </soapenv:Body>
</soapenv:Envelope>
4e9b9d8c-5839-4215-aa35-01b652869681