Additional resources

​

Authorization

​

How to Configure Advanced Search in App Studio Enterprise

1. Open ../src/main/webapp/search/app/controllers/search.controller.js
2. Add the following code block inside the SearchController function:
   Copy

   $scope.advancedBox = {
      showAdvanced: false,
      toggleAdvanced: function() {
          $scope.advancedBox.showAdvanced = !$scope.advancedBox.showAdvanced;
      }
   };
   

3. Open ../src/main/webapp/views/partials/header.tpl.html
4. Replace the <search:box> element with the code block below. The original <search:box> tag may span multiple lines and include nested elements such as <instant:result-list> and/or <query:suggestions>. You must replace the entire <search:box> tag with the following code block: Note: You must also update the <advanced:date-range> and <advanced:text> tags to point to fields in your data set. When using the <advanced:text> tag for searching within field values you must use an untokenized field.
   Copy

   <search:advanced>
      <search:box placeholder="Search..."></search:box>
      <a ng-click="advancedBox.toggleAdvanced()" class="toggle" styling="text-white">Advanced Search</a>
      <div class="tk-popover" ng-show="advancedBox.showAdvanced">
          <a ng-click="advancedBox.toggleAdvanced()" class="close">close</a>
          <layout:grid>
              <layout:block>
                  <advanced:date-range fields="published_date_tdt=Published Date,last_modified_tdt=Last Modified Date" min-view="day"></advanced:date-range>
                  <advanced:text fields="category_t=Category,theme_t=Theme"></advanced:text>
              </layout:block>
          </layout:grid>
      </div>
   </search:advanced>
   

5. Replace the <layout:include> tags in any HTML files that reference header.tpl.html file with an <ng:include> tag. 1.Replace this line: <layout:include file="views/partials/header.tpl.html"></layout:include> 2.With this line: <ng:include src="'views/partials/header.tpl.html'"></ng:include>
6. Add the following code block to ../src/main/webapp/styles/includes/custom.less: Note: You may need to update the color: rgb(255,255,255) attribute in the toggle class below in order for the Advanced Search... text to be visible in the header.
   Copy

   .tk-advanced-search {
      top: -5px;
      .tk-advanced-search .tk-advanced-search-input {
          -webkit-box-align: center;
          -ms-flex-align: center;
          align-items: center;
      }
      .toggle {
          color: rgb(255,255,255);
          font-size: 0.9em;
          text-decoration: underline;
          float: right;
          margin-top: 2px;
          font-style: italic;
      }
      .tk-popover {
          background: #fff;
          &:before, &:after {
              display: none;
          }
          .close {
              float: right;
              margin: -12px -8px 0 0;
          }
          select {
              margin-bottom: 0;
              margin-top: 0;
          }
      }
   }
   .tk-advanced-search .tk-advanced-search-input .entry,
   .tk-advanced-search .tk-advanced-search-input .field-select,
   .tk-advanced-search .tk-advanced-search-input .tk-widget-date-range .tk-from-date {
      margin-right: .5em;
   }
   .tk-widget-date-range .tk-from-date, .tk-widget-date-range .tk-to-date {
      width: 48%;
      margin:0;
   }
   .tk-widget-date-range .tk-to-date .tk-stl-datetimepicker {
      right:-40%;
   }
   .tk-widget-date-range .tk-from-date .tk-stl-datetimepicker {
      left: -40%;
   }
   .tk-advanced-search-input-text .entry {
      width:29.5%;
      margin-right: .8em!important;
   }
   .tk-advanced-search .tk-popover {
      .tk-advanced-search-input {
          clear:both;
          width: 100%;
          max-width: 100%;
          margin:10px 0 0;
          input {
              padding-left: 1em;
          }
          .entry {
              input {
                  width: 100%;
                  margin:0;
                  margin-top: 2px;
                  display: inline-block!important;
              }
          }
      }
      select {
          width: 28%;
          max-width: 150px;
          height: 38px;
      }
      .tk-widget-date-range {
          label {
              display: none;
          }
          input {
              margin-bottom: 0;
          }
      }
   }
   

7. Hard refresh the search UI in your browser. There will now be an Advanced Search... link under the search box in the header. Click this link to bring up the Advanced Search dialog box.

​

Implementing processors

​

Query Processor

query-profile: my-profile
workflow: twigkit.client.processor.query.AddUser
...

package twigkit.client.processor.query;
import com.google.inject.Inject;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import twigkit.model.Filter;
import twigkit.model.Query;
import twigkit.model.Value;
import twigkit.processor.QueryProcessor;
import twigkit.security.SecurityProvider;

public class AddUser extends QueryProcessor {
  private static final Logger logger = LoggerFactory.getLogger(AddUser.class);

  @Inject
  private SecurityProvider securityProvider;

  @Override
  public Query change(Query payload) {
        if (payload != null) {
          Filter userFilter = new Filter();
          userFilter.setField("user");
          Value user = new Value();    
          if (securityProvider != null) {
              if (securityProvider.getUser() != null) {
                  user.setActual(securityProvider.getUser().getName());
                  userFilter.setValue(user);
                  payload.addFilter(userFilter);
              } else {
                  logger.error("No user retrieved from " + securityProvider.getClass().getName());
              }
          } else if (payload.getUser() != null) {
              user.setActual(payload.getUser().getName());
              payload.addFilter(userFilter);
          } else {
              logger.error("No SecurityProvider provided and no user on the query!");
          }
        }
        return payload;
  }
}

​

Response processor with configuration

requestHandler: /select
query-profile: my-profile
workflow: processors.response.fuzzy-search

requestHandler: /spell

