Configuring REST API document data source

Configure the REST API document data source when you want to retrieve documents and their metadata from the external system. eShare displays the retrieved documents in a document tree in the Documents view, where users can access them. The documents and their metadata are stored and maintained in the target system. If you enable indexing, the system can search for object links in documents, and create links from 3D objects to relevant documents.

When you build the REST API document data source, proceed as follows:

1. Configure the selectors for the root folder or folders.

2. Configure the selectors for the subfolders.

3. Configure the selectors for the documents.

You can define the file types that the adapter supports. The default file types are PDF, DWG, DXF, DGN, and the image types BMP, GIF, JPG, PNG, and TIFF. If the adapter should support other file types, you can specify them according to the project's needs. Note that eShare cannot index these other file types, and the user needs to download the files to be able to view them in an external viewer.

You can work either in basic or advanced mode. In basic mode, eShare helps you build the selectors by providing suitable options in drop-down menus, whereas in the advanced mode, you need to program the selectors in a JavaScript-like but customized selector language. For example, a.b means "child b of object a", and a[3] means "element 3 of array a".

After you have created a selector, test it by clicking the Preview button and analyze the JSON response.

Prerequisites

Create the REST API adapter. Familiarize yourself with the external system and its data structure. You also need to understand the basics of programming.

If you want to enable indexing, ensure that a suitable document type has been defined. See Adapters and indexing.

Do the following:

1. On the Adapters list, click the REST API adapter to which to add the data source.

2. In the Data Sources section of the adapter settings, click Add data source.

3. Select REST API Document Data Source from the list.

4. Click Create Data Source.

5. In the Data Source section, specify the following settings:

   • Name – Enter a name for the data source.

   • Description (optional) – Enter a description for the data source.

   • State – Specify whether the data source is disabled or enabled (default).

6. In the Groups allowed to see the data section, select user groups that should be allowed to see the data that this data source provides.

   • If no groups are selected, only administrators will see the data.

   • Add user groups with Add.

   • Remove user groups with the remove button.

   • If the All Users group is selected, other group selections will be ignored.

7. The Adapter Configuration section is read-only.

8. In the Data Source Configuration section, specify the following settings:

   • General

     • Mode – Select the if you want to work in basic or advanced mode.

   • Indexing and Caching – Click Show to display the configuration.

     • Indexing – Select if the document indexing is enabled. If you enable indexing, eShare is able to create links between model objects and documents.

       Note: If you save the data source configuration with indexing, all data sources of the same adapter with indexing enabled, will be indexed again.

       If Enabled, specify the following settings:

       • Indexing Speed – Define the duration of indexing.

         If you select Duration, specify the target duration of each indexing round in Target Indexing Duration field (in minutes). The set duration takes effect only after the first full round of indexing has been completed. The default is 120.

         If you select As Fast As Possible, the target of each indexing round is to be completed in the shortest time as possible.

       • Indexing Mode – Indexing is done every time the data source configuration is saved. Indexing can also be triggered manually from the Project Administration's General view.

         If you select Once, indexing is done only after saving.

         If you select Daily, indexing is done once every day.

         If you select Once per Days of Week, indexing is done once on the selected days.

         If you select Given Times in Days of Week, indexing starts on given times of the day on the selected days. The times are given in the server's local time.

         If you select Days of Month, indexing is done once on the selected days of the month.

         If you select All the Time, indexing is done continuously. Warning: This can consume a lot of resources if As Fast as Possible is selected as indexing speed.

     • Load Subfolders On Demand – If enabled, the entire document tree is not loaded at once, but the contents are loaded and visible following the user's examination. The default is Disabled.

     • Folder Tree Caching – Define if the folder tree is cached or retrieved from the server.

       If you select Disabled, eShare fetches the folder tree from the server every time the user logs in or refreshes the browser.

       If you select Enabled, eShare saves the folder tree in the cache and updates it only periodically. The user sees the cached folder tree. Caching is renewed in intervals defined in Caching Interval field. The value is given in minutes.

   • File Types and Hierarchy – Click Show to display the configuration.

     • Hierarchy Type – Define how eShare should handle subfolder queries.

       If you select One-level, eShare does not query subfolders for further subfolders. Use One-level if the target system is simple.

       If you select Recursive, eShare will query subfolders for further subfolders. Use Recursive if the target system has a complex hierarchy or it is a node-based system.

     • Ignore File Extensions – If enabled, filtering documents by file extension is completely disabled. Documents may still be filtered by their file type if their file type is detected in some other manner.

     • File Types – Select the file types that the document data source adapter should support.

     • Additional File Types to Show – If the document data source adapter should support other file types, list them here. Separate the file types with a comma.

     • Get Zip file Contents – Define how eShare should handle ZIP file contents.

       If you select Disabled, eShare does not show the contents of the ZIP file in the document tree.

       If you select Enabled, eShare shows the contents of the ZIP file to the document tree.

     • File Type Detection – Define how eShare should detect the file type.

       If you select Extension only, eShare determines the document type by its extension, for example, .pdf. If the file does not have an extension, eShare ignores the file. Use this option unless there is a strong reason to select another method.

       If you select HEAD request, eShare fetches the document header and attempts to detect the document type from the header. Note that not all systems support HEAD requests.

       If you select GET request, eShare downloads the document. GET requests may have an effect on the system's performance, but they are supported by almost all systems. Use GET request only when the other options do not provide the desired result.

   • Custom Request Headers (optional) – Build custom headers if you need to define custom headers to be sent with the data request; for example, for authorization purposes.

     The header is a name-value pair. The components are target-system-specific, and you can add both static and dynamic elements. Enter the static elements as normal text.

