Documents Integration User Guide

Overview

The Documents integration allows an object in FieldTwin to be linked with documents and files held in one or more other web applications. Selecting an item in FieldTwin displays a list of its related documents.

The integration ships with 3 "document sources" as standard:

• Built-in database of hyperlinks
  - Associates document viewing links from any web-based system such as Sharepoint (or even YouTube) with a FieldTwin object
• Dynamic search hyperlinks
  - Provides a search link that triggers a search in another web-based system by passing across information about the selected FieldTwin object (such as its unique ID or tag)
• Uploaded documents in FieldTwin
  - Shows the list of files and documents that have been stored in FieldTwin against the selected object

The following third party integrations are also supported; and can be enabled on request:

• Omega365 PIMS
  - Integration with Omega365 Project Information Management System (PIMS) API. Provides the capability to display a list of PIMS documents or other records associated with the selected FieldTwin object.
• Bentley ALIM
  - Integration with Bentley AssetWise Asset Lifecycle Information Management system (ALIM) API. Provides the capability to display a list of ALIM documents or other records associated with the selected FieldTwin object.

These document sources can be enabled or disabled by an administrator. None are enabled by default. Additional custom document sources can be requested through FutureOn's professional services team.

Using the integration

Start by selecting the Documents tab in the bottom row of tabs in FieldTwin Design. If it is not shown, click the Layout button and select it to show it.

• Click on an asset, connection, well or well bore in FieldTwin Design
• The integration will automatically perform a search for related documents and show the results from each document source in adjacent tabs
• If available, the number of documents found will be shown next to the name of each tab
• The number of documents found is also shown next to the selected object in the Project View
• Select a tab to view the associated results

Note that the tab names can be set by an administrator and may appear differently from these examples.

Background searching

When background search is enabled the integration will respond to occasional requests from FieldTwin to update the document counts in the Project View. This typically occurs when the project is first loaded and when the multiple selection tool is used.

Background searches do not block the normal use of the integration, and repeat searches for the same objects are ignored.

When a document source such as Bentley ALIM requires signing in, background searches can only provide results after the sign in process has been completed.

Configuring the integration

The Documents integration is configured in FieldTwin Admin by an administrator user.
Select 'Integrations' → 'Documents' → 'Settings'

The Settings page provides configuration tabs for each of the enabled searches.

The following sections below describe in more detail how to set up and use each of the search tabs.

Setting up and using the Document Links tab

The Document Links tab enables a user to create a table of links to documents related to an object in FieldTwin. For example, these could be links to Microsoft Office 365 files.

Configuring the Document Links tab

Select the 'Links Database' tab in the Settings page.

The Document Links configuration provides the following settings:

• Tab Number: (Optional) is used to define the order of tabs on the results page. If left blank, the tab will be placed after any numbered tabs.
• Provider Name: (Required) this sets the name that is displayed in the tab header on the results page.
• Provider Logo URL: (Optional) this can be used to add an icon image in the tab header on the results page.

Enter the settings and press Save.

To remove Documents Links as a document source, click the Delete button.

Using the Document Links Tab

Once the Document Links tab has been set up, the tab enables the user to create a table of links to documents related to an object in FieldTwin. For example, these could be links to Microsoft Office 365 files.

Clicking on the title of a document will open the link in a new browser window.

You can sort the list of results by title or ID by clicking on the appropriate column header. The results are sorted by title initially.

Linking to a document

The document must have its own unique web address (URL, hyperlink, or link). In some applications you can copy this from the address bar in your web browser, but many applications provide a function for copying the link to your clipboard. For example, in an Office 365 document, click Share and then Copy link:

With this done, switch back to FieldTwin Design and click on an asset, connection, well, or layer. This sets the object that the document will be linked to. Next click the Add Link button inside the integration.

In the Add Link form:

• Optionally enter an ID or reference for the document
  The reference value can be anything that is meaningful to your organization's documentation structure or process; it is only used for display