name: twigkit.client.processor.response.FuzzySearch
fuzzy-platform: platforms.fusion.fuzzy

package twigkit.client.processor.response;
import com.google.inject.Inject;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import twigkit.conf.ConfiguredPlatformProvider;
import twigkit.model.Query;
import twigkit.model.Response;
import twigkit.model.messages.Message;
import twigkit.platform.Platform;
import twigkit.processor.ResponseProcessor;

import java.util.ArrayList;
import java.util.List;

public class FuzzySearch extends ResponseProcessor {
  private static final Logger logger = LoggerFactory.getLogger(FuzzySearch.class);

  @Inject
  private ConfiguredPlatformProvider platformProvider;

  @Override
  public Response change(Response response) {
        String fuzzyPlatformId = getParameterStringValue("fuzzy-platform");
        Platform fuzzyPlatform = platformProvider.get(fuzzyPlatformId);    
        if (response.getHits().getActual() > 0){
          return response;
        } else {
          Query query = response.getQuery();
          Response fuzzyResponse = fuzzyPlatform.search(query);
          String queryString = query.getValue().getActualAsString();    
          Message fuzzyMessage = new Message();
          fuzzyMessage.setType("fuzzy-results");
          fuzzyMessage.setValue("No results found for the term <em>"+queryString+"</em>. Returning results with similar words.");    
          List<Message> messages = new ArrayList<Message>();
          messages.add(fuzzyMessage);
          fuzzyResponse.setMessages(messages);    
          return fuzzyResponse;
        }
  }
}

​

How to Configure Solr Highlighting in App Studio

1. Open any HTML page that uses a <search:query> tag where highlighting should take place.
2. Modify the <search:query> tag to include the required hl.fl parameter (a complete list of optional parameters can be found here):
   
   If not using App Studio Enterprise, an additional hl parameter must be included and set to true for highlighting to work. App Studio Enterprise sets this parameter to true by default in ../src/main/resources/conf/platforms/fusion/fusion.conf (via highlighting: true).
   Copy

   <search:query var="query" parameters="*" results-per-page="12">
      <query:custom name="hl.fl" value="description_t"></query:custom>
   </search:query>
   

   Parameter Name	Parameter Value	Description
   hl.fl	description_t	comma separated list of fields where highlighting should occur
   hl (only required if not using App Studio Enterprise)	true	Boolean flag for whether or not highlighting should occur

3. Refresh the search UI in your browser and any hits will appear highlighted. NOTE: you must have the field(s) specified in the hl.fl parameter above displayed using a <search:field> on the HTML page.
4. See the Styling Highlighted Hits section below for steps to add custom styling to search hits.

​

How to Configure Solr Highlighting in a Fusion Query Pipeline

1. In the Query Workbench, add or modify an existing Additional Query Parameters stage.
2. Add the following required parameters (a full list of optional parameters can be found here):
   
   If not using App Studio Enterprise, an additional hl parameter must be included and set to true for highlighting to work. App Studio Enterprise sets this parameter to true by default in ../src/main/resources/conf/platforms/fusion/fusion.conf (via highlighting: true).

   Parameter Name	Parameter Value	Description
   hl.fl	description_t	comma separated list of fields where highlighting should occur
   hl (only required if not using App Studio Enterprise)	true	Boolean flag for whether or not highlighting should occur

3. Save the query pipeline, and return to your search application.
4. Run a new search that utilizes the query pipeline modified in step 2 and any hits will appear highlighted. NOTE: you must have the field(s) specified in the hl.fl parameter above displayed using a <search:field> on the HTML page.
5. See the Styling Highlighted Hits section below for steps to add custom styling to search hits.

​

Styling Highlighted Hits

1. Add the following CSS in order to add custom styling to Solr highlighting:
   1. If using App Studio Enterprise, this should go in ../src/main/webapp/styles/includes/custom.less
   2. Any custom CSS can be used in place of the example attributes below.
      Copy

      .result {
      em {
          background-color: yellow;
          font-weight: bold;
          font-style: normal;
      }
      }
      

​

Requirements

• Any JDBC-compliant relational database (such as Oracle, MySQL, or SQL Server) or a Fusion deployment
• Network access from the Appkit application to the relational database or to Fusion

​

Persist data in a relational database

​

Overview of procedure

1. Declare a Maven POM dependency in pom.xml to specify the database for storing the metadata that the Social module collects.
2. Configure a persistence.xml file with the appropriate elements, including those for database connections.
3. If necessary, perform other steps as required for specific databases.

​

Use Derby

​

Declare a POM dependency

<dependency>
    <groupId>twigkit</groupId>
    <artifactId>twigkit.social.provider.db.derby.memory</artifactId>
    <version>${project.parent.version}</version>
</dependency>

<dependency>
    <groupId>twigkit</groupId>
    <artifactId>twigkit.social.db.provider.derby</artifactId>
    <version>${project.parent.version}</version>
</dependency>

​

Create and configure persistence.xml

​

Specify the type of Hibernate ID generator mappings

• Apps created with versions of Appkit that precede version 4.2. Ensure that both pre- and post-Hibernate 5 IDs are generated using the old mapping. Add this property to the persistence.xml file:
  Copy

  <property name="hibernate.id.new_generator_mappings" value="false" />
  

• Apps created with Appkit 4.2 or later. Apps can use new ID generator mappings. Add this property to the persistence.xml file:
  Copy

  <property name="hibernate.id.new_generator_mappings" value="true" />
  

​

Specify the Derby system directory

-Dderby.system.home=*_/my/derby/directory_*

​

Use a different relational database

db.mysql
db.oracle
db.sqlserver

​

