Logo Help Center

Elvis 5 REST API - create

Elvis 5 REST API - create

GET/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 like 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.

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

Info: Requires Elvis 5.5.3 or higher.

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: For Elvis 5.9 and higher, 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./p>

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. The returned JSON has the same format as the hits returned in search results.

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"
}
Was this article helpful?
0 out of 0 found this helpful / Created: / Updated:
Have more questions? Submit a request

5 Comments

  • 0
    Avatar
    Jimmy Bway

    Hi can i have a full example using spring resttemplate ? or apache httpclient ?

  • 0
    Avatar
    Ankita Nalawade225

    could you please explain more on upload file on Elvis from FTP using form or using API or from local

    I have tried all,but its not working.

     

    Edited by Ankita Nalawade225
  • 0
    Avatar
    Erik Korver

    Hi Ankita,

    Please have a look at this article describing the scheduled FTP plugin to have Elvis Import from an FTP server: https://helpcenter.woodwing.com/hc/en-us/articles/202967245

  • 0
    Avatar
    Scott Griswold

    Would it be possible to get an example of what the "Filedata" part of the URL would look like?

    We have been making 0kb placeholders to attach images to after populating the metadata fields. Instead, we would like to place a specific file as the placeholder. Where would this file need to be in order to target it with the URL?

    Thank you,

    Scott Griswold

  • 0
    Avatar
    Nico Krijnen

    Hi Scott,

    Creating placeholders can indeed be done with just parameters in the URL. For uploading an actual file, that won't work. The "Filedata" can not be used as part of the URL in a GET request. It can only be sent as part of the POST body by doing a multipart/form-data POST.

    You can see an example on how to use it from a browser here:

    https://github.com/WoodWing/elvis-API-samples/blob/master/api_samples/upload_portal/upload.html#L163

    For technical details on how that works on HTTP level, see:

    https://stackoverflow.com/questions/8659808/how-does-http-file-upload-work

Please sign in to leave a comment.