Upload

You can upload a stream or text to a content binary field (e.g. a file) with the action named Upload. An upload request is actually two requests, one for creating a new content in the repository and one for fill its Binary field with the stream or text. The upload requests should have a bunch of required and optional parameters in their body, let's see them one by one.

name
create	URL parameter, required in the first request	this parameter should be added to the initial upload request
ContentType	string, optional	specific content type name for the uploaded content. If not provided, the system will try to determine it from the current environment: the upload content types configured in the web.config and the allowed content types in the particular folder. In most cases, this will be File.
FileName	string, required	name of the uploaded file.
Overwrite	boolean, optional, default value is `True`	determines whether the upload action should overwrite a content if it already exist with the same name. If false, a new file will be created with a similar name containing an incremental number (e.g. sample(2).docx).
UseChunk	boolean, optional, used in the first request, default is `False`	determines whether the system should start a chunk upload process instead of saving the file in one round. Usually this is determined by the size of the file.
PropertyName	string, optional, default value is 'Binary'	appoints the binary field of the content where the data should be saved.
ChunkToken	string, required only in the second request	the response of the first request returns this token. It must be posted in all of the subsequent requests without modification. It is used for executing the chunk upload operation.
FileText	string, optional	in case you do not have the file as a real file in the file system but a text in the browser, you can provide the raw text in this parameter.

Initial request

The first request is a create request that tells the system whether it should create a new file or use an existing one, and whether it should start a chunk upload process or not. The latter means if you want to upload the binary of a file in more parts - usually if the file is bigger than a configured value.

Subsequent requests

The first request returns an upload token that contains essential information for the upload process. You have to pass this data to subsequent requests without modification. If you declared in the first request that this will be a chunk upload, you have to specify the offset (Content-Range header) and the actual binary chunk in subsequent requests - otherwise you'll post the whole file in one round.

Content versioning

Depending on the versioning mode in the particular folder or list where you want to upload files and the actual state of existing files, the versioning behavior of the uploaded files can be different. The following sections describe whether new versions will be created or not for the uploaded files if they already exist. In case of new files there is not much to tell: the file will be created with the default version number determined by the versioning and approving settings (0.1 draft or 1.0 approved, etc.).

No versioning : If the file already exists, it will be overwritten - except if it is stated otherwise using the Overwrite parameter of the first request.
Major versioning: If the file already exists, a new version will be created with the next major number - or, if the Overwrite parameter was false, a completely new file with a similar name.
Major and minor versioning: A new minor version will be created - again, you can modify this behavior using the Overwrite parameter.

If the existing content is checked out by the current user, that version will be overwritten by the uploaded file and you will have to check in the file manually to make it accessible for others. If the content is checked out by another user, the file will not be uploaded.

Upload a file

The next example shows how to upload a file in two steps with two requests. The first response will be 5062*3196*True (or similar). This value must be passed to the second requests ChunkToken.

Copy

POST https://example.com/OData.svc/Root/Content('Documents')/Upload

-----------------------------8dc86bc2e2dc8b5
Content-Type: text/plain; charset=utf-8
Content-Disposition: form-data; name=FileName

MyFile.txt
-----------------------------8dc86bc2e2dc8b5
Content-Type: text/plain; charset=utf-8
Content-Disposition: form-data; name=ContentType

File
-----------------------------8dc86bc2e2dc8b5
Content-Type: text/plain; charset=utf-8
Content-Disposition: form-data; name=PropertyName

Binary
-----------------------------8dc86bc2e2dc8b5
Content-Type: text/plain; charset=utf-8
Content-Disposition: form-data; name=UseChunk

False
-----------------------------8dc86bc2e2dc8b5
Content-Type: text/plain; charset=utf-8
Content-Disposition: form-data; name=Overwrite

True
-----------------------------8dc86bc2e2dc8b5
Content-Type: text/plain; charset=utf-8
Content-Disposition: form-data; name=FileLength

21
-----------------------------8dc86bc2e2dc8b5
Content-Type: text/plain; charset=utf-8
Content-Disposition: form-data; name=ChunkToken

0**True*True
-----------------------------8dc86bc2e2dc8b5
Content-Disposition: form-data; name="files[]"; filename=MyFile.txt; filename*=utf-8''MyFile.txt

Content of MyFile.txt
-----------------------------8dc86bc2e2dc8b5--

Create a file with raw text

Following examples shows how to create a simple text file adding its raw text (this thing could be useful if you are working with text files' (e.g. .json, .txt, .md, .xml) content directly in the browser):

Copy

POST https://example.com/OData.svc/Root/Content('Documents')/Upload?metadata=no

models=[{
  "FileName":"MyFile.txt",
  "ContentType":"File",
  "PropertyName":"Binary",
  "UseChunk":false,
  "Overwrite":true,
  "FileLength":24,
  "FileText":"**** file text data ****"
}]

Update a CTD

Copy

POST https://example.com/OData.svc/Root/System/Schema/ContentTypes('GenericContent')/Upload

-----------------------------8dc86cabae328e4
Content-Type: text/plain; charset=utf-8
Content-Disposition: form-data; name=FileName

MyContentType
-----------------------------8dc86cabae328e4
Content-Type: text/plain; charset=utf-8
Content-Disposition: form-data; name=ContentType

ContentType
-----------------------------8dc86cabae328e4
Content-Type: text/plain; charset=utf-8
Content-Disposition: form-data; name=PropertyName

Binary
-----------------------------8dc86cabae328e4
Content-Type: text/plain; charset=utf-8
Content-Disposition: form-data; name=UseChunk

False
-----------------------------8dc86cabae328e4
Content-Type: text/plain; charset=utf-8
Content-Disposition: form-data; name=Overwrite

True
-----------------------------8dc86cabae328e4
Content-Type: text/plain; charset=utf-8
Content-Disposition: form-data; name=FileLength

476
-----------------------------8dc86cabae328e4
Content-Type: text/plain; charset=utf-8
Content-Disposition: form-data; name=ChunkToken

0**True*True
-----------------------------8dc86cabae328e4
Content-Disposition: form-data; name="files[]"; filename=MyContentType; filename*=utf-8''MyContentType

<?xml version='1.0' encoding='utf-8'?>
<ContentType name="MyContentType" parentType="GenericContent"
      handler="SenseNet.ContentRepository.GenericContent"
      xmlns="http://schemas.sensenet.com/SenseNet/ContentRepository/ContentTypeDefinition">
  <DisplayName>MyContentType</DisplayName>
  <Fields></Fields>
</ContentType>

-----------------------------8dc86cabae328e4--

Update a Settings file

Copy

POST https://example.com/OData.svc/Root/System('Settings')/Upload?metadata=no

models=[{
  "FileName":"MyCustom.settings",
  "ContentType":"Settings",
  "PropertyName":"Binary",
  "UseChunk":false,
  "Overwrite":true,
  "FileLength":13,
  "FileText":"{Key:'Value'}"
}]

Delete

Copy or move