Skip to main content
Appkit provides support for the Fusion REST Signals API, allowing user clicks and the creation of annotations (bookmarks, topics etc) to be recorded and tracked. To learn how to use these signals with Appkit, see Incorporating Fusion Signals in Appkit Applications.

​
Creating a collection for signals tracking

Using the Fusion UI, when a primary data collection is created, this also creates a collection for the signals. By default, the name of this signals collection is by <primary collection>_signals, where <primary collection> should be substituted with the name of the primary data collection. After data has been indexed and ingested into the primary collection, the Appkit Fusion Signals module can be used to populate the signals collection.

​
Tracking user clicks and annotations

Currently, Appkit will send information on user clicks that trigger URL requests as well as when a user creates an annotation, for example, a bookmark or comment. A signal event of type click will include, amongst other things, information about the URL that was clicked as well as the number of times that URL was clicked. A signal event of type annotation will include, amongst other things, information about the annotation target, the collection, and the creator. For a full list of properties that are stored, refer to the signals collection associated with your application.

​
Authentication

Activity tracking requires authentication. Both Fusion Impersonation via a Service Account and the Fusion Set Up Lucidworks Fusion Authentication can be used for this purpose.
To securely access Fusion via Appkit, a user has several options. They can either adopt Appkit’s Fusion security provider making use of session cookies to send repeated requests back to Fusion, or they can access Fusion via a service account if they are planning to use query pipelines. In this section, we describe how to set up the latter.

​
1 Set up a service account on the Fusion server

If a user wants to query Fusion through a pipeline by impersonating another user via a service account, they must first ensure such an account has been set up on the Fusion server. This account should have access rights to the required resources.

​
2 Add Security Trimming query stages to required pipelines

Query pipelines can have additional security filtering applied to ensure specific users do or do not have access to specific resources. This filtering can be set up by adding a Security Trimming stage to the query pipeline via the Fusion UI. The User ID key that is used in the security trimming stage to filter on results is supported in Appkit via the user-id attribute, which is described in the next section.

​
3 Update fusion.conf

To query Fusion using this approach, this attributes must be added to the platform fusion.conf file in src/main/resources/conf/platforms/fusion/:
impersonate: true
userName: joebloggs
password: password
user-id: username
Here, the impersonate attribute informs Appkit that users will be querying Fusion pipelines via a service account. Below that, both the userName and the password are the credentials for the service account that Fusion will authenticate against. The last attribute user-id is optional and by default takes the value of username. This is the parameter that will be appended to the query string and filtered on in the security trimming stage. For example, the complete query URL might appear as:
http://localhost:8764/api/apollo/query-pipelines/test-default/collections/test/select?&wt=json&q=*:*&debug=false&fl=x,y,z&start=0&username=joe@bloggs.com'
The Fusion security provider for Appkit allows authentication against Fusion using the Fusion Sessions API. With this provider configured, an application deployed within a Fusion defined ‘realm’ such as native can securely authenticate a user against Fusion.These sections describe how to set up Fusion authentication using the Sessions API within an Appkit application.

​
1. Add the security provider dependency

Authentication against Fusion using the Sessions API requires Appkit’s Fusion security provider module. To enable this module, first remove any existing security provider dependency from the pom.xml under the root of the project and insert this within the dependencies tag:
<dependency>
    <groupId>twigkit</groupId>
    <artifactId>twigkit.security.provider.fusion</artifactId>
    <version>${project.parent.version}</version>
</dependency>

​
2. Update security.conf and add fusion.conf

To invoke this module when Appkit starts up, add this to security.conf in src/main/resources/conf/security/:
type: spring_security
Then configure the session host, which security realm to use and the session timeout in fusion.conf in src/main/resources/conf/security/fusion. For example:
session-host: http://localhost:8764
session-timeout: 30
realm-name: native
The session-timeout parameter should be a time in minutes and be equal to your Fusion session timeout. By default, this value is 10. For further information, refer to the Fusion Session Api documentation.

​
3. Configure security filtering in the application

Spring Security operates using a Servlet filter which must be mapped in the web.xml file in src/main/webapp/WEB-INF:
<!-- Spring Security -->
    <context-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>classpath:spring-security.xml</param-value>
    </context-param>

    <listener>
        <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
    </listener>

    <filter>
        <filter-name>springSecurityFilterChain</filter-name>
        <filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
    </filter>

    <filter-mapping>
        <filter-name>springSecurityFilterChain</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>
<!-- Spring Security Ends -->
This should be added as the first filter in the chain (at the top of the web.xml file).

​
4. Instruct the application to use the Fusion security provider

For integration with security providers supported by Spring Security, configuration is managed in the spring-security.xml file in src/main/resources.Leave the initial section of this file dealing with HTTP URL patterns as configured. Remove any existing authentication manager configuration below that initial section, and add this:
<!-- Fusion authentication provider -->
<beans:bean id="fusionAuthenticationProvider" class="twigkit.security.fusion.FusionAuthenticationProvider"/>

<!-- Authentication manager configuration -->
<authentication-manager>
    <authentication-provider ref="fusionAuthenticationProvider"/>
</authentication-manager>
Now when a user logs into Appkit, if they have been successfully authenticated against Fusion, they will receive a session cookie that can be re-used to send subsequent requests. Access to Fusion in this way can extend for up to 10 minutes if there is no activity and up to a maximum of 8-hours if a request is received within a 10-minute interval.
Service account impersonation requires credentials for the service account and these are stored in the Fusion platform configuration. These credentials can be accessed by setting the name of the Fusion platform configuration via the platform-config parameter in the Fusion activity tracking configuration. If the credentials for a service account are not provided or cannot be found, a check will be made to see if a Fusion session cookie is available. Typically, this will be present when the user is known to the Fusion server and the Session API has been set up accordingly.