Documentation

Integrating Gitnox into your Ninox App

Welcome to Gitnox! 👋

Gitnox allows you to deploy and maintain different versions of your Ninox apps into thousands of teams without loosing control over your password protected apps. It also has a built in license management app which allows you to sell your Ninox apps on a subscription basis.

Gitnox offers you two main ways to perfectly manage your Ninox app: Version Control and Licensing. And the best part? All of this is done securely, with all your app is encrypted and all your data is stored securely.

Let's get you started !

Registration

All you need to do set up your gitnox account is: 

  • Your Name
  • An Email
  • A Password 

Once you've registered your account, you can get started. 

Logging in and getting started

Once you've logged into your account, using your email and password, you will be directed to your dashboard where you can get started. 

Sample Gitnox dashboard, with two applications

Once you've completed these steps you can proceed with setting up your application and then linking it.

Creating An Application

An application in Gitnox represents a database in Ninox.
It is the developer's database that you've integrated into your Ninox app.
This Gitnox application is the tool you will use to manage licences as well as taking snapshots of your Ninox side app. 

In order to create an app, click on the "Add A New Application" button on the upper-right side of the dashboard 

The button used to add an new application

Naming your App

Once you've clicked this button you will be prompted with an empty field where you will insert your project or application name. 

And then click on the save button in order to validate that name. 

In this example of the form, we are adding a project with the name of "Covid Manager"

App Overview

Once you've saved the name you will be taken to the application overview page, this page provides you with the information regarding the project you just created. 

These fields will be automatically generated. 

An example App information section for the Covid Manager we've created

The App ID is a unique ID that identifies your app in Gitnox.
This ID will be used to set up your Ninox app in order to make it compatible with Gitnox. 

The Testing License is a unique license created for each individual project of yours.
This license never expires and is used to see all your Snapshots, even ones that have not been published yet.
This ID will be used for two main tasks: further testing your Ninox code and to test a Snapshot taken before you roll it out to the customers.

At this point your application is successfully created, but you still to link it to your Ninox database / app. 

This will be done in the following section.

Linking to Ninox

Now that you've created your application, you will need to link it to your existing Ninox database. 

The Base URL

On the second half of the application information page, you will be presented with the "Base URL" field.

You will need to fill in this base url, depending on your Ninox subscription this URL might take one of two forms: 

Option One: If you are using the public Ninox solution, then the base url is: https://app.ninox.com/) *This URL will be autofilled *

Option Two: If you are using their private cloud option, then you need to replace the autofilled base url with the Ninox web address you use to access your Ninox database page. 

The base URL field, with the public Ninox solution URL used.

Once you've set your URL you'll move onto specifying exactly which team and database on your Ninox account you want to link. 

Setting the Team and Database

Below the Base URL field, there's a yellow button labelled "Choose Team / Database": 

The choose team / database button

Once you've clicked this button you will be presented with a popup asking for your Ninox credentials. In other words: The email and password used on your Ninox account. 

One thing to note is that Gitnox will never store this information in our databases. It will only be saved for the duration of your current session while you set up your project in order to avoid you having to input your credentials again at every step. Also, during this short amount of time this information will be encrypted.
Once you've logged out of your session this information will be cleared. 

The credentials form.

Once you've added your Username and Password, click the continue button in order to link your Gitnox account to Ninox. 

Next, you will be presented with a list of the teams present on your Ninox account. Simply select the team your Ninox database is saved under. 

A team that's procured from the user's Ninox account

You will then see a list of all the applications / databases created under that team.
Select the Ninox database that you want to link this project to . . . and you're done!

A database that's present in the team we've selected

One thing to note: If your Ninox database / application is password protected, you will need to enter the database password and hit the update button in order to complete this step.

  • If you don't have a password for your database, leave this field blank.* 

The database password field.

At this point your Gitnox account as well as your projects are up and running! You can now start to create licences as well as snapshots. 🎉

Licensing

Now that you've linked your Ninox app, you can start creating Licenses! 

Overview

A license is essentially what allows you to distribute the Ninox application you've created to your intended parties. Wether it's a company of a thousand or a freelancer team of one, giving these users access will be very easy, fast and reliable.
You will be giving each of these parties a dedicated and personalised copy of the application you've made, as well as be able to manage how the access and even for how long. 

Let's get started!

Creating a License

Creating a license is a very simple process, in fact it starts with just the click of a button. 

Wether you're granting access to a company of a thousand members or a freelancer team of one, creating a license is very simple and fast. 

