Spring Boot and the FormKiQ Document Stack

Introduction

This tutorial walks you through using Spring Boot and FormKiQ Stacks API to easily accept file uploads from a user, display uploaded files and to download the files again.

What You Need for this Tutorial

About 30 minutes
A favorite text editor or IDE
A FormKiQ Document Stack Sandbox Account (we will sign up as Step One, below)
JDK 11 or later
Gradle 4 or later

Note: The full Source Code for this Tutorial is available on GitHub

Step 1: Set Up a FormKiQ Document Stack Sandbox Account

By default the FormKiQ Demo environment is READONLY. Since this tutorial requires reading / writing files, you will need to set up a Sandbox Account:

Sign Up for FormKiQ Sandbox Account. You will receive an email with your temporary password.
Set your new password by visiting the FormKiQ Stacks Console. Once you have logged in with the username and password from the email you received, you will be asked to create a new password.

This will be the username and password you will need to complete this tutorial.

Note: Your Sandbox Account will be active for seven days; after that time it will be disabled. (Your email address will not be used for any contact lists or marketing.)

Step 2: Create a Spring Boot Project

We will create the tutorial project using Spring Initializr. This the fastest way to start a Spring Boot project. By filling in a few project parameters, it will generate a zip file containing a project that is ready to use.

Use the following configuration options:

Project: Gradle Project
Language: Java
Spring Boot: 2.3.4
Project Metadata:
- Group: com.formkiq.tutorials
- Artifact: fileupload
- Name: fileupload
- Description: Demo project for Spring Boot and FormKiQ Stacks
- Package Name: com.formkiq.tutorials.fileupload
- Packaging: Jar
- Java: 11

Click the Add Dependencies button and add Spring Web and Thymeleaf.

Once all configuration options have been chosen and the two dependencies have been added, click the Generate button, then download the ZIP file and unzip it into a new project directory.

Additional Dependencies

We require 2 additional dependencies to be added to the project. Open the file ./build.gradle (located in the root of the project directory), and add the following:

dependencies {
  // AWS Cognito Identity Provider
  implementation 'software.amazon.awssdk:cognitoidentityprovider:2.13.28'
  // FormKiQ Stacks Client
  implementation 'com.formkiq.stacks:client:1.1'
  ...
}

The software.amazon.awssdk:cognitoidentityprovider library is Amazon's offical library for interacting with Amazon Cognito, which FormKiQ Stacks uses for authentication. We will be using this library to authenticate with Cognito and to generate the Authentication Tokens we will need.

The com.formkiq.stacks:client:1.1 library is the official FormKiQ Client Library. This library makes interacting with the FormKiQ Stacks API a snap!

Application Class

When you ran the Spring Initializr, it automatically created the class com.formkiq.tutorials.fileupload.FileuploadApplication. This class is annotated with @SpringBootApplication.

@SpringBootApplication
public class FileuploadApplication {
  public static void main(String[] args) {
    SpringApplication.run(FileuploadApplication.class, args);
  }
}

This is a Spring Boot annotation that indicates the application's entry point, so running this class will start the application.

Step 3: Add the FormKiQ API Client and Cognito Authentication

FormKiqClientBuilder Class

In order to interact with the FormKiQ Stacks API, we will need to authenticate with Cognito and instantiate the com.formkiq.stacks.client.FormKiqClientV1 class using the Cognito authentication token.

Create com.formkiq.tutorials.fileupload.FormKiqClientBuilder.java:

package com.formkiq.tutorials.fileupload;
import java.util.Map;
import com.formkiq.stacks.client.FormKiqClient;
import com.formkiq.stacks.client.FormKiqClientConnection;
import com.formkiq.stacks.client.FormKiqClientV1;
import software.amazon.awssdk.auth.credentials.AnonymousCredentialsProvider;
import software.amazon.awssdk.services.cognitoidentityprovider.CognitoIdentityProviderClient;
import software.amazon.awssdk.services.cognitoidentityprovider.model.AuthFlowType;
import software.amazon.awssdk.services.cognitoidentityprovider.model.InitiateAuthRequest;
import software.amazon.awssdk.services.cognitoidentityprovider.model.InitiateAuthResponse;
  
public class FormKiqClientBuilder {

  /** Parameter Store Value: /formkiq/<appenvironment>/cognito/UserPoolClientId. */
  private static final String CLIENT_ID = "4b9bl9mkvbhpn0g0mjpj0hnhb7";

  /** Parameter Store Value: /formkiq/<appenvironment>/api/DocumentsHttpUrl. */
  private static final String HTTP_URL = "https://api-demo.tryformkiq.com/";

  private static CognitoIdentityProviderClient cognitoProvider = CognitoIdentityProviderClient
    .builder().credentialsProvider(AnonymousCredentialsProvider.create()).build();

