Storing new DMS objects with user interaction

Released: HTML page

You can open the Storage feature to store new DMS objects with properties and files. Mappings are required before the action can be performed. In the Basic information about mapping chapter, you can find general information for helping you to create mappings.

Perform the following steps to store DMS objects:

  • Determine the link relation for the storage dialog

  • Provide the file to be stored (optional)

  • Create a storage dialog with predefined properties and files

  • Display the storage dialog with predefined properties and files

  • Perform more actions after storing (optional)

Determine the link relation for the storage dialog

There are two link relations for the Storage feature:

  • Link relation without reference to a d.3 repository: Storage without reference to a d.3 repository allows the user to select the d.3 repository. In this case, however, you cannot temporarily upload the file. For more information about providing files see Provision of files.

  • Link relation with reference to a d.3 repository: When storing with reference to a d.3 repository, the user is no longer able to change the d.3 repository.

To determine the link relation to a d.3 repository, execute an HTTP GET request for the REST resource /dms.

Request

GET /dms
Accept: application/hal+json

The JSON object contains the link relation new.

Response

{
    "_links": {
        "new": {
            "href": "/dms/new/"
        }
    }
}

You must know the repository URL in order to determine the link relation with reference to a d.3 repository. In the chapter Determining a repository, you can learn how to determine the URL for a repository. Then execute an HTTP Get request on the URL for a repository as follows:

Request

GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27
Accept: application/hal+json

The JSON object for a repository contains the link relation new.

Response

{
        "_links": {
                "new": {
                        "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/new/"
                }
        },
        "id": "dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27"
}

Provide the file to be stored (optional)

The Provision of files chapter explains how to obtain the contentUri or contentLocationUri. This parameter is required to create a storage dialog for a new DMS object.

If you want to create a dossier, you do not need to provide the file.

Create a storage dialog with predefined properties and files

Send an HTTP POST request with the required properties as the Body to the URL that you received in the new link relation. 

Request

POST /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/new
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json

{
    "storeObjects": [{
        "displayValue": "Please verify the XYZ invoice",
        "filename": "myfile.txt",
        "contentLocationUri": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/blob/chunk/2018-01-01_temp_master_file_user1_44f7-95a6-58b8400ecf43",
        "sourceId": "/myapp/sources/mysourcel",
                "sourceCategory": "mycategory1",
                "sourcePropertiesUri": "/myapp/sources/mysourcel/properties/myfile.haljson",
                "successCallbackUri": "/myapp/sources/mysourcel/success/myfile"
    },
    {
        ...
    }]
}

The JSON object that is transferred to POST is described as follows:

Property

Description

storeObjects

Specifies the array of item properties and files that should be used to define the storage dialog. For information about an item of the array, see Defining the parameters for storing.

To store a single DMS object, you can also specify the JSON object of the item properties without the storeObjects parent array.

If the call is successful, the URL is returned to the storage dialog in the Location header:

Response

HTTP/1.1 201 Created
Location: /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/new/a09dd457-5a21-4b90-8134-e562092b50ea

If creating the storage dialog fails, an appropriate response is displayed. For more information see Response format for errors.

Displaying the storage dialog with predefined properties and files

Open the URL that you received in the Location header in the browser to show the created storage dialog to the user. The user can edit the properties and complete the storage of the DMS objects.

Perform more actions after storing (optional)

The URL is opened if the successCallbackUri parameter is specified while creating the storage dialog and the user has successfully completed the storage process. You can perform additional steps after performing this action. For more information see Feedback using "SuccessCallback" and "Userdata".