In the License section of your dashboard, locate and click the "Create a New License" button located on the top right of the section.

The create a new license button in the licences section.

Once you clicked the button you will be re-directed to the License creation page. 

The License Creation Page

Here you will input all the information needed in order to create your license. You can also access this page in order to update or edit already existing licences.

The license creation form.

Let's go through all the fields and what each of them means: 

Duration: The duration represents the validity of the License you're providing your client with. In other words, its how many days they can access the app you've provided them with for.
One thing to note is that the countdown only starts once a client has activated their license and not when the license has been created. 

Max Team Users: This field denotes the maximum number of users allowed on this application. It can be any number you want, and helps you customise access according to your client's needs. 

Remark: This is your personal remark on this license. It can be any note or label you want to keep about it, for example the name of the person you're providing the license with. 

Basic Data: In this field you can store data to be used in your Ninox app. This data has to be in the JSON format in order for it to be applied. This basic data can be restrictions such as enabling the demo version: {"demo": true} or any other data you want to push to your client. 

Extra Data: This field is smiler to the basic data field except it is used to store bigger or bulkier data such as encoded pictures, advertisements etc... This data has to be in the JSON format, and cannot exceed 16MBs.

*The data fields can be left blank. *

Once you've filled in all this information, go ahead and click the save button in order to finalise the creation of your license.

The Licences Table

Once you've created your licences you can see an overview of each of them in the Licences table on your dashboard. 

This table provides you with all the information regarding each License as well as provides you with management capabilities: 

Editing a License: If you want to update or edit an existing client's license, you can do so through the edit button present in the first column of the table on the left side. 

Disabling a license: If you ever need to disable a client's a license, this can be done easily using the red disable button present in the last column on the right the licences table. option of disabling a license if needed. This can be done by clicking the "Disable" button in the last column on the right.

Managing A Cluster

The cluster section of your dashboard shows you information about your clients and specifically the snapshots they've applied.
A client is present in a cluster only if you've chosen to save their information.

A cluster is used to oversee and manage the snapshots available to your clients, this can all be done through the Clusters table. 

The Clusters Table

The Cluster's table is present in the lower part of your dashboard. This table has three main purposes. 

A sample cluster table.

Overview: In this table, you can see that a user has applied on of your snapshots. You'll be able to see that user's email in order to identify them as well as which Team/Database they're working on. 

Apply Button: The apply button, present in the last column on the right of each entry allows you to apply the most recent snapshot to a user's application. It essentially pushes the latest update to that user. 

Apply All Button: The Apply All button, present in the top right corner, allows you to push the most recent update to all the users present in your cluster table. 

Now that you\ve gone through clusters, let's create some snapshots to apply.

Version Control (Snapshots)

Snapshots are Gitnox's way of keeping versions of the app you've created. 

Once you've linked your database for this first time you will have a version of this application saved on your Gitnox account.

But since it's just a "snapshot" of your app, if you change or update anything regarding this app on Ninox, no changes will be applied onto your already existing application on Gitnox.

In order to sync your changes, and create a update version of this application you will need to create a Snapshot. This same snapshot can be used to deploy all these changes and updates to your users. 

Creating a snapshot is very simple, let's get started.

Creating A Snapshot

On your dashboard, you'll se a Snapshots section, this is where can create and manage all your snapshots. 

Taking a snapshot is very easy! Simply click the "Take A New Snapshots" button on the top right corner of your Snapshots section. 

Once you've clicked this button Gitnox will take a snapshot of the current state of the linked app, and present you with a form to fill. 

The snapshot creation form.

Let's go through the fields of this form:

Title: This is the title you want to give your Snapshot 

Public Remark: This is the information you want your end clients to see whenever a new Snapshot is available for update. Usually, this contains a description of what was added, updated, fixed or enhanced in this new version. 

Private Remark: This is used for your own reference, you can include any information you want to keep about this Snapshot that you don't want the clients to see. 

Published Checkbox: If you set this to true, then this Snapshot will appear in the update list on the clients' Ninox app.
If this is set to false, then they will not be able to see it or update it. The only license that will be able to still see it is the "Testing license" that was generated when you created the Gitnox application.

Once you've filled in these fields go ahead an click the "Publish Snapshot" button in order to finalise your Snapshot creation. Your newly created Snapshot will appear in the Snapshots table.

Managing Snapshots

Once you've created your Snapshot, it will be available along with a list of all the other Snapshot's you've made in the Snapshot management table.

