Adobe Experience Cloud IPS API

Adobe Experience Cloud IPS API

Contents About Scene7 Image Production System API...17 IPS Web Service WSDL versions...18 Operations...23 Operation parameters...25 addcompany...25 addcompanymembership...26 addgroupmembers...27 addgroupmembership...27 addprojectassets...28 addtagfieldvalues...30 adduser...30 batchgetassetpublishcontexts...32 batchsetassetmetadata...33 batchsetfontfields...35 batchseticcprofilefields...36 batchsetimagefields...38 batchsetthumbasset...39 cdncacheinvalidation...41 checkassets...43 checklogin...44 copyimage...45 createassetset...46 createderivedasset...48 createfolder...49 createimageset...50 createmetadatafield...51 createproject...53 createpropertyset...54 Last updated 4/18/2018 IPS API

Contents createpropertyset...55 createtemplate...56 createviewerpreset...57 createvignettepublishformat...59 deleteasset...62 deleteassets...62 deleteassetmetadata...64 deletefolder...65 deletegroup...66 deleteimageformat...67 deleteimagemap...68 deletejob...68 deletemetadatafield...69 deleteproject...70 deletepropertyset...71 deletepropertyset...72 deletetagfieldvalues...72 deletevignettepublishformat...73 deletezoomtarget...74 emptyassetsfromtrash...75 executejob...76 forcerepublishassets...77 generatepassword...78 getactivejobs...79 getactivepublishcontext...80 getallcompanies...81 getallusers...81 getassetcounts...82 getassetjoblogs...84 getassetmetadatafields...85 getassetpublishhistory...86 getassets...87 getassetsby...88 getassociatedassets...90 Last updated 4/18/2018 IPS API

getautocroprect...93 getcdncacheinvalidationstatus...95 getcompanyinfo...96 getcompanymembers...97 getcompanymembership...98 getcompanysettings...99 getdiskusage...100 getdistinctmetadatavalues...101 getfolders...103 getfoldertree...104 getgenerationinfo...107 getgroupmembers...108 getgroupmembership...109 getgroups...110 getimageformats...110 getimagerenderingpublishsettings...111 getimageservingpublishsettings...112 getimagesetmembers...112 getjoblogs...113 getjoblogdetails...115 getmetadatafields...117 getoriginalfilepaths...118 getphotoshoppath...119 getphotoshoppaths...120 getprojects...121 getproperty...122 getpropertysets...123 getpropertyset...124 getpropertysets...125 getpublishcontexts...127 getscheduledjobs...128 getsearchstrings...129 getsystemproperties...130 gettagfieldvalues...131 Last updated 4/18/2018 IPS API

Contents getuniquemetadatavalues...132 getuserchars...133 getuserinfo...134 getusers...135 getviewerconfigsettings...137 getvignettepublishformats...138 getxmppacket...138 getzipentries...139 moveasset...140 moveassets...141 movefolder...143 pausejob...144 removeassetpermissions...144 removecompanymembership...145 removefolderpermissions...146 removegroupmembers...147 removegroupmembership...148 removeprojectassets...149 renameasset...150 renamefolder...152 renameproject...153 replaceimage...153 restoreassetsfromtrash...154 resumejob...156 savegroup...157 saveimageformat...157 saveimagemap...159 savemetadatafield...160 savezoomtarget...162 searchassets...163 searchassetsbymetadata...166 setassetscontextstate...170 setassetmetadata...171 setassetpermissions...172 Last updated 4/18/2018 IPS API

setassetpublishstate...173 setassetspublishstate...174 setassetsetdefinition...176 setcompanymembership...177 setcompanysettings...178 setfolderpermissions...179 setgroupmembers...180 setgroupmembership...181 setimagemaps...182 setimagesetmembers...183 setimagerenderingpublishsettings...184 setimageservingpublishsettings...184 setpassword...184 setprojectassets...186 settagfieldvalues...187 seturlmodifier...188 setuserinfo...189 setviewerconfigsettings...190 setzoomtargets...191 stopjob...192 submitjob...193 updateassetpermissons...196 updateassetset...197 updatefolderpermissions...197 updateimageset...198 updatemetadatafield...199 updatepropertyset...201 updatetagfieldvalues...202 updateviewerconfigsettings...203 updatevignettepublishformat...204 updatexmppacket...207 s...209 AcoInfo...209 Last updated 4/18/2018 IPS API

Contents ActiveJob...209 ActiveJobArray...211 AnimatedGifInfo...211 Asset...211 AssetArray...214 AssetContextStateUpdate...214 AssetContextStateUpdateArray...214 AssetCount...214 AssetCountArray...215 AssetJobLog...215 AssetJobLogArray...215 AssetMetadataFields...216 AssetMetadataFieldsArray...216 AssetMove...216 AssetMoveArray...216 AssetOperationFault...217 AssetOperationFaultArray...217 AssetPublishContexts...217 AssetPublishContextArray...217 AssetSetInfo...218 AssetSummary...218 AssetSummaryArray...219 AudioInfo...219 AutoColorCropOptions...219 AutomatedSetGenerationJob...219 AutoSetCreationOptions...220 AutoTransparentCropOptions...221 BatchMetadataUpdate...221 BatchMetadataUpdateArray...221 CabinetInfo...221 ColorManagementOptions...222 Last updated 4/18/2018 IPS API

Company...222 CompanyArray...223 CompanyMember...223 CompanyMemberArray...223 CompanyMembership...223 CompanyMembershipArray...224 CompanyMembershipUpdate...224 CompanyMembershipUpdateArray...224 CompanyMetadataInfo...224 CompanyMetadataInfoArray...225 CompanySettings...225 ConfigSetting...226 ConfigSettingArray...226 ContextStateUpdate...226 ContextStateUpdateArray...227 CreateVideoSitemapJob...227 CssInfo...227 CuePointInfo...228 DiskUsage...228 DiskUsageArray...228 EmailConfirmation...228 EmailArray...229 ExcludeByproductArray...229 ExcludeByproductCondition...229 ExcludeMasterVideoFromAVS...230 ExcelInfo...230 ExportJob...230 FlashInfo...231 Folder...232 FolderArray...232 FontFieldUpdate...232 Last updated 4/18/2018 IPS API

