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

Property	Description
reason	An optional short text for describing the cause of the error. This text is used as the title of the error message.
hint	An optional hint for the user with tips on error handling.
details	Optional detailed information on the error.
severity	Optional severity of the error. The following values are possible: Success = 0, Information = 1, Warning = 2, Error = 3
errorCode	An optional error code for internal identification.

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:

Property	Description
id	Specifies the ID of the batch for which you want to retrieve details.

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

Property	Description
id	Specifies the ID of the batch.
name	Specifies the display name of the batch.
importDateTime	Specifies the date and time when the batch was created. The time is specified in coordinated universal time (UTC).
creatorId	The ID of the identity provider user that created the batch.
creatorName	The current display name of the identity provider user that created the batch. If the user is deleted in the identity provider app, the name of the user at the creation time of the batch is returned.
pageCount	The current number of pages in the batch. Only pages that are currently visible in the batch are taken into account for this number.
binaries	Specifies an array with all pages of the batch. Deleted pages are also listed.
documents	Specifies an array with all the documents in the batch.
documents._links	Contains the link relations for the document.
documents._links.self	Self-link for the document.
_links	Contains the link relation for the batch.
_links.self	Self link.
_links.fileUpload	URL for adding files to a batch. For more information, see the section Adding pages to a batch.
_links.authorization	URL for querying and assigning the permissions for the batch.

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

Property	Description
id	Specifies the ID of the document.
binaries	Specifies an array with all the pages of the document.
sortingNumber	Specifies the one-based position of the document in the batch.
properties	Contains all the properties of the document.
properties.id	Specifies the ID of the property. For more information, see the section Adding properties to a document.
properties.value	Specifies the value for the property.
properties.name	Specifies the display name of the property.
properties.internal	Specifies whether the property is internal. Internal properties are intended only to be displayed for the user and cannot be edited.
_links	Contains the link relations for the document.
_links.self	Self link.
_links.addProperty	URL for adding properties to a document. For more information, see the section Adding properties to a document.
_links.deleteProperty	URL for deleting document properties. For more information, see the section Adding properties to a document.
_links.patchProperty	URL for editing one or more document properties. For more information, see the section Adding properties to a document.

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

Property	Description
authorizedUsers	Specifies an array with the identity provider user IDs that have permissions for the batch.
authorizedGroups	Specifies an array with the identity provider group IDs that have permissions for the batch.

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

Property	Description
authorizedUsers	Specifies the array with the identity provider user IDs that are to receive access to the batch.
authorizedGroups	Specifies the array with the identity provider group IDs that are to receive access to the batch.

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

Property	Description
id	Specifies the ID of the property. This ID can be used to read and edit the property on a document.
custom	Specifies whether the property was created by the administrator or the system.
name	Specifies the name of the property in the requested language.
propertyType	Specifies the data type of the property. You can find possible values in the table of available values for the propertyType property below.
belongsTo	An optional reference to a second linked property. For example, between a number field and a currency field, which are displayed together as a money value.

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

Value	Description
1	String: text value with a maximum of 450 characters.
2	Number: numeric value with a period as the decimal separator in a value range between ±1.0×10^-28 and ±7.9228 × 10^28.
3	Date: date value in the format yyyy-MM-dd.
4	DateTime: date and time value in the format yyyy-MM-ddTHH:mm:ss.fffzzz.
5	Currency: currency code with three characters as defined by ISO 4217.

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

Properties	Note
patches	Array of patch-objects
op	Operation of the patches, only use REPLACE
path	path which you want to change. /category or /name
value	New value as a string. When changing the id, the value must be the ID

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

Property	Description
id	Defines the unique technical name used to distinguish the extension from other extensions.
caption	Display text of the extension in the export wizard.
context	Specifies whether the export system is a manual or automatic export system. Specifies the value ExportImportProcess for a manual export system and the value ExportImportProcessAutomated for an automatic export system.
uriTemplate	Defines the URL to be called by the inbound app with the JSON object described below. No URL parameters are supported.
activationConditions (only available for manual export systems)	For each extension, the application communicates the activation conditions under which the manual export system should be displayed. An export system is displayed if all individual conditions are met. If there are no entries in the list of activation conditions, the export system is always active. If the contents of an activation condition are incorrect, the condition is also considered active. Activation conditions are entered as an array.
activationConditions.propertyId	Specifies the ID of the property to be checked for the activation condition. You can find possible values in the values table for the propertyId property below.
activationConditions.operator	The operator specifies how a single condition is evaluated. You can find possible values in the values table for the operator property below.
activationConditions.values	Specifies the values that are to be compared with the value of the propertyId property in the form of an array.

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