Declare the POM dependency

<dependency>
    <groupId>twigkit</groupId>
    <artifactId>twigkit.social.provider.db.mysql</artifactId>
    <version>${project.parent.version}</version>
</dependency>

<dependency>
    <groupId>twigkit</groupId>
    <artifactId>twigkit.social.provider.db.oracle</artifactId>
    <version>${project.parent.version}</version>
</dependency>

<dependency>
    <groupId>twigkit</groupId>
    <artifactId>twigkit.social.provider.db.sqlserver</artifactId>
    <version>${project.parent.version}</version>
</dependency>

​

Create and configure persistence.xml

​

Specify the type of Hibernate ID generator mappings

• Apps created with versions of Appkit that precede version 4.2. Ensure that both pre- and post-Hibernate 5 IDs are generated using the old mapping. Add this property to the persistence.xml file:
  Copy

  <property name="hibernate.id.new_generator_mappings" value="false" />
  

• Apps created with Appkit 4.2 or later. Apps can use new ID generator mappings. Add this property to the persistence.xml file:
  Copy

  <property name="hibernate.id.new_generator_mappings" value="true" />
  

​

Persist Social module data in Fusion

1. Configure Fusion.
2. Enable social features.

​

Troubleshooting database configuration

​

Connection issues

1. Add the dependency for Hibernate c3p0 to the pom.xml:
   Copy

   <!-- Hibernate c3p0 connection pooling -->
   <dependency>
      <groupId>org.hibernate</groupId>
      <artifactId>hibernate-c3p0</artifactId>
      <version>X.X.X.Final</version>
   </dependency>
   

   The version of Hibernate c3p0 you should use depends on the version of Appkit you are using. To begin with, try Hibernate version 4.1.7.Final (legacy) or 5.2.2.Final.
2. Add the configuration for C3P0 to the persistence.xml file:
   Copy

   <!-- c3p0 connection pool settings -->
   <property name="hibernate.connection.provider_class" value="org.hibernate.connection.C3P0ConnectionProvider" />
   <property name="hibernate.c3p0.max_size" value="100" />
   <property name="hibernate.c3p0.min_size" value="0" />
   <property name="hibernate.c3p0.acquire_increment" value="1" />
   <property name="hibernate.c3p0.idle_test_period" value="300" />
   <property name="hibernate.c3p0.max_statements" value="0" />
   <property name="hibernate.c3p0.timeout" value="100" />
   

​

Requirements

• Any relational JDBC-compliant database (such as Oracle or MySQL).
• Network access from the Appkit application to the relational database.

​

Database specific setup instructions

<dependency>
    <groupId>twigkit</groupId>
    <artifactId>twigkit.social.provider.db.derby.memory</artifactId>
    <version>${project.parent.version}</version>
</dependency>

<dependency>
    <groupId>twigkit</groupId>
    <artifactId>twigkit.social.db.provider.derby</artifactId>
    <version>${project.parent.version}</version>
</dependency>

-Dderby.system.home=/my/derby/directory

db.mysql
db.oracle
db.sqlserver

​

ID generator mappings in the persistence.xml

<property name="hibernate.id.new_generator_mappings" value="false" />

​

Troubleshooting database configuration

​

Connection issues

1. Add the dependency for Hibernate c3p0 to the pom.xml:
   Copy

   <!-- Hibernate c3p0 connection pooling -->
   <dependency>
      <groupId>org.hibernate</groupId>
      <artifactId>hibernate-c3p0</artifactId>
      <version>X.X.X.Final</version>
   </dependency>
   

   The version of Hibernate c3p0 you should use depends on the version of Appkit you are using. To begin with try version 4.1.7.Final (legacy) or 5.2.2.Final.
2. Add the configuration for C3P0 to the persistence.xml:
   Copy

   <!-- c3p0 connection pool settings -->
   <property name="hibernate.connection.provider_class" value="org.hibernate.connection.C3P0ConnectionProvider" />
   <property name="hibernate.c3p0.max_size" value="100" />
   <property name="hibernate.c3p0.min_size" value="0" />
   <property name="hibernate.c3p0.acquire_increment" value="1" />
   <property name="hibernate.c3p0.idle_test_period" value="300" />
   <property name="hibernate.c3p0.max_statements" value="0" />
   <property name="hibernate.c3p0.timeout" value="100" />
   

​

SSL keystore

​

SSL parameters

• Define which provider to use (the “search:platform” tag).
• Create a query from the URL, or any parameters you explicitly declare (the “search:query” tag).
• Send the query to the platform and obtain a response (the “search:response” tag).

<search:platform var="platform" conf="platforms.fusion.data"></search:platform>
<search:query var="query" parameters="*" results-per-page="12"></search:query>
<search:response var="response" platform="platform" query="query">
    <widget:spinner></widget:spinner>
</search:response>

​

The search:platform tag

<search:platform var="platform" conf="platforms.fusion.data"></search:platform>

​

The search:query tag

<search:query var="query" parameters="*" results-per-page="12"></search:query>

<search:query var="query" parameters='*,-rpp' results-per-page="12"></search:query>

​

The search:response tag

<search:response var="response" platform="platform" query="query">
    <widget:spinner></widget:spinner>
</search:response>

​

1 Add the security provider dependency

<dependency>
    <groupId>twigkit</groupId>
    <artifactId>twigkit.security.provider.cookie-cracker</artifactId>
    <version>${project.parent.version}</version>
</dependency>

​

2 Configure the cookie cracking endpoint

url: http://localhost:8080/twigkit/services/gsa/auth
cookies: twigkit-token
domain: localhost

