SharePointAdapter app
Range of functions
The SharePointAdapter app connects your d.velop platform to Microsoft SharePoint.
Using the API functions
Below, you’ll learn how you can use the programmer interface in the SharePointAdapter app for your own developments.
Authentication
The SharePointAdapter app interfaces require valid authentication from the Identity provider app.
You can learn how to acquire such authentication from the API documentation for the Identity provider app. This is created via the user interface of your d.velop cloud tenants.
Defining a source system
If you have a system that provides source data (e.g. an e-mail application or an ERP system), you must prepare the source system items to create mapping for a Microsoft SharePoint repository. An item from a source system is known as a source. A source contains source properties and source categories. When you define a source, the SharePointAdapter app can connect the identifier for the source metadata with the identifiers for the Microsoft SharePoint repository metadata.
Preparing your app
Your app must provide the appropriate interface so that the SharePointAdapter app can find source systems. The SharePointAdapter app uses the concept of an HTTP GET request to detect apps that serve as source systems for the root resource of the apps (systembaseuri path with the app name). A query is made to every app registered to the gateway.
Providing the URL for the sources
The root resources for the apps are retrieved when you access the mapping. The SharePointAdapter app checks whether the link relation sources is contained in the response. If it contains this link relation, the app, operating as a source system, provides at least one source for the SharePointAdapter app. The SharePointAdapter app carries out an HTTP GET request on the link provided and waits for a standardized JSON object with the HTTP status code 200 from the responding app.
Request
GET /myapp
Accept: application/hal+json
Response
{
"_links": {
"sources": {
"href": "/myapp/sources"
}
}
}
Providing the sources
After the source URLs have been determined, the app sources will be retrieved using an HTTP GET request from the SharePointAdapter app
The example shows how you can configure the HTTP response to the link relation sources to communicate the sources to the SharePointAdapter app.
Request
GET /myapp/sources
Accept: application/hal+json
Response
{
"sources" : [{
"id" : "/myapp/sources/mysource",
"displayName" : "My Source",
"categories": [{
"key": "mycategory1",
"displayName": "My category 1"
},
{
"key": "mycategory2",
"displayName": "My category 2"
}],
"properties" : [{
"key" : "myprop1",
"displayName" : "My property 1"
},
{
"key" : "myprop2",
"displayName" : "My property 2"
},
{
"key" : "myprop3",
"displayName" : "My property 3"
}]
}]
}
Structure of a source
| Property | Property of an included object | Description |
|---|---|---|
| sources | - | The source system can deliver several sources in this array (e.g. e-mail, attachments, etc.) in order to differentiate between the various types of mapping. |
| id | Specifies the unique source identifier. The ID must be a relative URI. To ensure clarity, the relative URI should start with the name of the app being supplied by the source system (e.g. /myapp/sources/mysource). | |
| displayName | Specifies the display name as it is shown on the administration interface Mapping in the field Source. The DMSApp uses the HTTP header Accept-Language for internationalization. This HTTP header must be evaluated by the source system and the source display name must be displayed in the specific language. | |
| categories | The array specifies the source categories being made available for mapping management and processing. | |
| properties | The array specifies the source properties being made available for mapping management and processing. |
Structure of a source category
| Property | Description |
|---|---|
| key | Specifies the unique source category identifier. |
| displayName | Specifies the display name as it is shown on the administration interface Mapping in the area Categories in the field Source. The DMSApp uses the HTTP header Accept-Language for internationalization. This HTTP header must be evaluated by the source system and the category display name must be displayed in the specific language. |
Structure of a source property
| Property | Description |
|---|---|
| key | Specifies the unique source property identifier. |
| displayName | Specifies the display name as it is shown on the administration interface Mapping in the area Properties in the field Source. The DMSApp uses the HTTP header Accept-Language for internationalization. This HTTP header must be evaluated by the source system and the property display name must be displayed in the specific language. |
Saving a new file (DMS object)
You can use this function to save files (DMS objects) in Microsoft SharePoint.
Complete the following steps to save a new DMS object:
- Determine the URL for a repository
- Determine the link relation to save a new DMS object
- Provide the new file
- Open the URL to save a new DMS object
Determining the URL for a repository
You need the repository ID to implement your own functions. With the SharePointAdapter app, you have the option of accessing multiple Microsoft SharePoint website libraries if you have configured multiple repositories.
Complete the following steps to determine which repositories have been set up:
- Determine the link relation to retrieve the list of repositories
- Retrieve the list of repositories
Determining the link relation to retrieve the list of repositories
The URL for a repository is available as a link relation in the response to the HTTP GET request.
Request
GET /sharepointadapter
Accept: application/hal+json
Response
{
"_links": {
"repo": {
"href": "/sharepointadapter/r/{repositoryid}",
"templated": true
}
}
}
Retrieving the list of repositories
You need the repository ID in order to be able to access repository-specific functions.
Replace the placeholder {repositoryid} in the URL /sharepointadapter/r/{repositoryid} with the repository ID. If you do not know the repository ID, retrieve the URL in the following way:
Request
GET /sharepointadapter/r
Accept: application/hal+json
In the response, you receive an array of repositories. The repository ID is listed as the property id and the display name is listed as the property name for each repository. You also receive some additional information regarding the configured repository.
Response
{
"repositories":[
{
"id": "d7f0a5a2-72d5-439d-8ea4-92958d77ba4d",
"name": "MyCompany SharePoint - ExampleSite",
"host": "https://mycompany.sharepoint.com",
"clientId": "e5a8e525-febf-4c88-bdb5-f67a680cd424",
"tenantId": "3324857c-429f-4aa1-bea3-a53d6d199b4a",
"siteCollection": {
"title": "ExampleSite",
"path": "https://mycompany.sharepoint.com/sites/ExampleSite",
"siteName": "https://mycompany.sharepoint.com/sites/ExampleSite"
}
},
...
]
}
If you already know the repository ID, you can replace the placeholder {repositoryid} in the URL /sharepointadapter/r/{repositoryid} with the repository ID. If you retrieve the URL with the repository ID, you get the following result:
Request
GET /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d
Accept: application/hal+json
The JSON object in the response is the same object as in the JSON objects list from the request to the URL /sharepointadapter/r.
Response
{
"id": "d7f0a5a2-72d5-439d-8ea4-92958d77ba4d",
"name": "MyCompany SharePoint - ExampleSite",
"host": "https://mycompany.sharepoint.com",
"clientId": "e5a8e525-febf-4c88-bdb5-f67a680cd424",
"tenantId": "3324857c-429f-4aa1-bea3-a53d6d199b4a",
"siteCollection": {
"title": "ExampleSite",
"path": "https://mycompany.sharepoint.com/sites/ExampleSite",
"siteName": "https://mycompany.sharepoint.com/sites/ExampleSite"
}
}
Determining the link relation to save a new DMS object
Retrieving the URL for a repository as follows:
Request
GET /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d
Accept: application/hal+json
The JSON object for a repository contains the link relation dmsobjectwithmapping.
Response
{
"_links": {
"dmsobjectwithmapping": {
"href": "/sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/o2m",
"templated": false
}
},
"id": "d7f0a5a2-72d5-439d-8ea4-92958d77ba4d",
"name": "MyCompany SharePoint - ExampleSite",
"host": "https://mycompany.sharepoint.com",
"clientId": "e5a8e525-febf-4c88-bdb5-f67a680cd424",
"tenantId": "3324857c-429f-4aa1-bea3-a53d6d199b4a",
"siteCollection": {
"title": "ExampleSite",
"path": "https://mycompany.sharepoint.com/sites/ExampleSite",
"siteName": "https://mycompany.sharepoint.com/sites/ExampleSite"
}
}
Providing the file to be saved
If you cannot provide your file with a prefixed URL, you can provide the file temporarily via the SharePointAdapter app. Using the URL for the temporarily uploaded file, you can then save the DMS object.
To temporarily upload a file, perform the following steps:
- Determine the URL for a repository
- Determine the link relation for a temporary file upload
- Open the URL for a temporary file upload
- Upload the temporary file
info: It is only possible to temporarily upload a file by indicating a repository ID.
Determining the URL for a repository
The URL for a repository is available as a link relation in the response to the HTTP GET request.
Request
GET /sharepointadapter
Accept: application/hal+json
Response
{
"_links": {
"repo": {
"href": "/sharepointadapter/r/{repositoryid}",
"templated": true
}
}
}
Determining the link relation for a temporary file upload
Retrieving the URL for a repository as follows:
Request
GET /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d
Accept: application/hal+json
The JSON object for a repository contains the link relations filecache and filecachemultipart.
Response
{
"_links": {
"filecache": {
"href": "/sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/cache",
"templated": false
},
"filecachemultipart":{
"href": "/sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/cache/multipart",
"icon": "",
"templated": false
}
},
"id": "d7f0a5a2-72d5-439d-8ea4-92958d77ba4d"
}
Opening the URL for a temporary file upload
Carry out an HTTP POST request to the URL you received in the link relation filecache. If the process was successful, you receive the HTTP status code 201 and the URL (contentLocationUri) in the HTTP header Location.
Request
POST /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/cache
Origin: https://baseuri
Response
HTTP/1.1 201 Created
Location: <Presigned-URL from AWS S3>
The link is required for the subsequent upload of the temporary file and as the URI for the storage of a new DMS object. The link is valid for 15 minutes. It will not be possible to upload using the specified URL once this time has expired.
Uploading the temporary file
Carry out an HTTP PUT request to the URL you received as the location, using the binary data as the body. If the process was successful, you receive the HTTP status code 200.
Request
PUT <Presigned-URL from AWS S3>
Origin: https://baseuri
<binary content>
Response
HTTP/1.1 200 OK
All content in the body will be treated as binary data from the uploaded file for the HTTP PUT request. It is not currently possible to upload using the multipart/form-data method.
Opening the URL for a temporary file upload utilizing several requests
Carry out a HTTP POST request to the URL you recieved in the link relation filecachemultipart.
Request
POST /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/cache/multipart
Origin: https://baseuri
Accept: application/json
Response
HTTP/1.1 201 Created
{
"_links":{
"multipartuploadurl":{
"href": "/sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/cache/multipart/<uploadId>/{part}",
"icon": "",
"templated": true
},
"completemultipartupload":{
"href": "/sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/cache/multipart/<uploadId>/complete",
"icon": "",
"templated": false
},
"abortmultipartupload":{
"href": "/sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/cache/multipart/<uploadId>/abort",
"icon": "",
"templated": false
}
},
"uploadId": "..."
}
| Property | Description |
|---|---|
| _links | Contains link relations for the item. |
| _links.multipartuploadurl | Relative URL for creating an upload URL for file parts. |
| _links.completemultipartupload | Relative URL for finishing the upload after all file parts have been uploaded successfully. |
| _links.abortmultipartupload | Relative URL for aborting the upload process. |
| uploadId | The unique id for the upload process. |
Uploading file parts
Carry out an HTTP GET request to the URL you received in the link relation multipartuploadurl. The last part of the url () is a placeholder which needs to be replaced by the part number of the file part.
Request
GET /sharepointadapter/r/5cdc40e2-f380-4c4e-9ba8-5026bae20dfd/cache/multipart/<uploadId>/1
Origin: https://baseuri
Response
HTTP/1.1 201 Created
Location: <Presigned-URL from AWS S3>
The upload url will be valid for 15 minutes after it has been created. Repeat the process until all of your file parts have been uploaded successfully.
Upload a file part
Carry out an HTTP PUT request to the URL you received as the location, using the binary data as the body. If the process was successful, you receive the HTTP status code 200.
Request
PUT <Presigned-URL from AWS S3>
Origin: https://baseuri
<binary content>
Response
HTTP/1.1 200 OK
ETag: as77e89a455d8c8e5d5x
Save the ETag value from the Header. It belongs to the number of the file part, which has been specified in the request for Uploading file parts and will be needed for finishing the upload process.
Finishing the multipart upload process
Carry out an HTTP POST request to the URL you received in the link relation completemultipartupload. Within the body, specify all file part numbers and the associated ETags.
Request
POST /sharepointadapter/r/5cdc40e2-f380-4c4e-9ba8-5026bae20dfd/cache/multipart/<uploadId>/complete
Origin: https://baseuri
{
"parts": [
{
"partNumber": 1,
"eTag": "as77e89a455d8c8e5d5x"
},
...
]
}
| Property | Type | Description | Obligation |
|---|---|---|---|
| parts | Array | List of all uploaded file parts. | Yes |
| parts.partNumber | Integer | The number of the file part. | Yes |
| parts.eTag | String | The ETag of the associated number from the upload of the file part. | Yes |
Response
HTTP/1.1 201 Created
Location: <Presigned-URL from AWS S3>
The Location header of the response contains the url which can be used for downloading the file. It is valid for 15 Minutes after the upload process has been completed.
Aborting the multipart upload process
Carry out an HTTP POST request to the URL you received in the link relation abortmultipartupload.
Request
POST /sharepointadapter/r/5cdc40e2-f380-4c4e-9ba8-5026bae20dfd/cache/multipart/<uploadId>/abort
Origin: https://baseuri
Response
HTTP/1.1 200 OK
Opening the URL to store a new DMS object
Carry out an HTTP POST request to this URL, using the required properties as the body.
Request
POST /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/o2m
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/json
{
"contentUri": "https://your.presigned.URL.to.the.file",
"filename": "UploadedFile.txt",
"sourceId": "/myapp/sources/mysource",
"sourceCategory": "mycategory1",
"sourceProperties": {
"properties": [{
"key": "myprop1",
"values": ["Please verify the XYZ invoice"]
},
{
"key": "myprop2",
"values": ["Name1@contoso.com","Name2@samplecompany.de"]
}
]
}
}
| Property | Type | Description | Obligation |
|---|---|---|---|
| contentUri | String | Specifies the URL from which the SharePointAdapter app downloads the file. | Yes |
| filename | String | Specifies the name of the file to be saved with the file extension. | Yes |
| sourceId | String | Specifies the source to which the mapping that is to be used for saving pertains. The source has to exist so that the properties under sourceProperties are applied. | Yes |
| sourceCategory | String | Specifies which category is to be used for mapping processing when saving. Specify the source category ID for this property. | Yes |
| sourceProperties | String | Specifies the JSON array with source properties that are used for mapping processing. | Yes |
| sourceProperties.properties.key | String | Specifies the source property ID. Only the properties that have been specified by you and set up by the administrator in the mapping are taken into consideration. | Yes |
| sourceProperties.properties.values | String | Specifies an array with the associated item property values. Even if you only want to transfer one value, you must transfer this value as a JSON array. | Yes |
As a response, you receive the link to the generated DMS object in the location header:
Response
HTTP/1.1 201 Created
Location: /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/o2m/<DMS-Object-ID>
Opening the URL to store a new DMS object without mapping
You can also perform an upload without configured mapping. In this case, you provide the information specified in the mapping directly in the request.
Carry out an HTTP POST request to this URL, using the required properties as the body.
Request
POST /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/o2m
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/json
{
"contentUri": "https://your.presigned.URL.to.the.file",
"filename": "UploadedFile.txt",
"sourceCategory": "mycategory1",
"sourceProperties": {
"properties": [{
"key": "myprop1",
"values": ["Please verify the XYZ invoice"]
},
{
"key": "myprop2",
"values": ["Name1@contoso.com","Name2@samplecompany.de"]
}
]
},
"destination": {
"Source": "SourceName",
"DestinationSite": {
"Path": "https://url.of.the.sharepoint/site"
},
"DestinationLibrary": {
"Id": "Library Guid",
"Type": 1,
"IsCheckOutRequired": false
},
"DestinationContentType": {
"Id": "ContentType Id",
}
}
}
| Property | Type | Description | Obligation |
|---|---|---|---|
| contentUri | String | Specifies the URL from which the SharePointAdapter app downloads the file. | Yes |
| filename | String | Specifies the name of the file to be saved with the file extension. | Yes |
| sourceId | String | Specifies the source to which the mapping that is to be used for saving pertains. The source has to exist so that the properties under sourceProperties are applied. | Yes |
| sourceCategory | String | Specifies which category is to be used for mapping processing when saving. Specify the source category ID for this property. | Yes |
| sourceProperties | String | Specifies the JSON array with source properties that are used for mapping processing. | Yes |
| sourceProperties.properties.key | String | Specifies the source property ID. Only the properties that have been specified by you and set up by the administrator in the mapping are taken into consideration. | Yes |
| sourceProperties.properties.values | String | Specifies an array with the associated item property values. Even if you only want to transfer one value, you must transfer this value as a JSON array. | Yes |
| destination | String | Specifies a JSON array with additional information about the storage location. | Yes |
| destination.Source | String | Specifies the name of the source type, for example SalesOrderConfirmation | Yes |
| destination.DestinationSite | String | Specifies a JSON array with additional information about the Microsoft SharePoint site to which the document will be uploaded. | Yes |
| destination.DestinationSite.Path | String | Specifies the URL to the Microsoft SharePoint site, for example https://url.of.the.sharepoint/site | Yes |
| destination.DestinationLibrary | String | Specifies a JSON array with additional information about the Microsoft SharePoint document library to which the document will be uploaded. | Yes |
| destination.DestinationLibrary.Id | String | Specifies the Microsoft SharePoint GUID of the Microsoft SharePoint document library to be used. | Yes |
| destination.DestinationLibrary.Type | String | Specifies the type of document library. | Yes |
| destination.DestinationLibrary.IsCheckOutRequired | String | Specifies whether the document must be checked out. | Yes |
| destination.DestinationContentType | String | Specifies a JSON array with additional information about the Microsoft Sharepoint content type. | Yes |
| destination.DestinationContentType.Id | String | Specifies the ID of the Microsoft SharePoint content type to be used. | Yes |
As a response, you receive the link to the generated DMS object in the location header:
Response
HTTP/1.1 201 Created
Location: /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/o2m/<DMS-Object-ID>
Creating a new list item
You can use this function to create a list item in SharePoint.
Carry out the following steps:
- Determine the URL for a repository
- Determine the link relation to create a new list item
- Open the URL to create a list item
Determine the link relation to create a new list item
Retrieving the URL for a repository as follows:
Request
GET /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d
Accept: application/hal+json
The JSON object for a repository contains the link relation dmsobjectwithmapping.
Response
{
"_links": {
"dmsobjectwithmapping": {
"href": "/sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/o2m",
"templated": false
}
},
"id": "d7f0a5a2-72d5-439d-8ea4-92958d77ba4d",
"name": "MyCompany SharePoint - ExampleSite",
"host": "https://mycompany.sharepoint.com",
"clientId": "e5a8e525-febf-4c88-bdb5-f67a680cd424",
"tenantId": "3324857c-429f-4aa1-bea3-a53d6d199b4a",
"siteCollection": {
"title": "ExampleSite",
"path": "https://mycompany.sharepoint.com/sites/ExampleSite",
"siteName": "https://mycompany.sharepoint.com/sites/ExampleSite"
}
}
Opening the URL to create a list item
Carry out an HTTP POST request to the following URL, using the required properties as the body:
Request
POST /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/o2m
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/json
{
"sourceId": "/myapp/sources/mysource",
"sourceCategory": "mycategory1",
"sourceProperties": {
"properties": [
{
"key": "myprop1",
"values": ["Please verify the XYZ invoice"]
},
{
"key": "myprop2",
"values": ["Name1@contoso.com","Name2@samplecompany.de"]
}
]
}
}
| Property | Type | Description | Obligation |
|---|---|---|---|
| sourceId | String | Specifies the source to which the mapping that is to be used for saving pertains. The source has to exist so that the properties under sourceProperties are applied. | Yes |
| sourceCategory | String | Specifies which category is to be used for mapping processing when saving. Specify the source category ID for this property. | Yes |
| sourceProperties | String | Specifies the JSON array with source properties that are used for mapping processing. | Yes |
| sourceProperties.properties.key | String | Specifies the source property ID. Only the properties that have been specified by you and set up by the administrator in the mapping are taken into consideration. | Yes |
| sourceProperties.properties.key | String | Specifies an array with the associated item property values. Even if you only want to transfer one value, you must transfer this value as a JSON array. | Yes |
As a response, you receive the link for creating a list item in the location header:
Response
HTTP/1.1 201 Created
Location: /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/o2m/<List-Item-ID>
Updating an existing item
You can use this function to update a DMS object that already exists in Microsoft SharePoint and retroactively adjust the metadata.
Opening the URL to adjust an existing item
Carry out an HTTP PUT request to the following URL, using the required properties as the body. You receive the URL in the location header of the response when you create a DMS object.
Request
PUT /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/o2m/<List-Item-ID>
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/json
{
"sourceId": "/myapp/sources/mysource",
"sourceCategory": "mycategory1",
"sourceProperties": {
"properties": [
{
"key": "myprop1",
"values": ["Please verify the XYZ invoice"]
},
{
"key": "myprop2",
"values": ["Name1@contoso.com","Name2@samplecompany.de"]
}
]
}
}
| Property | Type | Description | Obligation |
|---|---|---|---|
| sourceId | String | Specifies the source to which the mapping that is to be used for saving pertains. The source has to exist so that the properties under sourceProperties are applied. The value for this is taken from the DMS-Object Location, if the location contains this information. Old locations may not contain this information and require the specification of the sourceId in the body as property. If the sourceId is defined as a property in the body and by the DMS-Object Location, the property in the body has priority. | No |
| sourceCategory | String | Specifies which category is to be used for mapping processing when saving. Specify the source category ID for this property. The value for this is taken from the DMS-Object Location, if the location contains this information. Old locations may not contain this information and require the specification of the sourceCategory in the body as property. If the sourceCategory is defined as a property in the body and by the DMS-Object Location, the property in the body has priority. | No |
| sourceProperties | String | Specifies the JSON array with source properties that are used for mapping processing. | Yes |
| sourceProperties.properties.key | String | Specifies the source property ID. Only the properties that have been specified by you and set up by the administrator in the mapping are taken into consideration. | Yes |
| sourceProperties.properties.key | String | Specifies an array with the associated item property values. Even if you only want to transfer one value, you must transfer this value as a JSON array. | Yes |
As a response, you receive the link to the adjusted DMS object in the location header as well as the status 200:
Response
HTTP/1.1 200 OK
Location: /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/o2m/<List-Item-ID>
Retrieving the results of a search operation (DMS object)
When you retrieve the results of a search operation, you can limit the number of results by specifying a specific source and the associated source categories and source properties. You can also use a full text keyword to filter the search results.
To retrieve the results of a search operation, complete the following steps:
- Determine the URL for a repository
- Determine the link relation to retrieve the results of a search operation
- Specify behavioral parameters
- Open the URL for the results of a search operation
Determining the link relation to retrieve the results of a search operation
Retrieving the URL for a repository as follows:
Request
GET /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d
Accept: application/hal+json
The JSON object for a repository contains the link relation searchresultwithmapping.
Response
{
"_links": {
"searchresultwithmapping": {
"href": "/sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/srm",
"templated": false
}
},
"id": "d7f0a5a2-72d5-439d-8ea4-92958d77ba4d",
"name": "MyCompany SharePoint - ExampleSite",
"host": "https://mycompany.sharepoint.com",
"clientId": "e5a8e525-febf-4c88-bdb5-f67a680cd424",
"tenantId": "3324857c-429f-4aa1-bea3-a53d6d199b4a",
"siteCollection": {
"title": "ExampleSite",
"path": "https://mycompany.sharepoint.com/sites/ExampleSite",
"siteName": "https://mycompany.sharepoint.com/sites/ExampleSite"
}
}
Specifying behavioral parameters
Carry out an HTTP GET request to this URL with the required parameters.
Request
GET /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/srm?sourceid=/myapp/sources/mysource&sourceproperties={"myprop1":["Test E-Mail 1"]}&sourcecategories=["mycategory1"]&sourcepropertysort=myprop1&ascending=true&fulltext=test&page=1&pagesize=50
Accept: application/hal+json
| Parameter | Type | Description | Obligation |
|---|---|---|---|
| sourceid | String | Specifies the source to which the mapping to be used for the search pertains. The source has to exist so that the properties under sourceproperties are applied. | Yes |
| sourceProperties | String | Specifies search conditions based on properties from the source’s point of view. Search conditions are expected as a JSON object. Specify the mapped source property ID to limit the search operation to any number of criteria. Example: sourceproperties={"<ID_ source proptery1>":["<search refiner 1>", "<search refiner 2>"],"<ID_source proptery2>":["search refiner 3"]} | No |
| sourcecategories | String | Specifies a JSON array with source categories to search in. Example: sourcecategories=["mycategory1","mycategory2"] | No |
| sourcepropertysort | String | Specifies the mapped source property ID to sort by. If no sort order property is specified, the sorting is done as per the standard sorting order using the sorting criteria Last modified. | No |
| ascending | Bool | Specifies the sort order direction. ascending=true means results are sorted in ascending order (from small to large (A-Z) and from old to new). ascending=false: this means that results are sorted in descending order (from large to small (Z-A) and from new to old). If you do not specify an ascending parameter, the results will be sorted in descending order. | No |
| fulltext | String | Specifies a full text keyword. | No |
| page | Integer value | Specifies which page of the result list is requested. If you do not submit any parameters, page 1 will be requested. | No |
| pagesize | Integer value | Specifies how many items are shown per page. If you do not submit any parameters, 100 items per page will be requested. | No |
The following JSON object is returned as a result: Response
{
"_links": {
"next": {
"href": "/sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/srm?...page=2"
},
"self": {
"href": "/sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/srm?...page=1"
}
},
"page": 1,
"items": [
{
"_links": {
"self": {
"href": "/sharepointadapter/show?..."
},
"download": {
"href": "/sharepointadapter/search/download?..."
},
"preview": {
"href": "/sharepointadapter/redirect_to_document?..."
},
"edit": {
"href": "/sharepointadapter/redirect_to_document?..."
},
"openInLocation": {
"href": "/sharepointadapter/redirect_to_document?..."
}
},
"id": "<DMS-Object-ID>",
"sourceProperties": [
{
"key": "myprop1",
"value": "Test E-Mail 1",
"isMultiValue": false
},
{
"key": "myprop2",
"value": "John Smith",
"isMultiValue": false
},
"..."
],
"sourceCategories": [ "mycategory1" ]
},
"..."
]
}
| Property | Description |
|---|---|
| _links | Contains link relations for the item. |
| _links.self | Selt-link. |
| _links.next | Relative URL to retrieve the next page of the result list. This is only shown if there are more results. |
| _links.prev | Relative URL to retrieve the previous page of the result list. This is only shown if there are previous results. |
| page | Specifies the result list page number. |
| items | Specifies the array with search operation results items for the requested page. |
Structure of an item in the result list
| Property | Description |
|---|---|
| _links | Contains link relations for the item. |
| _links.self | Relative URL to open the preview. |
| _links.download | Relative URL for downloading the content. |
| _links.preview | Relative URL to open preview in SharePoint. |
| _links.edit | Relative URL to open the edit in SharePoint. |
| _links.openInLocation | Relative URL to open the location in SharePoint. |
| id | Specifies the item’s DMS object ID. |
| sourceProperties | Specifies the array with source properties that are available for the item. If the same source property has been mapped to multiple SharePoint properties and the item has these properties, the source property is returned multiple times with the respective values for the SharePoint property. |
| sourceCategories | Specifies the array with source category IDs that are available for the item. Multiple categories are only returned if multiple source categories have been mapped to the content type of the item. |
Structure of a source property
| Property | Description |
|---|---|
| key | Specifies the unique source property identifier. |
| value | Specifies the value of the mapped property. |
| isMultiValue | Specifies whether the mapped SharePoint property is a multi-value property. |
Calling the URL for the details of a DMS object (JSON representation)
If you have successfully created a DMS-Object, then the details of the DMS-Object can be retrieved as follows:
GET /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/<DMS-Object-ID>?sourceid=/myapp/sources/mysource
Accept: application/json
The following JSON object is returned as a result:
Response
{
"_links": {
"self": {
"href": "/sharepointadapter/r/.../o2m/...",
"icon": "",
"templated": false
},
"update": {
"href": "/sharepointadapter/r/.../o2m/...",
"icon": "",
"templated": false
},
"move": {
"href": "/sharepointadapter/r/.../o2m/.../move",
"icon": "",
"templated": false
},
"mainblobcontent": {
"href": "/sharepointadapter/search/download?...",
"icon": "",
"templated": false
},
"openInLocation": {
"href": "/sharepointadapter/redirect_to_document?...",
"icon": "",
"templated": false
},
"preview": {
"href": "/sharepointadapter/redirect_to_document?...",
"icon": "",
"templated": false
},
"edit": {
"href": "/sharepointadapter/redirect_to_document?...",
"icon": "",
"templated": false
}
},
"id": "<DMS-Object-ID>",
"sourceCategories": [
"mycategory1"
],
"sourceProperties": [
{
"key": "myprop1",
"value": "Please verify the XYZ invoice"
},
{
"key": "myprop2",
"value": "Name1@contoso.com"
}
]
}
| Property | Description |
|---|---|
| _links | Contains link relations for the item. |
| _links.self | Relative URL to the own element. |
| _links.update | Relative URL to update the element. |
| _links.move | Relative URL to mode the element. |
| _links.mainblobcontent | Relative URL for downloading the content. |
| _links.preview | Relative URL to open preview in SharePoint. |
| _links.edit | Relative URL to open the edit in SharePoint. |
| _links.openInLocation | Relative URL to open the location in SharePoint. |
| id | Specifies the item’s DMS object ID. |
| sourceCategories | Specifies the array with source category IDs that are available for the item. Multiple categories are only returned if multiple source categories have been mapped to the content type of the item. |
| sourceProperties | Specifies the array with source properties that are available for the item. If the same source property has been mapped to multiple SharePoint properties and the item has these properties, the source property is returned multiple times with the respective values for the SharePoint property. |
Structure of a source property
| Property | Description |
|---|---|
| key | Specifies the unique source property identifier. |
| value | Specifies the value of the mapped property. |
Delete a file in a SharePoint repository
Make an HTTP DELETE request to the following described path. You must allow deletion in the SharePoint Adapter. If deletion is not allowed, an error will be returned.
<Base-URI>/sharepointadapter/r/<Repository-ID>/o2m/<DMS-Object-ID>
Response
HTTP/1.1 200 OK
Verify stored user information for authentication against Microsoft SharePoint
To be able to communicate with Microsoft SharePoint, a user mapping between the user accounts on d.velop side and a Microsoft account must be established. To check if d.velop users have a Microsoft user, one of the following calls can be executed:
This query only checks if any Microsoft SharePoint credentials have been stored by the users. The stored credentials will not be checked for validity.
Request
Make an HTTP GET request to the following path:
<Base-URI>/sharepointadapter/oauth2/users/loggedIn?repoid=<Repository-ID>&users=<User-ID-List>
| Parameter | Type | Description | Obligation |
|---|---|---|---|
| repoid | String | Specifies the connection for which user verification is to be performed. | Yes |
| users | String | Comma-separated listing of the d.velop user IDs to be checked from the identity provider. | Yes |
Alternatively, an HTTP PUT request can be executed on the following path. This is especially useful if many users are to be checked, otherwise the maximum length of a URL can be reached by specifying the information in the URL parameters.
<Base-URI>/sharepointadapter/oauth2/users/loggedIn
Origin: <Base-URI>
Accept: application/json
Content-Type: application/json
{
{
"repositoryId": "<Repository-ID>",
"userIds": ["<User-ID-1>", "<User-ID-2>", ...]
}
}
Response
{
"repositoryId": "<Repository-ID>",
"users":[
{
"id": "<Benutzer-ID-1>",
"loggedIn": true
},
{
"id": "<Benutzer-ID-2>",
"loggedIn": false
},
...
]
}
| Property | Description |
|---|---|
| repositoryId | Specifies the ID of the checked connection. Is equal to the value specified in the request. |
| users | Specifies a list of checked users. |
| users.id | The ID of the respective user. |
| users.loggedIn | Indicates whether Microsoft SharePoint credentials exist for the user corresponding to the user ID. |