Content-Upload APIs

Owned by BrightSign TechDocs
Last updated: Jun 28, 2023
13 min read

 

Content Upload methods use a separate SOAP endpoint from all other Web API methods. To upload a file, the client must first call StartFileUpload(), then call AppendChunk() one or more times, then call CompleteFileUpload(). It is also possible to upload multiple associated webpage asset files using a session token provided by the StartWebPageUploadSession() method. The workflow for uploading webpage assets is outlined in the following section. 

The Content Upload service allows uploading files using multiple threads in parallel. To use multi-threading, the client must first call StartFileUpload() and obtain an upload token. The client then uploads chunks in multiple threads (using AppendChunk() with different parameters), specifying the partNumber int and offset for each thread along with the same upload token. After the chunks are uploaded, the client must call CompleteFileUpload(). The client may also upload several different files while at the same time specifying different upload tokens.

Web Page Upload Work Flow

  1. Call StartWebPageUploadSession() using parameters for the webpage file and associated content files. Retrieve the initialized session and upload tokens from the WebPageUploadStatus return.

  2. Call StartFileUpload() using parameters for the webpage file, as well as the session token and primary upload token from the WebPageUploadStatus return. Make sure to specify the ContentType enum as "Webpage".

  3. Call AppendChunk() for the number of times needed to complete the webpage file upload. Use the session token and primary upload token from the WebPageUploadStatus return.

  4. Call CompleteFileUpload() using the same content upload arguments utilized in Step 2.

  5. Repeat the following steps for each webpage asset file:

    1. Call StartFileUpload() using parameters for the asset file, as well as the session token and asset upload token from the WebPageUploadStatus return.

    2. Call AppendChunk() for the number of times needed to complete the asset file upload. Use the session token and asset upload token from the WebPageUploadStatus return.

    3. Call CompleteFileUpload() using the same content upload arguments utilized in Step 5a.

  6. Call CompleteWebPageUploadSession() using the same content upload arguments utilized in Step 1.

Web Page Update Work Flow

Orphaned web assets are marked for deletion after 24 hours.

  1. Call StartWebPageUploadSession() using an existing WebPageId string parameter and arguments for the new webpage file. Retrieve the initialized session and upload tokens from the WebPageUploadStatus return.

  2. Call StartFileUpload() using parameters for the new webpage file, as well as the session and upload tokens from the WebPageUploadStatus return. You will also need to specify the ContentId string (which is the same as the WebPageId string) of the webpage file to update. Ensure the ContentType enum is specified as “Webpage”.

  3. Call AppendChunk() for the number of times needed to complete the webpage file upload. Use the session token and primary upload token from the WebPageUploadStatus return. Note that when updating a webpage, the main HTML file must always be updated (even if changes are only being made to asset files).

  4. Call CompleteFileUpload() using the same content upload arguments utilized in Step 2.

  5. Repeat the following steps for each webpage asset file:

    1. Call StartFileUpload() using parameters for the asset file, as well as the session token and asset upload token from the WebPageUploadStatus return. The ContentUploadStatus return will contain an optional Content Negotiation response.

    2. If the Content Negotiation status matches the current asset, call CancelFileUpload() using the session and asset upload tokens.

    3. If the Content Negotiation status does not match the current asset:

      1. Call AppendChunk() for the number of times needed to complete the asset file upload. Use the session token and asset upload token from the WebPageUploadStatus return.

      2. Call CompleteFileUpload() using the same content upload arguments utilized in Step 5a.

Content Upload Web Methods

ContentUploadStatus StartFileUpload(string uploadToken, string sessionToken, string filename, long filesize, int chunksCount, enum ContentType, dateTime fileLastModifiedDate, string virtualPath, base64Binary fileThumb, string sha1Hash)

Initializes the content upload process by returning an upload token, which is a descriptor value that is utilized by the AppendChunk() and CompleteFileUpload() methods. This method may also receive an upload token if it is being used to upload a webpage file.

Required Permissions

Content: Upload Content

