README

Installation

Laravel 5.X

Step 1

Add the package to your composer.json and run composer update.

{
    "require": {
        "lasselehtinen/elvis": "3.0.0"
    }
}

Step 2

Add the service provider and alias in config/app.php:

'providers' => array(
    ...
    Lasselehtinen\Elvis\ElvisServiceProvider::class
),

Step 3

Publish the package config file by running:

php artisan vendor:publish

This copies the Elvis config to config/Elvis.php and references to the .env configuration file used by Laravel 5. So edit the .env file and add the following entries:

ELVIS_API_ENDPOINT_URI='http://elvis.domain.com/services/',
ELVIS_USERNAME='elvis_username',
ELVIS_PASSWORD='elvis_password'

Laravel 4.X

Step 1

Add the package to your composer.json and run composer update.

{
    "require": {
        "lasselehtinen/elvis": "1.0.1"
    }
}

Step 2

Add the service provider and alias in app/config/app.php:

'providers' => array(
    ...
    'Lasselehtinen\Elvis\ElvisServiceProvider'
),

And

'aliases' => array(
    ...
    'Elvis'           => 'Lasselehtinen\Elvis\Facades\Elvis'
),

Step 3

Publish the package config file by running:

php artisan config:publish lasselehtinen/elvis

Edit your app/config/packages/lasselehtinen/elvis/config.php and change the default Elvis REST API endpoint URI and the username and password.

Usage

List of supported functions

Login
Browse
Search
Profile
Create
Update
Updatebulk
Move / rename
Copy
Remove
Create folder
Create relation
Remove relation
Log usage stats
Messages / Localization
Checkout
Undocheckout
CreateAuthKey
UpdateAuthKey
RevokeAuthKeys
Logout

Login

You need to login as the first step. Store the CSRF token returned by the function and pass it to further requests.

$token = Elvis::login();
$search_results = Elvis::search($token, 'gtin:9789510123454');

This call is designed to allow you to browse folders and show their subfolders and collections, similar to how folder browsing works in the Elvis desktop client. Read more at https://helpcenter.woodwing.com/hc/en-us/sections/200449479-API.

Note: Even though it is possible to return the assets in folders, doing so is not advised. The browse call does not limit the number of results, so if there are 10000 assets in a folder it will return all of them. It is better to use a search to find the assets in a folder and fetch them in pages.

$browse_results = Elvis::browse($token, '/Folder/');

Parameter	Description
token	CSRF token returned by the login function.
path	The path to the folder in Elvis you want to list. Path is automatically encoded.
fromRoot	Allows returning multiple levels of folders with their children. When specified, this path is listed, and all folders below it up to the 'path' will have their children returned as well. This ability can be used to initialize an initial path in a column tree folder browser with one server call.
includeFolders	Indicates if folders should be returned.
includeAsset	Indicates if files should be returned.
includeExtensions	A comma separated list of file extensions to be returned. Specify 'all' to return all file types.

Search

Wrapper for the search API, returns the hits found. You can find more information at https://helpcenter.woodwing.com/hc/en-us/articles/202967175-REST-search. You can find details about the function parameters below.

Simple search:

$search_results = Elvis::search($token, 'gtin:9789510123454');

Parameter	Description
token	CSRF token returned by the login function.
query	Actual Lucene query, you can find more details in https://helpcenter.woodwing.com/hc/en-us/articles/202249409-Query-syntax
start	First hit to be returned. Starting at 0 for the first hit. Used to skip hits to return 'paged' results. Default is 0.
num	Number of hits to return. Specify 0 to return no hits, this can be useful if you only want to fetch facets data. Default is 50.
sort	The sort order of returned hits. Comma-delimited list of fields to sort on. Read more at https://helpcenter.woodwing.com/hc/en-us/articles/202967175-REST-search
metadataToReturn	Comma-delimited list of metadata fields to return in hits. It is good practice to always specify just the metadata fields that you need. This will make the searches faster because less data needs to be transferred over the network. Read more at https://helpcenter.woodwing.com/hc/en-us/articles/202967175-REST-search
appendRequestSecret	When set to true will append an encrypted code to the thumbnail, preview and original URLs.
facetsToReturn	Comma-delimited list fields to return facets for.
facetSelection	Array of facets and values with the facet as the key and the comma-delimited list of values that should be 'selected' for a given facet as the value. For example ['tags' => 'beach,ball', 'assetDomain' => 'image,video'].

