Inbound App

Basic information

This topic provides general information on the inbound API.

About the inbound API

This document shows you how to use the programming interface of the inbound app for your own developments. The inbound app provides functions related to importing, preparing, and processing of digital pages.

Scope of function of the inbound app

The inbound app covers the management of digital collections of pages, known as batches. It has the following functions:

• Import of pages from external systems (such as from the scan app)
• Export of batch pages for third-party systems
• Processing of the batch and its pages
• Simple authorization concept

Using the API functions

In this section you will learn about the different options for using the interfaces of the inbound app for your requirements.

General information

This chapter provides general information on using the API.

Format of error responses

This chapter describes the format in which errors are output. Depending on the processing result of the operation, different HTTP status codes are used to respond to the HTTP request. Optionally, descriptive information is returned.

Example response to a failed request:

HTTP/1.1 400 BadRequest

{
  "reason": "AuthorizedGroups and AuthorizedUsers are empty. At least one must be set. Parameter name: authorization",
  "details": "Exception type: System.ArgumentException",
  "severity": 3,
  "errorCode": 0
}

Notes on the properties

Using the API without a user context

You can use the app session in the identity provider app to call the API without a user context. All the public inbound app interfaces support this app session. For more detailed information about generating an app session, see the API documentation for the identity provider app. After creating a batch, ensure that users receive access to the batch. For more information, see the section Assigning batch permissions for users or groups.

Creating a batch

You can automatically create a new batch in the inbound app without requiring a user to perform an action. To create a new batch, perform the following steps:

• Determine the link relation for creating a new batch
• Call the URL for creating a new batch

Determining the link relation for creating a batch

Use an HTTP GET request to call the root URL of the inbound app:

Request

GET /inbound
Accept: application/hal+json

The JSON object of the inbound app contains the link relation importProcessTarget, which you can use to create a batch.

Response

{
  "_links": {
    "importProcessTarget": {
      "href": "inbound/importprocess",
      "templated": false
    }
  }
}

You also need to determine the link relation for the following functions:

• Assigning batch permissions for users or groups
• Adding pages to a batch
• Finishing the import

Calling the URL for creating a batch

After you have determined the link relation, you can call the URL to create a batch. Perform an HTTP POST request to the URL with the required properties as the body.

Request

POST /inbound/importprocess
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json

{
  "name": "my batch 1",
  "batchProfile": "0017836e-a74a-4258-8cc4-7b0ab3ea6bb2",
  "propertiesUrl": "/app/url",
  "properties": {
    "sa.propertyKey1": "value",
    "propertyKey2": "another value"
  }
}

The name field is optional and does not have to be transferred. If you do not transfer the name field, the name of the batch is assigned automatically. You can assign an import profile to the batch using the parameter batchProfile. If you do not specify this parameter, the default profile will be assigned to the batch. You can also transfer advanced properties using the properties field. This field is optional and does not have to be transferred. You should use a unique prefix for the property keys to avoid naming conflicts with other apps. These keys are returned upon querying of properties and postprocessing options. For more information, see the section Querying the properties and postprocessing options. The advanced properties of the batch cannot be included during creation. Do not fill out the advanced properties when creating a batch. If properties with the ID of a property of the currently selected catalog are passed, they will be applied to the documents. Alternatively, a URL can be specified with the propertiesUrl parameter. The URL will be called by the InboundApp and provided properties, as well as the category if applicable, applied. If the call is successful, you receive a response with the URL for the created batch in the Location header and the properties of the batch in the body.

Response

HTTP/1.1 201 Created
Location: /inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb

{
  "id": "0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb"
}

For information on the parameters of the JSON object, see the section Retrieving a batch. If creation of the batch fails, a corresponding response is returned. For further information, see the section Format of the error responses.

Alternatively, you can create a batch with an HTTP GET request.

Request

/inbound/importprocess/new?BatchProfileId=ProfileID&Properties={"Property1ID":"Property1Value","Property2ID":"Property2Value",...}

