Web Connector

Setup and Troubleshooting for Advanced Javascript usecases

Introduction

The Web Connector indexes HTML documents and also supports the indexing of web pages that use JavaScript by means of "JavaScript crawling".

This documentation describes how to use and handle JavaScript crawling in the context of advanced JavaScript use cases.

Note: For the use cases described here, basic knowledge of HTML and JavaScript is required. Furthermore, basic knowledge about the structure of the web page to be indexed is required.

Architecture

Web Connector without JavaScript (Regular Web Crawling)

In this mode, the web connector downloads the web page to be indexed directly using a single HTTP request. In this mode, it is not possible for the connector to properly index web pages with dynamic content.

Web connector with JavaScript (JavaScript crawling)

In this mode, the Web Connector downloads the web pages to be indexed indirectly using JavaScript crawling, allowing it to index web pages that are dynamically loaded with JavaScript.

However, this mode is very performance-intensive and should only be used if no better alternative is available. See the section Alternatives.

JavaScript crawling requires some additional settings, which are described in the following sections.

Comparison between Regular Web Crawling and JavaScript Crawling

The following table shows the main features and differences between regular web crawling and JavaScript crawling.

Configuration JavaScript crawling

Settings for indexing with JavaScript

The following settings can be used to regulate which pages should be indexed with JavaScript. Furthermore, you can also control whether only web pages with the content type "text/html" should be indexed (this is determined in a separate HEAD request).

A detailed explanation of the settings listed below can be found in the documentation Configuration - Web Connector.

• Enable JavaScript
• Skip Head Request
• Include JavaScript URL (regex)
• Exclude JavaScript URL (regex)

The idea behind these fine-grained configuration options is to only use JavaScript crawling for web pages when it is necessary.

Default behavior

When the Web Connector is run in JavaScript mode (without configuring any other settings), the web page content is loaded and indexed as soon as the configured "Page Ready State" is reached. If the configured "Page Ready State" is not reached within the "Network Timeout", an error is logged and the content is not indexed.

These settings can also be found here.

Behavior with Scripts

Scripts are JavaScript code fragments that can be configured for advanced use cases. The following sections describe how to use these scripts:

Content Presence Selector

If the default behavior of the connector is not sufficient (for example, a web page is indexed with incomplete content) it is possible to define a "Content Presence Selector". This selector can be specified using XPath or CSS selectors and changes the operation to recognize the content, so that now it waits for the selector. This is especially useful for complex web pages that take longer to load.

Scripts

For web pages that need user input or are more complex, the "Content Presence Selector" can be extended with the "Script" setting.

Configured scripts are executed based on events using the "Script Trigger Selectors". A Script Trigger Selector checks the DOM of the document to see if a certain condition occurs. When a Script Trigger Selector becomes active, the associated script is executed in the context of the current processing of the web page.

Processing stops when the Content Presence Selector becomes active (when the requested content is loaded).

For example, a Script Trigger Selector can detect if user input is currently required (e.g. a login form is displayed) and then perform actions in the associated script (e.g. a click on the login button)

The "Script Trigger Selectors" can be specified using XPath and CSS.

Assume Content if no Script triggered

In some cases, we cannot define an explicit "Content Presence Selector". This can be the case if elements of the content are already loaded in the DOM before the script is to be executed or if different web pages are to be indexed, for which we cannot define a common selector.

The setting "Assume Content if no Script triggered" exists to support these special cases. If this setting is enabled, the processing will be stopped as soon as no Script Trigger Selector is active and the web page will be indexed in this state.

Note: care should be taken with pages that load more slowly, as this setting may cause subsequent scripts to stop running and the content may be indexed prematurely and incomplete.

Use Cases

Intranet with unsupported API authentication

This example explains the steps required to set up Mindbreeze Web Connector to crawl an intranet website with unsupported API authentication (in regular crawling).

Requirements Analysis

Alternatives

First of all, the website to be indexed must be analyzed. Since indexing with JavaScript is very performance-intensive, the following questions should be answered first and foremost:

• Is the relevant website a supported data source for which another connector already exists?
• (e.g.: Microsoft Sharepoint Online, Salesforce, Google Drive, Box Connector).
• Is the authentication variant already supported with regular crawling? (Form, Basic, NTLM, OAuth).
• Is there an API that can be integrated in the Data Integration Connector?
  Configuration - Data Integration Connector

If none of these alternatives apply to the web page, we proceed with JavaScript crawling. Next, we analyze the behavior of the web page.