Contents FontFieldUpdateArray...233 FontInfo...233 GenerationAttribute...233 GenerationAttributeArray...233 GenerationInfo...234 GenerationInfoArray...234 Group...234 GroupArray...234 HandleArray...235 IccProfileFieldUpdate...235 IccProfileFieldUpdateArray...235 IccProfileInfo...235 IllustratorInfo...236 IllustratorOptions...236 ImageFieldUpdate...236 ImageFieldUpdateArray...237 ImageFormat...237 ImageFormatArray...237 ImageInfo...237 ImageMap...239 ImageMapArray...239 ImageMapDefinition...240 ImageMapDefinitionArray...240 ImageRenderingPublishJob...240 ImageServingPublishJob...240 ImageSetMember...241 ImageSetMemberArray...241 ImageSetMemberUpdate...241 ImageSetMemberUpdateArray...242 InDesignInfo...242 JavascriptInfo...242 Last updated 4/18/2018 IPS API

JobLog...242 JobLogArray...243 JobLogDetail...244 JobLogDetailArray...244 JobLogDetailAux...244 JobLogDetailAuxArray...245 Keywords...245 KeywordsArray...245 KnockoutBackgroundOptions...245 LayerViewInfo...246 ManualCropOptions...247 Mask...247 MaskArray...248 MaskInfo...248 MasterVideoInfo...248 MediaOptions...248 Metadata...249 MetadataArray...250 MetadataCondition...250 MetadataConditionArray...251 MetadataDelete...251 MetadataDeleteArray...251 MetadataField...252 MetadataFieldArray...252 MetadataPublishJob...252 MetadataUpdate...253 MetadataUpdateArray...254 MPEvent...254 MPEventArray...255 OperationFault...255 OperationFaultArray...255 Last updated 4/18/2018 IPS API

Contents OptimizeImagesJob...256 PdfInfo...256 PDFOptions...256 PdfSettingsInfo...256 Permission...257 PermissionArray...257 PermissonSet...257 PermissionSetArray...258 PermissionUpdate...258 PermissionUpdateArray...258 PerspectiveQuad...258 PhotoshopOptions...259 PhotoshopLayerOptions...259 PostScriptInfo...260 PostScriptOptions...260 PowerPointInfo...260 PremierExpressRemixInfo...261 Project...261 ProjectArray...261 Property...261 PropertyArray...262 PropertySet...262 PropertySetArray...262 PropertySet...262 PropertySetArray...263 PsdInfo...263 PublishContext...263 PublishContextArray...264 PublishHistory...264 PublishHistoryArray...264 PublishStateUpdate...265 Last updated 4/18/2018 IPS API

PublishStateUpdateArray...265 RenderSceneInfo...265 ReprocessAssetsJob...265 RipPdfsJob...268 RTFInfo...269 ScheduledJob...269 ScheduledJobArray...271 SearchFilter...271 SearchStrings...272 SearchStringsArray...273 ServerDirectoryPublishJob...273 SetMetadataFault...273 SetMetadataFaultArray...274 SetPropertySetPermissions...274 SvgInfo...274 StringArray...274 SwcInfo...275 SystemFieldCondition...275 SystemFieldConditionArray...276 TagCondition...276 TagConditionArray...276 TagConditionArray...277 TagFieldValues...277 TagFieldValuesArray...277 TagValueUpdate...277 TagValueUpdateArray...278 TagValueUpdateFault...278 TagValueUpdateFaultArray...278 TaskItemProgress...278 TaskItemProgressArray...279 TaskProgress...279 Last updated 4/18/2018 IPS API

Contents TaskProgressArray...280 TemplateInfo...280 ThumbAssetUpdate...280 ThumbAssetUpdateArray...280 ThumbnailOptions...281 UnCompressOptions...281 UnsharpMaskOptions...282 UploadDirectoryJob...283 UploadPostJob...286 UploadUrl...288 UploadUrlArray...289 UploadUrlsJob...289 UrlArray...291 User...291 UserArray...291 VideoCaptionInfo...292 VideoInfo...292 VideoPublishJob...292 ViewerPresetInfo...293 ViewerSwfInfo...293 VignetteInfo...293 WatermarkInfo...294 WindowCoveringInfo...294 WordInfo...294 XmlInfo...295 XmpKeywords...295 XslInfo...295 ZipEntry...295 ZipEntryArray...296 ZipInfo...296 ZoomTarget...296 Last updated 4/18/2018 IPS API

ZoomTargetArray...297 ZoomTargetDefinition...297 ZoomTargetDefinitionArray...297 String Constants...298 Active Job States...298 Asset Search System Fields...298 Asset Overwrite Modes...298 Asset Sort Fields...299 Asset s...299 AutoCrop Corner...300 Color Management Modes...300 Color Spaces...301 Email Settings...301 Font Styles...302 Font s...302 Generation Info...302 Illustrator Processes...302 Job Log File s...303 Job Log Sort Fields...303 Job Log s...304 Job Trigger States...306 Job s...306 Metadata Field s...307 Numeric/Date Comparison Operators...307 PDF Processes...307 Permission s...308 Photoshop Anchor Modes...308 Photoshop Layer Naming Modes...308 PostScript Colorspace Modes...308 Profile Classes...309 Last updated 4/18/2018 IPS API

Contents Publish State...309 Property Set s...309 Publish Context...309 Publish s...309 Region Shape...310 Search Match Modes...310 Sort Directions...310 String Comparison Operators...310 Trash State...311 User Char Filter Fields...311 User Roles...311 User Sort Fields...312 Viewer...312 Faults...313 authenticationfault...313 authorizationfault...313 ipsapifault...314 Change Log...315 Version 6.0...315 Operations: New and Modified...315 Data s: New and Modified...316 Version 4.5...317 Operations: New and Modified...317 Data s: New and Modified...317 Restricted Use...318 Version 4.4...320 Operations: New and Modified...320 Data s: New and Modified...320 String Constants: New and Modified...321 Version 4.2...321 Last updated 4/18/2018 IPS API

Data s: New and Modified...321 Version 4.0...322 New Additions and Changes...322 Version 3.8...329 Operations: New and Modified...329 Data s: New and Modified...329 String Constants: New and Modified...329 Version 3.7...330 Operations: New and Modified...330 Data s: New and Modified...331 String Constants: New and Modified...331 Uploading assets by way of HTTP POSTs to the UploadFile Servlet...333 Deprecated calls...338 Last updated 4/18/2018 IPS API

