webCOMAND

Attach Web Service

Upload one or more field/value pairs to store on the server, associated with a session (other sessions will not have access). The response includes an ID that can be used in the value of a subsequent Put service request's "_attach" property to affectively "attach" the field/value pair(s) to the Put request, as if it were included in the Put request itself.

The Attach service accepts two types of requests: Form and File.

Form Request

A Form request can be sent by a traditional HTML <form> submission or an AJAX request. GET and POST methods, and "application/x-www-form-urlencoded" and "multipart-form-data" enctypes are supported. Enctype "multipart-form-data" is used to upload files with traditional file inputs (ie. <input type="file" />).

Each form input name/value will be maintained on the server, including file inputs, until it is applied to an object in a Put service request using the _attach property.

File Request

A File request can be sent from a browser with the HTML5 XMLHttpRequest send method (see HTML5-powered Ajax file uploads), or from a software application the same way it would serve a file over HTTP to a client.

The content of a file request is the file, so the following "properties" must be sent as HTTP headers.

  • Content-Type: mime-type – The file mime-type.
  • Authorization: <token> – Optional parameter to define the User Token. If not defined, the cookie header will be checked for a token.
  • X-Session: <session ID> – Optional parameter to define the user session. If key is not defined, the cookie will be checked for a session.
  • X-File-Name: <filename> – The file name, including the extension, but excluding a preceding file path.
  • X-Field-Identifier: <field identifier> – The object field identifier the file will ultimately be attached to in a subsequent Put or Attach service request.

Response

The response includes the following properties, in addition to the Common Response Properties.

  • id: <ID> – A unique attachment number that can be used in subsequent Put or Attach requests.

Form Request Example


<form id="attachments" enctype="multipart/form-data">
	<label>Attachments</label>
	<input type="hidden" id="filename" name="Filename" />
	<input type="file" id="file" name="File" />
	<input type="submit" value="Attach File" />
	<ul></ul>
</form>

<label>To</label>
<input type="text" id="to" />

<label>Subject</label>
<input type="text" id="subject" />

<label>Message</label>
<textarea id="message"></textarea>

<input type="button" id="send" value="Send" />var attachments = [];
$('#attachments').on( 'submit', function( event ){
	var filename = $('#file').val().split(/(\\|\/)/g).pop();
	if( filename == '' ) {
		alert( 'No file selected to attach.' );
		return false;
	}
	$('#filename').val( filename );
	var formData = new FormData( $('#attachments')[0] );
	$.ajax({
		url: 'https://<account>.webcomand.com/ws/attach',
		type: 'POST',
		data: formData,
		cache: false,
		contentType: false,
		processData: false,
		success: function( data ){
			if( data.status === true ){
				attachments.push( { _attach: data.id } );
				alert( "Upload Successful." );
				$('ul',this).append( '<li>'+filename+'</li>' );
			} else {
				alert( "Upload Error: " + data.status );
			}
		}
	});
	return false; // prevent standard form submit
});

$('#send').on( 'click', function( event ){
	$.ajax({
		url: 'https://<account>.webcomand.com/ws/put',
		data: { content: {
			Type: { Identifier: 'Email' },
			To: $('#to').val(),
			Subject: $('#subject').val(),
			Message: $('#message').val(),
			Attachments: attachments
		}},
		success: function( data ){
			if( data.status === true ) {
				alert( "Email Sent." );
			} else {
				alert( "Email Error: " + data.status );
			}
		}
	});
});

File Request Example

<form method="POST" enctype="multipart/form-data"
 action="https://<account>.webcomand.com/ws/attach">
 <label>Attachments</label>
 <input type="hidden" id="filename" name="Filename" />
 <input type="file" id="file" name="File" />
 <input type="submit" value="Attach File" />
</form>