Profile

Retrieve details about the authenticated user.

$profile = Elvis::profile($token);

Create

This call will create a new asset in Elvis. It can be used to upload files into Elvis. It can also be used to create 'virtual' assets like collections. In that case no file has to be uploaded and Elvis will create a 0 kb placeholder for the virtual asset. Read more at https://helpcenter.woodwing.com/hc/en-us/articles/202967215-REST-create.

Note: Either assetPath, filename or name as to be specified in the metadata.

$create = Elvis::create($token, './file.txt', array('assetPath' => '/Users/demouser/filename.txt'));

Parameter	Description
token	CSRF token returned by the login function.
filename	The local filename to be created in Elvis. If you do not specify a filename explicitly through the metadata, the filename of the uploaded file will be used. Please note that in this case, you give the local filepath as a parameter. The wrapper will then convert it multipart/file.
metadata	Array containing the metadata for the asset as an array. Key is the metadata field name and value is the actual value.

Update

This call updates an existing asset in Elvis with a new file. It can also be used to update metadata. Works pretty much the same ways a create. Only difference is that you given additional parameter, the asset id. Read more at https://helpcenter.woodwing.com/hc/en-us/articles/202250049-REST-update.

$update = Elvis::update($token, '1_OSDdstqxbACb97Vd-ret', null, array('Description' => 'Nice view'));

Parameter	Description
sessionId	Session ID returned by the login function. This is used for further queries towards Elvis
asset_id	Elvis asset id to be updated
filename	The file that will replace the current file. Define as null if you just want to update metadata.
metadata	Array containing the metadata for the asset as an array. Key is the metadata field name and value is the actual value.

Updatebulk

This call updates the metadata of multiple existing assets in Elvis.

Available since Elvis 3.1

$updatebulk = Elvis::updatebulk($token, 'tags:animal', array('status' => 'Correction'));

Parameter	Description
sessionId	Session ID returned by the login function. This is used for further queries towards Elvis
q	A query matching the assets that should be updated
metadata	Array containing the metadata for the assets as an array. Key is the metadata field name and value is the actual value.
async	When true, the process will run asynchronous in the background. The call will return immediate with the processId. By default, the call waits for the process to finish and then returns the processedCount.

Returns either processedCount or processId depending on the value of async.

Move / rename

Move or rename a folder or a single asset. You can combine a rename operation and a move operation. Just specify the new target path.

When you move or rename a folder, all assets contained in the folder will also be moved to the new location. The subfolder structure will be kept intact.

$rename = Elvis::move($token, '/Path/to/asset/filename.ext', '/Path/to/asset/new-filename.ext');

Parameter	Description
sessionId	Session ID returned by the login function. This is used for further queries towards Elvis
source	Either a folderPath or assetPath of the folder or asset to be moved or renamed.
target	The folderPath or assetPath to which the folder or asset should be moved or renamed. If the parent folder is the same as in the source path, the asset will be renamed, otherwise it will be moved.)
folderReplacePolicy	Policy used when destination folder already exists. Aither AUTO_RENAME (default), MERGE or THROW_EXCEPTION.
fileReplacePolicy	Policy used when destination asset already exists. Either AUTO_RENAME (default), OVERWRITE, OVERWRITE_IF_NEWER, REMOVE_SOURCE, THROW_EXCEPTION or DO_NOTHING
filterQuery	When specified, only source assets that match this query will be moved.
flattenFolders	When set to true will move all files from source subfolders to directly below the target folder. This will 'flatten' any subfolder structure.