About Scene7 Image Production System API 17 About Scene7 Image Production System API The Scene7 IPS (Image Production System) Web Service API enables external applications and third-party developers to programmatically access IPS assets and functionality. This reference guide contains and defines all the services, methods, and data types used by the IPS Web Service API. It has been specifically tested for compatibility with Java (using the Apache Axis2 library), Adobe Flex, and Microsoft.NET. Standards and protocols The IPS API uses standard SOAP and HTTP protocols and is compatible with any client that conforms to these standards. Additional testing helps ensure the API is compatible with Java (using the Apache Axis2 library), Adobe Flex, and Microsoft.NET.

IPS Web Service WSDL versions 18 IPS Web Service WSDL versions The IPS Web Service is supported by a set of WSDL (Web Services Language) documents that are accessed from any IPS installation on which the IPS Web Service component is installed. Each IPS API release includes a new WSDL file that references a versioned target XML namespace. Prior WSDL namespace versions are also supported to allow for backwards compatibility with existing applications. WSDL access Access the Scene7 WSDLs as shown below. https://<ips_hostname:<ips_port>/<ips_webapp>/ webservice/ipsapi[-<api_version>].wsdl The default value for <IPS_webapp> is scene7. Service location The service URL is specified in the service section of the IPS Web Service WSDL document. The service URL is generally of the form: https://<ips_hostname>:<ips_port>/<ips_webapp>/ services/ipsapiservice Access URLs for Scene7 regions Geographic location Production URL Staging URL (use for pre-production development and testing) rth America https://s7sps1apissl.scene7.com/scene7/ https://s7sps1apissl-staging.scene7.com/scene7/ Europe, Middle East, Asia https://s7sps3apissl.scene7.com/scene7/ https://s7sps3apissl-staging.scene7.com/scene7/ Japan/Asia Pacific https://s7sps5apissl.scene7.com/scene7/ https://s7sps5apissl-staging.scene7.com/scene7/ Supported WSDLs Remember, you may need to modify your code if you want to use features in the latest version of the IPS API. The IPS API supports WSDLs for the following versions: API release version WSDL API namespace 6.8/2014R1 IpsApi-2014-04-03.wsdl http://www.scene7.com/ipsapi/xsd/2014-04-03 6.6/2013R1 IpsApi-2013-02-15.wsdl http://www.scene7.com/ipsapi/xsd/2013-02-15 6.0/2012R1 IpsApi-2012-02-14.wsdl http://www.scene7.com/ipsapi/xsd/2012-02-14 4.5 IpsApi-2010-01-31.wsdl http://www.scene7.com/ipsapi/xsd/2010-01-31 4.4 IpsApi-2009-07-31.wsdl http://www.scene7.com/ipsapi/xsd/2009-07-31

IPS Web Service WSDL versions 19 API release version WSDL API namespace 4.2 IpsApi-2008-09-10.wsdl http://www.scene7.com/ipsapi/xsd/2008-09-10 4.0 IpsApi-2008-01-15.wsdl http://www.scene7.com/ipsapi/xsd/2008-01-15 Pre-4.0 IpsApi.wsdl http://www.scene7.com/ipsapi/xsd Existing applications that need to be modified to use new features must upgrade to the latest API version and may need to make changes to existing code. See the change log for details. SOAP Bindings The IPS API Web Service supports a SOAP binding only. Supported transports The IPS API SOAP binding supports HTTP transport only. Make all SOAP requests using the HTTPS POST method. SOAP action header To process a request, set the SOAPAction HTTP header to the name of the requested operation. The operation name attribute in the WSDL binding section specifies the name. Message format The document/literal style is used for all input and output messages with types based on the XML Schema definition language (http://www.w3.org/tr/xmlschema-0/) and specified in the WSDL file. All types require qualified names using the target namespace value specified in the WSDL file. Request authentication The preferred method for passing authentication credentials in API requests is to use the authheader element as defined in the IPS API WSDL. <element name="authheader"> <complex> <sequence> <element name="user" type=""/> <element name="password" type=""/> <element name="locale" type="" minoccurs="0"/> <element name="app" type="" minoccurs="0"/> <element name="appversion" type="" minoccurs="0"/> <element name="gzipresponse" type="xsd:boolean" minoccurs="0"/> <element name="faulthttpstatuscode" type="xsd:int" minoccurs="0"/> </sequence> </complex> </element> Fields user Valid IPS user email.

IPS Web Service WSDL versions 20 password Password for user account. locale Optional locale for request. See Locale for details. app Calling application name. This parameter is optional, but it is recommended that you include it in all requests. appversion Calling application version. gzipresponse Optional flag to enable or disable gzip compression of response XML. By default, responses are gzip-compressed if the HTTP Accept-Encoding header indicates support for gzip. faulthttpstatuscode Optional parameter to override the HTTP status code for fault responses. By default, fault responses return HTTP status code 500 (Internal Server Error). Some client platforms, including Adobe Flash, are unable to read the response body unless a status code of 200 (OK) is returned. The authheader element is always defined in the namespace http://www.scene7.com/ipsapi/xsd, regardless of API version. The following is an example of using the authheader element in a request SOAP header: <soap:header xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <authheader xmlns="http://www.scene7.com/ipsapi/xsd"> <user>user@scene7.com</user> <password>mypassword</password> <app>myapp</app> <appversion>1.0</appversion> </authheader> </soap:header> Other request authentication methods If for some reason it is not possible for your client application to pass the authheader SOAP header, API requests can also specify credentials using HTTP Basic authentication (as specified in RFC 2617). For HTTP Basic authentication, the HTTP header section of each SOAP POST request must include a header of the form: Authorization: Basic base64(<ips_user_email>:<password>) Where base64() applies the standard Base64 encoding, <IPS_user_email> is the email address of a valid IPS user, and <password> is the user's password. Send the Authorization header preemptively with the initial request. If no authentication credentials are included in the request, IpsApiService does not respond with a status code of 401 (Unauthorized). Instead, a status code of 500 (Internal Server Error) is returned with a SOAP fault body stating that the request could not be authenticated. Before IPS 3.8, authentication via SOAP header was implemented using the AuthUser and AuthPassword elements in the namespace http://www.scene7.com/ipsapi. For example: <soap:header xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <AuthUser xmlns="http://www.scene7.com/ipsapi">user@scene7.com</authuser>

