Get filename and folder suggestions for a document

About this guide

This guide explains how to build experiences that help end users more quickly and reliably file documents in any document store, by using Aluma to retrieve suggestions for an appropriate filename and location for each document.

📘

Aluma API only

To use the features described in this guide you will need to make requests against the Aluma API directly. You cannot use the dashboard or the Aluma CLI to access these features.

Introduction

When scanning a document into a document store from a multifunction device (MFD) an end user is typically forced to navigate to the appropriate location for the document and manually type a filename, or use an unhelpful auto-generated filename. This makes for a painful user experience and inconsistency in filing by different members of a team.

You can use Aluma to build a streamlined user experience on an MFD, or as part of another document ingestion process, by using Aluma to suggest an appropriate filename and location for the document to the user. This reduces the time the user spends at the device and leads to more consistency in filenames and locations where documents are filed.

For each document processed, Aluma will suggest:

• A filing location and a set of possible alternatives
• A filename and a set of possible alternatives
• A set of filename "elements" from which a user can quickly build their own filename if they want something different to the suggested ones

Filing locations are based on how each end user organizes their digital content and are learnt by Aluma as each document is processed.

Filenames are based on key content extracted from the document, such as document titles, dates and names.

Overview

The diagram below shows how Aluma is typically integrated into a scan and filing process, or other document ingestion process:

1. The document is scanned on the MFD and an Aluma document is created from its contents.
2. The MFD application requests suggestions from Aluma.
3. The MFD application displays the filename and filing location suggestions to the user. The user approves the proposed filename and location suggestions, selects one of the alternative suggestions, or selects a different filename or folder if necessary.
4. The MFD application files the document in the document store.
5. The MFD application sends the filename and location that the user selected to Aluma, which learns from the user's selections in order to improve suggestions for next time.
6. The MFD application deletes the Aluma document.

Note that Aluma does not integrate directly with the document store. Aluma's understanding of document locations is abstract and can be used with any document store.

1 - Create Aluma document

From your MFD application you should make a Create document request to the Aluma API, with the contents of the scanned document and stores the Aluma document ID for use in subsequent requests.

2 - Get filename and location suggestions

Once the Aluma document has been created, you should make a Generate Suggestions request to the Aluma API, referencing the document's ID.

The request includes a context property. You should set this to a unique identifier for each end user such as an email address or username, so each user gets suggestions based on their own previous filing.

You can find a full example of the response in the Generate Suggestions endpoint reference. The response includes three main sections - filename suggestions, filename elements and folder suggestions.

Filename suggestions
The filename suggestions include a primary suggestion that would be appropriate to present to the user as a default choice and a set of alternatives that you may also choose to allow the user to select from.

"suggestions": {
    "filename": {
      "primary": {
          "filename": "Certificate Of Motor Insurance - Eleanor Harrison - Dec 31 2020.pdf"
        }
      },
      "alternatives": [
        {
          "filename": "Certificate Of Motor Insurance - Eleanor Harrison.pdf"
        },
        ...

Filename elements
A set of filename elements are also included that you can display in a user interface to enable a user to build up a different filename by selecting them and with little or no typing:

"suggestions": {
    "filename": {
      "elements": {
        "document_title": [ 
          "Certificate Of Motor Insurance"
        ],
        "document_date": [
          "Dec 31 2020"
        ],
        "name": [
           "Eleanor Harrison" 
        ]
      }

Note that Aluma is aware of different types of documents and these elements will be extended over time, so your application should be able to handle other elements that we add to the responses.

Folder suggestions
Finally, the response includes a primary filing location (we refer to locations as "folders") and a set of alternatives along with the reason they are being suggested.

"suggestions": {
  "folder": {
    "primary": {
        "folder_id": "1BTfb5MTRg-vAmMWyEPoNTHdAAk3N18aS",
        "reason": "learnt"
      }
    },
    "alternatives": [
      {
        "folder_id": "1X5TBmAMi9_rdv9YoONBbdqMvuMJNIyjX",
        "reason": "learnt"
      },
      ...

Each folder_id is a unique identifier for a location in your document store, such as a Google Drive, Office 365 or Box folder IDs. Aluma does not understand or use the folder_id except to learn which documents should be filed in each one. The folder_id can be any value meaningful to your application that enables you to uniquely identify a filing location.

Aluma learns which types of documents are filed in which folder_id through a request to the Store Suggestions Results endpoint (see step 6). You will start getting folder suggestions once you've processed at least one document sufficiently similar to a previous document, and suggestions will improve as more documents as processed.

The primary folder suggestion is only populated if Aluma is confident that the document is sufficiently similar to a previous document (and different from others). This is intended as a suggestion that would be appropriate to present to the user as a default choice.

3 - Display suggestions to user

Now you have the suggestions you can display them to the user. It is of course up to you how you do this, but our customers have found the following pattern works well.

Display the primary filename and folder suggestions and allow the user to file using these with a single interaction such as a "File Document" button. Also allow the user to indicate they would like to select a different filename or folder (and force them to do this if either of the primary suggestions are empty).

In most cases your application will need to convert your folder_id values to text (such as a pseudo-path) that are meaningful to users.

If the user indicates that they would like to select an alternative filename then provide an interface that enables them to either select one of the alternative filename suggestions or build their own through a combination of selecting filename elements and typing.

Allow the user to indicate they would like to select an alternative folder and provide an interface that enables them to either select one of the alternative suggestions or pick a folder from all the ones in your document store. The user will be required to do this if Aluma does not provide a primary folder suggestion.

4 - File Document

Now you have a filename and folder you can file the document in your document store.

5 - Update Aluma with filename and folder selected by user

In parallel with the filing of the document (to reduce elapsed time for the user) you should make a request to the Store Suggestion Results endpoint with the filename and folder selected by the user.

When Aluma receives this information it feeds it into its learning so that suggestions are improved for subsequent documents.

{
	"filename": "Certificate Of Motor Insurance - Eleanor Harrison - Dec 31 2020.pdf",
	"folder_id": "1BTfb5MTRg-vAmMWyEPoNTHdAAk3N18aS"			
}

6 - Delete Aluma Document

Finally you should make a request to the Delete Document endpoint to remove the document from Aluma. If you don't then the document will be automatically deleted after 10 minutes of inactivity, but it is better to delete it explicitly so you reduce the potential for hitting document quota limits.