Please see https://helpcenter.woodwing.com/hc/en-us/articles/202967265-REST-move-rename for more information about the folderReplacePolicy and fileReplacePolicy.

Copy

Copy a folder or a single asset.

When you copy a folder, all subfolders and assets contained in it will also be copied to the new location. The subfolder structure will be kept intact unless you set flattenFolder to true.

$copy = Elvis::copy($token, '/Path/to/asset/filename.ext', '/Path/to/asset/copy-filename.ext');

Parameter	Description
sessionId	Session ID returned by the login function. This is used for further queries towards Elvis
source	Either a folderPath or assetPath of the folder or asset to be moved or renamed.
target	The folderPath or assetPath to which the folder or asset should be moved or renamed. If the parent folder is the same as in the source path, the asset will be renamed, otherwise it will be moved.)
folderReplacePolicy	Policy used when destination folder already exists. Aither AUTO_RENAME (default), MERGE or THROW_EXCEPTION.
fileReplacePolicy	Policy used when destination asset already exists. Either AUTO_RENAME (default), OVERWRITE, OVERWRITE_IF_NEWER, REMOVE_SOURCE, THROW_EXCEPTION or DO_NOTHING
filterQuery	When specified, only source assets that match this query will be moved.
flattenFolders	When set to true will move all files from source subfolders to directly below the target folder. This will 'flatten' any subfolder structure.

Please see https://helpcenter.woodwing.com/hc/en-us/articles/202967305-REST-copy for more information about the folderReplacePolicy and fileReplacePolicy.

Returns either processedCount or processId depending on the value of async.

Remove

Remove one or more assets. This will remove only assets, no folders.

$ids = array('1_OSDdstqxbACb97Vd-ret', '1wefOS6bauK8uRxi0rn9EK');
$remove = Elvis::remove($token, null, $ids, null, false);

Parameter	Description
sessionId	Session ID returned by the login function. This is used for further queries towards Elvis
query	A query that matches all assets to be removed. Be careful with this and make sure you test your query using a search call to prevent removing assets that you did not want to be removed.
ids	Array containing the assetId's for the assets to be removed. Be careful with this and make sure you test your query using a search call to prevent removing assets that you did not want to be removed.
folderPath	The folderPath of the folder to remove. All assets and subfolders will be removed.
async	When true, the process will run asynchronous in the background. The call will return immediate with the processId. By default, the call waits for the process to finish and then returns the processedCount.

Either 'q' or 'ids' or 'folderPath' must be specified.

Returns either processedCount or processId depending on the value of async.

Create folder

Remove one or more assets. This will remove only assets, no folders.

$createFolder = Elvis::createFolder($token, '/Users/lasleh/New');

Parameter	Description
sessionId	Session ID returned by the login function. This is used for further queries towards Elvis
path	The full folderPath of the folder to be created.

Returns an object with the olderPaths of each folder as key with the corresponding result as value (always a string). The following results are possible:

"created"
"already exists"
"access denied"
an error message indicating why the folder could not be created

Create relation

Remove one or more assets. This will remove only assets, no folders.

$createRelation = Elvis::createRelation($token, 'contains', 'FWiH0ipWKVl8CkbFGm9me9', 'CFN7pN2S4GFBz4Vorc34VJ');

Parameter	Description
sessionId	Session ID returned by the login function. This is used for further queries towards Elvis
relationType	The type of relation to create. Read more at https://helpcenter.woodwing.com/hc/en-us/articles/202966905-Relations
target1Id	The id of the asset on one side of the relation.
target2Id	The id of the asset on one side of the relation.
metadata	A JSON encoded object with properties that match Elvis relation metadata field names. This metadata will be set on the relation in Elvis.

The operation returns an empty 200 OK status. If the operation fails, an error page with a 500 error status will be returned.

Remove relation

Remove one or more relations between assets.

$removeRelation = Elvis::removeRelation($token, ['77-nZwDXaTJ96lhhaDvp0t']);