• Enter a description for the document as you want it to appear in the search results
• Paste the document's link into the URL / Link box
  Or press ctrl + v on your keyboard to paste from the clipboard

Lastly, click the Add button on the form.

Changing or deleting a document link

From the search results, click the pencil icon to change the details for a link, or the trash can icon to delete a link.

Deleting a link does not remove the document from the other application.

Setting up and using Search Link tabs

Search Link tabs provide a clickable link that launches an external document management system, triggering a search for documents related to the currently selected FieldTwin object.

For example, a search link could be configured to search Microsoft Sharepoint. The name of the tab will usually be set as the name of the external application.

Configuring the Search Link tabs

The integration allows the user to configure multiple Search Link tabs, as many as required. The Settings page provides an Add button to add new Search Link tab configurations.

For example, one tab could be configured to search Microsoft Sharepoint, and a second tab could be configured for searching a Kongsberg Kognitwin project repository.

To configure each Search Link, select its tab in the Settings page. Each Search Link configuration provides the following settings:

• Tab Number: (Optional) is used to define the order of tabs on the results page. If left blank, the tab will be placed after any numbered tabs.
• Provider Name: (Required) this sets the name that is displayed in the tab header on the results page for the Search Link.
• Provider Logo URL: (Optional) this can be used to add an icon image in the tab header on the results page.
• Search URL / Link Template: (Required) This defines the search link to the external system. This should include placeholders for the FieldTwin attribute(s) that will be used for the search. These should be enclosed in % characters, for example %operatorTags%
• Link Text Template: (Optional) the link text to display with %Attribute% placeholders for FieldTwin to insert in the text. This enables the user to define the text string that will be displayed for the link.

Enter the settings and press Save.

The search link includes a reference to the selected FieldTwin object such as its unique ID, a tag number, or a metadata value that can identify it.

To remove a Search Link as a document source, click the Delete button.

Using the Search Link Tabs

Once a Search Link tab has been set up, the tab provides a clickable link to search the external system.

Clicking on the link will open a new browser window; and you may be asked to log in to the other system before the search runs.

Setting up and using the Uploaded Documents tab

FieldTwin Design provides a facility to upload document files into FieldTwin itself. This facility can be useful when a full-blown document management system is not required, or for sharing selected documents between collaborators who do not all have access to a private repository.

Configuring the Uploaded Documents tab

Select the 'Uploaded Documents' tab in the Settings page.

The Uploaded Documents configuration provides the same common settings as the other tab configurations:

• Tab Number: (Optional) is used to define the order of tabs on the results page. If left blank, the tab will be placed after any numbered tabs.
• Provider Name: (Required) this sets the name that is displayed in the tab header on the results page.
• Provider Logo URL: (Optional) this can be used to add an icon image in the tab header on the results page.

Enter the settings and press Save.

To remove Uploaded Documents as a document source, click the Delete button.

Using the Uploaded Documents tab

This tab in the Documents integration mirrors the content of the selected object's Properties/Documents tab (circled in the screenshot below). It offers the convenience of seeing what files have been uploaded in the same place as the other document sources.

Setting up and using the Omega365 PIMS tab

The Omega365 Project Information Management System (PIMS) API integration enables the user to select an object in FieldTwin and display a table of PIMS documents associated with the selected item.

Configuring the Omega365 PIMS tab

To configure the PIMS integration, select its tab in the Settings page.

The configuration provides the following settings:

• Tab Number: (Optional) is used to define the order of tabs on the results page. If left blank, the tab will be placed after any numbered tabs.
• Provider Name: (Required) this sets the name that is displayed in the tab header on the results page for the Search Link.
• PIMS Logo URL: (Optional) this can be used to add an icon image in the tab header on the results page.
• PIMS API Key: (Required) the PIMS API requires an API key to authorise access.
• PIMS Search URL Template: (Required) This defines the PIMS API URL for querying the PIMS system. This should include placeholders for the FieldTwin attribute(s) that will be used for the search. These should be enclosed in % characters, for example %operatorTags%.

