eRez Imaging Server 4.0

SOAP Reference

31-may-2007

 

Copyright 2001-2007 YaWah.com. All Rights Reserved

 

 

Contents

 

Contents. 1

What is SOAP. 2

What can the eRez SOAP interface do?. 2

Installation and system requirements. 2

Permissions. 3

Function Reference. 4

AddJob2 function. 4

AddJob function. 5

FileCopy function. 5

FileDelete function. 5

FileGetIPTC function. 7

FileGetXMP function. 7

FileInfo function. 7

FileMove function. 8

FileUpdateIPTC function. 9

FileUpdateXMP function. 9

GetExtension function. 9

GetJobStatus function. 10

ListFiles function. 11

Login function. 12

Logout function. 12

Search function. 12

StoreSelection function. 14

 


What is SOAP

 

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:

  1. Waiting in Queue.
  2. Image is being processed.
  3. Image is being packed for transmission.
  4. Package complete and ready for download.
  5. Job failed.
  6. Job cancelled by the user.
  7. Insufficient source image data. Must prompt user for action.
  8. 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.