• url is the URL of the cookie cracking endpoint that acts as an authentication provider.
• cookies specifies those cookies to pass through to the cookie cracking endpoint for inspection.
• domain specifies a domain to set on the cookies listed (optional except when the cookie cracking endpoint exists on a separate domain to the Appkit application, in which case it is required).

​

Prerequisites

​

How to create a new Web app

1. In the Fusion workspace, navigate to App Studio > Build New UI.
2. On the Set Query Source page, select the query profile to use for your search UI:
3. Click Next. App Studio connects to the specified collection and query profile to analyze your searchable data:
4. Click Next.
5. On the Set Result Title page, select the field to use as the title of each search result: Optionally, you can select a Target URL field, which contains the URL to use as the link in each search result.
6. Click Next.
7. On the Set Result Description page, select the field to use as the description of each search result:
8. Click Next.
9. On the Set Facets and Additional Fields page, select one or more multi-valued fields to use as facets:
   In some cases, facet fields are not selectable in the wizard. In this case, you can define facets later using markup.
   Optionally:
   • Select Enable search within facet to add a search box for searching the facet field names to the Facets pane.
   
   • Enter a user-friendly label for each facet field, such as “Genre” instead of “genres_ss”.
   • Select Include in results as Additional Field to display the values of the facet fields within each search result.
10. Click Next.
11. On the Customize UI page, enter a title and select a color theme:
12. Click Save and Launch UI. A preview of your search interface and data appear:
    It can take about a minute for the preview to appear. If the preview does not appear, refresh the browser tab.

1. If it does not already exist, create a new file named csrf.conf and place it in src/main/resources/conf/security.
2. In that file, set the property enabled to true. This tokenizes the requests.
3. By default, the time-to-live of the Appkit request token is 60 minutes. You can change this by setting the property duration to some other value; for example, duration: 30. Responses received without a request token or with a request token has expired are rejected.

enabled: true
duration: 30

​

UI deployment overview

1. Develop your search interface.
2. Publish your UI to Fusion Server using the instructions below.

​

Publishing a search interface to Fusion Server

1. In the Fusion workspace, navigate to App Studio and select your search interface. The configuration panel appears.
2. Next to Publish Status, click the toggle:
3. Click Save. The interface is only published after you click Save, which also enables the View Published UI button.
4. Click View Published UI to launch a new window where you can view the interface as an end user. Your published interface is available at http://localhost:8764/webapps/<project-name>#/search.

​

Migrating a search interface to other Fusion hosts

​

Download or build a WAR file

​

Downloading a WAR file

1. In the Fusion workspace, navigate to App Studio and select your search interface. The configuration panel appears.
2. Click Download war:

​

Building a WAR file

1. In a shell window, switch to your project directory:
   Copy

   cd /path/to/project-directory
   

2. Create application files:
   Copy

   ./app-studio package
   

1. In a terminal window, switch to your project directory:
   Copy

   cd \path\to\project-directory
   

2. Create application files:
   Copy

   app-studio.bat package
   

• search-app-latest.x.jar This is an executable Java JAR file file.
• search-app-project.zip Use this file to share your project with other search interface developers.
• search-app.war You can upload this file to Fusion to deploy it.

​

Upload the WAR file

​

Uploading with the Fusion UI

1. From the App Studio menu, select your project: The project configuration panel appears.
2. Click Upload. Fusion prompts you to confirm that you want to upload a project that will delete the existing one.
3. Click Yes, continue.
4. Navigate to your WAR file and select it. After the upload is complete, you can edit or publish the uploaded project.

​

Uploading with the REST API

curl -u USERNAME:PASSWORD -X PUT http://localhost:8764/api/webapps/Movie_Search/war -F 'file=@movies.war'

​

Running a dedicated node for a search interface

• agent
• api
• log-shipper
• webapps

cd fusion/latest.x/bin
./agent start
./api start
./log-shipper start
./webapps start

cd fusion\latest.x\bin
agent.cmd start
api.cmd start
log-shipper.cmd start
webapps.cmd start

​

Development

​

Environment / Profile management

​

Setting up a profile

​

Packaging and Deployment

​

Packaging

​

Deployment

​

Create a new App Studio context in Fusion

1. Fusion is installed
2. A Fusion App is created

curl -v -u USERNAME:PASSWORD -H 'Content-type: application/json' -X POST 'http://localhost:8764/api/apollo/apps/my-fusion-app-name/webapps' -d '{"id": "myasapp","name": "My AS App","contextPath": "/"}'

​

Upload the WAR to the Fusion webapps service

curl -v -u USERNAME:PASSWORD -H 'Content-type: application/zip' -X PUT 'http://localhost:8764/api/apollo/apps/my-fusion-app-name/webapps/myasapp/war' --data-binary @ROOT.war

​

Troubleshooting

​

Data is not appearing on the page as expected

​

Check response data

​

Get query from webapps/servlet logs and fire it against Fusion

08:57:41.058 DEBUG twigkit.search.solr.SolrPlatform - Searching Solr with start=0&rows=20&hl=true&q=match&facet=true&facet.field={!ex%3Dgenre_ss}genre_ss&facet.field=year_i&fl=*,score&fq={!tag%3Dgenre_ss}genre_ss:(Animation)&username=admin&session=37045658-9052-4ba4-b1d2-0221be5e2d02&spellcheck=true&spellcheck.collate=true&q.op=OR took 200 ms

​

Page is totally blank/elements look broken or strange

​

Check browser console

Uncaught Error: [$injector:modulerr] Failed to instantiate module myApp due to:
Error: [$injector:modulerr] Failed to instantiate module lightning due to:
Error: [$injector:nomod] Module 'lightning' is not available! You either misspelled the module name or forgot to load it. If registering a module ensure that you specify the dependencies as the second argument.

