Adobe Experience Cloud IPS API

Transcription

1 Adobe Experience Cloud IPS API

2 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

3 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

4 getautocroprect...93 getcdncacheinvalidationstatus...95 getcompanyinfo...96 getcompanymembers...97 getcompanymembership...98 getcompanysettings...99 getdiskusage getdistinctmetadatavalues getfolders getfoldertree getgenerationinfo getgroupmembers getgroupmembership getgroups getimageformats getimagerenderingpublishsettings getimageservingpublishsettings getimagesetmembers getjoblogs getjoblogdetails getmetadatafields getoriginalfilepaths getphotoshoppath getphotoshoppaths getprojects getproperty getpropertysets getpropertyset getpropertysets getpublishcontexts getscheduledjobs getsearchstrings getsystemproperties gettagfieldvalues Last updated 4/18/2018 IPS API

5 Contents getuniquemetadatavalues getuserchars getuserinfo getusers getviewerconfigsettings getvignettepublishformats getxmppacket getzipentries moveasset moveassets movefolder pausejob removeassetpermissions removecompanymembership removefolderpermissions removegroupmembers removegroupmembership removeprojectassets renameasset renamefolder renameproject replaceimage restoreassetsfromtrash resumejob savegroup saveimageformat saveimagemap savemetadatafield savezoomtarget searchassets searchassetsbymetadata setassetscontextstate setassetmetadata setassetpermissions Last updated 4/18/2018 IPS API

6 setassetpublishstate setassetspublishstate setassetsetdefinition setcompanymembership setcompanysettings setfolderpermissions setgroupmembers setgroupmembership setimagemaps setimagesetmembers setimagerenderingpublishsettings setimageservingpublishsettings setpassword setprojectassets settagfieldvalues seturlmodifier setuserinfo setviewerconfigsettings setzoomtargets stopjob submitjob updateassetpermissons updateassetset updatefolderpermissions updateimageset updatemetadatafield updatepropertyset updatetagfieldvalues updateviewerconfigsettings updatevignettepublishformat updatexmppacket s AcoInfo Last updated 4/18/2018 IPS API

7 Contents ActiveJob ActiveJobArray AnimatedGifInfo Asset AssetArray AssetContextStateUpdate AssetContextStateUpdateArray AssetCount AssetCountArray AssetJobLog AssetJobLogArray AssetMetadataFields AssetMetadataFieldsArray AssetMove AssetMoveArray AssetOperationFault AssetOperationFaultArray AssetPublishContexts AssetPublishContextArray AssetSetInfo AssetSummary AssetSummaryArray AudioInfo AutoColorCropOptions AutomatedSetGenerationJob AutoSetCreationOptions AutoTransparentCropOptions BatchMetadataUpdate BatchMetadataUpdateArray CabinetInfo ColorManagementOptions Last updated 4/18/2018 IPS API

8 Company CompanyArray CompanyMember CompanyMemberArray CompanyMembership CompanyMembershipArray CompanyMembershipUpdate CompanyMembershipUpdateArray CompanyMetadataInfo CompanyMetadataInfoArray CompanySettings ConfigSetting ConfigSettingArray ContextStateUpdate ContextStateUpdateArray CreateVideoSitemapJob CssInfo CuePointInfo DiskUsage DiskUsageArray Confirmation Array ExcludeByproductArray ExcludeByproductCondition ExcludeMasterVideoFromAVS ExcelInfo ExportJob FlashInfo Folder FolderArray FontFieldUpdate Last updated 4/18/2018 IPS API

9 Contents FontFieldUpdateArray FontInfo GenerationAttribute GenerationAttributeArray GenerationInfo GenerationInfoArray Group GroupArray HandleArray IccProfileFieldUpdate IccProfileFieldUpdateArray IccProfileInfo IllustratorInfo IllustratorOptions ImageFieldUpdate ImageFieldUpdateArray ImageFormat ImageFormatArray ImageInfo ImageMap ImageMapArray ImageMapDefinition ImageMapDefinitionArray ImageRenderingPublishJob ImageServingPublishJob ImageSetMember ImageSetMemberArray ImageSetMemberUpdate ImageSetMemberUpdateArray InDesignInfo JavascriptInfo Last updated 4/18/2018 IPS API