Value	Description
properties.name	The name of the current batch.
properties.creatorName	The name of the batch creator.
properties.importDateTime	The date the batch was created in ISO 8601 format.
properties.*	A batch property that you can define using the API. You have to replace the asterisk with the specified property. For more information, see the section Calling the URL for creating a batch.

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

Value	Description
OR	An OR condition is met if the current value of the property matches one of the values. It is not case sensitive.
NOTOR	A NOTOR condition is met if the current value of the property does not match any of the values. It is not case sensitive.
NOTEMPTY	A NOTEMPTY condition is met if the current value of the property is not empty.
GREATERTHAN	A GREATERTHAN condition is met if the current value of the property is greater than the initial value.
SMALLERTHAN	A SMALLERTHAN condition is met if the current value of the property is less than the initial value.

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

Property	Description
importProfileId	Indicates the ID of the import profile, which has been used to import the documents.
propertiesUri	Using the URL of property propertiesUri, you can query the property and postprocessing options of the document. The query as to whether you want to delete a document after the successful export is a possible postprocessing option. This option is communicated by the inbound app.
sourceFilesUri	You can use the URL of the property sourceFilesUri to determine the source files for the document. With an HTTP GET request, you receive a list of URLs. This list includes the files from which the document was produced. For certain processes, these files must be stored permanently.
originFilesUri	You can use the URL of the property originFilesUri to determine the imported files for the document. With an HTTP GET request, you receive a list of URLs. This list includes the files that the user imported and from which the source files for the document were produced, where applicable. For certain processes, these files must be stored permanently.
authorizationUri	You can use the URL of the property authorizationUri to determine the batch permissions for the document. You can use an HTTP GET request to retrieve the list described under Calling the URL for querying permissions for the batch. For certain processes, we recommend authorizing the same users for further processing.
successCallbackUri	During a manual export, you must notify the inbound app with the URL of the successCallbackUri property if the document was successfully saved by the export system. This call must be performed for every document. If you do not perform this step, the inbound app cannot evaluate the postprocessing options, thereby diminishing the user experience. For automatic export systems, the success callback needs to be invoked only if the storage process is performed asynchronously (see Export system response during automatic storage)).
errorCallbackUri	The URL of the errorCallbackUri property is available only with automatic storage. The error callback needs to be invoked only if the storage process is performed asynchronously (see Export system response during automatic storage)).
primaryExportFile	This parameter determines whether the generated file is provided in the original format or as a PDF. Depending on the profile you chose, the respective default value is used. The value 1 specifies the original format; the value 2 specifies a PDF format.
exportFiles	The application provides URLs via which each generated file can be called. The property downloadUrl contains the URL for the created file. The property mimeType describes the Internet media type, and the extension describes the specific file extension for the created file.
sourceSystem	Indicates the source system from which the document originates. You can use the property to query properties from other apps.

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

Property	Description
storeResult	You must specify whether each document that was transferred when the export system was called was processed successfully. For further information, see the section Calling the export system. With automatic storage, successfully exported documents are always deleted from the batch.
storeResult.location	Specifies the storage location of the document.
storeResult.message	In case of an error, you can provide a description of the error.

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

Property	Description
location	Specifies the storage location of the document.

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

Property	Description
message	In case of an error, you can provide a description of the error.

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

Property	Description
properties	List of properties.
properties.key	Property key.
properties.values	List of values.
properties.type	Data type that describes the property.
userData	List of postprocessing options.
userData.key	Property key.
userData.display	Display text.
userData.values	List of values.
userData.values.value	Value of the property.
userData.values.display	Display text.
userData.values.default	Definition of the default value.

Possible data types for the "properties" property

Data type	Description
String	Data type for character strings.
Datetime	Data type for time specified in ISO 8601 format.
Number	Data type for integer values and floating point numbers.

Notes on the properties of a document

Property	Description
creatorName	Name of the batch creator.
importProcessname	Name of the batch.
importProcessId	ID of the batch.
importDateTime	Batch creation time.
documentName	Name of the document.
documentCategoryId	ID of the document category.
documentCategoryName	Name of the document category.

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

Property	Description
location	The document storage location.
userData.key	Key of the postprocessing option.
userData.values	List of the selected values.

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.