1. rm -rf node_modules package-lock.json\
2. pm cache clear -f\
3. npm install

./twigcrypt.sh yourSecretSeed 'yourSensitiveValue'

username:jbloggs
password:Enc(ABC123==)

password: yourSecretSeed

​

Adding sensitive configuration parameters to Spring Security XML files

• Environment variables
• Configuration parameters

​

Passing environment variables

my property: \#{systemEnvironment['USER_TEST']}

​

Passing in configuration parameters

my property: \#{systemProperties['user_test']}

​

App Studio

​

App Studio 4.0

• app-studio.sh. A Bash script for Linux and macOS
• app-studio.bat. A batch file for Windows

./app-studio.sh status

app-studio.sh status

<layout:include file="views/partials/header.tpl.html" action="search"></layout:include>

​

Sidebar with facet list

<layout:block md="1-3" lg="1-4" drawer="left" id="sidebar" styling="blocksidebar-light">
    <layout:sidebar>
        <layout:box>
            <!-- List facets and give them intuitive labels -->
            <search:facet-list facet-names="genres_ss" response="response" platform="platform" query="query" styling="facet-list facet-list-wrappedheader">
              <search:facet when-field="genres_ss" show="10" search-enabled="true" platform="platform" query="query" max-characters="40" show="12" show-more="24" collapsible="true"></search:facet>
              <search:facet show="10" max-characters="40" show="12" show-more="24" collapsible="true"></search:facet>
            </search:facet-list>
        </layout:box>
    </layout:sidebar>
</layout:block>

​

1 Add the Fusion Signals dependency

<dependency>
        <groupId>twigkit</groupId>
        <artifactId>twigkit.activity.fusion-signals</artifactId>
        <version>${project.parent.version}</version>
</dependency>

​

2 Add fusion.conf to activity tracking resources

signals-endpoint: http://localhost:8764/api/apollo/signals/image_catalog
signals-index-pipeline:
commit: true
async: false
platform-config: platforms.fusion

impersonate: true
userName: joebloggs
password: Enc(<encoded password>)

​

Version 4.1

​

Version 4.0

​

Licensing

​

Requirements

• Oracle Java JDK 1.8 or later
• A running instance of Fusion Server, with one or more collections of indexed data

​

Installation

1. Download App Studio.
2. Copy the App Studio zip file to any convenient path.
3. Expand the archive: unzip app-studio-latest.x-zip-package.zip This creates an app-studio directory.

​

What is next

• See Startup and Shutdown for information about using the App Studio scripts.
• See Create a New Web App to learn how to create your first search app.

./app-studio dist

app-studio.bat dist

​

Standalone app directory

search-app-standalone/
	README.md
	app/
	build/
	config/
	keystore.jks
	lib
	search-app-start.bat
	search-app-stop.bat
	search-app-stop.ps1
	search-app.sh

search-app-standalone\
	README.md
	app\
	build\
	config\
	keystore.jks
	lib
	search-app-start.bat
	search-app-stop.bat
	search-app-stop.ps1
	search-app.sh

​

Requirements

• Any JDBC-compliant relational database (such as Oracle, MySQL, or SQL Server) or a Fusion deployment
• Network access from the Appkit application to the relational database or to Fusion

​

Persist data in a relational database

​

Overview of procedure

1. Declare a Maven POM dependency in pom.xml to specify the database for storing the metadata that the Social module collects.
2. Configure a persistence.xml file with the appropriate elements, including those for database connections.
3. If necessary, perform other steps as required for specific databases.

​

Use Derby

​

Declare a POM dependency

<dependency>
    <groupId>twigkit</groupId>
    <artifactId>twigkit.social.provider.db.sqlserver.memory</artifactId>
    <version>${project.parent.version}</version>
</dependency>

<dependency>
    <groupId>twigkit</groupId>
    <artifactId>twigkit.social.db.provider.sqlserver</artifactId>
    <version>${project.parent.version}</version>
</dependency>

​

Create and configure persistence.xml

​

Specify the type of Hibernate ID generator mappings

• Apps created with versions of Appkit that precede version 4.2. Ensure that both pre- and post-Hibernate 5 IDs are generated using the old mapping. Add this property to the persistence.xml file:
  Copy

  <property name="hibernate.id.new_generator_mappings" value="false" />
  

• Apps created with Appkit 4.2 or later. Apps can use new ID generator mappings. Add this property to the persistence.xml file:
  Copy

  <property name="hibernate.id.new_generator_mappings" value="true" />
  

​

Specify the Derby system directory

-Dderby.system.home=*_/my/derby/directory_*

​

Use a different relational database

db.mysql
db.oracle
db.sqlserver

​

Declare the POM dependency

<dependency>
    <groupId>twigkit</groupId>
    <artifactId>twigkit.social.db.provider.sqlserver</artifactId>
    <version>${project.parent.version}</version>
</dependency>

<dependency>
    <groupId>twigkit</groupId>
    <artifactId>twigkit.social.db.provider.sqlserver</artifactId>
    <version>${project.parent.version}</version>
</dependency>

<dependency>
    <groupId>twigkit</groupId>
    <artifactId>twigkit.social.db.provider.sqlserver</artifactId>
    <version>${project.parent.version}</version>
</dependency>

​

Create and configure persistence.xml

​

Specify the type of Hibernate ID generator mappings

• Apps created with versions of Appkit that precede version 4.2. Ensure that both pre- and post-Hibernate 5 IDs are generated using the old mapping. Add this property to the persistence.xml file:
  Copy

  <property name="hibernate.id.new_generator_mappings" value="false" />
  

