|
POST http://yourserver.com/services/create
?Filedata=<multipart/form-data encoded file>
&metadata=<JSON encoded metadata>
&<Elvis metadata field name>=<value>
&metadataToReturn=<comma-delimited fields>
&nextUrl=<next URL>
|
What does it do?
Upload and create an asset.
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 such as Collections. In that case no file has to be uploaded and Elvis will create a 0 kb placeholder for the virtual asset.
When you want to create a new asset, certain metadata is required. The metadata is needed to determine where the file will be stored in Elvis.
Tip: The create service behaves almost identical to the update service. The update service has an additional 'id' parameter to specify the asset that should be updated.
|
Note: The Create call automatically renames a file when not explicitly passing a name as metadata. Background info: While the Create service does not support the FileReplacePolicy, it does allow the autoRename argument (with True as the default). When passing 'name' or 'filename' as metadata to give the new file a custom name, and this name conflicts with an existing file, the PathAlreadyExistsException is still in effect. As a work-around, a custom 'name' can be passed within the file object in the Post fields. When this name conflicts, the autoRename is activated (but not if explicitly passing name as part of the metadata). |
POST requests only
This REST API only accepts POST requests, not GET requests. Also, the POST request needs to include a cross-site request forgery (csrf) token.
The csrf token is a unique code which, by including it in the request, also makes the POST request unique and therefore much more secure.
The csrf token is obtained by first logging in to Elvis Server through a POST request. The response that is received will include the csrf token which can then be used in subsequent POST requests as a http header:
"X-CSRF-TOKEN: <some_csrf_token>"For more information including examples, see Elvis 6 REST API - Performing a POST request with a csrf token.
Parameters
| Filedata |
The file 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. The parameter is named "Filedata" because that is the standard name used by flash uploads. This makes it easy to use flash uploaders to upload batches of files to Elvis. Optional. If omitted, a 0kb placeholder file will be created. |
| metadata |
A JSON encoded object with properties that match Elvis metadata field names. This metadata will be set on the asset in Elvis. Optional. You can also use parameters matching Elvis field names. |
|
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. metadataToReturn=name,rating,assetCreated Specify "all", or omit to return all available metadata. metadataToReturn=all Leave 'empty' to return only minimal fields metadataToReturn= Optional. Default returns all fields. |
| * |
Any parameter matching an Elvis metadata field name will be used as metadata. This metadata will be set on the asset in Elvis. Optional. You also use the 'metadata' parameter. |
| nextUrl |
When specified, the service will send a 301 redirect to this URL when it is completed successfully. If you place '${id}' in the URL, it will be replaced with the Elvis asset id of the created asset. Optional. If omitted, a simple 200 OK status code will be returned. Note: This must be a relative URL on the same domain as the Elvis server. If you do specify an absolute URL with a domain, only the part of the URL after the domain will be used to redirect to. |
Return value
Depending if a nextUrl is specified, this service will either send a 301 redirect, or return a JSON response with a hit containing all info and metadata about the created asset.
If the operation fails, an error page with a 500 error status will be returned.
Examples
Upload form
This simple HTML form uploads a file into Elvis, into the folder /Upload Zone:
<form action="http://demo.elvisdam.com/services/create"
method="post" enctype="multipart/form-data">
<input type="hidden" name="nextUrl" value="...mypage.html#${id}">
<input type="hidden" name="folderPath" value="/Upload Zone">
<label for="file">File </label>
<input type="file" name="Filedata" id="file">
<br><br>
<input type="submit" value="Create">
</form>Tip: The auto-organize mechanism will put the file into /Upload Zone/Auto organized/(year)/(date) to keep the top-level folder organized.
Creating collections
The following call creates a new empty collection in /Demo Zone/Collections:
|
create http://demo.elvisdam.com/services/create
?folderPath=/Demo Zone/Collections
&assetType=collection
&name=My Collection
|
As you can see the location of the asset is specified using several metadata fields. If you want to specify this with one field, use the assetPath field, which contains the complete path including the filename:
|
create http://demo.elvisdam.com/services/create
?assetPath=/Demo Zone/Collections/My Collection.collection
|
The JSON result returned by the service has the following format and information. If you upload a real file, like an image instead of creating a virtual asset like the collection above, the result will also have thumbnail and preview URLs:
{
"permissions" : "VPUMECD",
"id" : "0pBENZZH4ro9pRuHSAAlYr",
"metadata" : {
"assetPath" : "/Demo Zone/Collections/My Collection.collection",
"assetCreator" : "admin",
"folderPath" : "/Demo Zone/Collections",
"assetModified" : {
"value" : 1297422957338,
"formatted" : "2011-02-11 12:15:57 +0100"
},
"metadataComplete" : "true",
"assetCreated" : {
"value" : 1297422957338,
"formatted" : "2011-02-11 12:15:57 +0100"
},
"extension" : "collection",
"assetModifier" : "admin",
"assetType" : "collection",
"name" : "My Collection",
"assetRevision" : 1,
"filename" : "My Collection.collection",
"assetDomain" : "container"
},
"thumbnailHits" : [ ],
"originalUrl" : "http://localhost:8080/controller/file/Demo%20Zone/Collections/My%20Collection.collection"
}
Comment
Do you have corrections or additional information about this article? Leave a comment! Do you have a question about what is described in this article? Please contact Support.
5 comments
For additional information about controlling the user name that is set as the creator/importer, see the Feedback Forum.
It would be great if the create service supported fileReplacePolicy parameter like the copy service does. As is, if creating a file at a path that already exists you get:
[errorname] => PathAlreadyExistsException
Hi Craig,
This would require a change to the API. Please post your idea in the Assets Feedback Forum. There more people can join the conversation.
It was brought to my attention by WoodWing Support that while the create service does not support the FileReplacePolicy, it does allow the autoRename argument (and true seems to be the default).
In some testing I have found that if you are passing 'name' or 'filename' as metadata to give a custom name to the new file, and this name conflicts with an existing file then you still get the PathAlreadyExistsException. As a work-around you can pass a custom 'name' within the file object in the post fields - if this name conflicts then autoRename kicks in (but not if explicitly passing name as part of the Assets metadata). Took me a while to figure this out so thought I would post here in case someone else is trying something similar.
TL;DR- create will auto-rename as long as you are not explicitly passing a name as Assets metadata.
Hi Craig,
Thanks for adding this additional information. I have used it to update the main article to give this scenario some more attention.
Best regards,
Maarten van Kleinwee
Senior Technical Writer, WoodWing Software
Please sign in to leave a comment.