10 JobLog JobLogArray JobLogDetail JobLogDetailArray JobLogDetailAux JobLogDetailAuxArray Keywords KeywordsArray KnockoutBackgroundOptions LayerViewInfo ManualCropOptions Mask MaskArray MaskInfo MasterVideoInfo MediaOptions Metadata MetadataArray MetadataCondition MetadataConditionArray MetadataDelete MetadataDeleteArray MetadataField MetadataFieldArray MetadataPublishJob MetadataUpdate MetadataUpdateArray MPEvent MPEventArray OperationFault OperationFaultArray Last updated 4/18/2018 IPS API

11 Contents OptimizeImagesJob PdfInfo PDFOptions PdfSettingsInfo Permission PermissionArray PermissonSet PermissionSetArray PermissionUpdate PermissionUpdateArray PerspectiveQuad PhotoshopOptions PhotoshopLayerOptions PostScriptInfo PostScriptOptions PowerPointInfo PremierExpressRemixInfo Project ProjectArray Property PropertyArray PropertySet PropertySetArray PropertySet PropertySetArray PsdInfo PublishContext PublishContextArray PublishHistory PublishHistoryArray PublishStateUpdate Last updated 4/18/2018 IPS API

12 PublishStateUpdateArray RenderSceneInfo ReprocessAssetsJob RipPdfsJob RTFInfo ScheduledJob ScheduledJobArray SearchFilter SearchStrings SearchStringsArray ServerDirectoryPublishJob SetMetadataFault SetMetadataFaultArray SetPropertySetPermissions SvgInfo StringArray SwcInfo SystemFieldCondition SystemFieldConditionArray TagCondition TagConditionArray TagConditionArray TagFieldValues TagFieldValuesArray TagValueUpdate TagValueUpdateArray TagValueUpdateFault TagValueUpdateFaultArray TaskItemProgress TaskItemProgressArray TaskProgress Last updated 4/18/2018 IPS API

13 Contents TaskProgressArray TemplateInfo ThumbAssetUpdate ThumbAssetUpdateArray ThumbnailOptions UnCompressOptions UnsharpMaskOptions UploadDirectoryJob UploadPostJob UploadUrl UploadUrlArray UploadUrlsJob UrlArray User UserArray VideoCaptionInfo VideoInfo VideoPublishJob ViewerPresetInfo ViewerSwfInfo VignetteInfo WatermarkInfo WindowCoveringInfo WordInfo XmlInfo XmpKeywords XslInfo ZipEntry ZipEntryArray ZipInfo ZoomTarget Last updated 4/18/2018 IPS API

14 ZoomTargetArray ZoomTargetDefinition ZoomTargetDefinitionArray String Constants Active Job States Asset Search System Fields Asset Overwrite Modes Asset Sort Fields Asset s AutoCrop Corner Color Management Modes Color Spaces Settings Font Styles Font s Generation Info Illustrator Processes Job Log File s Job Log Sort Fields Job Log s Job Trigger States Job s Metadata Field s Numeric/Date Comparison Operators PDF Processes Permission s Photoshop Anchor Modes Photoshop Layer Naming Modes PostScript Colorspace Modes Profile Classes Last updated 4/18/2018 IPS API

15 Contents Publish State Property Set s Publish Context Publish s Region Shape Search Match Modes Sort Directions String Comparison Operators Trash State User Char Filter Fields User Roles User Sort Fields Viewer Faults authenticationfault authorizationfault ipsapifault Change Log Version Operations: New and Modified Data s: New and Modified Version Operations: New and Modified Data s: New and Modified Restricted Use Version Operations: New and Modified Data s: New and Modified String Constants: New and Modified Version Last updated 4/18/2018 IPS API