• Apps created with Appkit 4.2 or later. Apps can use new ID generator mappings. Add this property to the persistence.xml file:
  Copy

  <property name="hibernate.id.new_generator_mappings" value="true" />
  

​

Troubleshooting database configuration

​

Connection issues

1. Add the dependency for Hibernate c3p0 to the pom.xml:
   Copy

   <!-- Hibernate c3p0 connection pooling -->
   <dependency>
      <groupId>org.hibernate</groupId>
      <artifactId>hibernate-c3p0</artifactId>
      <version>X.X.X.Final</version>
   </dependency>
   

   The version of Hibernate c3p0 you should use depends on the version of Appkit you are using. To begin with try version 4.1.7.Final (legacy) or 5.2.2.Final.
2. Add the configuration for C3P0 to the persistence.xml:
   Copy

   <!-- c3p0 connection pool settings -->
   <property name="hibernate.connection.provider_class" value="org.hibernate.connection.C3P0ConnectionProvider" />
   <property name="hibernate.c3p0.max_size" value="100" />
   <property name="hibernate.c3p0.min_size" value="0" />
   <property name="hibernate.c3p0.acquire_increment" value="1" />
   <property name="hibernate.c3p0.idle_test_period" value="300" />
   <property name="hibernate.c3p0.max_statements" value="0" />
   <property name="hibernate.c3p0.timeout" value="100" />
   

​

1: Configure your alerting module database

1. Add this dependency to your pom.xml:
   Copy

   <dependency>
      <groupId>twigkit</groupId>
      <artifactId>twigkit.social.runtime</artifactId>
      <version>${project.parent.version}</version>
   </dependency>
   <dependency>
    <groupId>twigkit</groupId>
    <artifactId>twigkit.alert.db.derby.memory</artifactId>
    <version>${project.parent.version}</version>
   </dependency>
   

2. Remove any existing reference to twigkit.social modules. Currently the in-memory database and MySQL are supported (twigkit.alert.db.mysql).

​

2: Add alerting module ORM mapping to your persistence configuration

<mapping-file>META-INF/alert/orm.xml</mapping-file>

​

3: Tell the Quartz scheduler how to connect to the database

org.quartz.scheduler.instanceName = AlertScheduler
org.quartz.threadPool.threadCount = 4
org.quartz.jobStore.class = org.quartz.impl.jdbcjobstore.JobStoreTX
org.quartz.jobStore.driverDelegateClass = org.quartz.impl.jdbcjobstore.StdJDBCDelegate
org.quartz.jobStore.dataSource = AlertDataSource

org.quartz.dataSource.AlertDataSource.driver = ${javax.persistence.jdbc.driver}
org.quartz.dataSource.AlertDataSource.URL = ${javax.persistence.jdbc.url}
org.quartz.dataSource.AlertDataSource.user = ${javax.persistence.jdbc.user}
org.quartz.dataSource.AlertDataSource.password = ${javax.persistence.jdbc.password}
org.quartz.dataSource.AlertDataSource.maxConnections = 30
org.quartz.jobStore.tablePrefix = qrtz_

​

Compiling a self-contained application

./app-studio dist

app-studio.bat dist

search-app-project.zip
search-app-standalone/
	README.md
	app/
	build/
	config/
	keystore.jks
	lib
	search-app-start.bat
	search-app-stop.bat
	search-app-stop.ps1
	search-app.sh

​

Compiling a .jar file

1. In a shell window, switch to your project directory:
   Copy

   cd /path/to/Project_Directory
   

2. Run the following command:
   Copy

   ./app-studio package
   

​

Launching a self-executing deployment

java -jar search-app-VERSION.x-y.y.y.jar

1. Add this dependency to your pom.xml file:
   Copy

   <dependency>
    <groupId>twigkit</groupId>
    <artifactId>twigkit.alert.runtime</artifactId>
    <version>${project.parent.version}</version>
   </dependency>
   

2. Set up conf/alert/email/smtp.conf; see below for an example configuration:
   Copy

   # User to log into Appkit
   twigkit-user: foo
   twigkit-password: bar    
   # User to send emails as
   from: foobar@twigkit.com
   password: foobar    
   # Override to address for all config-based alerts
   to: reporting@some-alerting-domain.com    
   # SMTP details
   mail.smtp.host: smtp.gmail.com
   mail.smtp.port: 587
   mail.smtp.auth: true
   mail.smtp.starttls.enable: true
   

3. Set up conf/alert/email/alerts/alerts.conf; see below for an example configuration:
   Copy

   email-template: http://localhost:8080/email/
   

4. Add the alert .conf files to conf/alert/email/alerts/my-alert-name-here.conf; see below for an example:
   Copy

   to: foobar@twigkit.com
   subject: New documents on brewing
   query: ?q=homebrew
   cron-expression: 30 * * * * ?
   

   Here, the cron-expression defines how often to send the alert as described in this Quartz tutorial.
5. Create a JSP, in this case configured as above, on a standard Appkit application would be in src/main/webapp/WEB-INF/pages/email.jsp and the content would include:
   Copy

   <%@ page contentType="text/html" pageEncoding="UTF-8" %>
   <%@ include file="/WEB-INF/tags/client/taglibs.jspf" %>
   <search:localization var="resources" bundleName="resources" />    
   <search:twigkit>
      <search:platform conf="platforms.solr" />
      <search:query var="query" parameters="*" />
      <search:response var="response" platform="${platform}" query="${query}" />
   </search:twigkit>    
   <!DOCTYPE html>
   <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
      <h1>Automated alert for query ${query.value}</h1>
      <search:resultList response="${response}">
          <search:result>
              <search:field name="title" />
              <search:field name="description" />
          </search:result>
      </search:resultList>
   </html>
   

