Document Handling through API using WSO2 Enterprise Integrator

3 min readMay 20, 2019

In this blog post we’re going to explore how to handle documents using WSO2 EI. We are going to explore a very common use case i.e. accepting a file from a client as an attachment and writing the file to a FTP server through EI. We have used the tooling support provided via WSO2 EI tooling to create and manage the artifacts.

An brief overview of the use case is as follows:

A REST API will be defined to handle the files sent by clients (Such as Postman REST Client) as attachments
The files sent as attachments will be written to a FTP server given using the VFS transport in EI

The diagram below gives you a high level overview of the use case:

Follow the steps given below:

Define a REST API to handle the files sent by clients as attachments. These files will be written to a FTP server given using the VFS transport.

Source view of the REST API created

Deploy the created REST API in EI. Now let’s go through each element in the API and understand what each means.

The property mediator will save the name of the file sent as an attachment. This name will be used when writing the file to the FTP server.

A payload factory mediator will be used to construct the request that will be sent to the FTP server. This request will have the binary content of the file sent as an attachment.

When constructing the payload we need to consider the following:

Since we are constructing a SOAP envelope, the format of the payload should be of XML and it should be inside a ‘root’ tag.
In the SOAP body we specify the content of the file as a binary.

The script mediator will be used to invoke the functions of a variety of scripting languages such as JavaScript, Groovy, or Ruby. Here we will be using JavaScript as the scripting language. The script specified inline will set the ‘isBinary’ flag of the binary node to true.

A property mediator will be used to remove the initial request URI.

A property mediator will be used to specify a valid file name for the file written by the VFS transport.

Another property mediator will be used to set the message type to “application/octet-stream”. A MIME attachment with the content type “application/octet-stream” is a binary file. This binary file will be written to the FTP server using the VFS transport.

A property mediator will be set the OUT_ONLY property on messages that are involved in out-only invocations to avoid EI from registering unnecessary callbacks for response handling and finally running out of memory.

A call mediator will be used to the send message to a FTP server using the VFS transport. When specifying the URI of the FTP server follow this “vfs:ftp://user:password@host-of-the-ftp/location-to-save-the-file”

A payload factory mediator will be used to construct a success response which will be sent back to the client using a respond mediator.

2. Use the Postman REST Client to send a file as an attachment or use the a curl command.

curl -v POST http://localhost:8280/file/save -F ‘file=@path/to/file’

Then we will get the following response:

<soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">    
   <soapenv:Body>       
       <status>File saved successfully</status>            
       <fileName>FILE_NAME</fileName>       
       <location>LOCATION_WHERE_THE_FILE_SAVED</location>  
  </soapenv:Body>
</soapenv:Envelope>

Now if we check the location of the FTP server where we wanted to save the file sent as an attachment, we can see a file with the same name and with the same content saved there.

For more information refer the following resources:

Now as for how to end with a bang? Well, that’s another blog post for another time so stay tuned:) :)

Document Handling through API using WSO2 Enterprise Integrator

Written by Natasha Wijesekare