You can assign an import profile to the batch using the parameter BatchProfileId. If you do not specify this parameter, a dialog that lets you select the import profile is displayed in the user interface.

Optionally, you can pass JSON-formatted document properties to the batch using the Properties parameter. If the passed property IDs are available in the currently selected catalog, they will be applied to the documents.

Determining the BatchProfileId

Use an HTTP GET request to call the root URL of the inbound app:

Request

GET /inbound
Accept: application/hal+json

The JSON object for the inbound app contains the link relation batchProfiles, which you can use to call all the import profiles.

Response

{
  "_links": {
    "batchProfiles": {
      "href": "/inbound/batchprofile",
      "templated": false
    }
  }
}

Calling the URL for requesting the import profiles

You can use the link relation for the import profiles to call the list of all the import profiles as follows:

Request

Get /inbound/batchprofile
Accept: application/hal+json

If the call is successful, the import profiles are returned in the body as JSON:

Response

HTTP/1.1 200 O

{
  "_links": {},
  "profiles": [
    {
      "batchProfileId": "0017836e-a74a-4258-8cc4-7b0ab3ea6bb2",
      "name": "My favorite profile"
    }
  ]
}

Retrieving a batch

You can retrieve the details and properties of a batch as a JSON representation or display the detail view for a batch. To do this, you must know the ID of the batch. To retrieve a batch, you must perform the following steps:

• Determine the link relation for retrieving the batch
• Call the URL for retrieving the batch

Determining the link relation for retrieving the batch

Use an HTTP GET request to call the root URL of the inbound app:

Request

GET /inbound
Accept: application/hal+json

The JSON object of the inbound app contains the link relation importProcess, which you can use to call a batch.

Response

{
  "_links": {
    "importProcess": {
      "href": "inbound/importprocess/{id}",
      "templated": true
    }
  }
}

Using parameters when retrieving a batch

You can use the following parameters to influence the retrieval or display the details for a batch:

Calling the URL for retrieving the batch properties

When you have generated a URL, you can retrieve the details of the batch as follows:

Request

Get /inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb
Accept: application/hal+json

If the call is successful, the properties of the batch are returned in the body as JSON:

Response

HTTP/1.1 200 Ok

{
  "id": "0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb",
  "name": "my batch 1",
  "importDateTime": "2019-01-28T10:46:25.0131376Z",
  "creatorId": "4a0df94e-da62-4f84-823b-2cc97b16341e",
  "creatorName": "John Doe",
  "pageCount": 0,
  "binaries": [],
  "documents": [
    {
      "id": "6f53d725-f4f5-442e-a058-a01eaf05cbf5",
      "binaries": [],
      "sortingNumber": 1,
      "_links": {
        "self": {
          "href": "/inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb/document/6f53d725-f4f5-442e-a058-a01eaf05cbf5",
          "templated": false
        }
      }
    }
  ],
  "_links": {
    "self": {
      "href": "/inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb",
      "templated": false
    },
    "fileUpload": {
      "href": "/inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb/blob",
      "templated": false
    },
    "authorization": {
      "href": "/inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb/authorization",
      "templated": false
    }
  }
}

Notes on the properties

If retrieval of the batch fails, a corresponding response is returned. For further information, see the section Format of error responses.

Calling the URL for batch details (HTML page)

If you want to call the HTML representation of the batch, you first have to generate the URL. For more information on generating the URL, see the section Determining the link relation for retrieving the batch.

Enter the URL in the browser to display the HTML page.

Request

GET /inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb
Accept: application/hal+json

Retrieving a document

You can retrieve the details and properties of a batch document as a JSON representation. To do so, you must know which documents a batch contains. To retrieve a document, you must perform the following steps:

• Determining and calling the link relation for retrieving the batch
• Determining the link relation for retrieving the document
• Calling the URL for retrieving the document

Determining and calling the link relation for retrieving a batch

