DocumentationDynamic Media Image Production System API

searchAssets

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

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>
4e9b9d8c-5839-4215-aa35-01b652869681