16 Data s: New and Modified Version New Additions and Changes Version Operations: New and Modified Data s: New and Modified String Constants: New and Modified Version Operations: New and Modified Data s: New and Modified String Constants: New and Modified Uploading assets by way of HTTP POSTs to the UploadFile Servlet Deprecated calls Last updated 4/18/2018 IPS API

17 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.

18 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. 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: services/ipsapiservice Access URLs for Scene7 regions Geographic location Production URL Staging URL (use for pre-production development and testing) rth America Europe, Middle East, Asia Japan/Asia Pacific 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 wsdl 6.6/2013R1 IpsApi wsdl 6.0/2012R1 IpsApi wsdl IpsApi wsdl IpsApi wsdl

19 IPS Web Service WSDL versions 19 API release version WSDL API namespace 4.2 IpsApi wsdl IpsApi wsdl Pre-4.0 IpsApi.wsdl 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 ( 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 .

20 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 regardless of API version. The following is an example of using the authheader element in a request SOAP header: <soap:header xmlns:soap=" <authheader xmlns=" <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_ >:<password>) Where base64() applies the standard Base64 encoding, <IPS_user_ > is the 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 For example: <soap:header xmlns:soap=" <AuthUser xmlns="

21 IPS Web Service WSDL versions 21 <AuthPassword xmlns=" </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=" <soapenv:header> <authheader xmlns=" <user>user@scene7.com</user> <password>mypassword</password> <app>myapp</app> <appversion>1.0</appversion> </authheader> </soapenv:header> <soapenv:body> <ns1:addcompanyparam xmlns:ns1=" <ns1:company>sample Company</ns1:company> <ns1:expires> t12:00:00-06:00</ns1:expires> </ns1:addcompanyparam> </soapenv:body> </soapenv:envelope> And the corresponding response: HTTP/ OK Server: Apache-Coyote/1.1 Content-: text/xml;charset=utf-8 Transfer-Encoding: chunked Date: Fri, 21 Jul :47:55 GMT <?xml version='1.0' encoding='utf-8'?><soapenv:envelope xmlns:soapenv=" <soapenv:header /> <soapenv:body> <ns1:addcompanyreturn xmlns:ns1=" <ns1:companyinfo> <ns1:companyhandle>2</ns1:companyhandle> <ns1:name>sample Company</ns1:name> <ns1:rootpath>samplecompany/</ns1:rootpath> <ns1:expires> t18:00:00.000z</ns1:expires> </ns1:companyinfo> </ns1:addcompanyreturn> </soapenv:body> </soapenv:envelope> SOAP faults

22 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/ Internal Server Error Server: Apache-Coyote/1.1 Content-: text/xml;charset=utf-8 Transfer-Encoding: chunked Date: Fri, 21 Jul :36:20 GMT Connection: close <?xml version='1.0' encoding='utf-8'?> <soapenv:envelope xmlns:soapenv=" <soapenv:header /> <soapenv:body> <soapenv:fault> <faultcode>soapenv:client</faultcode> <faultstring>authorizationexception</faultstring> <detail> <ns1:authorizationfault xmlns:ns1=" <code xmlns=" <reason xmlns=" does not have permission to access operation 'addcompany'</reason> </ns1:authorizationfault> </detail> </soapenv:fault> </soapenv:body> </soapenv:envelope>

23 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 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 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 For example, the locale string for US English is en-us.

25 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 26 Request <ns1:addcompanyparam xmlns:ns1=" <ns1:company>planetary</ns1:company> </ns1:addcompanyparam> Response <ns1:addcompanyreturn xmlns:ns1=" <ns1:companyinfo> <ns1:companyhandle>137</ns1:companyhandle> <ns1:name>planetary</ns1:name> <ns1:rootpath>planetary/</ns1:rootpath> <ns1:expires> t23: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=" <ns1:userhandle>621 jduvar@adobe.com</ns1:userhandle> <ns1:companyhandlearray> </ns1:items>47</ns1:items> </ns1:companyhandlearray> </ns1:addcompanymembershipparam> Response ne.