For more information on determining and calling the link relation of the batch, see the section Retrieving a batch.

Determining the link relations for retrieving the document

The JSON object for the batch contains an array with all the included documents, each of which have a self link relation that you can use to retrieve the document.

Calling the URL for retrieving the document properties

Perform an HTTP GET request for the URL.

Request

Get /inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb/document/6f53d725-f4f5-442e-a058-a01eaf05cbf5
Accept: application/hal+json

If the call is successful, the properties of the document are returned in the body as JSON:

Response

HTTP/1.1 200 Ok

{
  "id": "6f53d725-f4f5-442e-a058-a01eaf05cbf5",
  "binaries": [],
  "sortingNumber": 1,
  "properties": [
    {
      "id": "069d1f97-ab46-4d17-a4ef-0408fc4f1289",
      "value": "RN-1847",
      "name": "Order number",
      "internal": false,
      "_links": {
        "self": {
          "href": "/inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb",
          "templated": false
        }
      }
    }
  ],
  "_links": {
    "self": {
      "href": "/inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb/document/6f53d725-f4f5-442e-a058-a01eaf05cbf5",
      "templated": false
    },
    "addProperty": {
      "href": "/inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb/document/6f53d725-f4f5-442e-a058-a01eaf05cbf5/properties",
      "templated": false
    },
    "deleteProperty": {
      "href": "/inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb/document/6f53d725-f4f5-442e-a058-a01eaf05cbf5/properties/{propertyId}",
      "templated": false
    },
    "patchProperty": {
      "href": "/inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb/document/6f53d725-f4f5-442e-a058-a01eaf05cbf5/properties",
      "templated": true
    }
  }
}

Notes on the properties

If the retrieval of the document fails, a corresponding response is returned. For further information, see the section Format of error responses.

Assigning batch permissions for users or groups

A user can only view and edit those batches for which they have permission. Initially, the person who created the batch is the only person with permission. If you have permissions for a batch, you can give other users and user groups permission to access the batch. Any user who is granted permission can view and edit the batch. You can query which permissions are currently assigned. To do this, you need the ID of the batch. The query request must be performed in the context of a user who already has permissions for the batch. Perform the following steps:

• Determine the link relation for retrieving a batch.
• Call the URL for retrieving a batch.
• Determine the link relation for querying and assigning permissions.
• Call the URL for querying and assigning permissions for the batch.

Determining and calling the link relation for retrieving a batch

To determine and call the link relation of the batch, proceed as described in the section Retrieving a batch.

Determining the link relation for querying and assigning permissions

The JSON object of the batch contains the link relation authorization, which you can use to define permissions for the batch.

Calling the URL for querying permissions for the batch

Perform an HTTP GET request for the URL.

Request

GET /inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb/authorization
Accept: application/hal+json

If the call is successful, the batch permissions are returned in the body as JSON:

Response

HTTP/1.1 200 Ok

{
  "authorizedUsers": ["UserId1", "UserId2"],
  "authorizedGroups": ["GroupId1", "GroupId2"]
}

Notes on the properties

If retrieval of the batch permissions fails, a corresponding response is returned. For further information, see the section Format of error responses.

To assign other users or user groups permissions to view and edit a batch, you must know the ID of the batch (as when querying the permissions). The request must be performed in the context of a user who has permissions for the batch. To assign one or more permissions for a batch, perform the following steps:

• Determine the link relation for querying and assigning permissions. For more information on determining the link relation, see the section Determining the link relation for retrieving the batch.
• Call the URL for querying and assigning permissions for the batch.

Calling the URL for assigning permissions for the batch

Perform an HTTP POST request with the required properties as body for this URL.

Request

POST /inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb/authorization
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json

{
  "authorizedUsers": ["UserId3", "UserId4"],
  "authorizedGroups": ["GroupId3", "GroupId4"]
}

Notes on the properties

You can specify any number of users or groups or a combination of both. At least one of the two arrays must receive a value. Observe the following when specifying users or groups:

• Users and groups that already have access to the batch are not added again.
• Upon transfer of a group ID, only the group is saved, not the members currently within the group. Therefore, if the members of the group later change, this also affects the access permissions of the batch.
• If users or groups that already have access to the batch are not included in the request, they will not have their batch permission withdrawn as a result of the request.

If the call is successful, HTTP status code 200 is returned. If configuration of the permissions fails, a corresponding response is returned. For further information, see the section Format of error responses.

Adding pages to a batch

You can add pages to a batch automatically. To do this, you must know the ID of the batch. The request must be performed in the context of a user who has permissions for the batch. To add one or more pages to a batch, perform the following steps:

• Determine the link relation for retrieving a batch.
• Call the URL for retrieving a batch.
• Determine the link relation for adding pages.
• Call the URL for adding pages.

You can add pages in two different ways:

• When you call the URL for adding pages, send a file in the body.
• When you call the URL for adding pages, send a link to a file in the body.

The following file types are supported:

• pdf
• tiff
• jpeg
• gif
• bmp
• png
• docx (cloud only)
• xlsx (cloud only)
• pptx (cloud only)
• msg (cloud only)
• eml (cloud only)
• xml (xRechnung and ZUGFeRD formats; cloud only)

Determining and calling the link relation for retrieving a batch

For more information on determining and calling the link relation of the batch, see the section Retrieving a batch.

Determining the link relation for adding pages

The JSON object of the batch contains the link relation fileUpload, which you can use to add pages to a batch.

Calling the URL for adding pages

If you want to send the file in the body, perform an HTTP POST request with the file in the body for this URL. You also have to enter the header value Content type accordingly. Alternatively, if you want to specify a link to the file, perform an HTTP POST request to this URL with the required properties as body.

Request

POST /inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb/blob
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/json
Content-Disposition: attachment; filename="ExampleName.pdf"

{
  "contentUri": "/myApp/files/6979814d-8dbe-4998-adc0-cc570a42fa92"
}

The file name of the Content-Disposition parameter is used as the display name of the document. The file name must be URI encoded and entered in the Content-Disposition parameter. The contentUri parameter is a mandatory parameter. The URL can be relative to the base address or absolute. If the URI is relative to the base address, the authentication information of the current user is forwarded. If the call is successful, the URL is returned for the added file in the Location header.

Response

HTTP/1.1 201 Created
Location: /inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb/blob/294c0d89-1e3f-4917-9b8e-32a42afa2954

If the adding of pages fails, a corresponding response is returned. For further information, see the section Format of error responses.

Adding properties to a document

You can automatically define and process document properties in a batch. To do this, you must know the ID of the batch. The request must be performed in the context of a user who has permissions for the batch. To add one or more properties to a document, perform the following steps:

• Determine the link relation for retrieving a batch.
• Call the URL for retrieving a batch.
• Determine the link relation for retrieving the available property fields.
• Call the URL for retrieving the available properties.
• Determine the link relation for retrieving the document whose properties you want to edit.
• Determine the link relations for adding, deleting or editing the property.
• Call the URL of the action that you want to perform.

Determining and calling the link relation for retrieving a batch

For more information on determining and calling the link relation of the batch, see the section Retrieving a batch.

Determining the link relations for retrieving the property fields

The JSON object of the batch contains the link relation propertyDefinition, which you can use to retrieve the available property fields in the inbound app.

Calling the URL for requesting the property fields

Perform an HTTP GET request for the URL.

Request

GET /inbound/propertydefinitions
Accept: application/hal+json

If the call is successful, the available property fields are returned in the body as JSON:

Response

HTTP/1.1 200 Ok