Configure access to root folders

Root folders are the base folders of the document data source. When you configure the root folders, create first a request that returns information about the root folders. Next, define an array that contains the root folders that you want to use. Preview the response and analyze it. Select the root folder IDs and the root folder names from the JSON response.

Do the following:

1. Click Show in the Structure - Root Folders section to display the configuration.

2. Build the URL from which eShare should parse the root folder names and IDs in the Request URL field.

   Enter the URL as normal text, but to add the ID, type "ID" and select the ID from the drop-down menu.

   Test the URL by clicking Test, and analyze the test response.

3. Create the root folder array selector. In the Root Folder Array Selector section, pick the main JSON array where the root folders are listed, and define the array with child elements. The root folder array selector can have one or more child elements. Click Preview to verify the result.

   Click Select a child, and define the type of the element. Define the child's property name, array index, or a condition that limits the results. Test the root folder array selector by clicking Preview. eShare validates the array.

4. Create the root folder ID selector from the array. In the Root Folder ID Selector 1 From Array section, select the folder IDs for the root folders. eShare injects the IDs into the request URLs, and links the number of selectors to the number of subfolder ID selectors.

   Click Select a child, and define the type of the element. Define the child's property name, array index, or a condition that limits the results. Test the selector by clicking Preview.

   To add another ID selector, click Add ID Selector.

5. Create the root folder name selector. In the Root Folder Name Selector From Array section, select the display names of the root folders. The options depend on the selector.

   Click Select a child, and define the type of the element. Define the child's property name, array index, or a condition that limits the results. Test the root folder array selector by clicking Preview.

6. To enable getting the documents in the root folder, enter root folder IDs in the Root Folder IDs section. Specify root folder ID for each root folder ID selector.

Configure access to subfolders

eShare fetches the subfolders based on the IDs of the folder on the previous level; either root folders or subfolders. When you configure subfolders, create first a request that returns information about the subfolders. You can use the Parent Folder ID as a parameter in the request. Next, define the array that contains the subfolders that you want to use. Preview the response and analyze it. From the JSON response, select the subfolder IDs and the subfolder names.

Do the following:

1. Click Show in the Structure - Subfolders section to display the configuration.

2. Build the URL from which eShare should parse the subfolder names and IDs in the Request URL field.

   Enter the URL as normal text, but to add the ID, type ID and select the ID from the drop-down menu.

   Test the URL by clicking Test, and analyze the test response.

3. Create the subfolder array selector. In the Subfolder Array Selector section, pick the main JSON array where the subfolders are listed, and define the array with child elements. The subfolder array selector can have one or more child elements. Click Preview to verify the result.

   Click Select a child, and define if the type of the element. Define the child's property name, array index, or a condition that limits the results. Test the subfolder array selector by clicking Preview. eShare validates the array.

4. Create the subfolder ID selector from the array. In the Subfolder ID Selector 1 From Array section, select the folder IDs for the subfolders. The IDs are injected into the request URLs. The number of selectors is linked to the number of subfolder ID selectors.

   Click Select a child, and define if the type of the element. Define the child's property name, array index, or a condition that limits the results. Test the selector by clicking Preview.

   To add another ID selector, click Add ID Selector.

