Skip to content

Documents Integration User Guide

Contents

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 uploaded directly into FieldTwin for the selected object (this is a new feature in 6.4.1)

These 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.

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 capabilty 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 capabilty to display a list of ALIM documents or other records associated with the selected FieldTwin object.

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.

Starting point

Click on an asset, connection, or well 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. Select a tab to view the associated results.

Search results

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

Configuring the integration

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

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

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

Configuration

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.

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'.

Configuration Links

To remove the Documents Links as a document source, click the Delete button. A Confirm dialog will be displayed for the user to confirm the removal.

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.

Document Links

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:

Copy link to document

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.

Adding a link

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
    Press ctrl + v on your keyboard to paste from the clipboard

Lastly click the Add button on the form.

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.

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.

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.

Configuration Add Button

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'.

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.

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.

Configuration Search Link

To remove a Search Link as a document source, click the Delete button. A Confirm dialog will be displayed for the user to confirm the removal.

Once the Search Link tabs have been set up, the tabs provide clickable links to search the external systems.

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.

Search link

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 the Uploaded Documents as a document source, click the Delete button. A Confirm dialog will be displayed for the user to confirm the removal.

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.

Uploaded documents

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 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'.

Configuration PIMS

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. A Confirm dialog will be displayed for the user to confirm the removal.

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 to PIMS that will open the item 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 Add button enables multiple ALIM tabs to be configured.

Configuration Add ALIM

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'.

Configuration ALIM

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.

Results ALIM

To remove an ALIM tab as a document source, click the Delete button. A Confirm dialog will be displayed for the user to confirm the removal.

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.

Results ALIM Sign In

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 tabs operate 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 tab.