{
  "propertyDefinitions": [
    {
      "id": "069d1f97-ab46-4d17-a4ef-0408fc4f1289",
      "custom": false,
      "name": "Order number",
      "propertyType": 1
    },
    {
      "id": "0d36c8da-c5ef-4cd3-9e75-9a931dcb6c7a",
      "custom": false,
      "name": "Total amount",
      "propertyType": 2,
      "belongsTo": "66de5185-b270-4920-8f01-643a7ea4b7b1"
    },
    {
      "id": "66de5185-b270-4920-8f01-643a7ea4b7b1",
      "custom": false,
      "name": "Total amount currency",
      "propertyType": 5,
      "belongsTo": "0d36c8da-c5ef-4cd3-9e75-9a931dcb6c7a"
    }
  ]
}

Notes on the properties

Possible values for the “propertyType” property of a property field:

Determining and calling the link relation for retrieving a document

For more information about determining and calling the link relation of the document, see the section Retrieving a document.

Determine the link relations for adding, deleting or editing the property

Depending on what you want to do with the property, you require one of the following three link relations from the JSON object of the document:

• addProperty", which you can use to add a property to the document if it does not already contain this property.
• deleteProperty", which you can use to delete a property from a document if it contains this property.
• patchProperty", which you can use to edit the value of a document property if the document already contains this property.

Calling the URL for adding a property

Execute an HTTP POST request against the addProperty route.

Request

POST /inbound/importprocess/fcc8c956-bfcb-4b30-bc09-9161f6f16eb2/document/6f53d725-f4f5-442e-a058-a01eaf05cbf5/properties
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json

{
  "propertyDefinitionId": "069d1f97-ab46-4d17-a4ef-0408fc4f1289",
  "value": "RN-1857"
}

The field propertyDefinitionId must contain the ID of one of the property fields retrieved beforehand. The field value must contain the desired value as a string. The string must be formatted appropriately for the propertyType of the property field.

Response

HTTP/1.1 201 Created
Location: /inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb/6f53d725-f4f5-442e-a058-a01eaf05cbf5/properties/069d1f97-ab46-4d17-a4ef-0408fc4f1289

{
  "id": "069d1f97-ab46-4d17-a4ef-0408fc4f1289",
  "name": "Order number",
  "value": "value",
  "internal": false
}

Calling the URL for deleting a property

Replace the placeholder in the deleteProperty route with the ID of the property to be deleted and execute an HTTP DELETE request against the route.

Request

DELETE /inbound/importprocess/fcc8c956-bfcb-4b30-bc09-9161f6f16eb2/document/6f53d725-f4f5-442e-a058-a01eaf05cbf5/properties/069d1f97-ab46-4d17-a4ef-0408fc4f1289
Origin: https://baseuri
Accept: application/hal+json

Response

HTTP/1.1 200 OK

Calling the URL for editing a property

Execute an HTTP PATCH request against the patchProperty route to edit one or more properties at the same time.

Request

PATCH /inbound/importprocess/fcc8c956-bfcb-4b30-bc09-9161f6f16eb2/document/6f53d725-f4f5-442e-a058-a01eaf05cbf5/properties
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json

{
  "patches": [
    {
      "op": "REPLACE",
      "path": "0d36c8da-c5ef-4cd3-9e75-9a931dcb6c7a",
      "value": "123"
    },
    {
      "op": "REPLACE",
      "path": "66de5185-b270-4920-8f01-643a7ea4b7b1",
      "value": "EUR"
    }
  ]
}

The field patches contains an array of patch objects. The field patches.op contains the operation (always “REPLACE” here). The field patches.path must contain the ID of a property set for the document. The field patches.Value must contain the desired value as a string. The string must be formatted appropriately for the propertyType of the property field.

Response

HTTP/1.1 200 OK

Error Response If editing of the properties fails, a corresponding response is returned. For further information, see the section Format of error responses. If only individual request properties could not be changed, the response contains a list of the operations that were not executed successfully in addition to the usual fields. All the request properties that are not included in this list were changed successfully.

HTTP/1.1 400 BadRequest

