Introduction to Sisense Git Integration

This section covers:

Sisense Git Integration brings the powerful source control technology of Git to Sisense.

Git Integration Functionality

The Git Integration functionality addresses the following business needs:

  • Version control for Sisense assets:
    • Gives Sisense content designers the ability to trace, review and undo changes of their Sisense assets using Git functionality
    • Enables a collaborative review process of new changes to Sisense assets via merge requests on the remote repository in a way that is similar to the software development code review procedure
  • CI/CD pipelines:
    • Allows Sisense to be integrated into existing customer CI/CD pipelines
    • Provides the ability to apply changes in bulk
    • Uses APIs for full automation

How it Works

Git is used differently in Sisense from the way it is normally used in software development projects. This is because Sisense assets are not just code, and Sisense is a web application deployed on cloud servers and used via browsers.

The following table compares the important differences between how Git is most commonly used in development (via an IDE) and how it is implemented in Sisense:


 IDE Sisense
What Code files Dashboards, Widgets, and Data Models, etc., which are saved as sets of child JSON files
Who Software engineer Any user in Sisense that creates Dashboards, Data Models, etc., and maintains them
Where Local repository in personal laptop or workstation Project on the Sisense server which is 'local' to all Sisense users using the server

What Git Integration Adds to Sisense

Git Integration is based on these Sisense components:

  • Git Integration GUI client
  • REST API for all Git actions
  • JSON-based file representations of Sisense assets
  • Projects - Each project groups assets into a local Git repository

The relationships between these components are illustrated in the following diagram:

Using across Multiple Environments

Sisense local repositories (projects), which are part of the Sisense deployment, can be synchronized by means of a central remote repository, (such as Github, Gitlab, Azure, etc.).

Each Sisense environment (Dev, Staging, Production) can be checked out on a different branch of the project ("local" repository), as needed.

Core Principles

These are the core principles and ideas that underlie the development of the Sisense Git Integration functionality:

  • 'Local' repository: The Sisense application is treated like a coding or development environment (not to be confused with a Sisense development deployment) with local Git repositories on the Sisense server. A physical folder is created for each project ("local" repository) in the git directory of the Sisense server file system, /app/explore/files/git/.
  • GUI-based: Interaction with the local repositories is via a rich, standard Git GUI that is built into the Sisense application. Two major design goals of the GUI client were to:
    • Align with the most popular Git clients for smooth onboarding and easy interaction
    • Adapt to the specifics of Sisense as a BI platform
  • Natural Git experience: Sisense Git Integration uses common terminology and a familiar user experience. There is no 'magic' behind the scenes; no automation or obfuscation.
  • You are in control: Users choose which Sisense assets to include in which projects (repositories), when and what to commit/push, and so on. The user is fully in charge of what actions to perform according to their business goals.
  • Support current workflow and preferences: Teams already using Git should have no trouble integrating Sisense into their daily operations.
  • Fully opt-in: No one is required to use Sisense Git Integration. The Sisense viewer experience is not impacted.
  • No exposure of user/ownership information: Owners, shares, data security, and other sensitive or environment-dependent data are not checked-in into the Git repositories.
  • Vendor-agnostic: Supports using any remote Git server, whether SaaS (Gitlab.com, Azure, etc.) or privately hosted, as long as the following requirements are met:
    • Vendor utilizes Git as the version control technology
    • HTTPS authentication is supported

Note:

For internal or on-premises git servers the Sisense instance must have network access to the git server.

Terminology

Asset

An asset is any Sisense resource or entity, such as a dashboard or data model which can be source-controlled via the Sisense Git Integration feature. Assets are assigned to a project and converted (see Asset Translation and Management) into a set of physical files in JSON format within a predetermined directory structure in the project's storage folder (a "local" Git repository). Dashboards and data models are the only supported types of assets at the moment.

Only the owner's copies of assets can be used for Git Integration.

Project

A project is an entity/resource in Sisense that uses Git to manage one or more Sisense assets. Projects are created by admin users and represent a physical storage folder (/app/explore/files/git/<project>/) and the Git repository initiated within it. Each asset can only be assigned to a single project.

Even though a project is the Sisense representation of a local repository, it is local to the Sisense server. All of the users using Git Integration work on the server instance, and not on their local computers.

Git project contributor

Any Sisense user with a role higher than Viewer, who has access to a project, can be a contributor.

Remote repository

A remote repository is any Git server repository defined as a remote for a project. Only one remote can be set per project, and this is optional. GitHub, Gitlab, Azure, and Bitbucket have been tested and are officially supported as remote repositories.

Roles and Permissions

Admins

Includes users with the roles Super Admin and Admin. These users are mainly in charge of creating, sharing, and configuring Git projects to be used by non-admin users.

Admin users can add all of the available assets on the system level to the projects.

Non-Admins

Includes users with the roles of Data Admin, Data Designer, and Dashboard Designer. All of these users have the same rights within the projects created by Admins and shared with them.

Non-admins can only assign assets owned by them. The only exception is Data Admins who can add any available data models on the instance, as defined by their permission scheme in the Sisense application.

Enabling Sisense Git Integration

The admin can activate and deactivate Git Integration using the Git Integration toggle in Admin tab -> App Configuration -> Feature Management (http://.../app/settings/featureManagementConf/) -> Management.

When Git Integration is enabled all of the users with a role higher than Viewer will see the Git icon in the top-right corner of the application.

Clicking this icon opens the Projects (Git Integration) UI in a new browser tab, where:

  • Admins will see the list of all existing projects and have the ability to create a new one

  • Non-Admins will see the project or projects shared with them

GUI Interface

The major interface for interacting with the local repository is implemented via a rich, standard Git GUI which is part of the Sisense application. (See Working with Git Integration Projects for more information.)

The project page is opened by clicking on one of the available projects in the projects list.

REST APIs

As an API first company a list of the corresponding API endpoints is available under the projects group: REST API v2.0 Reference.

At the moment, only the REST endpoints essential for CI/CD flows are available. The rest of the methods will be introduced with a later release.