Parameter	Description
sessionId	Session ID returned by the login function. This is used for further queries towards Elvis
relationIds	Array containing relation id's to be removed. To find the relation ids, use a relation search. https://helpcenter.woodwing.com/hc/en-us/articles/202967175-REST-search

The operation returns an empty 200 OK status.

If the operation fails, an error page with a 500 error status will be returned.

Log usage stats

Logs an entry in the stats database for usage statistics about assets. A record will be added to the "usage_log" table, see Query stats for details.

$logUsage = Elvis::logUsage($token, 'FWiH0ipWKVl8CkbFGm9me9', 'CUSTOM_ACTION_test', array('metadataKey'=>'value'));

Parameter	Description
sessionId	Session ID returned by the login function. This is used for further queries towards Elvis
assetId	The id of the asset for which the action is logged.
action	Name of the action that is logged. This must start with "CUSTOM_ACTION_", if it does not, this prefix will be added to the logged action name.
additionalQueryParameters	Array of additional query parameters that are logged as details for the action.

This call does not return a value, it only returns an http 200 status OK.

Messages / Localization

Retrieve message bundles from the Elvis server.

Allows localization of a custom plugin using messages available on the server. The messages from the webclient web or desktop client acm can be used in your own plugin. It is also possible to use any custom messages defined in the Config/messages folder.

The common message bundle cmn is always returned and merged with the requested bundle. The common bundle contains messages for relations, metadata fields, metadata groups and metadata values. The common message keys have the following structure:

Relations:

relation.[relation type].label

Metadata fields:

field_label.[field name]

Metadata groups:

field_group_label.[group name]

Metadata values:

field_value_label.[field name].[value]

For a full list of available messages see this knowledge base article.

 $messages = Elvis::messages($token, 'fi_FI');

Parameter	Description
sessionId	Session ID returned by the login function. This is used for further queries towards Elvis
localChain	Array containing list of locales, the first supplied locale is leading. If a message is missing for a locale it will fall back to the next locale in the chain for that message.
ifModifiedSince	The date of the last requested cached messages, specified in milliseconds since the standard base time known as "the epoch", namely January 1, 1970, 00:00:00 GMT.
bundle	The bundle to return, can be either web or acm. The cmn bundle will always be returned combined with the requested bundle.

The service returns an object containing all keys and messages. Please note that commas in object properties have to be referenced like this:

$messages->{'field_label.creatorEmail'}

Checkout

Checks out an asset from the system locking the file for other users.

$checkout= Elvis::checkout($token, $assetId);

Parameter	Description
sessionId	Session ID returned by the login function.
assetId	The Elvis id of the asset to be checked out.

This will return the checkout metadata in the response as an object.

Undocheckout

Undo a checkout for a single asset

$checkout = Elvis::undocheckout($token, $assetId);

Parameter	Description
sessionId	Session ID returned by the login function.
assetId	Elvis id of the asset that was checked out.

CreateAuthKey

Create an authKey in Elvis.

$createAuthKey = Elvis::createAuthKey($token, 'Test', '2999-01-01', array($assetId));

Parameter	Description
sessionId	Session ID returned by the login function.
subject	AuthKey subject
validUntil	Expiry date, in one of the date formats supported by Elvis. See https://helpcenter.woodwing.com/hc/en-us/articles/202249409-Query-syntax for more details
assetIds	Array of of asset id's to share, do not specify for a pure upload request (requestUpload must be true is this case)
description	AuthKey description that will be shown to receiver of the link.
downloadOriginal	Allow downloading original files. Setting this to true will automatically force downloadPreview to true as well.
downloadPreview	Allow viewing and downloading previews. Setting this to false will only show thumbnails and will also force downloadOriginal to false.
requestApproval	Request for approval.
requestUpload	Allow uploading new files, must be true when asset id's is not specified.
containerId	Container asset id which uploaded files are related to. Only relevant when requestUpload=true.
importFolderPath	folderPath where files are uploaded. Required when requestUpload=true.
notifyEmail	Email address to send notifications to when upload or approval is finished. Only relevant when requestUpload=true or requestApproval=true.
sort	Client setting, specify a comma-delimited list of fields to sort the results on. Follows the same behavior as sort in REST - search call
viewMode	Client setting. Possible values 'thumbnail', 'list' or 'mason'.
thumbnailFields	Client setting, array containing list of fieldnames for showing metadata in the thumbnail view.
listviewFields	Client setting, array containing list of fieldnames for showing metadata in the list view.
filmstripFields	Client setting, array containing list of fieldnames for showing metadata in the filmstrip view.
thumbnailZoomLevel	Client setting, thumbnail zoom level in the thumbnail view.
listviewZoomLevel	Client setting, thumbnail zoom level in the list view.
filmstripZoomLevel	Client setting, thumbnail zoom level in the filmstrip view.