{
  "reason": "Not all properties were updated: 0d36c8da-c5ef-4cd3-9e75-9a931dcb6c7a: Invoice is not a valid number.",
  "severity": 3,
  "errorCode": 0,
  "PatchErrors": {
    "0d36c8da-c5ef-4cd3-9e75-9a931dcb6c7a": "Invoice is not a valid number."
  }
}

The additional field PatchErrors is a dictionary with the IDs of the properties that were not processed successfully as the key and an associated error message as the value.

Changing category and name of a document

You can change the category as well as the name of a document. To do so, you need to know the batch id as well as the document id. The Request must be performed in the context of a user who has access to the batch you want to change.

• Determine the Linkrelation for accessing a batch.
• Call the URL to access the batch.
• Determine the linkrelation for changing the document.
• Change the document by calling the correct URL.

Determining and calling the linkrelation for a batch

Information on determining and calling the linkrelation of a batch can be found in the section Retrieving a batch

Determining the id for every category

To change the category, the id of the new category is needed. To determine the ids, you can get a list of all categories in your repository.

Request

GET /inbound/categories
Origin: https://baseuri
Accept: application/hal+json

Response

{
  "categories": [
    {
      "id": "dc144c5f-bd22-4f4f-92a8-338782db479c",
      "name": "Contract"
    }
  ]
}

Determining and calling the URL to change the document

Replace the placeholder from the documentUpdate route with the id of the document you want to change and perform a HTTP PATCH. The Id of the document can be found in the JSON of the batch.

Request

PATCH /inbound/importprocess/e69bb791-3a90-4ebf-bd9d-36d411886c92/document/62a2cd1c-26b9-45cf-897d-8de6ba46e0b8
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/json

{
  "patches": [
    {
      "op": "REPLACE",
      "path": "/category",
      "value": "c3dc3e4b-34d5-41cd-bb9e-755b3b5c62a0"
    },
    {
      "op": "REPLACE",
      "path": "/name",
      "value": "newname"
    }
  ]
}

Notes on the properties

Response

HTTP/1.1 200 OK

Error Response

If editing of the propertiy fails, a corresponding Response is returned. For further information, see the section Format of error responses.

HTTP/1.1 400 BadRequest

{
  "reason": "Path value '/invalidPath' is not valid.",
  "details": "Exception type: System.ArgumentException",
  "severity": 3,
  "errorCode": 0
}

Finishing the import

When you are done adding pages, you can finish the import. Once the import is complete and all individual pages have been analyzed, an analysis process for all documents begins. During the analysis process, the application automatically assigns categories to documents. When you finish importing a batch, it is locked against manual editing for the most part.

Determining and calling the link relation for retrieving a batch

For more information on determining and calling the link relation of the batch, see the section Retrieving a batch.

Determining the link relation for finishing the import

The JSON object of the batch contains the link relation update, which you can use to change the status of the batch with an HTTP PATCH request. To finish the import, use the value 1 for the value parameter.

Request

PATCH /inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/json

{
  "path": "/state",
  "Op": "REPLACE",
  "value": "1"
}

A response with status code 200 indicates that the call was successful.

Response

HTTP/1.1 200 OK

Connecting external systems

This section shows you how to connect external systems (third-party applications) to the inbound app in order to integrate additional target systems. Extension points enable you to add your own functions to the inbound app.

Preparing your app

To ensure the inbound app can find extensions, your app must provide this interface. To find apps that provide extensions, the inbound app uses the concept of an HTTP GET request for the root resource of the apps (systemBaseUri path with the app name). All apps that are registered on the HTTP gateway are queried. Make sure that the administrator has not actively excluded your app.

Providing the URL for the extension points

The root resources of these apps are requested cyclically. The response from an app is then checked to determine whether it contains a link relation called inboundExtensions. This link relation acts as a signal used by the app extensions for the inbound app. The inbound app performs an HTTP GET request for the specified link and waits for the app to return a standard JSON Object with HTTP status code 200.

Request

GET https://host/myapp/ HTTP/1.1
Accept: application/hal+json

