Retrieving, saving and editing mapping

Released: JSON representation

In this chapter, you can learn how to create and manage mapping for properties and for the categories of a source system (for instance, an e-mail application) for a d.3 repository. This mapping is used for storage, for retrieving the details of an element and for retrieving and displaying the results of searches in d.3one integrations. When saving a mapping, you choose which external data (for instance, the properties of an e-mail) is assigned to which d.3 document property.

There can only be one unique mapping for each source in a source system.

The Defining a source system chapter explains how to create a source for mapping. In the Basic information about mapping chapter, you can find general information for helping you to create mappings. For useful information about write access, see Basic information about write access.

Determining the link relation for managing mapping

In the chapter Determining a repository, you can learn how to determine the URL for a repository. Then, execute an HTTP Get request for the REST resource 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 mappingconfig.

Response

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

Storing mapping

Send an HTTP POST request with the mapping for your source system as the Body for the URL that you received in the mappingconfig link relation. If the mapping is stored successfully, you receive the HTTP status code 201 Created.

Request

POST https://host/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/m HTTP/1.1
Origin: https://host
Accept: application/hal+json
Content-Type: application/hal+json

{
        name: "My Source",
        sourceId: "/myapp/sources/mysource",
        mappingItems: [{
                destination: "RECH",
                source: "mycategory1_ID",
                type: 1
        },
        {
                destination: "3",
                source: "myprop1_ID",
                type: 0
        },
        {
                destination: "property_caption",
                source: "myprop2_ID",
                type: 0
        }]
}

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

Property	Property of a contained object	Description
`name`	-	Specifies the name of the mapping.
`sourceId`	-	Indicates the unique identifier of the source. The ID must be a relative URI. The relative URI should start with the name of the app that provides the source system in order to ensure uniqueness (e.g. `/myapp/sources/mysource`).
`mappingItems`	-	Specifies the array with the mapping elements. This array maps the properties and categories from the source system to the properties and categories of the d.3 repository.
	`type`	Specifies the mapping element type. Possible values are: When the value is 0, the mapping element relates to a property. When the value is 1, the mapping element relates to a category.
	`source`	Specifies the ID of the property in the source system.
	`destination`	When you map a category, `destination` specifies the ID of the category in the d.3 repository. If you map a property, `destination` contains one of the following values: The advanced property ID as it is defined in the d.3 repository. `property_last_modified_date` `property_last_alteration_date` `property_editor` `property_remark1` `property_remark2` `property_remark3` `property_remark4` `property_owner` `property_caption` `property_filename` `property_filetype` `property_document_number` `property_variant_number` `property_creation_date` `property_size` `property_state` `property_access_date` `property_colorcode` When you want to specify the creation date (`property_creation_date`) of the DMS object, the specification of the property is only considered when a new DMS object is saved without any user interaction. For more information see Storing a new DMS object without user interaction. Please note that you can only specify d.3 properties as target that are assigned to at least one d.3 category as property.

Retrieving stored mapping

To retrieve the mapping, execute an HTTP GET request for the URL /dms/r/<RepositoryID>/m?sourceId=<SourceID>. The value of the sourceID property indicates the unique identifier of the source (for example, /myapp/sources/mysource).

Request

GET https://host/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/m?sourceId=%2Fmyapp%2Fsources%2Fmysource HTTP/1.1
Accept: application/hal+json

As the response, you receive the object with the stored mapping.

Response

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

{
        mappings: [{
                _links: {
                        self: {
                                href: "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/m/<MappingContainerID>"
                        }
                }
                name: "My Source",
                sourceId: "/myapp/sources/mysource",
                mappingItems: [{
                        destination: "RECH",
                        source: "mycategory1_ID",
                        type: 1
                },
                {
                        destination: "3",
                        source: "myprop1_ID",
                        type: 0
                },
                {
                        destination: "property_caption",
                        source: "myprop2_ID",
                        type: 0
                }]
        }]
}

The properties of the objects are the same properties as when the mappings are stored.

Deleting stored mapping

When you retrieve mapping for your source, you receive a link relation for each stored mapping (_links.self.href). For this URL, you can execute an HTTP Delete request to delete the mapping.

Request

DELETE https://host/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/m/<MappingContainerID> HTTP/1.1
Origin: https://host
Accept: application/hal+json

Editing stored mapping

When you retrieve mapping for your source, you receive a link relation for each stored mapping (_links.self.href). For this URL, you can execute an HTTP PUT request to update the map. The object that you transfer is the same as the object for storing mapping.

Request

PUT https://host/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/m/<MappingContainerID> HTTP/1.1
Origin: https://host
Accept: application/hal+json
Content-Type: application/hal+json

{
        name: "My Source",
        sourceId: "/myapp/sources/mysource",
        mappingItems: [{
                destination: "RECH",
                source: "mycategory1_ID",
                type: 1
        },
        {
                destination: "3",
                source: "myprop1_ID",
                type: 0
        },
        {
                destination: "property_caption",
                source: "myprop2_ID",
                type: 0
        }]
}

Deleting the current version of a DMS object without user interaction

Retrieving and saving the notes of a DMS object