searchAssets

Last update: 2022-03-08
  • Created for:
  • Developer
    Admin

Search for assets based on your specified criteria.

Syntax

searchAssets: About

searchAssets is the primary method of retrieving IPS assets. This method is used for various purposes such as browsing the folder hierarchy or finding a specific asset by name.

Response Size

searchAssets returns up to 1000 assets in a single call. To return up to 10,000 assets per call, limit the response data to a subset of the totalRows, name, handle, type, and subType fields. To return larger sets, set up paging with the resultPage parameter.

Limit Result File Size with responseFieldArray or excludeFieldArray

Limit the size of your data set with the responseFieldArray or excludFieldArray parameters. These parameters help reduce memory use and bandwidth and can improve server response times.

Authorized User Types

  • IpsUser
  • IpsAdmin
  • IpsCompanyAdmin
  • TrialSiteAdmin
  • TrialSiteUser
  • ImagePortalAdmin
  • TrialSiteUser
  • ImagePortalAdmin
  • ImagePortalUser
  • ImagePortalContrib
  • ImagePortalContribUser
NOTE

The user must have read access to return assets.

Parameters

Input (searchAssetsParam)

Name Type Required? Description
companyHandle xsd:string Yes The handle to the company with the assets you want to search.
accessUserHandle xsd:string No Lets administrators work as a different user.
accessGroupHandle xsd:string No Lets administrators work as part of a different group.
folder xsd:string No The root path for searching for assets. If omitted, the company root folder is used.
includeSubfolders xsd:boolean No Set to true to search subfolders.
publishState xsd:string No Publish state choice.
trashState xsd:string No Trash state choice. Default is NotInTrash.
conditionMatchMode xsd:string No

Choice of Search Match Modes for combining results of keywordArray,

conditionMatchMode

systemFieldConditionArray, and metadataConditionArray. Default is MatchAll.

keywordArray types:StringArray No

Note: Deprecated parameter. It is advised that you do not use it.

A string array of keywords to match.

systemFieldMatchMode xsd:string No

Choice of Search Match Modes for combining systemFieldCondition matches. Default is MatchAll

.

systemFieldConditionArray

types:SystemFieldConditionArray

No The array of system field conditions.
tagMatchMode xsd:string No Search Match Modes string constants. The default is MatchAll.
tagConditionArray types:TagConditionArray No

An array of tag field search predicates.

Predicates are combined according to the tagMatchMode setting, and then combined with any terms in keywordArray, systemFieldConditionArray, and metadataConditionArray according to the conditionMatchMode setting.

metadataMatchMode xsd:string No Search Match Modes for combining metadataCondition matches. Default is MatchAll.
metadataConditionArray

types:MetadataConditionArray

No The array of metadata field search conditions.
assetTypeArray types:StringArray No Array of Asset Types to include in search.
excludeAssetTypeArray types:StringArray No Array of Asset Types to exclude from search.
assetSubTypeArray types:StringArray No A list of sub type names to filter against.
strictSubTypeCheck xsd:boolean No If true and assetSubTypeArray is not empty, only assets whose sub types are in assetSubTypeArray are returned. If false (default), then assets with no defined sub type are returned.
excludeByproducts xsd:boolean No If true, byproduct assets generated during ingestion of a primary asset, such as ripped PDF page images, are excluded from search results. Default is false.
excludByproductArray

types:ExcludeByproductArray

No Array of byproduct asset generation conditions to exclude from search results. If present, this parameter overrides the excludeByproducts setting.
projectHandle xsd:sting No Handle of a project containing the assets to search.
recordsPerPage xsd:int No Maximum number of results to return.
resultsPage xsd:int No Specifies the page of results to return, based on recordsPerPage page size.
sortBy xsd:string No Choice of asset sort fields.
sortDirection xsd:string No Choice of sort direction.
responseFieldArray types:StringArray No Contains a list of fields and subfields for inclusion in the response.
excludeFieldArray types:StringArray No Contains a list of fields and subfields for exclusion from the response.

Output (searchAssetsReturn)

Name Type Required Description
totalRows xsd:int No Number of rows a search returns when records per page are not limited.
assetArray types:AssetArray No Assets that the search returns.

Examples

This code sample searches for image assets that belong to a specific company. The response is truncated for brevity.

Request

<ns1:searchAssetsParam xmlns:ns1="http://www.scene7.com/IpsApi/xsd">
   <ns1:companyHandle>47</ns1:companyHandle>
   <ns1:includeSubfolders>true</ns1:includeSubfolders>
   <ns1:assetTypeArray>
      <ns1:items>Image</ns1:items>
   </ns1:assetTypeArray>
</ns1:searchAssetsParam>

Response

<searchAssetsReturn xmlns="http://www.scene7.com/IpsApi/xsd">
   <totalRows>210</totalRows>
   <assetArray>
      <items>
         <assetHandle>24265|1|17061</assetHandle>
         <type>Image</type>
         <name>Autumn Leaves</name>
         ...
      </items>
    </assetArray>
</searchAssetsReturn>
Previous page
Next page

On this page