1. Add this dependency to your pom.xml. Remove any previous reference to twigkit.social modules.
   Copy

   <dependency>
      <groupId>twigkit</groupId>
      <artifactId>twigkit.social.runtime</artifactId>
      <version>${project.parent.version}</version>
   </dependency>
   <dependency>
    <groupId>twigkit</groupId>
    <artifactId>twigkit.alert.db.derby.memory</artifactId>
    <version>${project.parent.version}</version>
   </dependency>
   

2. Add a configuration file in conf/alert/email/smtp.conf; see below for an example configuration:
   Copy

   # User to log into Appkit (service account)
   twigkit-user: admin
   twigkit-password: password    
   # Email account to use to send alert emails
   from: foobar@twigkit.com
   password: foobar    
   # SMTP details
   mail.smtp.host: smtp.gmail.com
   mail.smtp.port: 587
   mail.smtp.auth: true
   mail.smtp.starttls.enable: true
   

3. Add another configuration file for the email template in conf/alert/email/alerts/alerts.conf; see below for an example configuration:
   Copy

   email-template: http://localhost:8080/email/
   subject-prefix: New report for saved query
   

4. Add the saved query alert scheduling form to the search header (header.tag):
   Copy

   <social:searchHeader query="${query}" action="${action}" logoImage="/assets/logo-google.png" logoHeight="42" logoImageAlt="Appkit for GSA">
      <jsp:attribute name="searchFormBody">
          <instant:resultList platformConf="platforms.gsa">
              <instant:result>
                  <a href="{{result.fields.url.val[0]}}">
                      <instant:field fieldName="title" />
                  </a>
              </instant:result>
          </instant:resultList>
      </jsp:attribute>
      <jsp:attribute name="searchControls">
          <\%-- Bookmarks --%>
          <widget:popover id="bookmark-list" title="Bookmarks" linkText="" align="right">
              <social:bookmarkList emptyText="You do not currently have any bookmarks." user="${social:getCurrentUserProfile()}" format="dd MMM yyyy" />
          </widget:popover>    
          <\%-- Saved Searches --%>
          <widget:popover id="saved-searches" title="Saved Searches" linkText="" align="right">
              <alert:savedQueryAlertForm query="${query}" />
              <alert:savedQueryAlertList user="${social:getCurrentUserProfile()}" action="${action}" format="dd MMM yyyy" emptyText="You do not currently have any saved searches." />
          </widget:popover>
      </jsp:attribute>
   </social:searchHeader>
   

5. Create the email template JSP, in src/main/webapp/WEB-INF/pages/email.jsp. For example:
   Copy

   <%@ page contentType="text/html" pageEncoding="UTF-8" %>
   <%@ include file="/WEB-INF/tags/client/taglibs.jspf" %>    
   <search:twigkit>
      <search:platform var="delegatePlatform" conf="platforms.elasticsearch" />
      <alert:platform delegatePlatform="${delegatePlatform}" />
      <alert:query dateField="updated" />
      <alert:response var="response" platform="${platform}" query="${query}">    
      </alert::response>
   </search:twigkit>    
   <!DOCTYPE html>
   <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">    
   <h1>Automated alert for query ${query.value}</h1>
   <search:result-list response="response">
      <search:result>
          <search:field name="title" />
          <search:field name="summary" />
      </search:result>
   </search:result-list>    
   </html>
   

• The ‘alert seen’ functionality is reliant on a field in the data specifying the date the document was last updated, in this case named updated
• The ‘to address’ of the email alert will either be chosen by the user via the form (default) or can be set by using the toAddress attribute on the saved query alert form tag.
• Appkit includes full user impersonation, so any security trimming is applied automatically.

​

Scripts

• app-studio.sh. A Bash script for Linux and macOS
• app-studio.bat. A batch file for Windows

​

Obtain usage information about the scripts

• Linux and macOS: ./app-studio.sh -help
• Windows: app-studio.bat -help

• Linux and macOS: ./app-studio **_command_** -help
• Windows: app-studio.bat **_command_** -help

​

Shutdown commands

• Linux and macOS: ./app-studio stop [-p port] [-V]
• Windows: app-studio.bat stop [-p port] [-V]

​

Parameters

​

Stopping multiple App Studio instances

./app-studio.sh stop -p 9000

​

Version 4.0

​

What is next

• See Create a New Web App to learn how to create your first search app.

​

Scripts

• app-studio.sh. A Bash script for Linux and macOS
• app-studio.bat. A batch file for Windows

​

Obtain usage information about the scripts

• Linux and macOS: ./app-studio.sh -help
• Windows: app-studio.bat -help

• Linux and macOS: ./app-studio **_command_** -help
• Windows: app-studio.bat **_command_** -help

​

Startup commands

• Linux and macOS: ./app-studio start [--production] [-f] [-p port] [-m memory] [-t timeout] [-V]
• Windows: app-studio.bat start [-f] [-p port] [-m memory] [-t timeout] [-V]

​

Parameters

​

Starting multiple App Studio instances

./app-studio.sh start -p 9000

​

Version 4.0

​

Starting in production mode

./app-studio-standalone.sh start --production

​

What is next

• See Create a New Web App to learn how to create your first search app.

1. Add this dependency to your pom.xml file:
   Copy

   <dependency>
    <groupId>twigkit</groupId>
    <artifactId>twigkit.alert.runtime</artifactId>
    <version>${project.parent.version}</version>
   </dependency>
   