IPS Web Service WSDL versions 21 <AuthPassword xmlns="http://www.scene7.com/ipsapi">mypassword</authpassword> </soap:header> This style is still supported for backwards compatibility but has been deprecated in favor of the authheader element. Request authorization After the caller's credentials are authenticated, the request is checked to ensure that the caller is authorized to perform the requested operation. Authorization is based on the user role of the caller and may also require checking the target company, target user, and other operation parameters. In addition, Image Portal users must belong to a Group with the required permissions to perform certain folder and asset operations. The Operations reference section details the authorization requirements for each operation. Sample SOAP request and response The following example shows a complete addcompany operation, including HTTP headers: POST /scene7/services/ipsapiservice HTTP/1.1 User-Agent: Axis/2.0 SOAPAction: addcompany Content-: text/xml; charset=utf-8 <?xml version='1.0' encoding='utf-8'?> <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:header> <authheader xmlns="http://www.scene7.com/ipsapi/xsd"> <user>user@scene7.com</user> <password>mypassword</password> <app>myapp</app> <appversion>1.0</appversion> </authheader> </soapenv:header> <soapenv:body> <ns1:addcompanyparam xmlns:ns1="http://www.scene7.com/ipsapi/xsd/2008-01-15"> <ns1:company>sample Company</ns1:company> <ns1:expires>2008-07-31t12:00:00-06:00</ns1:expires> </ns1:addcompanyparam> </soapenv:body> </soapenv:envelope> And the corresponding response: HTTP/1.1 200 OK Server: Apache-Coyote/1.1 Content-: text/xml;charset=utf-8 Transfer-Encoding: chunked Date: Fri, 21 Jul 2006 20:47:55 GMT <?xml version='1.0' encoding='utf-8'?><soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:header /> <soapenv:body> <ns1:addcompanyreturn xmlns:ns1="http://www.scene7.com/ipsapi/xsd/2008-01-15"> <ns1:companyinfo> <ns1:companyhandle>2</ns1:companyhandle> <ns1:name>sample Company</ns1:name> <ns1:rootpath>samplecompany/</ns1:rootpath> <ns1:expires>2008-07-31t18:00:00.000z</ns1:expires> </ns1:companyinfo> </ns1:addcompanyreturn> </soapenv:body> </soapenv:envelope> SOAP faults

IPS Web Service WSDL versions 22 When an operation encounters an exception condition, a SOAP fault is returned as the body of the SOAP message in place of the normal response. For example, if a non-admin user attempts to send the previous addcompany request, the following response is returned: HTTP/1.1 500 Internal Server Error Server: Apache-Coyote/1.1 Content-: text/xml;charset=utf-8 Transfer-Encoding: chunked Date: Fri, 21 Jul 2006 16:36:20 GMT Connection: close <?xml version='1.0' encoding='utf-8'?> <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:header /> <soapenv:body> <soapenv:fault> <faultcode>soapenv:client</faultcode> <faultstring>authorizationexception</faultstring> <detail> <ns1:authorizationfault xmlns:ns1="http://www.scene7.com/ipsapi/xsd"> <code xmlns="http://www.scene7.com/ipsapi/xsd">20003</code> <reason xmlns="http://www.scene7.com/ipsapi/xsd">user does not have permission to access operation 'addcompany'</reason> </ns1:authorizationfault> </detail> </soapenv:fault> </soapenv:body> </soapenv:envelope>

23 Operations This section describes the common operation parameters handled by the IPS Web Service API. For a complete description of each operation parameter, seeoperation parameters. Handles: About Handles reference IPS objects returned by certain API operations. You can also pass handles as parameters to subsequent operation calls. Handles are string data types (). Handles are intended for use during a single application session only. Furthermore, you should make handles persistent because their format can change between IPS releases. When you write interactive applications, you implement session timeouts and discard all handles between sessions, particularly after an IPS upgrade. When you write non-interactive applications, call the appropriate operations to retrieve handles each time the application is run. The following Java/Axis2 code samples show incorrect and correct code execution: Incorrect Handle Code This code sample is incorrect because it contains a hard-coded value (555) for the company handle. SearchAssetsParam searchparam = new SearchAssetsParam(); searchparam.setcompanyhandle("555");// INCORRECT searchparam.setfolder("myfolder"); SearchAssetsReturn retval = ipsapi.searchassets(searchparam, authheader); Correct Handle Code This code sample is correct because it calls getcompanyinfo to return valid handle. It does not rely on a hard-coded value. Use this method or other IPS API equivalent to return the required handle. GetCompanyInfoParam companyinfoparam = new GetCompanyInfoParam(); companyinfoparam.setcompany("my Company"); GetCompanyInfoReturn companyinforeturn = ipsapi.getcompanyinfo(companyinfoparam, authheader); String companyhandle = companyinforeturn.getcompanyinfo().getcompanyhandle(); SearchAssetsParam searchparam = new SearchAssetsParam(); searchparam.setcompanyhandle(companyhandle); //CORRECT searchparam.setfolder("myfolder"); SearchAssetsReturn retval = ipsapi.searchassets(searchparam, authheader); Common Handle s companyhandle Most operations require you to set a company context by passing in a companyhandle parameter. The company handle is a pointer returned by certain operations such as getcompanyinfo, addcompany, and getcompanymembership. userhandle The userhandle parameter is an optional parameter for operations that target a specific user. By default, these operations target the calling user (the user whose credentials are passed in for authentication). However, admin users with the proper permissions can specify a different user. For example, the setpassword operation normally sets the password of the authenticated user, but an admin can use the userhandle parameter to set the password for a different user. For operations that require a company context (using the companyhandle parameter), both the authenticated and target users must be members of the specified company. For operations that do not require a company context, the authenticated and target users must both be members of at least one common company. The following operations can retrieve user handles:

24 getusers getallusers getuserinfo getcompanymembers getgroupmembers adduser accessuserhandle and accessgrouphandle By default, operations that require access permissions (read, write, delete) operate in the permission context of the calling user. Certain operations allow you to modify this context with the accessuserhandle or accessgrouphandle parameter. The accessuserhandle parameter allows an admin to impersonate another user. The accessgrouphandle parameter allows the caller to operate in the context of a specific user group. responsefieldarray and excludefieldarray Some operations allow the caller to restrict which fields are included in the response. Limiting fields can help reduce the time and memory required to process the request and reduce the size of the response data. The caller can request a specific list of fields by passing a responsefieldarray parameter, or with an enumerated a list of excluded fields via the excludefieldarray parameter. Both responsefieldarray and excludefieldarray specify fields by using a node path separated by /. For example, to specify that searchassets returns only the name, last modified date, and metadata for each asset refer to the following: <responsefieldarray> <items>assetarray/items/name</items> <items>assetarray/items/lastmodified</items> <items>assetarray/items/metadataarray</items> </responsefieldarray> Similarly, to return all fields (except for permissions): <excludefieldarray> <items>assetarray/items/permissions</items> </excludefieldarray> te that the node paths are relative to the return node root. If you specify a complex type field without any of its sub-elements (for example, assetarray/items/imageinfo), then all of its sub-elements are included. If you specify one or more sub-elements in a complex type field (for example, assetarray/items/imageinfo/originalpath), then only those sub-elements are included. If you do not include responsefieldarray or excludefieldarray in a request, all fields are returned. Locale Since IPS 4.0, the IPS API supports setting the locale context of an operation by passing the authheader locale parameter. If the locale parameter is not present, the HTTP header Accept-Language will be used. If this header is also not present, the default locale for the IPS server will be used. Certain operations also take explicit locale parameters, which may be different than the operation locale context. For example, the submitjob operation takes a locale parameter that sets the locale used for job logging and email notification. Locale parameters use the format <language_code>[-<country_code>] Where the language code is a lower-case, two-letter code specified by ISO-639 and the optional country code is an upper-case, two-letter code specified by ISO-3266. For example, the locale string for US English is en-us.

25 Operation parameters addcompany Adds a company to the system. Sends the name of the company to be added to the system and optionally sends whether the company expires. When this operation is invoked, the system gets a companyinfo type that contains a company handle and descriptive fields. If the company name requested already exists in the system, it throws an ipsapifault. Authorized User s IpsAdmin TrialSiteAdmin ImagePortalAdmin Input (addcompanyparam) company The name of the company to add. expires xsd:datetime The expiration date of the company. Provide the time zone with the request for this field. Time zones are adjusted to Central Time. Output (addcompanyreturn) companyinfo Handle to and name, root path, expiration date, and time of the new company. Examples This example demonstrates a request to add a company to the IPS system and the response detailing the information about the added company that is needed to perform other operations.

26 Request <ns1:addcompanyparam xmlns:ns1="http://www.scene7.com/ipsapi/xsd"> <ns1:company>planetary</ns1:company> </ns1:addcompanyparam> Response <ns1:addcompanyreturn xmlns:ns1="http://www.scene7.com/ipsapi/xsd"> <ns1:companyinfo> <ns1:companyhandle>137</ns1:companyhandle> <ns1:name>planetary</ns1:name> <ns1:rootpath>planetary/</ns1:rootpath> <ns1:expires>2101-01-31t23:00:00.030z</ns1:expires> </ns1:companyinfo> </ns1:addcompanyreturn> addcompanymembership Adds a user to one or more companies. Authorized User s IpsAdmin IpsCompanyAdmin TrialSiteAdmin ImagePortalAdmin Input (addcompanymembershipparam) userhandle The handle to the user whose membership you want to add. membershiparray types:companymembershipupdatearray An array of companies that you're adding the user to. Output (addcompanymembershipreturn) The IPS API does not return a response for this operation. Examples This example uses companyhandlearray to add a user to a single company. Request <ns1:addcompanymembershipparam xmlns:ns1="http://www.scene7.com/ipsapi/xsd"> <ns1:userhandle>621 jduvar@adobe.com</ns1:userhandle> <ns1:companyhandlearray> </ns1:items>47</ns1:items> </ns1:companyhandlearray> </ns1:addcompanymembershipparam> Response ne.

27 addgroupmembers Adds users from a specific company to a specific group. Authorized User s IpsAdmin IpsCompanyAdmin ImagePortalAdmin Input (addgroupmembersparam) companyhandle The handle to the company. grouphandle The group handle. userhandlearray types:handlearray An array of handles to users who you want to add to a group. Output (addgroupmembersparam) The IPS API does not return a response for this operation. Examples This example uses addgroupmembersparam to add a user to a single company. The IPS API does not return a response for this operation. Request <ns1:addgroupmembersparam xmlns:ns1="http://www.scene7.com/ipsapi/xsd"> <ns1:companyhandle>47</ns1:companyhandle> <ns1:grouphandle>225</ns1:grouphandle> <ns1:userhandlearray><ns1:items>70 kmagnusson@adobe.com</ns1:items></ns1:userhandlearray> </ns1:addgroupmembersparam> Response ne. addgroupmembership Adds a user to an array of groups. Authorized User s IpsAdmin IpsCompanyAdmin ImagePortalAdmin

28 Input (addgroupmembershipparam) userhandle Handle to the user whose group membership you want to add. grouphandlearray xsd:handlearray Array of handles to the groups you want the company to belong to. Output (addgroupmembershipparam) The IPS API does not return a response for this operation. Examples This example adds a group to a company with grouphandlearray. This example uses one group only. Request <ns1:addgroupmembershipparam xmlns:ns1="http://www.scene7.com/ipsapi/xsd"> <ns1:companyhandle>47</ns1:companyhandle> <ns1:grouphandlearray><ns1:items>225</ns1:items></ns1:grouphandlearray> </ns1:addgroupmembershipparam> Response ne. addprojectassets Adds one or more assets to a project. Authorized User s IpsUser IpsAdmin IpsCompanyAdmin ImagePortalAdmin ImagePortalContrib ImagePortalContribUser Input (addprojectassetsparam)

