SOAP (Simple Object Access Protocol) is a lightweight protocol intended for exchanging structured information in a decentralized, distributed environment. It uses XML technologies to define an extensible messaging framework providing a message construct that can be exchanged over a variety of underlying protocols. The framework has been designed to be independent of any particular programming model and other implementation specific semantics.

What can the eRez SOAP interface do?

The SOAP interface of the eRez Imaging Server makes part of the eRez Imaging Server functionality available for programmatic access from other software packages. In the same way that humans can use the Web Interface of the server to retrieve information on and process images on the server, the SOAP Web Service can be used by software programs to retrieve information on and process images.

The SOAP interface is completely independent of platform and programming language and is supported by Java, .NET and other development environments.

The details of how SOAP works and how it can be used with your particular development environment are beyond the scope of this document.

A sample interface with source code in Java is included here in the “erez4/soap/java soap sdk” folder of your eRez installation.

Installation and system requirements

The SOAP interface for the eRez Imaging Server is an optional add-on that requires a special license from YaWah.com. You can verify that a valid SOAP license is installed by looking at the server status page. If SOAP is enabled you will see the line “SOAP:1” on the page as illustrated below.

With a valid license in place the eRez Imaging Server will function as a “Web Service” servicing request at the URL “http://yourhost:yourport/erez4/rpc”.

The available functions are described in the WSDL file “erez3.wsdl”. This Web Services Description Language (WSDL) files is an XML document, developed to define the XML message, operation, and protocol mapping for the eRez Imaging Server’s Web Service.

You can access the public WSDL for your server via the following link:

../erez?cmd=expand&vtl=soap/erez3.wsdl

Permissions

Most of the commands that can be performed using SOAP require the user to have certain permissions.

The permissions used by the SOAP interface are:

· View.

· List.

· Download.

· Upload.

· Edit.

· Delete.

Use the eRez Administration Console to create roles and users and assign access rights to the individual shared folders on your server.

Function Reference

The Rest of this document contains a detailed description of each the available SOAP methods.

AddJob2 function

Name	wsAddJob2
Description	Adds an image processing job to the eRez Asynchronous Queue (Download Queue).
Required Permissions	Download permission for source folder and Upload permission for destination folder.
Input	Name	Type	Description
wsAddJob2Request	handle	String	Login handle as returned by the Login function.
	src	String	eRez path to the source.
	dst	String	eRez path of the destination image.
	template	String	Download Template to use.
	top	Float	Top cropping (none = 0.0)
	left	Float	Left cropping (none = 0.0)
	bottom	Float	Bottom cropping (none = 1.0)
	right	Float	Right cropping (none = 1.0)
	angle	Float	Rotation in degrees (none = 0.0).
	width	Int	Width in pixels (overrides the value from the download template).
	height	Int	Height in pixels (overrides the value from the download template).
	clippath	String	Name of a clipping path to use.
Output	Name	Type	Description
wsAddJob2Response	jobid	Long	Unique job identifier. Use GetJobStatus to get information about progress.

AddJob function

Name	wsAddJob
Description	Adds an image processing job to the eRez Asynchronous Queue (Download Queue).
Required Permissions	Download permission for source folder and Upload permission for destination folder.
Input	Name	Type	Description
wsAddJobRequest	handle	String	Login handle as returned by the Login function.
	src	String	eRez path to the source.
	dst	String	eRez path of the destination image.
	template	String	Download Template to use.
	top	Float	Top cropping (none = 0.0)
	left	Float	Left cropping (none = 0.0)
	bottom	Float	Bottom cropping (none = 1.0)
	right	Float	Right cropping (none = 1.0)
	angle	Float	Rotation in degrees (none = 0.0).
Output	Name	Type	Description
wsAddJobResponse	jobid	Long	Unique job identifier. Use GetJobStatus to get information about progress.

FileCopy function

Name	wsFileCopy
Description	Copy a file.
Required Permissions	Download permission for source folder and Upload permission for destination folder.
Input	Name	Type	Description
wsFileCopyRequest	handle	String	Login handle as returned by the Login function.
	src	String	eRez path to the source.
	dst	String	eRez path of the destination image.
Output	Name	Type	Description
wsFileCopyResponse	result	Boolean	True if the file was copied successfully.

FileDelete function

Name	wsFileDelete
Description	Copy a file.
Required Permissions	Delete permission for source folder.
Input	Name	Type	Description
wsFileDeleteRequest	handle	String	Login handle as returned by the Login function.
	src	String	eRez path to the image.
Output	Name	Type	Description
wsFileDeleteResponse	result	Boolean	True if the file was deleted.

FileGetIPTC function

Name	wsFileGetIPTC
Description	Get IPTC tags from an image file. See also FileUpdateIPTC.
Required Permissions	List permission for source folder.
Input	Name	Type	Description
wsFileGetIPTCRequest	handle	String	Login handle as returned by the Login function.
	src	String	eRez path to the image.
Output	Name	Type	Description
wsFileGetIPTCResponse	result	Array of IPTCField	Each element contains the following fields: tag : Integer identifier. data: Binary data.

FileGetXMP function

Name	wsFileGetXMP
Description	Get XMP data from an image file. See also FileUpdateXMP.
Required Permissions	List permission for source folder.
Input	Name	Type	Description
wsFileGetXMPRequest	handle	String	Login handle as returned by the Login function.
	src	String	eRez path to the image.
Output	Name	Type	Description
wsFileGetXMPResponse	result	binary	XMP data

FileInfo function