Response

HTTP/1.1 200 OK
Content-Type: application/hal+json

{
  "_links": {
    "inboundExtensions": {
      "href": "/myapp/inboundExtensions"
    }
  }
}

The query of the root resources is performed anonymously (without authentication).

Adding export systems

You can add manual and automatic export systems. When you add a manual export system, this system is made available to your users as an option in the export wizard. Automatic export systems are used to store batches without user interaction.

Example

The example shows how you can format the HTTP response of the link relation inboundExtensions in order to add a manual and an automatic export system using the extension point.

Response

{
  "extensions": [
    {
      "id": "myapp-FileDownload",
      "caption": "Download file",
      "context": "ExportImportProcess",
      "uriTemplate": "/myapp/export",
      "activationConditions": [
        {
          "propertyId": "exportedDocuments.count",
          "operator": "OR",
          "values": ["2"]
        }
      ]
    },
    {
      "id": "myapp-AutomatedExport",
      "caption": "Automated export from myApp",
      "context": "ExportImportProcessAutomated",
      "uriTemplate": "/myapp/exportautomated"
    }
  ]
}

Notes on the properties

Possible values for the "propertyId" property of an activation condition:

Possible values for the "operator" property of an activation condition:

Calling the export system

The inbound app performs an HTTP POST request to the URL specified as the property (uriTemplate). The required properties are sent as the body.

Request

POST /myapp/export
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json

{
  "importProfileId": "62fd81f9-eb87-4461-9f3d-b1cd66bb5dde",
  "documents": [
    {
      "propertiesUri": "/inbound/importprocess/fcc8c956-bfcb-4b30-bc09-9161f6f16eb2/document/6f53d725-f4f5-442e-a058-a01eaf05cbf5/properties",
      "sourceFilesUri": "/inbound/importprocess/fcc8c956-bfcb-4b30-bc09-9161f6f16eb2/stored/505d86b1-0a21-45f3-8b1f-80112138b497/sourcefiles",
      "successCallbackUri": "/inbound/importprocess/fcc8c956-bfcb-4b30-bc09-9161f6f16eb2/stored/505d86b1-0a21-45f3-8b1f-80112138b497",
      "primaryExportFile": 2,
      "exportFiles": [
        {
          "downloadUrl": "/inbound/importprocess/fcc8c956-bfcb-4b30-bc09-9161f6f16eb2/blob/faf1de7e-467b-4c5f-9f33-1ab0fcc45013?ImportProcessId=fcc8c956-bfcb-4b30-bc09-9161f6f16eb2",
          "mimeType": "application/pdf",
          "extension": ".pdf"
        }
      ],
      "sourceSystem": "inboundApp"
    }
  ]
}

The HTTP POST request transfers a list of documents to the export system.

Notes on the properties

Export system response during manual storage

For a manual export system, the successful response of the export system to the HTTP POST request must return a URL to the export dialog of the export system as location header:

Response

HTTP/1.1 201 Created
Location: /myapp/downloadpage

Export system response during automatic storage

For automatic export, your export system must return for each document whether it was saved successfully. There are two options for doing so. As the first option, your export system can process the inbound app query synchronously and return the following result once the export is performed:

Response

HTTP/1.1 200 OK

{
  "storeResult": [
    {
      "location": "/myapp/location",
      "errorCode": 0,
      "message": ""
    }
  ]
}

Notes on the properties

Alternatively, your export system can carry out the storage process asynchronously. This is useful for avoiding timeouts during the export when processing large documents. To do so, your export system must answer the Calling the export system with the HTTP status 202 Accepted. In this case, the inbound app does not evaluate the contents of the response and waits for either the success callback or error callback to be invoked for each document.

Success callback invocation

POST /inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb/document/74e53fa9-d8fb-4769-85ff-0783902f3ba2/storesuccess?tokenId=f30dae4a-488e-441c-a8c7-95ed5421f6c2
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/json