29 companyhandle Handle to the company associated with the current project. projecthandle Handle to the project you're adding assets to. projecthandlearray xsd:handlearray Array of assets you're adding to the current project. Output (addprojectassetsparam) successcount xsd:int The number of assets added successfully. warningcount xsd:int The number of warnings generated when the operation attempted to add assets to a project. errorcount xsd:int The number of errors generated when the operation attempted to add assets to a project. warningdetailhandle xsd:assetoperationfaultarray Array of warnings generated by assets when the operation attempted to add them to a project. companyhandle xsd:assetoperationfaultarray Array of errors generated by assets when the operation attempted to add them to a project. Examples This example adds a single asset (referenced by its handle) in an asset handle array to a project specified in the request. The operation completed successfully when the response successcount returns 1. Request <addprojectassetsparam xmlns="http://www.scene7.com/ipsapi/xsd/2008-01-15"> <companyhandle>c 6</companyHandle> <projecthandle>p 6 ProjectTestAPI</projectHandle> <assethandlearray> <items>a 732 1 535</items> </assethandlearray> </addprojectassetsparam>

30 Response <addprojectassetsreturn xmlns="http://www.scene7.com/ipsapi/xsd/2008-01-15"> <successcount>1</successcount> <warningcount>0</warningcount> <errorcount>0</errorcount> </addprojectassetsreturn> addtagfieldvalues Adds new tag values to the dictionary of an existing tag field. Authorized User s IpsAdmin IpsCompanyAdmin ImagePortalAdmin Input (addtagfieldvaluesparam) companyhandle The handle of the company containing the tag field. fieldhandle The handle of the tag field to be modified. valuearray An array of tag values to add to the field's existing dictionary. Output (addtagfieldvaluesparam) The IPS API does not return a response for this operation. Examples Request <addtagfieldvaluesparam xmlns="http://www.scene7.com/ipsapi/xsd/2010-01-31"> <companyhandle>c 3</companyHandle> <fieldhandle>m 3 ASSET SingleFixedTag</fieldHandle> <valuearray> <items>pineapple</items> <items>banana</items> </valuearray> </addtagfieldvaluesparam> Response ne. adduser Creates a user account and adds that account to one or more companies.

31 When adding a user to multiple companies, specify those companies by their company handles in companyhandlearray. This operation returns the handle to user you just added. Authorized User s IpsAdmin IpsCompanyAdmin TrialSiteAdmin ImagePortalAdmin Input (adduserparam) first The user's first name. last The user's last name. email The user's email address. defaultrole Sets the role for a user in each company they belong to. te, however, the IpsAdmin role overrides other per-company settings. password Sets the user's password passwordexpires xsd:datetime Sets the password expiration period. Provide the time zone when passing in the request. Time zones are adjusted to Central Time. isvalid xsd:boolean Determines if the user is valid. membershiparray xsd:companymembershipupdatearray An array of company handles. Output (adduserparam) userhandle The handle to the user. Examples The IPS API returns a user handle element that specifies the new user. Request <ns1:adduserparam xmlns:ns1="http://www.scene7.com/ipsapi/xsd"> <ns1:first>joe</ns1:first> <ns1:last>user</ns1:last> <ns1:email>juser@adobe.com</ns1:email> <ns1:defaultrole>trialsiteuser</ns1:role>

32 <ns1:password>passw0rd</ns1:password> <ns1:isvalid>true</ns1:isvalid> <ns1:companyhandlearray> <ns1:items>47</ns1:items> </ns1:companyhandlearray> </ns1:adduserparam> Response <ns1:adduserreturn xmlns:ns1="http://www.scene7.com/ipsapi/xsd"> <ns1:userhandle>525s juser@scene7.com</ns1:userhandle> </ns1:adduserreturn> batchgetassetpublishcontexts Returns the publish contexts for assets marked for publication. Authorized User s IpsUser IpsAdmin IpsCompanyAdmin TrialSiteAdmin TrialSiteUser ImagePortalAdmin ImagePortalUser ImagePortalContrib ImagePortalContribUser te: The user must have read access to return the assets. All users have access to the shared company. Input (batchgetassetpublishcontextsparam) companyhandle Handle to the company. assethandlearray types:handlearray A list of assets you want to query for active (marked for publish) contexts. Output (batchgetassetpublishcontextsreturn) assetpublishcontextsarray types:assetpublishcontextsarray An array of publish contexts in which each asset is marked for publish.

33 Examples Request <batchgetassetpublishcontextsparam xmlns="http://www.scene7.com/ipsapi/xsd/2011-11-04"> <companyhandle>c 301</companyHandle> <assethandlearray> <items>a 27007</items> <items>a 27008</items> </assethandlearray> </batchgetassetpublishcontextsparam> Response <batchgetassetpublishcontextsreturn xmlns="http://www.scene7.com/ipsapi/xsd/2011-11-04"> <assetpublishcontextsarray> <items> <assethandle>a 27007</assetHandle> <publishcontextarray> <items> <contexthandle>pc 3002</contextHandle> <context>imageserving</context> <context>imageserving</context> </items> </publishcontextarray> </items> <items> <assethandle>a 27008</assetHandle> <publishcontextarray> <items> <contexthandle>pc 3004</contextHandle> <context>video</context> <context>video</context> </items> <items> <contexthandle>pc 3001</contextHandle> <context>imagerendering</context> <context>imagerendering</context> </items> </publishcontextarray> </items> </assetpublishcontextsarray> </batchgetassetpublishcontextsreturn> batchsetassetmetadata Sets asset metadata using batch mode. Authorized User s IpsUser IpsAdmin IpsCompanyAdmin ImagePortalAdmin ImagePortalContrib ImagePortalContribUser Input (batchsetassetmetadataparam)

34 companyhandle The handle to the company whose metadata you want to set in a batch operation. updatearray types:batchmetadataupdatearray The array of metadata updates applied to the assets. Output (batchsetassetmetadataparam) successcount xsd:int The number of successfully set metadata. warningcount xsd:int The number of warnings generated when the operation attempted to set metadata. errorcount xsd:int The number of errors generated when the operation attempted to set metadata. warningdetailarray types:assetoperationfaultarray The array of details associated with the assets generating warnings when the operation attempted to batch set metadata for the assets. errordetailarray types:assetoperationfaultarray The array of details associated with the assets that generating erros when the operation attempted to batch set metadata for the assets. Examples Request <batchsetassetmetadataparam xmlns="http://www.scene7.com/ipsapi/xsd/2008-01-15"> <companyhandle>c 6</companyHandle> <updatearray> <items> <assethandlearray> <items>a 743 1 538</items> <items>a 744 1 539</items> </assethandlearray> <updatearray> <items> <fieldhandle>m 6 IMAGE savemetadatafield</fieldhandle> <value>400</value> </items> </updatearray> </items> <items> <assethandlearray> <items>a 732 1 535</items>