Parameters

  • uploadToken string: The token of an upload that was initialized by the StartWebPageUploadSession() method. This parameter is only specified if the file being uploaded is a webpage file.

  • sessionToken string: The token of an upload session initialized by the StartWebPageUploadSession() method. This parameter enables uploading of files related to a webpage file; it should only be specified if a webpage file or associated asset file is being uploaded.

  • filename string: The name of the file to be uploaded. A descriptive error will be returned if any of the following conditions occur:

    • This string is empty.

    • The string has more than 128 characters.

    • The file name is not valid.

  • filesize long: The size of the file in bytes. This parameter must be an unsigned integer value no greater than 5000000000 (i.e. 5GB). A descriptive error will be returned if the value is negative.

  • chunksCount int: The number of chunks the file consists of (starting at 1). The optimal chunk size is 256KiB. Files that are larger than this chunk size must be split into smaller parts by the client. Multiple chunks should be uploaded using multiple AppendChunk() calls specifying the same upload token.

  • contentType enum: Auto, Image, Video, Audio, Webpage: The type of the content file. The default type is “Image”.

  • fileLastModifiedDate DateTime: A value representing the last time the associated file was modified on the user storage (e.g. the "Date modified" value in Windows). This value can also be initialized later by modifying the Content entity.

  • virtualPath string: The path in the BSN Library to which the file should be uploaded (the default is “\Shared\Incoming\”). If the path does not exist, it will be created. It must also contain leading and trailing slashes and be no longer than 128 characters.

  • fileThumb base64Binary: The optional thumbnail data as a binary attachment. This parameter will be generated by the server if it is not specified.

  • sha1Hash string: The SHA1 hash of the current file. The server performs verification of the uploaded file using the specified hash. A descriptive error will be returned if the specified hash does not match the hash value calculated by the server. This parameter is optional; the server-side hash verification process is skipped if this parameter is not specified.

ContentUploadStatus AppendChunk(string uploadToken, int partNumber, binary data, long offset)

Appends chunks onto files that are larger than 256Kib. It returns True if the upload is successful. Otherwise, it returns False.

Required Permissions

Content: Upload Content, Update Content

The Update Content permission is only required if the CompleteFileUpload() is called with a [string]contentId value that corresponds to an existing content entity (i.e. the client is attempting to overwrite a content entity).

Parameters

  • uploadToken string: The token of the upload that was initialized by the StartFileUpload() or StartWebPageUpload() method. A descriptive error is returned if the string value is empty or not specified.

  • sessionToken string: The token of the upload session initialized by the StartWebPageUpload() method. This token should only be provided if the client is uploading a set of webpage assets.

  • partNumber int: The number of the part, starting from 0.

  • data base64Binary: The binary data of the file chunk.

  • offset long: The offset of the current file chunk. The first chunk has an offset of 0. A descriptive error is returned if the offset value is not positive.

ContentUploadStatus CompleteFileUpload(string uploadToken, string sessionToken, string filename, long filesize, int chunksCount, enum ContentType, dateTime fileLastModifiedDate, string virtualPath, base64Binary fileThumb, string sha1Hash)

Returns the Content ID of the uploaded file if file upload is successful. Otherwise, it returns a descriptive error. If a specified parameter is different between the StartFileUpload() and CompleteFileUpload() calls on a file, the specification in the CompleteFileUpload() call will overwrite the original StartFileUpload() specification.

Required Permissions

Content: Upload Content

Parameters

  • uploadToken string: The token of the upload that was initialized by the StartFileUpload() method. A descriptive error is returned if the string value is empty or not specified.

  • sessionToken string: The token of the upload session initialized by the StartWebPageUpload() method. This token should only be provided if the client is uploading a set of webpage assets.

  • filename string: The name of the uploaded file. A descriptive error will be returned if any of the following conditions occur:

    • This string is empty.

    • The string has more than 128 characters.

    • The file name is not valid.

  • filesize long: The size of the video file in bytes. This parameter must be an unsigned integer value no greater than 5000000000 (i.e. 5GB). A descriptive error will be returned if the value is negative.

  • chunksCount int: The number of chunks the file consists of (starting at 1). The optimal chunk size is 256KiB. Files that are larger than this chunk size must be split into smaller parts by the client. Multiple chunks should be uploaded using multiple AppendChunk() calls specifying the same upload token.

  • sha1Hash string: The SHA1 hash of the current file. The server performs verification of the uploaded file using the specified hash. A descriptive error will be returned if the specified hash does not match the hash value calculated by the server. This parameter is optional; the server-side hash verification process is skipped if this parameter is not specified.

  • contentType enum: Auto, Image, Video, Audio, Webpage: The type of the content file. The default type is Image.

  • fileLastModifiedDate DateTime: A value representing the last time the associated file was modified on the user storage (e.g. the "Date modified" value in Windows). This value can also be initialized later by modifying the Content entity.

  • virtualPath string: The path in the BSN Library to which the file should be uploaded (the default is “\Shared\Incoming\”). If the path does not exist, it will be created. It must also contain leading and trailing slashes and be no longer than 128 characters.

  • fileThumb base64Binary: The optional thumbnail data as a binary attachment. This parameter will be generated by the server if it is not specified.