Returns object containing the authKey and links to different clients.

UpdateAuthKey

Update an authKey in Elvis.

With this API call it is possible to update certain properties of an authKey. Please note that it is not possible to add or remove assets from an authKey once it has been created.

$updateAuthKey = Elvis::updateAuthKey($token, $authKey, 'Test', '2999-02-02');

Parameter	Description
sessionId	Session ID returned by the login function.
key	The authKey which will be updated.
subject	AuthKey subject
validUntil	Expiry date, in one of the date formats supported by Elvis. See https://helpcenter.woodwing.com/hc/en-us/articles/202249409-Query-syntax for more details
description	AuthKey description that will be shown to receiver of the link.
downloadOriginal	Allow downloading original files. Setting this to true will automatically force downloadPreview to true as well.
downloadPreview	Allow viewing and downloading previews. Setting this to false will only show thumbnails and will also force downloadOriginal to false.
requestApproval	Request for approval.
requestUpload	Allow uploading new files, must be true when asset id's is not specified.
containerId	Container asset id which uploaded files are related to. Only relevant when requestUpload=true.
importFolderPath	folderPath where files are uploaded. Required when requestUpload=true.
notifyEmail	Email address to send notifications to when upload or approval is finished. Only relevant when requestUpload=true or requestApproval=true.
sort	Client setting, specify a comma-delimited list of fields to sort the results on. Follows the same behavior as sort in REST - search call
viewMode	Client setting. Possible values 'thumbnail', 'list' or 'mason'.
thumbnailFields	Client setting, array containing list of fieldnames for showing metadata in the thumbnail view.
listviewFields	Client setting, array containing list of fieldnames for showing metadata in the list view.
filmstripFields	Client setting, array containing list of fieldnames for showing metadata in the filmstrip view.
thumbnailZoomLevel	Client setting, thumbnail zoom level in the thumbnail view.
listviewZoomLevel	Client setting, thumbnail zoom level in the list view.
filmstripZoomLevel	Client setting, thumbnail zoom level in the filmstrip view.

Returns object containing the authKey and links to different clients.

RevokeAuthKeys

Create an authKey in Elvis.

$revokeAuthKeys = Elvis::revokeAuthKeys($token, array($assetId));

Parameter	Description
sessionId	Session ID returned by the login function.
keys	list of authKeys.

Returns an empty object if succesfull.

Logout

It is a good practice to close the session after you are done with your queries so it doesn't take API licences unnecessarily. You can use logout for this.

$logout = Elvis::logout($token);

Parameter	Description
sessionId	Session ID returned by the login function.

lasselehtinen / elvis

Maintainers

Details

README

Installation

Laravel 5.X

Step 1

Step 2

Step 3

Laravel 4.X

Step 1

Step 2

Step 3

Usage

List of supported functions

Login

Browse

Search

Profile

Create

Update

Updatebulk

Move / rename

Copy

Remove

Create folder

Create relation

Remove relation

Log usage stats

Messages / Localization

Checkout

Undocheckout

CreateAuthKey

UpdateAuthKey

RevokeAuthKeys

Logout