Name	wsFileInfo
Description	Get textual information for a file as ascii, html or xml formatted text. If you use the standard template “soap/info.xml” you can use this XML schema to extract information from the XML data.
Required Permissions	List permission for source folder.
Input	Name	Type	Description
wsFileInfoRequest	handle	String	Login handle as returned by the Login function.
	src	String	eRez path to the source.
	dst	String	eRez path of the destination image.
	template	String	The Velocity template used to render the text.
	escapetype	Int	Escape used for text: 0 : none (pure ASCII) 1 : HTML 2 : XML
Output	Name	Type	Description
wsFileInfoResponse	result	Binary	Text data as an array of UTF-8 encoded bytes.

FileMove function

Name	wsFileMove
Description	Move/Rename a file.
Required Permissions	Delete permission for source folder and Upload permission for destination folder.
Input	Name	Type	Description
wsFileMoveRequest	handle	String	Login handle as returned by the Login function.
	src	String	eRez path to the source.
	dst	String	eRez path of the destination image.
Output	Name	Type	Description
wsFileMoveResponse	result	Boolean	True if the file was copied successfully.

FileUpdateIPTC function

Name	wsFileUpdateIPTC
Description	Write IPTC fields to an an image file. All existing IPTC data is replaced.
Required Permissions	Edit permission for source folder.
Input	Name	Type	Description
wsFileUpdateIPTCRequest	handle	String	Login handle as returned by the Login function.
	src	String	eRez path to the image.
	iptc	Array of IPTCField	Each element contains the following fields: tag : Integer identifier. data: Binary data.
Output	Name	Type	Description
wsFileUpdateIPTCResponse	result	Boolean	True if the file was updated successfully.

FileUpdateXMP function

Name	wsFileUpdateXMP
Description	Write XMP data to an an image file. All existing XMP data is replaced. See also FileGetXMP.
Required Permissions	Edit permission for source folder.
Input	Name	Type	Description
wsFileUpdateXMPRequest	handle	String	Login handle as returned by the Login function.
	src	String	eRez path to the image.
	xmp	Binary	XMP data
Output	Name	Type	Description
wsFileUpdateXMPResponse	result	Boolean	True if the file was updated successfully.

GetExtension function

Name	wsGetExtension
Description	Get the filename extension for a given Download template.
Required Permissions	None
Input	Name	Type	Description
wsGetExtensionRequest	template	String	Login handle as returned by the Login function.
Output	Name	Type	Description
wsGetExtensionResponse	extension	String	Filename extension such as “.tif” and “.eps” etc..

GetJobStatus function

Name	wsGetJob
Description	Get status information about a job in the asynchronous download queue.
Required Permissions	None (requires a valid JobID)
Input	Name	Type	Description
wsGetJobStatusRequest	jobid	Long	Unique job identifier as returned by AddJob or AddJob2.
Output	Name	Type	Description
wsGetJobStatusResponse	result	JobInfo structure	The JobInfo structure contains the following fields: Status: Int. Possible values are: Waiting in Queue. Image is being processed. Image is being packed for transmission. Package complete and ready for download. Job failed. Job cancelled by the user. Insufficient source image data. Must prompt user for action. In transit for FTP upload. . Percentcompleted: Int Percentage completed (0 – 100). Message: String Error messages from the image processor (if any).

ListFiles function

Name	wsListFiles
Description	Returns an alphabetically sorted list of files and folders in the specified eRez folder. NOTE: Per convention sub-folders are <b>always</b> placed at the beginning of the array.
Required Permissions	List permission for source folder.
Input	Name	Type	Description
wsListFilesRequest	handle	String	Login handle as returned by the Login function.
	source	String	Path to the eRez folder.
	filter	Boolean	If set to true the eRez server will filter out unsupported file types. Otherwise all files are returned in the list.
Output	Name	Type	Description
wsListFilesResponse	result	Array Of FileInfo	The FileInfo structure contains the following fields: filename : String. The name of the file or directory. modTime : Long The time and date the file was last modified as milliseconds since January 1 1970. isDirectory : Boolean True if the element is a directory. fileSize : Long The size of the file in bytes.

Login function

Name	wsLogin
Description	Log onto the server using a login and password.
Required Permissions	None
Input	Name	Type	Description
wsLoginRequest	login	String	User’s login
	password	String	User’s password
Output	Name	Type	Description
wsLoginResponse	handle	String	A unique hard-to-fake handle used to authorize subsequent calls.

Logout function

Name	wsLogout
Description	Log out from the server and invalidate the handle.
Required Permissions	None
Input	Name	Type	Description
wsLogoutRequest	handle	String	Login handle as returned by the Login function.
Output	Name	Type	Description
wsLogoutResponse			(empty)

Search function

Name	wsSearch
Description	Returns list of files matching the query sorted by relevance.
Required Permissions	List permission for source folder.
Input	Name	Type	Description
wsSearchRequest	handle	String	Login handle as returned by the Login function.
	query	String	Path to the eRez folder.
	maxhits	Int	The maximum number of hits to return.
Output	Name	Type	Description
wsSearchResponse	result	Array Of FileInfo	The FileInfo structure contains the following fields: filename : String. The full path and name of the file. modTime : Long The time and date the file was last modified as milliseconds since January 1 1970. isDirectory : Boolean Always False. fileSize : Long The size of the file in bytes.

StoreSelection function

Name	wsSearch
Description	Stores a list of file path and names as a collection and return the unique ID.
Required Permissions	none
Input	Name	Type	Description
wsStoreSelectionRequest	objects	Array of String	List of paths.
Output	Name	Type	Description
wsStoreSelectionResponse	result	String	Unique ID of the stored collection.