WebPageUploadStatus StartWebPageUploadSession(array webpageAssets[], string uploadToken, string sessionToken, string filename, long filesize, int chunksCount, enum ContentType, string virtualPath, base64Binary fileThumb, string sha1Hash)

Initializes a session for uploading a set of webpage asset files. This method accepts a set of parameters for the HTML file similar to StartFileUpload(). It also accepts an array of parameters for each asset file associated with the webpage. If successful, this method will return a session token that will be utilized in each individual set of StartFileUpload()/CompleteFileUpload() transactions.

This method will return a descriptive error if the size of the SOAP message (i.e. XML payload) is greater than 2MiB.

Required Permissions

Content: Upload Content

Parameters

  • webpageAssets array: An array of one or more sets of WebPageAssetUploadArguments, which can contain the following:

    • filename string: The name of the file to be uploaded. A descriptive error will be returned if any of the following conditions occur:

      • This string is empty.

      • The string has more than 128 characters.

      • The file name is not valid.

    • filesize long: The size of the file in bytes. This parameter must be an unsigned integer value no greater than 5000000000 (i.e. 5GB). A descriptive error will be returned if the value is negative.

    • chunksCount int: The number of chunks the file consists of (starting at 1). The optimal chunk size is 256KiB. Files that are larger than this chunk size must be split into smaller parts by the client. Multiple chunks should be uploaded using multiple AppendChunk() calls specifying the same upload token.

    • contentType enum: Auto, Image, Video, Audio, Webpage: The type of the asset file. The default type is Image.

    • virtualPath string: The path in the BSN Library to which the file should be uploaded. If the path does not exist, it will be created. It must also contain leading and trailing slashes and be no longer than 128 characters.

    • relativePath string: The relative path of the associated asset file in relation to the webpage HTML file.

    • sha1Hash string: The SHA1 hash of the current file. The server performs verification of the uploaded file using the specified hash. A descriptive error will be returned if the specified hash does not match the hash value calculated by the server. This parameter is optional; the server-side hash verification process is skipped if this parameter is not specified.

    • webpageAssetId string

  • filename string: The name of the webpage file to be uploaded. A descriptive error will be returned if any of the following conditions occur:

    • This string is empty.

    • The string has more than 128 characters.

    • The file name is not valid.

  • filesize long: The size of the webpage in bytes. This parameter must be an unsigned integer value no greater than 5000000000 (i.e. 5GB). A descriptive error will be returned if the value is negative.

  • chunksCount int: The number of chunks the file consists of (starting at 1). The optimal chunk size is 256KiB. Files that are larger than this chunk size must be split into smaller parts by the client. Multiple chunks should be uploaded using multiple AppendChunk() calls specifying the same upload token.

  • contentType enum: Auto, Image, Video, Audio, Webpage: The type of the content file, which should be specified as “Webpage”.

  • virtualPath string: The path in the BSN Library to which the file should be uploaded (the default is “\Shared\Incoming\”). If the path does not exist, it will be created. It must also contain leading and trailing slashes and be no longer than 128 characters.

  • fileThumb base64Binary: The optional thumbnail data as a binary attachment. This parameter will be generated by the server if it is not specified.

  • sha1Hash string: The SHA1 hash of the webpage file. The server performs verification of the uploaded file using the specified hash. A descriptive error will be returned if the specified hash does not match the hash value calculated by the server. This parameter is optional; the server-side hash verification process is skipped if this parameter is not specified.

WebPageUploadStatus CompleteWebPageUploadSession(array webpageAssets[], string sessionToken, string filename, long filesize, int chunksCount, enum ContentType, string virtualPath, base64Binary fileThumb, string sha1Hash)