A Sample Snapshot's table

This table provides you with some fields to help you keep track of your versions at a glance: 

ID: This is your Snapshot's unique ID.

Version: This is your Snapshot's version number 

Title: This is the title you've given your Snapshot 

Published: This indicates wether your Snapshot is published, or only available for testing purposes.

Archived Snapshots

Once a Snapshot has been archived you it will no longer show in the default Snapshot table, in order to be able to see any archived Snapshots simply toggle the "Show Archived" checkbox on the top left of the table. 

Editing a Snapshot:

A Snapshot being edited.

In the last column on the right hand side of the table, you will find an "Edit" button, this button allows you to update the name and remarks of the Snapshot.
It also allows you to update the status of it, changing wether its published or not.
And finally it allows you to archive the Snapshot if needed. 

Applying a Snapshot.

Also present in the last column on the right hand side is the "Apply" button, this button allows you to apply the selected snapshot onto your Ninox application. 

A couple things to keep in mind are: 

  • If you apply an earlier version of your snapshot, any changes and updates made on the Ninox app after the creation of this Snapshot will not be preserved. 
  • This only applies the Snapshot to your app, in order to apply it to a client's app you need to do so through the Cluster's section.

Now that you have your App set up on the Gitnox side you will need to set up a few fields on your Ninox app in order to be able to give out licences.

Setting Up Licenses - Ninox Side.

Let’s Get Started:

Open your Ninox app and create a new table dedicated to your Licenses

This table will serve to set up licenses from the Ninox side as well as serves as a dashboard that displays key metrics to keep track of.

Once it has been created we will need to insert fields and formulas to get it properly cabled with your Gitnox account. Your License table has 4 main parts:

  1. The License Part

  2. The Ninox Credentials Part

  3. The Versioning and Team Control Part

  4. The Gitnox and Cluster Part

In this documentation we set up the fields required for each section followed by the methods to set up for these fields

  1. The License Part - Field Definitions

This part communicates with your Gitnox app in order to activate licenses. Here are the steps to follow to set it up:

  • Create a text field and for your License number in our example we named it : ‘License Number’
  1. The Ninox Credentials Part - Field Definitions

The second part takes in the user’s Ninox credentials in order to set up a license for your users.

One thing to note is that Gitnox never keeps your credentials, and they are encrypted

  • Create a text field for the Ninox Username
  • Create a text field for the Ninox password
  • Create a hidden number field to save the current version in, in our example it is labelled: _Current Version
  • Create a hidden number field to save the latest version in, in our example it is labelled: _Latest Version
  • Create a hidden date field to save the expiry date in, in our example it is labelled: _Expires On
  1. The Versioning and Team Control Part - Field Definitions

This part helps you keep track of the versions as well as the team restrictions for this specific License

  • Create a formula with the label “Current Version”, in it call “_Current Version” in order to get a visual display of the current version

  • Create a formula with the label “Latest Version”, in it call “_Latest Version” in order to get a visual display of the latest version

  • Create a formula with the label “Expires On”, in it call “_Expires On” in order to get a visual display of the expiry date

  • Create a hidden number in order to save the Maximum team users into it, in our example we labelled it “ _Max_Team_Users”

  • Create a formula with the label “Max Team Users”, in it call “_Max_Team_Users” in order to get a visual display of the Max team users for this license

  1. The Gitnox and Cluster Part - Field Definitions

This section will help you create new clusters in your Gitnox app

  • Create a hidden formula with the label Master, insert this code

     databaseId() = “bc”
  • Create a text field labelled: Gitnox Username

  • Create a text field labelled: Gitnox Password