35 <items>a 739 1 537</items> </assethandlearray> <updatearray> <items> <fieldhandle>m 6 IMAGE savemetadatafield</fieldhandle> <value>300</value> </items> </updatearray> </items> </updatearray> </batchsetassetmetadataparam> Response <batchsetassetmetadatareturn xmlns="http://www.scene7.com/ipsapi/xsd/2008-01-15"> <successcount>4</successcount> <warningcount>0</warningcount> <errorcount>0</errorcount> </batchsetassetmetadatareturn> batchsetfontfields Sets font metadata fields. Authorized User s IpsUser IpsAdmin IpsCompanyAdmin ImagePortalContrib ImagePortalContribUser Input (batchsetfontfieldsparam) companyhandle Handle to the company that contains the fonts. updatearray types:fontfieldupdatearray Array of font field updates. Output (batchsetfontfieldsparam) successcount xsd:int The number of successfully set font fields. warningcount xsd:int Number of warnings generated when the operation attempted to set font fields. errorcount xsd:int Number of errors generated when the operation attempted to set font fields.

36 warningdetailarray types:assetoperationfaultarray The array of details associated with the assets that generated warnings when the operation attempted to apply the updates. errordetailarray types:assetoperationfaultarray The array of details associated with the assets that generated errors when the operation attempted to apply the updates. Examples Request <batchsetfontfieldsparam xmlns="http://www.scene7.com/ipsapi/xsd/2009-07-31"> <companyhandle>c 1</companyHandle> <updatearray> <items> <assethandle>a 450 14 19</assetHandle> <font>bookman Old Style Font </font> <postscript>bookman Old Style PostScript</postscript> <rtf>bookman Old Style RTF</rtf> <fontfamily>bookman Old Style Family</fontFamily> <style>bolditalic</style> <type>open </type><type>otf</type> </items> </updatearray> </batchsetfontfieldsparam> Response <batchsetfontfieldsreturn xmlns="http://www.scene7.com/ipsapi/xsd/2009-07-31"> <successcount>1</successcount> <warningcount>0</warningcount> <errorcount>0</errorcount> </batchsetfontfieldsreturn> batchseticcprofilefields Sets ICC profile metadata fields. Authorized User s IpsUser IpsAdmin IpsCompanyAdmin ImagePortalAdmin ImagePortalContrib ImagePortalContribUser Input (batchseticcprofilefields)

37 companyhandle Handle to the company that contains the ICC profiles. update array Array of ICC profile updates. Output (batchseticcprofilefields) successcount xsd:int The number of successfully set ICC profile fields. warningcount xsd:int The number of warnings generated when the operation attempted to set the ICC profile fields. errorcount xsd:int The number of errors generated when the operation attempted to set the ICC profile fields. warningdetailarray types:assetoperationfaultarray The array of details associated with the assets that generated warnings when the operation attempted to apply the updates. errordetailarray types:assetoperationfaultarray The array of details associated with the assets that generated errors when the operation attempted to apply the updates. Examples Request <batchseticcprofilefieldsparam xmlns="http://www.scene7.com/ipsapi/xsd/2009-07-31"> <companyhandle>c 1</companyHandle> <updatearray> <items> <assethandle>a 1808 13 169</assetHandle> <class>output</class> <colorspace>cmyk</colorspace> <pcs>luv</pcs> </items> </updatearray> </batchseticcprofilefieldsparam> Response <batchseticcprofilefieldsreturn xmlns="http://www.scene7.com/ipsapi/xsd/2009-07-31"> <successcount>1</successcount> <warningcount>0</warningcount>

38 <errorcount>0</errorcount> </batchseticcprofilefieldsreturn> batchsetimagefields Sets image-specific fields for one or more image assets. Authorized User s IpsUser IpsAdmin IpsCompanyAdmin ImagePortalAdmin ImagePortalContrib ImagePortalContribUser Input (batchsetimagefields) companyhandle The handle to the company that contains the image assets. updatearray types:imagefieldupdatearray The array of image field updates. Output (batchsetimagefields) successcount xsd:int The number of successfully set image fields. warningcount xsd:int The number of warnings generated when the operation attempted to set the image fields. errorcount xsd:int The number of errors generated when the operation attempted to set the image fields. warningdetailarray types:assetoperationfaultarray The array of details associated with the assets that generated warnings when the operation attempted to apply the updates. errordetailarray types:assetoperationfaultarray The array of details associated with the assets that generated errors when the operation attempted to apply the updates.

39 Examples This example sets data in the fields of two images in an update array. In the array, the images are specified by their asset handles and contain resolution in pixels, x- and y-position anchor coordinates, and user data. The response indicates that fields for both images were set successfully. Request <batchsetimagefieldsparam xmlns="http://www.scene7.com/ipsapi/xsd/2008-01-15"> <companyhandle>c 21</companyHandle> <updatearray> <items> <assethandle>a 140626 1 102524</assetHandle> <resolution>72</resolution> <anchorx>50</anchorx> <anchory>100</anchory> <userdata>nada1</userdata> </items> <items> <assethandle>a 96680 1 64865</assetHandle> <resolution>150</resolution> <anchorx>100</anchorx> <anchory>50</anchory> <userdata>nada2</userdata> </items> </updatearray> </batchsetimagefieldsparam> Response <batchsetimagefieldsreturn xmlns="http://www.scene7.com/ipsapi/xsd/2008-01-15"> <successcount>2</successcount> <warningcount>0</warningcount> <errorcount>0</errorcount> </batchsetimagefieldsreturn> batchsetthumbasset Sets the thumbnail image for one or more assets. Thumbnail Asset s Allowed thumbnail asset types consist of the following: Image AdjustedView Mask Template PsdTemplate Authorized User s IpsUser IpsAdmin IpsCompanyAdmin ImagePortalAdmin ImagePortalContrib ImagePortalContribUser

