File Upload Manipulator

A File Upload Manipulator enables you to modify files, right after an editor finished the upload.

1 Mode of Operation

The File Upload Manipulator will only be invoked for manual uploads that are passed through the backend. This will also apply for proxied uploads that are performed using frontend editing. Uploading files via Pageimport or any other means will NOT trigger the File Upload Manipulator.

As soon as the upload is finished Gentics CMS will send a POST Request to the File Upload Manipulator structured as described here.

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

conf.d/*.conf

// The URL where the File Upload Manipulator can be found
$FILEUPLOAD_MANIPULATOR_URL = "http://localhost/manipulator.php";

// Options for the HTTP socket.
// If you set the timeouts too low, the FUM HTTP request can fail.
$FILEUPLOAD_MANIPULATOR_SOCKETOPTIONS = array(
	// Time in ms to wait for new data, if this time elapses
	// and no data was received, the FUM and the
	// fileupload will fail.
	'socketTimeout'     => 15000,
	// Timeout in ms to establish a HTTP connection to the FUM.
	'connectionTimeout' => 5000,
	// Max number of attempts to establish a connection to the FUM.
	'connectionRetry'   => 3
);

// URLs from where the File Upload Manipulator may access
// Gentics CMS.
$FILEUPLOAD_MANIPULATOR_ACCEPT_HOST = array("127.0.0.1");

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 internal file id of Gentics CMS
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
lang Language of the user
folder Oject that contains information about the folder where the file was uploaded to, with the following attributes: “id”, “name”, “nodeid”. If the node is a channel, “nodeid” will be the channel ID. If the folder is localized, “id” will be the ID of the localized version of the folder
user User uploading the file
user.id ID of the user
user.firstName User’s first name
user.lastName User’s last name
user.description User’s description
user.email User’s email address

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",
	"lang":"de",
	"folder": {
		"id":56,
		"name":"test folder",
		"nodeid":3
	},
	"user": {
		"id": 4711,
		"firstName": "John",
		"lastName": "Doe",
		"description": "Testuser",
		"email": "john.doe@somewhere.com"
	}
}

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
filename the file will be renamed
mimetype the files mimetype will be changed to this
url When provided, Gentics CMS 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 POST a request to postponeurl that is structured like its first response (see Response). If the File Upload Manipulator sends a postponed response, please make sure, that the implementation will copy the temporary file in the url first. This is because the temporary file will be deleted after one day, if no response like ACCEPTED or DENIED is returned.

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 = tempnam('/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));
?>