5. Create the subfolder name selector. In the Subfolder Name Selector From Array section, select the display names of the subfolders. The options depend on the subfolder array selector.

   Click Select a child, and define the type of the element. Define the child's property name, array index, or a condition that limits the results. Test the selector by clicking Preview.

Configure access to documents

eShare recognizes the documents that exist in the subfolder based on the request and array that you create. When you configure the document level, create first a request that returns information about the folder contents. You can use the Parent Folder ID as a parameter in the request. Next, select an array that contains the documents in the folder. Preview the response and analyze it. From the JSON response, select the document IDs and document names.

Do the following:

1. Click Show in Structure - Documents in Folder section to display the configuration.

2. Build the URL from which eShare should parse the document names and IDs in the Request URL field.

   Enter the URL as normal text, but to add the ID, type "ID" and select the ID from the drop-down menu.

   Test the URL by clicking Test, and analyze the test response.

3. Create the document array selector. In the Document Array Selector section, pick the main JSON array where the documents are listed, and define the array with child elements. The document array selector can have one or more child elements. Click Preview to verify the result.

   Click Select a child, and define the type of the element. Define the child's property name, array index, or a condition that limits the results. Test the document array selector by clicking Preview. eShare validates the array.

4. Create the document ID selector from the array. In the Document ID Selector 1 From Array section, select the document IDs. The IDs are injected into the request URLs.

   Click Select a child, and define the type of the element. Define the child's property name, array index, or a condition that limits the results. Test the selector by clicking Preview.

   To add another ID selector, click Add ID Selector.

5. Create the document name selector. In the Document Name Selector From Array section, select the display names of the documents. The options depend on the document array selector.

   Click Select a child, and define the type of the element. Define the child's property name, array index, or a condition that limits the results. Test the selector by clicking Preview.

Displaying document properties

Define the properties and metadata that eShare needs to display the documents in the Documents view. When you configure the document properties, create first a request that returns information about the document. Build the request using the Document ID parameter. Test the request and analyze the JSON response. Next, select the download ID or link from the JSON response. The response depends on the external service; some services return the full link instead of the ID.

Construct a request that downloads the file using the download ID. Test the request and analyze the JSON response, and select the document name and metadata from the response.

Examples of document metadata that you can display in the Documents view are name, version, author, and ID. You can also create a selector for file types, which will help eShare detect the document type. Name the selector File Type, and enter the value in the format "application/pdf".

Do the following:

1. Click Show in the Displaying Document Properties section to display the configuration.

2. Select Make Separate Document Info Request to be disabled or enabled (default). Disabling the setting enables using Documents in folder request instead of Document info request.

3. Build the URL from which eShare should parse the document names and IDs in the Request URL field.

   Enter the URL as normal text, but to add the ID, type ID and select the ID from the drop-down menu. There can be multiple document IDs.

   Test the URL by clicking Test, and analyze the test response.

4. Create the document download ID selector. In the Document Download ID Selector section, define the array with child elements. The document download ID selector can have one or more child elements.

   Define the child's property name, array index, or a condition that limits the results. Test the document array selector by clicking Preview. eShare validates the array. Analyze the information and enter the download URL in the Download URL field. This is the URL from where the documents are downloaded.

   To add another ID selector, click Add ID Selector.

5. Define the document name selector. This is the property that eShare uses to get the name when downloading the document. In the Document Name Selector section, define the array with child elements. The document name selector can have one or more child elements.

   Define the child's property name, array index, or a condition that limits the results. Test the selector by clicking Preview.

6. Define the metadata selectors in the Additional Metadata Selectors section. eShare uses metadata selectors to provide the user information about the document. If you need to define several similar selectors, you can copy them with the Copy button and modify them as needed.

   • Metadata Cache Time – Configure the cache time for the metadata in minutes.

   To add a metadata selector, click Add Selector. Select whether the metadata for the selector comes from Document Info or Folder Info. Enter the name of the metadata selector. eShare displays the name to the user in the Documents view.

   Click Select a child, and define the type of the element. Define the child's property name, array index, or a condition that limits the results. Test the document metadata selector by clicking Preview.

7. Click Save.