Skip to main content

Getting Started

The SBA Framework is used in a variety of contexts by both technical and non-technical people. This section presents different approaches to getting started, depending on your role and overall objectives.

In this documentation, we make the assumption that you are a Sinequa customer or partner and that you can access a Sinequa server in your organization (or at the very least that you can connect to our training server, using your provided Sinequa credentials).

Browse sample applications and components​

If you are new to Sinequa and just want to see what is on the menu, you can start by browsing our list of sample applications.

If you want to discover new functionalities that may be useful for an existing application, have a look at the Components and Analytics libraries. You can also test most of the SBA Framework's components in the Vanilla Builder application.

Sinequa also comes with pre-packaged apps (that are deployed out-of-the-box), and you can test these apps directly with your own data (See prepackaged applications below).

Create a first application​

Vanilla Builder​

A good way to get started that does not require any developer skills is to use the Vanilla Builder application. Vanilla Builder is a no-code tool that lets administrators customize an application by drag-and-dropping components and editing their settings, appearance and behavior.

When the customization is complete, it can be exported as a standalone application that can be deployed independently on Sinequa.

Vanilla Builder is also a good way to discover and try out a wide range of components available in the SBA Framework without having to study the documentation and API.

Pre-packaged applications​

Another common way to get started is to copy one of the pre-packaged apps available in the Sinequa administration:

Prepackaged applications

However, please note the following warnings:

warning

Copying the "app" object exposes a new application at the URL <sinequa>/app/<app-name>, but it does not copy the application's workspace, which contains the source code and build artifacts for the app. The new app will still be referencing the original workspace (See server configuration).

warning

While it is possible to copy the workspace as well, you should carefully consider Version Control and Continuous Integration for the long-term maintainability of your project (See our Version Control and Updates guides).

note

To recap: Copying the "app" object is fine if you just want to customize the application's configuration and web services. However, if you copy the workspace and want to edit the source code, you must have a clear understanding of how to develop an application, which you can learn more about in the next section.

Develop an application​

SBA developers should be familiar with the following topics:

  • General web development (HTML, CSS and JavaScript languages)
  • The basics of the Angular web development framework (i.e., by completing an online tutorial)

After ensuring an understanding of these topics, new developers should use this website to become familiar with Sinequa-specific concepts. In particular:

BUT, if you are a learn-by-doing person who doesn't read documentation if they can avoid it and you really just want to get started now, then let's go:

  1. Clone the repository

    git clone https://github.com/sinequa/sba-angular.git
    cd sba-angular

  2. Install dependencies with npm

    npm install

  3. Build Vanilla Search and test it using our demo server (Sinequa account required):

    npm run start:vanilla

    This commands is shorthand for ng serve vanilla-search --ssl=true --proxy-config=./projects/vanilla-search/src/proxy.conf.json. It builds the application then serves it on your computer at https://localhost:4200. The proxy file specifies the URL of the Sinequa server (in this case, our demo server)

Maintain and monitor an existing application​

If you manage an existing application, you typically have to perform different tasks:

  • Monitor the usage of the application (e.g., evaluate the adoption, the relevance of search results, the performance of the engine, read user feedback, etc.). Fortunately, there's an app for that! The Usage Analytics application displays all this information within a set of dashboards.

    info

    The SBA standard components and applications have a built-in audit system that records all relevant user actions into logs. These logs can be periodically indexed in an audit index. The Usage Analytics application computes metrics directly based on this data.

  • Modify the application's configuration. Applications can be customized without changing their source code (to some extent). There are three possible ways to achieve this:

    • Customizing the configuration of the application's web services, in particular the query web service. This approach is documented in the server configuration guide.
    • Customizing the application's JSON configuration. Each application has a set of internal settings that can be overridden by adding properties in the "Customization (JSON)" tab of the application. This typically includes the list of facets, metadata, and preview highlights, and it allows certain functionalities to be turned on or off (e.g., baskets, saved queries, etc.).
    • Customizing the application's UI with Vanilla Builder. Note that modifying the application in Vanilla Builder does not directly modify its source code. It modifies a JSON configuration describing the layout and configuration of each component. This configuration is persisted in the administrator's User Settings, but it can also be downloaded and reopened later for further customization.

  • Implement changes in the application code. Making changes in the application's source code is more consequential than changes in the configuration because there are multiple factors to consider:

    • The versioning of the code (see version control guide)
    • The process of deployment (see deployment guide)
    • And most importantly: any change that you apply may eventually conflict with a future update and/or might necessitate future maintenance (see the next point).

  • Update the SBA Framework. Sinequa regularly releases new versions of the libraries and applications. These updates often introduce breaking changes:

    • Library upgrades (Angular, Bootstrap, RxJS, D3, etc.) often introduce breaking changes. So when Sinequa upgrades these libraries, the entire codebase is migrated accordingly.
    • As the SBA Framework evolves, bugs are fixed, features are added, and components & applications are refactored. These changes can be in direct conflict with how you use these components or how you customized these components.
    warning

    If your application is heavily customized, these updates will probably be difficult. If your customization makes use of, say, Bootstrap, you will have to follow the relevant guide from Bootstrap to migrate your code.

    Carefully read the updates guide to learn how to manage this situation and how to be prepared by adopting development and version control best practices.

    note

    To recap: You must take ownership of anything you customize. This includes taking responsibility for fixing conflicts with future updates and potentially migrating your code when libraries are upgraded.