1 Mode of Operation
Whenever a user uploads a new file from the backend he is presented with a list of options of an available File Upload Manipulators he can choose from.
The File Upload Manipulator will only be invoked for manual uploads using the backend. Uploading files via WebDAV, Pageimport or any other means will NOT trigger the File Upload Manipulator.
As soon as the upload is finished Gentics Content.Node will send a POST Request to the File Upload Manipulator structured as follows:
The File Upload Manipulator is then expected to process the file and return a status code:
Status Code | Description |
---|---|
ACCEPTED | File is available for saving |
DENIED | File must not be saved (a virus was found etc.) |
POSTPONED | Processing the file will take some time. The File Upload Manipulator will issue a HTTP POST request to the postponeurl when manipulation is completed. Meanwhile the original file is being saved to the CMS and available to be used by editors. |
2 Configuration
// The URL where the File Upload Manipulator can be found $FILEUPLOAD_MANIPULATOR_URL = "http://localhost/manipulator.php"; // Example set of File Upload Manipulator options // 'regex' is optional and will only be evaluated // on the client using JavaScript // Options are optional. $FILEUPLOAD_MANIPULATOR_OPTIONS["video_to_flash"] = array( 'name' => "AVI Video to Flash", 'regex' => '/.*.avi/' ); $FILEUPLOAD_MANIPULATOR_OPTIONS["convert_pdf"] = array( 'name' => "Convert PDF", 'regex' => '/.*.pdf/' ); // URLs from where the File Upload Manipulator may access // Gentics Content.Node. $FILEUPLOAD_MANIPULATOR_ACCEPT_HOST = array("127.0.0.1");
Options can currently not be internationalized
3 Protocol Description
The protocol relies on JSON requests.
3.1 Request
The request to the file Upload Manipulator will contain the following parameters:
Parameter | Description |
---|---|
id | temporary file name |
fileid | Gentics Content.Node’s internal file id |
filename | Name of the file |
mimetype | The file’s mime type |
url | URL where the file can be fetched from |
postponeurl | postback url in case the file takes longer to process |
options | set of File Upload Manipulator options the User has activated |
lang | Language of the user |
This is an example request to the File Upload Manipulator right after a file has been uploaded.
{ "id":"\/home\/Node\/tmp\/fum2w0USX", "fileid":5099, "filename":"eicar.com", "mimetype":"application\/octet-stream", "url":"http:\/\/localhost\/.Node\/?do=15008&cmd=fetch&filename=fum2w0USX", "postponeurl":"http:\/\/localhost\/.Node\/?do=15008&cmd=postponedone&filename=fum2w0USX", "options":{"video_to_flash":null}, "lang":"de" }
3.2 Response
The File Upload Manipulator is expected to generate a JSON response which contains the following parameters:
Parameter | Description |
---|---|
status (required) | May be one of: ACCEPTED (file was accepted and found to need no further modification), DENIED (file was rejected – eg. may contain a virus) or POSTPONED (file we be replaced after further processing by using the postback URL) |
msg | Will be used as user feedback for status DENIED and POSTPONED |
filename | the file will be renamed |
mimetype | the files mimetype will be changed to this |
url | When provided, Gentics Content.Node will use this to download binary contents for the file |
3.3 Postpone Request
If the File Upload Manipulator delivered POSTPONED as a status, it can deliver a request to postponeurl that is structured like it’s first response (see Response).
3.4 Simple Implementation Example
<?php // A Very simple 'File Upload Manipulator' which will check all uploaded files // for viruses using the linux virus scanner 'ClamAV' (command 'clamscan' // has to be in the PATH) // read in JSON formatted data .. $data = file_get_contents('php://input'); $req = json_decode($data); // create a temporary file $tmp = tempname('/Node/tmp', 'clamav'); // download file from the URL .. copy($req->{'url'}, $tmp); $output = array(); $exitcode = 0; // execute virus scan .. exec('clamscan '.$tmp, $output, $exitcode); // delete temporary file unlink($tmp); $status = 'ACCEPTED'; $msg = ''; // If exitcode != 0 a virus was detected by clam av if( $exitcode > 0) { $status = 'DENIED'; // Depending on the User's language return the right error message. if ($req->{'lang'} == 'de') { $msg = 'Es wurde ein Virus in dieser Datei gefunden.'; } else { $msg = 'A Virus was detected while scanning the file.'; } } echo json_encode(array('status' => $status, 'msg' => $msg)); ?>