Configuring REST API object attributes data source

Configure the REST API Object Attributes data source when you want to show data from the source system in the model's object attributes. You can, for example, add information from the project management system to the model. The attributes that you create pick data from the JSON response sent by the external system. You can add object attribute data to the project's model objects or Smart Points.

From the user's perspective, these attributes are just like any other attributes stored in the 3D model, only their values can change dynamically according to data in the external source.

Prerequisites

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

If you want to add object attribute data for Smart Points, make sure that Smart Point Types have been configured for the model.

Open the project and the REST API adapter that should have the object attributes data source. The REST API adapter is available in the Project Admin view, in the Adapters and Data Sources section.

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 Object Attributes 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. Continue by configuring the data source.

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

    • Provide data for – Select whether to retrieve the data to objects or Smart Points.

      If you select Model Objects, the retrieved data will be added to objects that have the tag specified in the URL or headers.

      If you select Smart Points, the retrieved data will be added to Smart Points of the specified type.

    • Refresh Automatically – Define if eShare should refresh the data automatically. If you enable refreshing the data automatically, define the refresh interval in seconds. The default value is 10 seconds.

    • Allow Search Queries – Select Enabled if the data source can be used in search queries.

      If search queries are enabled, define Maximum Number of Data Source Queries, which determines the number of queries the data source can be included in. The field can be left empty for no limit. The default is 250.

  9. In Request Configuration, specify the following:

    • Request Mode – Specifies whether incoming data is requested as per object or from a large JSON list.

      If each object or group has its own REST API endpoint, select Per Object mode.

      If there is only one endpoint, it is a better option to select Full List. If Full List is selected, set the Keep Cache Time which specifies how often the list is refreshed. The default is 60 minutes.

      If you want to chain requests, select Chained Requests.

    • HTTP request type – Define if the adapter should be able to read data from or also post data to the service with the request.

      If you select GET, the adapter can only fetch data from the service.

      If you select POST, you can specify a body that the system sends with the request. The body must be in JSON format and it its validated while you create it.

    • URL – Build the URL for the target service. The components are target-system-specific, and you can add both static and dynamic elements. 

      Enter static elements of the URL as normal text. eShare suggests dynamic elements when you start to enter text; select the element that you want to use.

    • Custom 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. eShare suggests dynamic elements when you start to enter text; select the element that you want to use.

    • Select data for next request – Visible if selected mode is Chained Requests.

      • Enter Variable name.

      • Click Select a child.

      • Click Preview to verify the result in JSON format.

      To add more data selectors, click Add data selector.

      Enter data for second request in the same way.

    If you selected Chained Requests mode, you can add more requests by selecting Add request.

  10. In the Testing section, you can test the HTTP request to make sure it provides the correct data. Check that the URL is correct, and click Test. eShare provides the JSON response. Analyze the output, and use the results to build the attributes for the data source. The response is target-system-specific.

Creating the attributes

Create the attributes in the Response data selectors section.

The attributes extract data from the JSON response by using selectors. An attribute can map to one or more pieces of data. You can work either in basic mode or advanced mode.

  • If you use the basic mode, eShare assists you in selecting data.
  • In the advanced mode, you need to code the attribute in a custom selector language that is similar to JavaScript. The syntax is as follows:
    • parent.child
    • array[index]

If you need to create several similar attributes, you can copy them with the Copy button and modify them as needed. If needed, rearrange the attribute fields with the arrow up and arrow down buttons . You can also build conditions for the attributes.

If you are creating attributes for request per object:

  1. Enter the Display name. This is the title of the attribute and displayed in the model object's or Smart Point's properties.

  2. Enter the Display category. Use the category to group the attributes in the properties pane.

  3. Select Attribute Type as either Text or Hyperlink. If you select hyperlink, enter Link Address and Link Display Text in the fields.

  4. Build the attribute. Select the data in the Select field. In basic mode, the options for selecting data are Property, Array Element, and Condition. The accepted values depend both the selected data type and the external system and are available in the JSON response that eShare provided in the Testing section.

  5. To add more variables to the attribute, click Select a child.

  6. Click Preview to verify the result in JSON format.

  7. To add more attributes, click Add attribute.

  8. To add a document link to the data source, click Add document link and specify the following:

    • Select Document Data Source.

    • For Document ID Selector, click Preview, or, in basic mode, add more attributes by clicking Select a child. To add another selector, click Add ID selector.

    • For Name Selector, click Preview, or in basic mode, add more attributes by clicking Select a child.

    • To add another document link, click Add document link.

  9. Click Save.

If you are creating attributes for request for a full list:

  1. In the Array Selector section, the array that contains a list of objects containing attributes is selected. Each object within the array should map to a model object or smart point.

  2. Click Select a child.

  3. Build the attribute. In basic mode, the options for selecting data are Property, Array Element, and Condition. The accepted values depend both the selected data type and the external system and are available in the JSON response that eShare provided in the Testing section.

  4. To add more variables to the attribute, click Select a child.

  5. Click Preview to verify the result in JSON format.

  6. In the Match Model Attributes/External ID section, select the Attribute to match. In basic mode, the options for selecting data are Property, Array Element, and Condition. The accepted values depend both the selected data type and the external system and are available in the JSON response that eShare provided in the Testing section.

  7. To add more variables to the attribute, click Select a child.

  8. Click Preview to verify the result in JSON format.

  9. To add more attributes, click Add attribute.

  10. In the Attributes to Show section, enter the Display name. This is the title of the attribute and displayed in the model object's or Smart Point's properties.

  11. Enter the Display category. Use the category to group the attributes in the properties pane.

  12. Select Attribute Type as either Text or Hyperlink. If you select hyperlink, enter Link Address and Link Display Text in the fields.

  13. To add more variables to the attribute, click Select a child.

  14. Click Preview to verify the result in JSON format.

  15. To add more attributes, click Add attribute.

  16. To add a document link to the data source, click Add document link and specify the following:

    • Select Document Data Source.

    • For Document ID Selector, click Preview, or, in basic mode, add more attributes by clicking Select a child. To add another selector, click Add ID selector.

    • For Name Selector, click Preview, or in basic mode, add more attributes by clicking Select a child.

    • To add another document link, click Add document link.

  17. Click Save.