Product DocsMenu

Coveo Platform 7.0 >
Administrator Help > Coveo REST Search API 8.0 > Creating a Search API Hosted JavaScript Search Page

Creating a Search API Hosted JavaScript Search Page

Search API 8.0.457+ (March 2015)

The Coveo Search API comes bundled with the Coveo JavaScript Search framework and can conveniently host one or more search pages. Authorized users can create and modify search pages hosted by the Search API using the JavaScript Search Legacy Interface Editor.

To create a JavaScript Search Page to be hosted in by the Search API

  1. Ensure that the Search API v8.0.457+ is installed on a server and configured to connect with a Coveo Enterprise Search server (see Installing the Coveo Search API, Customizing and Starting the Coveo Search API, and Identifying the REST Search API Version).

  2. Configure the Search API searchPageDesigners permissions:

    You must configure who can create and modify search pages hosted by the Search API.

    1. Using an administrator account, connect to the server on which the Search API is installed.

    2. Using a text editor, open the search API configuration file [Search_API_Path]\config.yml (by default C:\Program Files\Coveo Search API 8\config.yml).

    3. In the file, ensure that the windowsAuthentication or basicAuthentication, as well as the admin sections are configured in the file:

      • When users are authenticated as Active Directory users:

        Add a windowsAuthentication section in which the provider value matches the Coveo Enterprise Search (CES) security provider name (by default Active Directory).

        In the admin section:

        • The provider value must be Windows to indicate that users are authenticated using the windowsAuthentication method.

        • The searchPageDesigners section determines who can create and modify search pages hosted by the Search API.

        Example: In the following configuration, only MYDOMAIN\username3 and members or the Administrators group can create and edit search pages.

        windowsAuthentication:
          enabled: true
          provider: Active Directory
        
        admin:
          enabled: true
          provider: Windows
          groups:
            - name: Administrators
              members: ["MYDOMAIN\\username1","MYDOMAIN\\username2"]
          searchPageDesigners:
            - MYDOMAIN\username3
            - Administrators

        Note: For a Windows provider, you cannot specify Active Directory group names. You must rather specify individual users.

        OR

      • When users are not authenticated:

        Add a basicAuthentication section to rather define users in the Search API configuration file. You must include a provider parameter with a CES security provider name as the value (such as Active Directory), but this security provider is not used for the purpose of the admin section.

        In the admin section:

        • The provider value must be Basic to indicate that users are authenticated using the basicAuthentication method.

        • The users section defines each user and the associated password BCrypt hash.

          You must choose the for each user, encrypt it using a BCrypt tool, copy the BCrypt hash in the section, and communicate the password to each user.

          Note: You can find online BCrypt tools (such as the BCrypt Calculator) to encrypt and test encrypted hashes against passwords.

        Example: In the following configuration, only members of the MyDesigners group (username2 and username3) can create and modify search pages hosted by the Search API.

        basicAuthentication:
          enabled: true
          provider: Active Directory
        
        admin:
          enabled: true
          provider: Basic
        
          users:
            - name: username1
              hash: $2a$04$DqADemxWjVVbBaWrR4/c0OTwPDXI3aXpDlGllLu0P8E1akMFJmkPm 
            - name: username2
              hash: $2a$04$kZsiWWieKKAHJA1K06OB4.reFSbYB3N9XEuGo938ly7qR/LM1.17W
            - name: username3
              hash: $2b$343feNiWVeKKAsKDu6d$fwbphYDS.6tIgGj84n00fD9lsdsf8924d3bJ
        
          administrators:
            - username1
        
          groups:
            - name: MyDesigners
              members: ["username2", "username3"]
        
          searchPageDesigners:
            - MyDesigners

      Important: The syntax in config.yml YAML file is picky: 

      • Respecting the indentation is critical. An indentation level must be two spaces, not a tabulation (the presence of one or more tab characters in the file will prevent the Search API service to start!). Some text editors may automatically insert tabs when adding lines. If possible configure your text editor to show all characters minimize risks of creating an invalid configuration file.

      • When specifying Windows users:

        • The domain or machine name MUST BE in capital letters (ex.: MYCOMPANY\myusername).

        • When specifying a user in an array, the username must be within quotes and a backslash character (\) must be escaped with another backslash (ex.: ["MYDOMAIN\\username1","MYDOMAIN\\username2"]).

        • When specifying one user, you do not need quotes and must not escape backslash characters (ex.: MYDOMAIN\username3).

      • The complete config.yml file specifications are available from the Coveo Developers site (see Windows Service Configuration File).

    4. Save the config.yml file.

    5. Restart the Coveo Search API service to make changes effective:

      1. In the Windows Services window, right-click Coveo Search API, and then select Restart (see How to Access Services Window in Windows XP, Windows 7 & 8).

      2. Ensure that the Coveo Search API service does not immediately stop. If it is the case, your config.yml file is invalid. You must identify and fix syntax errors.

  3. In a browser, to start the creation process for the default search page, enter the URL of the Search API server with the port and without a path name.

    Examples:

    • When the Coveo Search API is deployed on the machine which hostname is search, the URL using the default port (8080) would be:
      http://search.mycompany.com:8080

    • When the browser currently runs on the server where the Coveo Search API is installed, you can use: 
      http://localhost:8080

    Note: You can change the port used by the Coveo Search API by setting the port attribute in the http section of the config.yml file (see The http Section).

    OR 

    To create a search page with a custom name, enter the URL of the Search API server followed by the desired name in the path.

    Example: When the Coveo Search API is deployed on the machine which hostname is search, the URL using the default port (8080) could be:
    http://search.mycompany.com:8080/MyAweSomeSearchPage

    which will create a MyAweSomeSearchPage.html file.

  4. With a browser that does not support integrated authentication or when basic authentication is configured for searchPageDesigners permissions, in the browser log in dialog box that appears, enter your username and password.

    If your credentials are not recognized, contact your Search API administrator to validate that you are authorized to create and modify search pages and which authentication method is used.

  5. In the This Search Page Is not Configured Yet dialog box, click the Click Here to Start button to launch the search page creation process.

    Note:

    • It you get the following message, the user you are logged with does not have permissions to create a search page (see step 2).

      Seems like you don't have access to create a page.

    • With Internet Explorer, the dialog box may not appear (all white) failing to lad when the Compatibility mode is enabled. Deactivate the Compatibility mode (see Browser Support).

  6. In the Setup Search Page dialog:

    1. You can disable one or more suggested tabs corresponding to the found index content.

    2. Optionally, click More Tabs, when you want to immediately add tabs for other types of sources that are not yet indexed.

      Note: Added tabs will contain no results until you index content of the corresponding type.

      You can always add or remove tabs later using the Legacy Interface Editor (see Making Basic JavaScript Search Page Customization With the Legacy Interface Editor).

    3. Click Create Page.

    The search page appears.

    The search page files are saved on the Search API server in the [Search_API_Path]\pages\ folder (by default C:\Program Files\Coveo Search API 8\pages\). The default search page file name is default.html.

What's Next?

Use the Legacy Interface Editor to customize the page (see Accessing the JavaScript Search Legacy Interface Editor for a Search API Hosted Page).

Note: The Legacy Interface Editor is also bundled with Coveo for Salesforce and its usage is documented in the Coveo for Salesforce online help (see JavaScript Search Legacy Interface Editor Overview).

People who viewed this topic also viewed