Enter the settings and press Save.

The PIMS API Key and details about how to format the API search URL should be requested from Omega365.

A typical query URL template is shown below. The bracketing and quotation characters must be correct otherwise the API will return an error:

https://company.pimshosting.com/fieldview/tagdocs?filter={
   and: [
      { equals: { left: { field: "Domain" }, right: "Domain-Name" } },
      { equals: { left: { field: "TagNo" }, right: "%operatorTags%"  } }
   ]
} 

To remove PIMS as a document source, click the Delete button.

Using the Omega365 PIMS tab

The Omega365 PIMS results tab operates in the same way as the other results tabs. When an object is selected in FieldTwin, the integration will trigger a query of the PIMS API and a table of results will be displayed.

The table shows a list of PIMS documents associated with the selected object, providing the Document Id, Title, Revision and Document Type.

The Document Id provides a clickable link that will open the item inside PIMS in a new browser tab.

Setting up and using the Bentley ALIM tabs

The Bentley AssetWise Asset Lifecycle Information Management System (ALIM) API integration enables the user to select an object in FieldTwin and display tables of ALIM records associated with the selected item.

Configuring the Bentley ALIM tabs

The ALIM integration supports configuring multiple tabs, as many as required, to enable a number of different ALIM queries to be invoked.

The tab Add button enables multiple ALIM tabs to be configured.

To configure each ALIM tab, select the tab in the Settings page.

The configuration provides the following settings:

• Tab Number: (Optional) is used to define the order of tabs on the results page. If left blank, the tab will be placed after any numbered tabs.
• Provider Name: (Required) this sets the name that is displayed in the tab header on the results page for the Search Link.
• ALIM Logo URL: (Optional) this can be used to add an icon image in the tab header on the results page.
• ALIM Search URL Template: (Required) This defines the base URL for querying the ALIM system.
• ALIM Search Filter Template: (Required) This defines the Filter for querying the ALIM system. This should include placeholders for the FieldTwin attribute(s) that will be used for the search. These should be enclosed in % characters, for example %operatorTags%.
• ALIM Search Include List Template: (Required) This defines the list of data items that should be returned from the search query.
• ALIM Link URL: (Required) This defines the ALIM link URL for opening ALIM records in a browser tab.

Enter the settings and press Save.

Details about how to format the API search URLs, Context code, Filter and Include List should be requested from Bentley.

More details about the ALIM API can be found here:
https://datastorage.eus2.es-cs.bentley.com/docs/api/index.html

The ALIM configuration settings page is quite complex, but it provides flexibility to configure any API request (using the URL, Filter and Include List settings) to perform any required ALIM search query and define the data attributes to be displayed in the results tables.

The example above shows the configuration for an ALIM API Search for documents matching an object tag.

• The Search URL provides a context code which defines the company repository (eg. Dev, QA, Prod); and specifies a search for matching 'tags'
• The Filter template defines the database query to be invoked using parameters from the selected FieldTwin object
• The Include List defines which attributes of the matching records should be displayed in the results. There can be any reasonable number of attributes, and the results table will create colums for each attribute. The Id attribute must be provided first; this is used to create the clickable link to open ALIM records in a browser tab.

To remove ALIM as a document source, click the Delete button.

Using the Bentley ALIM tabs

If ALIM is enabled in the Documents Integration, the Results page will initially display a Sign In button. The user will need to sign in to Bentley to authorise access to the ALIM API.

Clicking the Sign In button will open a popup window for the user to log in. It is only necessary to sign in once at the beginning of a session.

Note: The browser security settings may need to be changed to allow pop-up windows.

The ALIM results tab operates in the same way as the other results tabs. When an object is selected in FieldTwin, the integration will trigger each of the configured ALIM queries, and will display the results in a table in each ALIM tab.