Returns the Web Page ID of the uploaded webpage file if the upload session is successful. Otherwise, it returns a descriptive error. If a specified parameter is different between the StartWebPageUploadSession() and CompleteWebPageUploadSession() calls, the specification in the CompleteWebPageUploadSession() call will overwrite the original StartWebPageUploadSession() specification. This is true for both the webpage file and associated asset files.

This method will return a descriptive error if the size of the SOAP message (i.e. XML payload) is greater than 2MiB.

Required Permissions

Content: Upload Content

Parameters

  • webpageAssets array: An array of one or more sets of WebPageAssetUploadArguments, which can contain the following:

    • filename string: The name of the file to be uploaded. A descriptive error will be returned if any of the following conditions occur:

      • This string is empty.

      • The string has more than 128 characters.

      • The file name is not valid.

    • filesize long: The size of the file in bytes. This parameter must be an unsigned integer value no greater than 5000000000 (i.e. 5GB). A descriptive error will be returned if the value is negative.

    • chunksCount int: The number of chunks the file consists of (starting at 1). The optimal chunk size is 256KiB. Files that are larger than this chunk size must be split into smaller parts by the client. Multiple chunks should be uploaded using multiple AppendChunk() calls specifying the same upload token.

    • contentType enum: Auto, Image, Video, Audio, Webpage: The type of the asset file. The default type is Image.

    • virtualPath string: The path in the BSN Library to which the file should be uploaded. If the path does not exist, it will be created. It must also contain leading and trailing slashes and be no longer than 128 characters.

    • RelativePath string: The relative path of the associated asset file in relation to the webpage HTML file.

    • sha1Hash string: The SHA1 hash of the current file. The server performs verification of the uploaded file using the specified hash. A descriptive error will be returned if the specified hash does not match the hash value calculated by the server. This parameter is optional; the server-side hash verification process is skipped if this parameter is not specified.

    • webpageAssetId string: The ContentId string of the webpage asset file. The client should specify this value only when an asset file is being updated.

  • sessionToken string: The token of the upload session initialized by the StartWebPageUpload() method.

  • filename string: The name of the uploaded webpage. A descriptive error will be returned if any of the following conditions occur:

    • This string is empty.

    • The string has more than 128 characters.

    • The file name is not valid.

  • filesize long: The size of the webpage in bytes. This parameter must be an unsigned integer value no greater than 5000000000 (i.e. 5GB). A descriptive error will be returned if the value is negative.

  • chunksCount int: The number of chunks the file consists of (starting at 1). The optimal chunk size is 256KiB. Files that are larger than this chunk size must be split into smaller parts by the client. Multiple chunks should be uploaded using multiple AppendChunk() calls specifying the same upload token.

  • contentType enum: Auto, Image, Video, Audio, Webpage: The type of the content file, which should be specified as “Webpage”.

  • virtualPath string: The path in the BSN Library to which the file should be uploaded (the default is “\Shared\Incoming\”). If the path does not exist, it will be created. It must also contain leading and trailing slashes and be no longer than 128 characters.

  • fileThumb base64Binary: The optional thumbnail data as a binary attachment. This parameter will be generated by the server if it is not specified.

  • sha1Hash string: The SHA1 hash of the webpage file. The server performs verification of the uploaded file using the specified hash. A descriptive error will be returned if the specified hash does not match the hash value calculated by the server. This parameter is optional; the server-side hash verification process is skipped if this parameter is not specified.

ContentUploadStatus CancelFileUpload(string uploadToken)

Cancels the specified content upload and deletes all uploaded file chunks. This method returns status information about the cancelled content upload.

Required Permissions

None

Parameters

  • uploadToken string: The token of the content upload that should be cancelled. If the content upload with the specified token does not exist, the method will immediately return Null without error.

ContentUploadStatus GetFileUploadStatus(string uploadToken)

Returns general information and upload status information about the content file associated with the specified upload token.

Required Permissions

None

Parameters

  • sessionToken string: The token of the upload session initialized by the StartFileUpload() method. If the specified session token does not correspond to an existing session, the method will return Null without error.

WebPageUploadStatus GetWebPageUploadStatus(string sessionToken)

Returns general information and upload status information about all webpage asset files associated with the specified session token.

Required Permissions

None

Parameters

  • sessionToken string: The token of the upload session initialized by the StartWebPageUpload() method. If the specified upload token does not correspond to an existing upload, the method will return Null without error.

ON THIS PAGE