  /**
    * Logins into Cognito and returns a Authentication token that is valid for 1 HR.
    * 
    */
    private static String loginToCognito(final String email, final String password) {

    InitiateAuthRequest req =
    InitiateAuthRequest.builder().clientId(CLIENT_ID).authFlow(AuthFlowType.USER_PASSWORD_AUTH)
    .authParameters(Map.of("USERNAME", email, "PASSWORD", password)).build();

    InitiateAuthResponse response = cognitoProvider.initiateAuth(req);
    return response.authenticationResult().idToken();
    }

  /**
    * Builds a {@link FormKiqClient} instance using a valid Cognito Email / Password.
    */
    public static FormKiqClient build(final String email, final String password) {
    String token = loginToCognito(email, password);

    FormKiqClientConnection connection =
      new FormKiqClientConnection(HTTP_URL).cognitoIdToken(token);
    return new FormKiqClientV1(connection);
    }
}

How It Works

The first step in the FormKiQClientBuilder is to authenticate with Cognito and retrieve the Cognito Authentication idToken. This is all done in the loginToCognito method. In order to authenticate with Cognito, we need to know the Cognito ClientId.

For the FormKiQ Stacks Demo and Sandbox Account, this value is 4b9bl9mkvbhpn0g0mjpj0hnhb7, but if you have FormKiQ installed in your own AWS Private Cloud, you can find this value by looking in the AWS Parameter Store Console under the /formkiq//cognito/UserPoolClientId key.

By using a valid Cognito ClientId, Username and Password, Cognito will return an IdToken that can be used to authenticate ourselves withe FormKiQ Stacks API.

The next step is to get the FormKiQ Stacks API URL. For the FormKiQ Stacks Demo account this URL is https://api-demo.tryformkiq.com/. You can find this value in your FormKiQ Stacks installation by looking in the AWS Parameter Store Console under the /formkiq//api/DocumentsHttpUrl key.

Using the Cognito IdToken and FormKiQ Stacks API URL, we can create an instance of com.formkiq.stacks.client.FormKiqClientConnection and using that create an instance of com.formkiq.stacks.client.FormKiqClientV1 instance.

The FormKiqClientV1 instance will be used in the FileuploadController to interact with the FormKiQ Stacks API.

Step 4: Add the File Uploader

FileuploadController

Create com.formkiq.tutorials.fileupload.FileuploadController.java. Make sure you replace REPLACE_WITH_SANDBOX_EMAIL and REPLACE_WITH_SANDBOX_PASSWORD with your Sandbox Account you created (or for private cloud, your installed FormKiQ Stacks parameters).

package com.formkiq.tutorials.fileupload;

import java.io.IOException;
import java.io.InputStream;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpRequest.BodyPublisher;
import java.net.http.HttpRequest.BodyPublishers;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.text.SimpleDateFormat;
import java.util.Date;
import java.util.Map;
import java.util.stream.Collectors;
import javax.annotation.Resource;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.multipart.MultipartFile;
import org.springframework.web.servlet.mvc.method.annotation.MvcUriComponentsBuilder;
import org.springframework.web.servlet.mvc.support.RedirectAttributes;
import com.formkiq.stacks.client.FormKiqClient;
import com.formkiq.stacks.client.models.DocumentUrl;
import com.formkiq.stacks.client.models.Documents;
import com.formkiq.stacks.client.requests.GetDocumentContentUrlRequest;
import com.formkiq.stacks.client.requests.GetDocumentUploadRequest;
import com.formkiq.stacks.client.requests.GetDocumentsRequest;
import software.amazon.awssdk.utils.IoUtils;
      
@Controller
public class FileuploadController {
      
  /** Signup for your Cognito Sandbox Account at: https://www.formkiq.com/products/document-stack/demo */
  /** Cognito User. */
  private static final String COGNITO_USER = "REPLACE_WITH_SANDBOX_EMAIL";
  /** Cognito Password. */
  private static final String COGNITO_PASSWORD = "REPLACE_WITH_SANDBOX_PASSWORD";
  /** {@link FormKiqClient}. */
  private FormKiqClient client;
      
  public FileuploadController() {
    this.client = FormKiqClientBuilder.build(COGNITO_USER, COGNITO_PASSWORD);
  }
      
  @GetMapping("/")
  public String listUploadedFiles(Model model) throws IOException, InterruptedException {
      
    /* The Date / TZ are not required, but defaults to current UTC date without them. */
    String tz = new SimpleDateFormat("Z").format(new Date());
    GetDocumentsRequest req = new GetDocumentsRequest().date(new Date()).tz(tz);
      
    Documents results = this.client.getDocuments(req);
      
    model.addAttribute("files",
      results.documents().stream()
        .map(doc -> Map.of("name", doc.path(), "path",
          MvcUriComponentsBuilder
            .fromMethodName(FileuploadController.class, "serveFile", doc.documentId())
            .build().toUri().toString()))
        .collect(Collectors.toList()));
        
    return "uploadForm";
  }
      
  @GetMapping("/files/{documentId:.+}")
  @ResponseBody
  public ResponseEntity<Resource> serveFile(@PathVariable String documentId)
    throws IOException, InterruptedException {
      
    GetDocumentContentUrlRequest req = new GetDocumentContentUrlRequest().documentId(documentId);
    DocumentUrl content = this.client.getDocumentContentUrl(req);
      
    return ResponseEntity.status(307).header("Location", content.url()).build();
  }
      
