Inline File Validation with URI

For general information about inline file validation, see Inline File Validation (Overview)


To set up a validation handler for inline file validation, define a URL in the <transfer> section of aspera.conf and define values for the REST service.

The code examples in the steps below are for an admin using a Java servlet deployed on an Apache web server, but this process is generalizable to other programming languages and other servers.
  1. Configure the REST service.
    web.xml must have values for the <servlet> and <servlet_mapping> sections to provide the necessary information for validation.
    Note: The <servlet-name> (URL handler) value is reused in both aspera.conf (in the next step) and custom code (see Custom Code for Including and Excluding Files, below).
    <?xml version="1.0" encoding="UTF-8"?>
    <web-app xmlns=""
  2. Edit the <transfer> section in aspera.conf to add the server's IP address and port, and the servlet name (URL handler) found in web.xml. For example:

Validation Requests and Returned Responses

During the inline validation process, ascp automatically generates a JSON-based request. The call is made with the URL already defined in aspera.conf. For example:

POST URL/validation/files HTTP/1.1
Content-type: application/json

The system then generates a JSON accepted or error response (OK or Bad Request) .

Sample JSON accepted response:

The "file_encryption" field is only returned if server-side EAR is present.

    "id" : "1111-2222-333",
    "file_encryption" : {               
        "passphrase" : "supersecret"
    "aspera_response_object_name" : {
        "startstop" : "start"
        "xfer_id" : "AAAA-BBBB",             
        .  .  .
        "file_csum" : "a1000abf882",
        "file_csum_type" : "sha2-256" 

Sample JSON error response:

If a file validation fails, it terminates the session with an error message from the URI.

HTTP 400 Bad Request
  "error" : {
    "code" : "1022",
    "message" : "The file fails validation"

Custom Code for Including and Excluding Files

Administrators can include or exclude files by enabling whitelisting, blacklisting, or another method of their own design. You can do this by creating custom code in the programming language of your choice, using a web server that runs a REST service. (Connect Server users have the option to use the web server associated with that installation).

The following is an example of custom code that creates a file blacklist, using a Java servlet deployed on an Apache web server. Note that this code uses the servlet name SimpleValidator, which was defined in web.xml above.
package aspera.validation;


import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

@WebServlet(name = "SimpleValidator")
public class SimpleValidator extends HttpServlet {
    protected void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
        StringBuilder fileRequestJSON = new StringBuilder();
        BufferedReader reader = request.getReader();
        String line = "";
        Gson gson = new Gson();

        System.out.println("Got Validation request...");
        while (line != null) {
            line = reader.readLine();
            if (!(line == null)) {

        ValidationInput validationInput = gson.fromJson(fileRequestJSON.toString(), ValidationInput.class);

        System.out.println("FileData JSON: " + fileRequestJSON.toString());

        if (validationInput.file != null && validationInput.file.endsWith(".sh")
           || validationInput.file.endsWith(".exe")) {

            JsonObject innerObject = new JsonObject();
            innerObject.addProperty("message", "Cannot transfer executable file!!");
            innerObject.addProperty("code", 1);

            JsonObject jsonObject = new JsonObject();
            jsonObject.add("error", innerObject);


        else {

            JsonObject jsonObject = new JsonObject();
            jsonObject.addProperty("success", true);
            jsonObject.addProperty("data", "File is ok to transfer");
            jsonObject.addProperty("code", 1);