Passing a document as an input parameter

A client application built with Flex cannot pass a document directly to a LiveCycle process. Instead, the client application uses an instance of the mx.rpc.livecycle.DocumentReference ActionScript class to pass input parameters to an operation that expects a com.adobe.idp.Document instance. A Flex client application has several options for setting up a DocumentReference object:

When the document is on the server and its file location is known, set the DocumentReference object’s referenceType property to REF_TYPE_FILE. Set the fileRef property to the location of the file, as the following example shows:

        ... 
        var docRef:DocumentReference = new DocumentReference(); 
        docRef.referenceType=DocumentReference.REF_TYPE_FILE; 
        docRef.fileRef = "C:/install/adobe/cs2/How to Uninstall.pdf"; 
        ...

When the document is on the server and you know its URL, set the DocumentReference object’s referenceType property to REF_TYPE_URL. Set the url property to the URL, as the following example shows:

        ... 
        var docRef:DocumentReference = new DocumentReference(); 
        docRef.referenceType=DocumentReference.REF_TYPE_URL; 
        docRef.url = "http://companyserver:8080/DocumentManager/116/7855"; 
        ...

To create a DocumentReference object from a text string in the client application, set the DocumentReference object’s referenceType property to REF_TYPE_INLINE. Set the text property to the text to include in the object, as the following example shows:

... 
var docRef:DocumentReference = new DocumentReference(); 
docRef.referenceType=DocumentReference.REF_TYPE_INLINE; 
docRef.text = "Text for my document"; 
// Optionally, you can override the server's default character set 
// if necessary: 
// docRef.charsetName=CharacterSetName 
...

When the document is not on the server, use the Remoting upload servlet to upload a document to LiveCycle. New in LiveCycle is the ability to upload secure documents. When uploading a secure document, you have to use a user who has the Document Upload Application User role. Without this role, the user cannot upload a secure document. It is recommended that you use single sign on to upload a secure document. (See Passing secure documents to invoke processes using Remoting.)

Note: if LiveCycle is configured to allow unsecure documents to be uploaded, you can use a user that does not have the Document Upload Application User role to upload a document. A user can also have the Document Upload permission. However, if LiveCycle is configured to only allow secure documents, then ensure that the user has the Document Upload Application User role or Document Upload permission. (See Configuring LiveCycle to accept secure and unsecure documents.)

You use standard Flash upload capabilities for the designated upload URL: http://SERVER:PORT/remoting/lcfileupload. You can then use the DocumentReference object wherever an input parameter of type Document is expected
```
private function startUpload():void 
{     
fileRef.addEventListener(Event.SELECT, selectHandler); 
fileRef.addEventListener("uploadCompleteData", completeHandler); 
try  
{ 
    var success:Boolean = fileRef.browse(); 
}  
 
catch (error:Error)  
{ 
    trace("Unable to browse for files."); 
} 
} 
 
     
private function selectHandler(event:Event):void { 
var request:URLRequest = new 
URLRequest("http://SERVER:PORT/remoting/lcfileupload") 
try  
    { 
    fileRef.upload(request); 
    }  
 
catch (error:Error)  
    { 
    trace("Unable to upload file."); 
    } 
} 
 
private function completeHandler(event:DataEvent):void  
{ 
    var params:Object = new Object(); 
    var docRef:DocumentReference = new DocumentReference(); 
    docRef.url = event.data as String; 
    docRef.referenceType = DocumentReference.REF_TYPE_URL; 
}
```
The Remoting Quick Start uses the Remoting upload servlet to pass a PDF file to the MyApplication/EncryptDocument process. (See Invoking a short-lived process by passing an unsecure document using Remoting.)