40 te: The user must have read/write access to the target asset and read access to the thumb asset. Input (batchsetthumbassetparam) companyhandle The handle to the company that contains the assets. updatearray types:thumbassetupdatearray The array of updates. Output (batchsetthumbassetparam) successcount xsd:int The number of successfully set thumbnails. warningcount xsd:int The number of warnings generated when the operation attempted to set the thumbnails. errorcount xsd:int The number of errors generated when the operation attempted to set the thumbnails. warningdetailarray types:assetoperationfaultarray The array of details associated with the assets that generated warnings when the operation attempted to apply the updates. errordetailarray types:assetoperationfaultarray The array of details associated with the assets that generated errors when the operation attempted to apply the updates. Examples Request <batchsetthumbassetparam xmlns="http://www.scene7.com/ipsapi/xsd/2010-01-31"> <companyhandle>c 3</companyHandle> <updatearray> <items> <assethandle>a 234</assetHandle> <thumbassethandle>a 189</thumbAssetHandle> </items> </updatearray>

41 Response <batchsetthumbassetreturn xmlns="http://www.scene7.com/ipsapi/xsd/2010-01-31"> <successcount>1</successcount> <warningcount>0</warningcount> <errorcount>0</errorcount> </batchsetthumbassetreturn> cdncacheinvalidation Forwards the supplied list of URLs to the Scene7 CDN (Content Distribution Network) provider to invalidate their existing cache of HTTP responses. cdncacheinvalidation: About CDN cache invalidation forces all HTTP requests for these URLs to be revalidated against the current published data on the Scene7 network once this invalidation request is processed through the CDN network. Any URLs that are not connected to the Scene7 service URL structure and directly matching the Scene7 company root ID assigned when the company is created will result in an API fault for the entire request. Any invalid URLs that the CDN does not support that it considers invalid will also result in an API fault for the entire request. Frequency of Use: Rules The rules governing the frequency of the use of this feature are controlled by Scene7's CDN partners. The CDN retains the discretion to degrade the responsiveness of these invalidations to maintain optimum performance of its service to its users. Should Scene7 be notified of overuse of this feature we will need to resort to disabling the feature on either a per company basis or entirely across the service. Confirmation Emails Confirmation emails from the Scene7 CDN partner can be sent to the list's creator or up to 5 other email addresses. The API sends the confirmation when the entire CDN network has been notified that the URLs referenced in the email have been cleared. A single call to cdncacheinvalidation can send multiple emails if the number of URLs supplied exceed the number that Scene7 can deliver to the CDN partner on a single notification. Currently, that would be if the request exceeds 100 URLs, but is subject to change based at the request of the CDN partner. Supported Since 6.0 Authorized User s IpsAdmin IpsCompanyAdmin Input (cdncacheinvalidationparam) companyhandle The handle to the company connected with the URLs to invalidate.

42 urlarray types:urlarray List of up to 1000 URLs to invalidate from the CDN cache. All URLS must contain the Scene7 company root ID to be invalidated. Output(cdnCacheInvalidationReturn) invalidationhandle A handle referencing the purge request. You can use this handle to poll the purge status by way of the getcdncacheinvalidationstatus operation. See getcdncacheinvalidationstatus. estimatedseconds xsd:int Estimated seconds to completion of the purge request. Clients should wait for this time before polling status. Example This example requests four URLs to be invalidated in the CDN cache. The response contains summary counts of the success of the operations and a list of error details supplied directly from the CDN to assist the client in use of this feature. Request <cdncacheinvalidationparam xmlns="http://www.scene7.com/ipsapi/xsd/2012-02-14"> <companyhandle>c 6</companyHandle> <urlarray> <items>http://s7d7.scene7.com/is/image/jjesquire/11008047?$thumbnail$</items> <items>http://s7d7.scene7.com/is/image/jjesquire/11008047?$product$</items> <items>http://s7d7.scene7.com/is/image/jjesquire/11008047?$large$</items> <items>http://s7d7.scene7.com/is/image/jjesquire/imagesetconfigdefaults?req=userdata</items> </urlarray> </cdncacheinvalidationparam> Response <cdncacheinvalidationreturn xmlns="http://www.scene7.com/ipsapi/xsd/2012-02-14"> <successcount>4</successcount> <warningcount>0</warningcount> <errorcount>0</errorcount> </cdncacheinvalidationreturn>

43 checkassets Checks for IPS ID conflicts by comparing asset names against all names a company's Image Serving/Image Rendering catalog namespace. Authorized User s IpsUser IpsAdmin ImagePortalAdmin ImagePortalContrib ImagePortalContribUser ImagePortalUser TrialSiteAdmin TrialSiteUser Parmaeters Input (checkassetsparam) companyhandle The handle to the company that contains the user. assetsarray types:stringarray An array of asset names to check. Output (checkassetsreturn) inusearray types:stringarray An array of asset names in use. Examples This sample code requests the asset names in use for a specified company. The response returns an array of asset names that are in use. Request <checkassetsparam xmlns="http://www.scene7.com/ipsapi/xsd/2008-09-10"> <companyhandle>c 1</companyHandle> <assetarray> <items>abc123</items> <items>def456</items> </assetarray> </checkassetsparam> Response <checkassetsreturn xmlns="http://www.scene7.com/ipsapi/xsd/2008-09-10"> <inusearray> <items>def456</items> </inusearray> </checkassetsreturn>

44 checklogin Checks if a user with a specific company (identified by handle), email address, and password can log in. te: If the company handle is omitted, this method checks the login of the default user. Authorized User s IpsUser IpsAdmin IpsCompanyAdmin TrialSiteAdmin TrialSiteUser ImagePortalAdmin ImagePortalUser ImagePortalContrib ImagePortalContribUser Input (checkloginparam) companyhandle The handle to the company that contains the user. email The user's email address. password The user's password. Output (checkloginparam) status User's log in status. Examples This sample code uses a company handle parameter, email address, and a password to determine if a user can log in to IPS. If the user can log in, this method returns the string, ValidLogin. If the user cannot log in, this method returns the string, InvalidLogin. Request <ns1:checkloginparam xmlns:ns1="http://www.scene7.com/ipsapi/xsd"> <ns1:companyhandle>137</ns1:companyhandle> <ns1:email>juser3@scene7.com</ns1:email> <ns1:password>welcome</ns1:password> </ns1:checkloginparam>