Import Integration

Output Organizer can be used to import and modify documents right away. If you call the Organizer on its root path you will be redirected to a newly created, empty collection.

In contrast to this approach, you can also prepare a collection for the user with some prepared elements and/or metadata. For this you can use a provided REST API described later in this documentation article. The prepared collection can be accessed using the collection ID returned in the creation process.

Import Elements into a Output Organizer collection

Storing documents and creating collections is typically handled by the process Output Organizer is integrated in. That said, Output Organizer itself provides options to upload documents through the browser or a REST API. Documents uploaded to Output Organizer in one of these ways are considered temporary data and should not be relied on for archival purposes. You can also simply integrate documents from existing storage solution by using a file URI or URL in the collection.

File Browser

To upload local files simply click on the big "Choose Documents" button and a file browser opens where you can pick one or multiple files to include in cour collection.

Start	Choose	Import

Files uploaded this way will create two elements each. One will be an immutable reference to the uploaded document in the "original documents" branch. The second element in the "output" branch is the main document to work with and can be modified at will and exported later.

Drag and Drop

Drag and Drop works mostly the same as choosing file with the File browser. It allows you to pick local files from your Computer, but also allows integration with other Jadice Application.
Using a Jadice Swing Viewer or Jadice Webtoolkit, the whole document or even individual pages can be dragged between the applications.

Start	Drag	Import

REST API

If you want to use the Rest API we need to first introduce the structure of a collection, which is actually pretty simple.
A collection contains Metadata and a list of elements along with some technical information.
These elements themselves also contain metadata and a specification. This specification contains information about the documents data and all the modification made to it.

In this article we make a practical approach and show what is needed to upload a document, include it in a collection and then vie the collection in a browser.
If you want a more detailed look at Elements structure you can refer to Collection Element Specifications

Upload document (optional)

Output Organizer uses the levigo Eureka API to upload documents. The storage medium is configurable, but by default the documents are stored in a cache that will be cleared after a configured time or if it overflows. Therefor if you want to rely on the document storage of Output Organizer for long term storage, you should change the storage configuration (see Deployment). For our purposes we keep it very simple and only upload a single document without any additional information.

REST request:
Endpoint: /api/v1/documents
Method: POST
Headers: Content-Type: multipart/form-data *
Request Body: Your file as multipart-form-data containing the document content. **

*: if the authentication is enabled for the Organizer, you will need a valid Authorization header for this request.
**: The key of the file in the multipart-form-field will define the "role" of the uploaded stream for the document and can be any string except __DOC which is reserved for the document definition.

JSON response:

{
    "documentId": "b7299468-a03c-4fb6-b19c-1c8126590686",
    "versionTimestamp": "2023-09-18T14:13:42.140656417Z",
    "_links": {
        "self": {
            "href": "https://output-organizer.levigo.de/api/v1/documents/b7299468-a03c-4fb6-b19c-1c8126590686"
        },
        "contentElements": {
            "href": "https://output-organizer.levigo.de/api/v1/documents/b7299468-a03c-4fb6-b19c-1c8126590686/content"
        }
    },
    "dateCreated": "2023-09-18T14:13:42.140476414Z",
    "contentElements": [
        {
            "fileName": "testdoc_jadice_blue.pdf",
            "role": "__PART",
            "type": "application/pdf",
            "encryption": "SHARED",
            "length": 679273,
            "digest": {
                "algorithm": "SHA-256",
                "bytes": "J1WYcubTiD5irXzFxd+erhwbXEXcBOmXSRfnLy7x/hE="
            },
            "_links": {
                "self": {
                    "href": "https://output-organizer.levigo.de/api/v1/documents/b7299468-a03c-4fb6-b19c-1c8126590686/content/c09b8870-6e42-4456-998c-4227aabfe7eb"
                }
            },
            "id": "c09b8870-6e42-4456-998c-4227aabfe7eb"
        }
    ],
    "dateModified": "2023-09-18T14:13:42.140477814Z"
}