27 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=" <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 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=" <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 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=" <companyhandle>c 6</companyHandle> <projecthandle>p 6 ProjectTestAPI</projectHandle> <assethandlearray> <items>a </items> </assethandlearray> </addprojectassetsparam>

30 30 Response <addprojectassetsreturn xmlns=" <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=" <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 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. The user's 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=" <ns1:first>joe</ns1:first> <ns1:last>user</ns1:last> <ns1: >juser@adobe.com</ns1: > <ns1:defaultrole>trialsiteuser</ns1:role>

32 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=" <ns1:userhandle>525s </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 33 Examples Request <batchgetassetpublishcontextsparam xmlns=" <companyhandle>c 301</companyHandle> <assethandlearray> <items>a 27007</items> <items>a 27008</items> </assethandlearray> </batchgetassetpublishcontextsparam> Response <batchgetassetpublishcontextsreturn xmlns=" <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 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=" <companyhandle>c 6</companyHandle> <updatearray> <items> <assethandlearray> <items>a </items> <items>a </items> </assethandlearray> <updatearray> <items> <fieldhandle>m 6 IMAGE savemetadatafield</fieldhandle> <value>400</value> </items> </updatearray> </items> <items> <assethandlearray> <items>a </items>

35 35 <items>a </items> </assethandlearray> <updatearray> <items> <fieldhandle>m 6 IMAGE savemetadatafield</fieldhandle> <value>300</value> </items> </updatearray> </items> </updatearray> </batchsetassetmetadataparam> Response <batchsetassetmetadatareturn xmlns=" <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 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=" <companyhandle>c 1</companyHandle> <updatearray> <items> <assethandle>a </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=" <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 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=" <companyhandle>c 1</companyHandle> <updatearray> <items> <assethandle>a </assetHandle> <class>output</class> <colorspace>cmyk</colorspace> <pcs>luv</pcs> </items> </updatearray> </batchseticcprofilefieldsparam> Response <batchseticcprofilefieldsreturn xmlns=" <successcount>1</successcount> <warningcount>0</warningcount>

38 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 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=" <companyhandle>c 21</companyHandle> <updatearray> <items> <assethandle>a </assetHandle> <resolution>72</resolution> <anchorx>50</anchorx> <anchory>100</anchory> <userdata>nada1</userdata> </items> <items> <assethandle>a </assetHandle> <resolution>150</resolution> <anchorx>100</anchorx> <anchory>50</anchory> <userdata>nada2</userdata> </items> </updatearray> </batchsetimagefieldsparam> Response <batchsetimagefieldsreturn xmlns=" <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 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=" <companyhandle>c 3</companyHandle> <updatearray> <items> <assethandle>a 234</assetHandle> <thumbassethandle>a 189</thumbAssetHandle> </items> </updatearray>

41 41 Response <batchsetthumbassetreturn xmlns=" <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 s Confirmation s from the Scene7 CDN partner can be sent to the list's creator or up to 5 other addresses. The API sends the confirmation when the entire CDN network has been notified that the URLs referenced in the have been cleared. A single call to cdncacheinvalidation can send multiple s 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 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=" <companyhandle>c 6</companyHandle> <urlarray> <items> <items> <items> <items> </urlarray> </cdncacheinvalidationparam> Response <cdncacheinvalidationreturn xmlns=" <successcount>4</successcount> <warningcount>0</warningcount> <errorcount>0</errorcount> </cdncacheinvalidationreturn>

43 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=" <companyhandle>c 1</companyHandle> <assetarray> <items>abc123</items> <items>def456</items> </assetarray> </checkassetsparam> Response <checkassetsreturn xmlns=" <inusearray> <items>def456</items> </inusearray> </checkassetsreturn>

44 44 checklogin Checks if a user with a specific company (identified by handle), 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. The user's address. password The user's password. Output (checkloginparam) status User's log in status. Examples This sample code uses a company handle parameter, 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=" <ns1:companyhandle>137</ns1:companyhandle> <ns1: >juser3@scene7.com</ns1: > <ns1:password>welcome</ns1:password> </ns1:checkloginparam>