2. Set up conf/alert/email/smtp.conf; see below for an example configuration:
   Copy

   # User to log into Appkit
   twigkit-user: foo
   twigkit-password: bar
   # User to send emails as
   from: foobar@twigkit.com
   password: foobar
   # Override to address for all config-based alerts
   to: reporting@some-alerting-domain.com
   # SMTP details
   mail.smtp.host: smtp.gmail.com
   mail.smtp.port: 587
   mail.smtp.auth: true
   mail.smtp.starttls.enable: true
   

3. Set up conf/alert/email/alerts/alerts.conf; see below for an example configuration:
   Copy

   email-template: http://localhost:8080/email/
   

4. Add the alert .conf files to conf/alert/email/alerts/my-alert-name-here.conf; see below for an example:
   Copy

   to: foobar@twigkit.com
   subject: New documents on brewing
   query: ?q=homebrew
   cron-expression: 30 * * * * ?
   

   Here, the cron-expression defines how often to send the alert as described in this Quartz tutorial.
5. Create a JSP, in this case configured as above, on a standard Appkit application would be in src/main/webapp/WEB-INF/pages/email.jsp and the content would include:
   Copy

   <%@ page contentType="text/html" pageEncoding="UTF-8" %>
   <%@ include file="/WEB-INF/tags/client/taglibs.jspf" %>
   <search:localization var="resources" bundleName="resources" />
   <search:twigkit>
      <search:platform conf="platforms.solr" />
      <search:query var="query" parameters="*" />
      <search:response var="response" platform="${platform}" query="${query}" />
   </search:twigkit>
   <!DOCTYPE html>
   <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
      <h1>Automated alert for query ${query.value}</h1>
      <search:result-list response="response">
          <search:result>
              <search:field name="title" />
              <search:field name="description" />
          </search:result>
      </search:result-list>
   </html>
   

​

Sending event notifications

import com.google.common.eventbus.EventBus;
import com.google.inject.Inject;

@Inject
EventBus eventBus;

...

eventBus.post(new MyEvent());

​

Subscribing to events

import eventBus.register.Subscribe;

public class MyEventSubscriber {
    @Subscribe
    public void newEvent(MyEvent event) {
    // implement your business logic here
    }
}

import com.google.common.eventbus.EventBus;
import com.google.inject.Inject;

@Inject
EventBus eventBus;

...

eventBus.register(new MyEventSubscriber());

​

Standard event types

• twigkit.security.event.LoginEvent: User logs into the system.
• twigkit.event.ResponseEvent: A search response was retrieved from a data provider.

• twigkit.event.QueryEvent: A search query was formulated and submitted to a data provider.
• twigkit.event.ClickEvent: User clicked a link on a page, possibly linked to a search query.

​

Data is not appearing on the page as expected

​

Check the response data

1. Open your browser’s developer tools.
2. Click the Network tab.
3. Look for an XHR request similar to the one shown below (starting with platforms.fusion…) and select it.
   
   Here you can navigate through the values being returned from Fusion.
4. To determine which response is which (as you may have multiple) look at the platform that populates the response, which also populates the element on your page.
   You can then track down the value you are looking for. So if looking at results, a result list iterates through the results, so we should look inside a result. In each result, there’s a set of fields and associated values:
   
   Note that other processing may happen in between receiving the response and displaying it on the page (response processors, modifications in the HTML, security trimming, and so on).

​

Get query from webapps/servlet logs and fire it against Fusion

1. Make sure your logger is configured to print out debug logging for the twigkit class in logback.xml in your environment profile (or if not using a profile, in the main resources directory):
   Copy

   <logger name="twigkit" level="DEBUG"/>
   

2. In fusion/version/var/log/webapps/, sort by date (ls -l) and view the latest one with the suffix of stderrout.
   Here you will see some entries that should follow the format of the following:
   Copy

   08:57:41.058 DEBUG twigkit.search.solr.SolrPlatform - Searching Solr with start=0&rows=20&hl=true&q=match&facet=true&facet.field={!ex%3Dgenre_ss}genre_ss&facet.field=year_i&fl=*,score&fq={!tag%3Dgenre_ss}genre_ss:(Animation)&username=admin&session=37045658-9052-4ba4-b1d2-0221be5e2d02&spellcheck=true&spellcheck.collate=true&q.op=OR took 200 ms
   

3. To determine which entry is the correct one, check the query that populates the response you’re interested in, and match the parameters you’re setting in the tag as well as any Solr parameters being applied to the query via interaction on the page (keyword = q, facet filters = fq, and so on).
4. Go to the Query Workbench in Fusion and select the Published URI in the URI tab:\
5. Remove every parameter given in this URL after select?.
6. Append the parameters from the webapps logs.
7. Put the resulting URL into your browser.
   The result will be the response of the query fired by App Studio, but unaltered by App Studio.

​

Page is totally blank/elements look broken or strange

​

Check the browser console

1. Open your browser’s developer tools.
2. Click the Console tab.
   Here you can check for any issues related to client-side components.
3. Look for the following error:
   Copy

   Uncaught Error: [$injector:modulerr] Failed to instantiate module myApp due to:
   Error: [$injector:modulerr] Failed to instantiate module lightning due to:
   Error: [$injector:nomod] Module 'lightning' is not available! You either misspelled the module name or forgot to load it. If registering a module ensure that you specify the dependencies as the second argument.
   

   • If you see the error above, you should wipe your node_modules directory and reinstall the modules before building:
   1. rm -rf node_modules package-lock.json
   2. npm cache clear -f
   3. npm install
   • If you do not see this error, then typically there is a problem in your Javascript code.