this looks quite extensive but the only thin we care about is the content link of the created document. In this example a UUID of b7299468-a03c-4fb6-b19c-1c8126590686 was created for the document and within a contentElement for our uploaded document with the ID c09b8870-6e42-4456-998c-4227aabfe7eb. Because we only have a single document stream we can omit the ID of the element and access the file at https://output-organizer.levigo.de/api/v1/documents/b7299468-a03c-4fb6-b19c-1c8126590686/content

In general {Host}/api/v1/documents/{documentId}/content can be used to include the document in our collection.

Create collection

By creating collections using the REST API you can include documents using a download URL from the upload in the previous section or any other accessible source.

To emulate the typical collection scheme we recommend to create two collection elements for each document. One for the import and one for the export branch.

REST request:
Endpoint: /api/v1/collections Method: POST
Headers: Content-Type: application/json
Request Body: JSON containing the collection definition.

The JSON definition for the collection may look as follows:

{
    "typeId": "import-output",
    "elements": [
        {
            "metadata": {
                "output-organizer": {
                    "element-type": "import",
                    "filename": "testdoc_jadice_blue.pdf"
                }
            },
            "specification": {
                "type": "artifact",            
                "contentURI": "https://output-organizer.levigo.de/api/v1/documents/b7299468-a03c-4fb6-b19c-1c8126590686/content",
                "mediaType": "application/pdf"
            }
        }
    ]
}

After the Output Organizer server receives the collection it is preprocessed. The preprocessing can be expanded using Intents (see Intents). By default, the preprocessing creates a second element using the same document in a slightly more complex format, that allows the persistence of modifications. The originally imported document acts as a reference to the original data and is read only. The new element represents the output document to be modified and later exported.
The resulting collection should look like this:

{
    "typeId": "import-output",
    "elements": [
        {
            "metadata": {
                "output-organizer": {
                    "element-type": "import",
                    "filename": "testdoc_jadice_blue.pdf"
                }
            },
            "specification": {
                "type": "artifact",            
                "contentURI": "https://output-organizer.levigo.de/api/v1/documents/b7299468-a03c-4fb6-b19c-1c8126590686/content",
                "mediaType": "application/pdf"
            }
        },
        {
            "metadata": {
                "output-organizer": {
                    "element-type": "output",
                    "filename": "testdoc_jadice_blue.pdf"
                }
            },
            "specification": {
                "type": "compositePaged",
                "pageSequences": [
                    {
                        "contentURI": "https://output-organizer.levigo.de/api/v1/documents/b7299468-a03c-4fb6-b19c-1c8126590686/content",
                        "mediaType": "application/pdf"
                    }
                ]
            }
        }
    ]
}

As you can see in this definition the input and output documents are defined by the filed elements[].metadata.output-organizer.element-type: import | output.
The field elements[].metadata.output-organizer.filename represents the display name for the element in the tree view. The two elements have different specification: the import element is of type artifact and is therefore immutable. The type compositePaged on the output element allows modifications like reordering or deleting pages and splitting or merging documents.

Adding Metadata
You can add additional metadata to the collection or individual elements. For example:

{
  "typeId": "import-output",
  "metadata": {
    "custom": {
      "collection": "metadata"
    }
  },
  "elements": [
    {
      "metadata": {
        "type": "import",
        "filename": "testdoc_jadice_blue.pdf",
        "custom": {
          "element": "metadata"
        }
      },
      "specification": {
        "type": "artifact",
        "contentURI": "https://output-organizer.levigo.de/api/v1/documents/b7299468-a03c-4fb6-b19c-1c8126590686/content",
        "mediaType": "application/pdf"
      }
    }
  ]
}

You can use the metadata and elements[].metadata fields to add any custom metadata information. This information wil be transported through the editing process and included in the export result. The metadata key "output-organizer" is reserved for technical metadata used by Output Organizer itself.