{
  "location": "/myapp/location"
}

Notes on the properties

Error callback invocation

POST /inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb/document/91aba59a-cf40-4599-9a3d-792f36ccfdf6/storeerror?tokenId=ea1fb6cb-02f6-4fce-ae3d-bd18c7c3d0dd
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/json

{
  "message": "Error while storing",
  "errorCode": 123
}

Notes on the properties

Querying the properties and postprocessing options

To query the properties and postprocessing options of a document, perform an HTTP GET request for the URL stored as propertiesUri. For manual export, you must transfer the postprocessing options with the URL of the successCallbackUri property. Properties that are specified during batch creation are also listed in the response. For further information, see the section Creating a batch.

Request

GET /inbound/importprocess/fcc8c956-bfcb-4b30-bc09-9161f6f16eb2/document/6f53d725-f4f5-442e-a058-a01eaf05cbf5/properties
Accept: application/hal+json

The JSON object contains the following information:

Response

{
  "properties": [
    {
      "key": "creatorName",
      "values": ["Andrew Administrator"],
      "type": "String"
    },
    {
      "key": "importProcessname",
      "values": ["Batch name"],
      "type": "String"
    },
    {
      "key": "importProcessId",
      "values": ["2ae14919-6e90-4534-ad2b-2fbc79d3e51d"],
      "type": "String"
    },
    {
      "key": "importDateTime",
      "values": ["2019-01-01T12:00:00+02:00"],
      "type": "Datetime"
    },
    {
      "key": "documentName",
      "values": ["6f53d725-f4f5-442e-a058-a01eaf05cbf5"],
      "type": "String"
    },
    {
      "key": "documentCategoryId",
      "values": ["cb2ea8f9-9980-4ac7-9777-025173b2a5f1"],
      "type": "String"
    },
    {
      "key": "documentCategoryName",
      "values": ["E-Mail"],
      "type": "String"
    }
  ],
  "userData": [
    {
      "key": "deleteBatchUserData",
      "display": "Delete document after successful storage?",
      "values": [
        {
          "value": "delete",
          "display": "Delete document",
          "default": false
        },
        {
          "value": "notDelete",
          "display": "Keep document",
          "default": true
        }
      ]
    }
  ]
}

Notes on the properties

Possible data types for the "properties" property

Notes on the properties of a document

Transferring the postprocessing options

To transfer the postprocessing options to the inbound app for manual export, perform an HTTP POST request to the URL of the successCallbackUri property.

Request

POST /inbound/importprocess/fcc8c956-bfcb-4b30-bc09-9161f6f16eb2/stored/505d86b1-0a21-45f3-8b1f-80112138b497
Origin: https://baseuri
Content-Type: application/json

{
  "location": "/myapp/location",
  "userData": [
    {
      "key": "deleteBatchUserData",
      "values": ["notDelete"]
    }
  ]
}

Notes on the properties

Restricting export systems

By default, all export systems are displayed in export wizards. You can control whether manual export systems are displayed using a query parameter or a batch property.

Restricting the export system with a query parameter

To display only the export system with the ID myapp-FileDownload, call a batch with the following URL.

URL for an export system

/inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb?exportSystem=myapp-FileDownload

If the query parameter appears multiple times, all the specified export systems are displayed.

Restricting the export system with the batch property

To display only the export system with the ID myapp-FileDownload, you have to use the exportSystem property when creating the batch. When creating a batch with an HTTP POST request, you must use the batch property exportSystem.

Request

POST /inbound/importprocess
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json

{
  "name": "my batch 1",
  "properties": {
    "exportSystem": "myapp-FileDownload"
  }
}

Alternatively, you can also specify the batch property exportSystem when creating a batch with an HTTP GET request.

Request

/inbound/importprocess/new?exportSystem=myapp-FileDownload

Creating an export system with activation conditions

You can specify activation conditions when creating an export system. These conditions are taken into account when the export page is called. For more information, see the section Adding export systems.