Elvis Proxy Server [since 10.5]

A proxy server is added to the Elvis plug-in for Enterprise Server to expose the Elvis Preview API to Enterprise client applications. This is called the Elvis proxy server. The client may request for an Elvis image preview, which then will be proxied to the Elvis Server Preview API. The client may also let the user create a crop of an image, which can be requested through the API as well.

Note - At the time writing this chapter, there are no client applications using the proxy server yet.

Compared with the Transfer Server, using the proxy has the following advantages:

1) ‘Stable’ URLs contain the whole preview/crop download definition, so they never have to be adjusted e.g. to be used in another context. Authorization is done through HTTP headers, to exclude access tokens or tickets from the URL, which may vary per user session or client application.

The responsibilities of the proxy server are:

The Elvis proxy server is shipped with the Elvis server plug-in for Enterprise Server. This plug-in must be activated to be able to use the proxy. The proxy accepts a HTTP GET request and composes a REST request for Elvis Server. The response is streamed back to the caller. The proxy talks to the Elvis Server that is configured with the ELVIS_URL option in the Enterprise/config/config_elvis.php file.

Web service integration

This paragraph describes how a client application could integrate with the proxy.

Determine the proxy base URL

When the client does support the Elvis proxy, it should first check the FeatureSet in the LogOnResponse:

<LogOnResponse>
    ...
    <FeatureSet>
        <Feature>
            <Key>ContentSourceProxyLinks_ELVIS</Key>
            <Value>http://localhost/Enterprise/server/plugins/Elvis/restproxyindex.php</Value>
        </Feature>
    </FeatureSet>
    ...
</LogOnResponse>

If the ContentSourceProxyLinks_ELVIS feature is found, the client may assume the Elvis plug-in is activated. Else, it is deactivated and the proxy should not be used.

The feature value provides the entry point of the proxy. This should be used by the client as a base URL to compose requests for the proxy.

Request for preview

For example, when the user clicks an image listed in the search results, the client requests for a preview as usual, but now it indicates that it supports the proxy by providing the ContentSourceProxyLinks_ELVIS item in the RequestInfo:

<GetObjects>
    ...
    <IDs>
        <String>123</String>
    </IDs>
    <Lock>false</Lock>
    <Rendition>preview</Rendition>
    <RequestInfo>
        <String>ContentSourceProxyLinks_ELVIS</String>
    </RequestInfo>
    ...
</GetObjects>

When the image is stored in Elvis, Enterprise provides the download URL as follows:

<GetObjectsResponse>
    ...
    <Objects>
        <Object>
            <MetaData>
                <BasicMetaData>
                    <ID>123</ID>
                    ...
                    <ContentSource>ELVIS</ContentSource>
                    ...
                </BasicMetaData>
                ...
            </MetaData>
            ...
            <Files>
                <Attachment>
                    ...
                    <FileUrl xsi:nil="true"/>
                    ...
                    <ContentSourceFileLink xsi:nil="true"/>
                    <ContentSourceProxyLink>http://localhost/Enterprise/server/plugins/Elvis/restproxyindex.php?...</ContentSourceProxyLink>
                    ...
                </Attachment>
            </Files>
        </Object>
    </Objects>
</GetObjectsResponse>

When the client application is migrating ContentSourceFileLink to ContentSourceProxyLink_ELVIS and finds both options in the LogOnResponse, it should provide only the ContentSourceProxyLink_ELVIS option in RequestInfo of the GetObjects request.

Proxy API

This paragraph describes the API provided by Elvis proxy server.

Request parameters

Parameter Meaning
ticket [Optional] The Enterprise ticket obtained through the LogOn service response. Either the ticket or the ww-app parameter is required. When the client does not support cookies, this parameter can be used, but since the ticket often changes, the URLs won’t be ‘stable’ 1).
ww-app [Optional] The client application name that was provided in the LogOn service request. Either the ticket or the ww-app parameter is required. This parameter can be used instead of the ‘ticket’ parameter to have ‘stable’ URLs 1). Note that when the client does not run in a web browser it should round-trip web cookies by itself.
objectid [Required] The ID of the workflow object in Enterprise. The object may reside in workflow or trash can.
rendition [Required] The file rendition to download. Supported values: ‘native’, ‘preview’ or ‘thumb’.
preview-args [Optional] The preview- or cropping dimensions. See Elvis Preview API for details.

1) ‘Stable’ URLs have the following advantages:

HTTP return codes

The following HTTP codes may be returned:

Preview example

When the Foo Bar client wants an Elvis image preview for object id 123, the proxy can be called as follows:

http://localhost/Enterprise/server/plugins/Elvis/restproxyindex.php?ww-app=Foo%20Bar&objectid=123&rendition=preview&preview-args=maxWidth_600_maxHeight_400.jpg

The proxy will then resolve the Elvis Server URL, resolve the asset id from the object id and authorise the connection with Elvis credentials. In the example, the URL could be composed as follows:

http://localhost:18800/preview/6uk-q7GeKiD9yTAgKPsu6F/previews/maxWidth_600_maxHeight_400.jpg

In this example the Enterprise object id 123 is a shadow object for Elvis asset id 6uk-q7GeKiD9yTAgKPsu6F.

Crop example

When the Foo Bar client wants an Elvis image crop for object id 123, the proxy can be called as follows:

http://localhost/Enterprise/server/plugins/Elvis/restproxyindex.php?ww-app=Foo%20Bar&objectid=123&rendition=preview&preview-args=cropWidth_590_cropHeight_390_cropOffsetX_10_cropOffsetY_10.jpg

In this example, the result is the same as for the preview example above, but now a border of 10 pixels is removed (cropped).