Now that we’ve implemented all our required fields, let’s set up the methods and functions

  1. The License Part - Methods Definitions
  • Create a button for activation: In this field you will input this code snippet for the function:
      function activateLicense(license : License) do
       let appId := **INSERT YOUR GITNOX APP ID HERE**
       let response := do as server http("GET", "https://app.gitnox.com/api/licenses/activate?appId=" + appId + "&license=" + license.’License Number' + "&teamId=" + teamId())
      end;
      if response.error then
        alert(“Error Connecting to License Server")
      else
      if response.result.success = true then
          license.(‘_Expires On' := response.result.expiresOn);
          alert(“License Activated. Expires on: " + response.result.expiresOn)
      else
           alert(“Invalid License")
          end
       end
      end;
      activateLicense(this)

6. The Ninox Credentials Part - Method Definitions

This section implements two functions: Verifying a license and Updating it.

Verifying:

  • Create a button with the Verify label, and include this code snippet in it:

      function updateLicenseInfos(license : License) do
              if ‘_Current Version' = null then
              ‘_Current Version' := 0
          end;
          let response := do as server
              http("GET", "https://app.gitnox.com/api/licenses/info/" + license.’License Number' + "/" + teamId())
          end;
          if response.error then
              alert(“License Verification Failed")
          else
              if response.result.found = true then
              let snapshotsVersions := for s in response.result.snapshots do
              s.id
          end;
              license.(‘_Latest Version' := max(snapshotsVersions))
          else
              alert("Invalid license or license disabled")
               end
          end
      end;
      updateLicenseInfos(this)

Updating

  • Create a button with this code snippet in order to update the Ninox License
    function upgradeSchema(snapshotId : number) do
        let license := this;
        let baseUrl := "https://app.ninox.com";
        let body := {
            password: license.'Ninox Password',
            baseUrl: baseUrl,
            username: license.'Ninox Username',
            snapshotId: text(snapshotId),
            databaseId: databaseId(),
            teamId: teamId(),
            license: license.’License Number'
        };
        let headers := {
            'Content-Type': "application/json"
        };
        let response := do as server
            http("POST","https://app.gitnox.com/api/snapshots/ninox/apply", headers, body)
        end;
        if response.result.appliedSuccessfully = true then
            license.(‘_Current Version' := license.’_Latest Version');
            alert("Success")
        else
            alert(response.result.errorMessage)
        end
    end
  1. The Gitnox and Cluster Part - Method Definitions
  • Create a button labelled Deploy to Cluster which will allow you to deploy your current version to the cluster, it in include this code snippet:
          let t := this;
          let gitnoxAppId := 1;
          let response := http("POST", "https://app.gitnox.com/api/authenticate", {
                  'Content-Type': "application/json;charset=utf-8",
                  Accept: "application/json, text/plain, */*"
              }, {
                  username: 'Gitnox Username',
                  password: 'Gitnox Password',
                  rememberMe: false
              });
          if response.error then
              alert("Failed to connect to gitnox")
          else
              let jwt := response.result.id_token;
              let encryptRequest := http("POST", "https://app.gitnox.com/api/encrypt", {
                      'Content-Type': "application/json;charset=utf-8",
                      Accept: "application/json, text/plain, */*",
                      Authorization: "Bearer " + jwt,
                      Referer: "https://app.gitnox.com/login"
                  }, {
                      username: 'Ninox Username',
                      password: 'Ninox Password',
                      dbPassword: null
                  });
              if encryptRequest.error then
                  alert("Error encrypting data")
              else
                  let encryptedUsername := encryptRequest.result.username;
                  let encryptedPassword := encryptRequest.result.password;
                  let snapshotId := encryptRequest.result.snapshotId;
                  let takeSnapshot := {
                          snapshot: {
                              published: true,
                              deleted: false,
                              publicRemark: "Automatic Snapshot " + now(),
                              privateRemark: "",
                              application: {
                                  id: "" + gitnoxAppId
                              }
                          },
                          username: encryptedUsername,
                          password: encryptedPassword
                      };
                  let takeSnapshotRequest := http("POST", "https://app.gitnox.com/api/snapshots", {
                          'Content-Type': "application/json;charset=utf-8",
                          Accept: "application/json, text/plain, */*",
                          Authorization: "Bearer " + jwt,
                          Referer: "https://app.gitnox.com/login"
                      }, takeSnapshot);
                  let snapshotResponseId := takeSnapshotRequest.result.id;
                  let applyAppRequest := http("POST", "https://app.gitnox.com/api/deployments/apply-all/" + gitnoxAppId, {
                          'Content-Type': "application/json;charset=utf-8",
                          Accept: "application/json, text/plain, */*",
                          Authorization: "Bearer " + jwt,
                          Referer: "https://app.gitnox.com/login"
                      }, null);
                  void
              end
          end;
          'Ninox Password' := null;
          'Gitnox Password' := null
    Once you’ve set up all these fields and methods you will be left with a dashboard in which you can control your Licenses from the Ninox App side.

Troubleshooting tips:

If you are facing errors with the methods make sure the names of the fields you’ve set up match the one’s you're calling in your methods.

Demo

You can find a working demo ninox application here

Support
If you have any question regarding the integration, please feel free to contact us on support@gitnox.com, we'll be happy to help you go through a full integration.

By using this website, you agree to our privacy policy