Behavior

In order to analyze the behavior of the web page, we first need to make sure that the necessary credentials (username, password) are available and that the login works with a browser (e.g.: Chrome, Firefox).

If the login in the browser was successful, it will be checked if all contents that should be indexed are available. (It is possible that the user does not have sufficient permissions to see the relevant content).

If all content is displayed correctly, the individual pages are analyzed in detail.

For the analysis of the individual pages, a distinction must be made between three types:

• Login pages
• Content pages
• Redirects ("redirected pages")

Login Pages

• How is the login form structured, which fields have to be filled in?
• How is the login triggered? Which button has to be pressed?
• How long does the entire login process take? (timeouts may have to be adjusted)
• To which hosts are connections established (e.g. loading fonts or JavaScript components from other servers)?

Note: 2-factor authentications can NOT be supported.

Content Pages

The following points are to be considered here:

• Are actions required by the user to view the content? E.G.:
• Do you need to scroll down to load the whole content?
• Does a button need to be pressed to view the content?
• Does an element need to be entered and confirmed to display the content? (e.g. cookie banner)  
• Do you need to operate a menu?
• How quickly does the page react to these actions? (maybe timeouts have to be adjusted)
• Which hosts are connections established to? (e.g. loading fonts or JavaScript components from other servers)?
• see "Forwarded pages" for more information.

Redirects (Redirected Pages)

For web pages that redirect to other pages, it is important to note that the web connector blocks all unknown hosts by default for security reasons. (Error code: BLOCKED_BY_CLIENT)

To allow other hosts, they must be specified as "Additional Network Resources Hosts" in the settings.

Note: This also applies to sitemaps. Here, all relevant hosts must be specified as "Additional Network Resources Hosts".

Browser Developer Console

When the analysis of these pages is complete, you can begin to recreate the login using JavaScript in the browser's Developer Console (F12).

Login Page

The first step is to locate the elements of the login window (e.g.: username, password, login button) and note the corresponding selector.

For the login page, the selector for the form is very suitable as a "Script Trigger Selector". Using XPath, you can specify more complex selector, which for example, search for the combination of username and password ID.
(//*[@id='username'] and //*[@id='password'])

1. Locate an element in the DOM.
2. Copy the CSS selector of an element
3. Copy the XPATH selector of an element

Once the selectors are noted, they can be tested in the console tab of the developer console as follows:

Once all elements of the login page have been found, you can begin recreating the login process in the console:

1. Enter your username
2. Enter your password
3. Press „Login“

If the login via the Developer Console was successful, the three commands can be created as a standalone script in the Management Center using the corresponding "Script Trigger Selector".

Content pages/redirects (Redirected pages)

The content page(s) contain the content to be indexed. For these pages, it is important to note that there is only one "Content Presence Selector" per data source. It is therefore important to make sure that all pages have the same selector or that the option "Assume Content if no Script triggered" is active.

For this step it is also important that ALL pages are checked (not only start/login page). If it is difficult to consistently identify the content with a single Content Presence Selector, we recommend splitting the indexing into multiple data sources.

In some cases, special user interactions may also need to be performed for the content pages to see the final content. Scripts can be configured for this purpose, following the same procedure as for the login script.

1. identify selectors (trigger selector & selector of the element being interacted with)
2. test selectors
3. imitate user interaction in the development console
4. copy script to configuration and test indexing

Redirected pages behave like normal content pages, and are treated the same way. If user interaction is required, a script must be configured. Otherwise the default JavaScript process behavior will be executed. When linking to hosts that do not correspond to the configured "Crawling Root" hosts, these must also be specified as Additional Network Resources hosts.

Troubleshooting

If too few, too many or incomplete documents are indexed, check the following items:

1. Check configuration for correctness
   1. Selectors
   2. Scripts
2. Check website for response time, adjust timeouts
3. Check logs for errors
   1. /current/log-mescrawler_launchedservice.log
   2. /current/job/logs/crawl.log
4. app.telemetry
   1. check Crawler Service
   2. check Index Service
5. activate Advanced Settings "Enable Verbose Logging", crawl again and check logs
   1. /current/log-webdriver-webdriver/current/chromedriver-logs/*
   2. /current/log-webdriver-webdriver/current/chromedriver-screenshots/*
   3. /current/log-webdriver-webdriver/current/chromedriver-javascript-process.csv
   4. /current/log-webdriver-webdriver/current/chromedriver-network.csv
   5. /current/log-webdriver-webdriver/current/log-webdriver.log