  @PostMapping("/")
  public String handleFileUpload(@RequestParam("file") final MultipartFile file,
    final RedirectAttributes redirectAttributes) throws IOException, InterruptedException {
      
    long contentLength = file.getSize();
      
    /* FormKiQ Demo restricts the ContentLength, so contentLength MUST be specified. */
    GetDocumentUploadRequest uploadRequest = new GetDocumentUploadRequest()
      .path(file.getOriginalFilename()).contentLength(contentLength);
      
    // Retrieve URL that can be used to upload document.
    DocumentUrl upload = this.client.getDocumentUpload(uploadRequest);
      
    // Upload Document
    InputStream inputStream = file.getInputStream();
      
    BodyPublisher ofContent = BodyPublishers.ofByteArray(IoUtils.toByteArray(inputStream));
      
    /*
      * Because ContentLength is specified above, the ByteArray must be used instead of InputStream.
      * This is because using an InputStream does not set the 'Content-Length' header. If
      * Content-Length isn't specified you can use InputStream directly. As shown below.
      */
    // BodyPublisher ofContent = BodyPublishers.ofInputStream(() -> inputStream);
      
    HttpRequest request =
      HttpRequest.newBuilder().uri(URI.create(upload.url())).method("PUT", ofContent).build();
      
    HttpResponse<String> response =
      HttpClient.newHttpClient().send(request, BodyHandlers.ofString());
      
    if (response.statusCode() != FormKiqClient.HTTP_STATUS_OK) {
      throw new IOException(response.body());
    }
      
    redirectAttributes.addFlashAttribute("message",
      "You successfully uploaded " + file.getOriginalFilename() + "!");
      
    return "redirect:/";
  }
}

How It Works

FileuploadController has 3 methods:

listUploadedFiles - lists uploaded files by user
serveFile - downloads the uploaded file
handleFileUpload - uploads the File to FormKiQ Stacks

The listUploadedFiles method uses the FormKiqClient's getDocuments() method to retrieve all documents that have been uploaded for a particular date. It is important to specify your Timezone in this request, otherwise, the default Timezone of UTC will be used.

The serveFile method uses the FormKiqClient's getDocumentContentUrl() method to retrieve the contents of a document. The URL returned has temporary access to the file; you can specify how long this URL is valid for but it defaults to one hour.

The handleFileUpload method uses the FormKiqClient's getDocumentUpload() method to retrieve an Amazon CloudFront URL that the contents of the MultipartFile upload can be sent to. The URL provided only accepts the "PUT" request method.

File Upload HTML Template

The following uses a Thymeleaf template (from src/main/resources/templates/uploadForm.html) to provide a File Input for uploading of files, and will display which files have been uploaded and provide a link to download them:

<html xmlns:th="https://www.thymeleaf.org">
  <body>
    <div th:if="${message}">
      <h2 th:text="${message}"/>
    </div>
    <div>
      <form method="POST" enctype="multipart/form-data" action="/">
      <table>
        <tr><td>File to upload:</td><td><input type="file" name="file" /></td></tr>
        <tr><td></td><td><input type="submit" value="Upload" /></td></tr>
      </table>
      </form>
    </div>
    <div>
      <ul>
      <li th:each="file : ${files}">
        <a th:href="${file.path}" th:text="${file.name}" />
      </li>
    </ul>
    </div>
  </body>
</html>

Step 5: Run the Application

In order to run the application using gradle we need to tell gradle that it needs to run the com.formkiq.tutorials.fileupload.FileuploadApplication.main(String[] args). Edit build.gradle and add the following:

plugins {
  ...
  id 'application'
}

...
application {
  mainClassName = 'com.formkiq.tutorials.fileupload.FileuploadApplication'
}
...

Now when you run the below command you should see the following output:

./gradlew clean build run

Along with a several output entries from Spring Boot.

Open your browser and visit http://localhost:8080 and you should see the upload form.

When you upload a file you should see the message: You successfully uploaded , and you should see a file download link below.

Fileupload in the Browser: message received after uploading a file

Summary

Congratulations! You have completed the FileUpload Tutorial and have learned how to build a Spring Boot application that uses the FormKiQ Stacks API to upload, store, and distribute files.

View this Tutorial on GitHub

Spring Boot and the FormKiQ Document Stack - Uploading Files

Friday, June 12, 2020

Learn how to build a Spring Boot application that uses FormKiQ Stacks API to upload, store, and distribute files

Introduction

What You Need for this Tutorial

Step 1: Set Up a FormKiQ Document Stack Sandbox Account

Step 2: Create a Spring Boot Project

Additional Dependencies

Application Class

Step 3: Add the FormKiQ API Client and Cognito Authentication

FormKiqClientBuilder Class

How It Works

Step 4: Add the File Uploader

FileuploadController

How It Works

File Upload HTML Template

Step 5: Run the Application

Summary