One of the main pillars for Nblocks is that you, as a developer, should have speed, flexibility and complete control. 

Speed is important, so you get value much faster than if you do it yourself. Flexibility so you can make changes fast and full control so you add and change things exactly the way you need.

In this article, we will focus on flexibility by showing you how to configure Nblocks using the App profile.

We will show some of its settings, what they do and why we’ve architectured it the way we’ve done. We will take a newly created Nblocks app and set this up for a real use case by changing the onboarding flow, introducing payment plans and adding an additional user role. I’ll be walking you through the example step by step.

Throughout this tutorial, I’ll be using a frontend project and a backend project which you can clone from Github yourself. They both contain the tutorial starting point and end result.

Configuration designed for an agile process

My development team comes from a background where flexibility is key. Hard coding interactions and workflows and keeping the number of customisations low might look good on paper (and in code) since it keeps the complexity low and user stories few, but after a while, the real world comes knocking on the door and rocks this foundation. In the beginning, rarely do you know the end goal of your product and exactly how your users want to interact with it. This is something that gets clearer and clearer during the agile process of pilot customers, feedback loops and finding the unique values of your product. Because of that, we’ve made Nblocks flexible enough to help you along that process.

The anatomy of your app profile configuration

Every time you create a new app in Nblocks, you’re given an app profile and API keys to authenticate with Nblocks on behalf of that app. The app profile holds your configuration, which Nblocks will use every time you or one of your users interacts with your app. From the start, all configurations are set to sensible defaults so you can get started quickly.

The App profile has three types of configurations.

1. First one regards your branding like logos, naming, colours, email senders etc. 
2. The other category is user workflow configurations like authentication flows, onboarding flows, default user roles etc. 
3. The third one affects the core business logic. These are, for example, your pricing plans, the user role model, URLs to different resources, credentials to third-party integrations etc.

All these three types are located in one place and one data structure, so you can easily get an overview of all your configs. Although covering only a backend project here, some of these settings are also used on the frontend.

The app profile is stored in the nblocks service, and we will show you to access it and how to change it.

Let’s get started!

App profile

Making changes to your app profile is straightforward.

You can either use a ready made npx command or by interacting with our Rest API using a plain curl call or  Postman.

You can checkout the branch essentials-nblocks-configuration-start of the backend project and code along yourself or checkout essentials-nblocks-configuration-start to get all code changes.

git checkout essentials-nblocks-configuration-start

To fetch the latest version of our Nblocks app profile, we can run one of the following commands,

npx @nebulr-group/nblocks-plugin-tool get-app

or

curl 'https://account-api.nebulr-core.com/app' 

--header 'x-api-key: YOUR_API_KEY' 

--output nblocks/config/app-configuration.json

And to push the app profile you can use one of the following commands

npx @nebulr-group/nblocks-plugin-tool push-app

curl –request PUT 'https://account-api.nebulr-core.com/app' 

--header 'x-api-key: YOUR_API_KEY' 

--data nblocks/config/app-configuration.json

Throughout the tutorial I’m going to use the terminal tool that nicely integrates with your backend project code base. The tool will read and write to your Nblocks configuration folder located at nblocks/config relative to your project root. The app profile is located under nblocks/config/app-configuration.json and the tool will resolve your api key from the file nblocks/config/main.env. The terminal tool will look for these paths so make sure to run it from the base of your backend project.

From your backend projects base run:

npx @nebulr-group/nblocks-plugin-tool get-app

It will overwrite the app profile located in nblocks/config/app-configuration.json

Open the file, and you will see the following content.

{
   "id": "63c705c33808d900083b2cbe",
   "name": "Oscars app",
   "domain": "OSCARS_APP_79CC",
   "apiUrl": "http://localhost:3000",
   "uiUrl": "http://localhost:8080",
   "defaultRole": "OWNER",
   "roles": {
       "OWNER": [
           "AUTHENTICATED",
           "USER_READ",
           "USER_WRITE",
           "TENANT_READ",
           "TENANT_WRITE"
       ]
   },
   "businessModel": {
       "plans": [],
       "taxes": []
   },
   "logo": "https://public.nblocks.dev/assets/logos/nblocks-logo-purple.png",
   "websiteUrl": "https://your-landing-page.com",
   "privacyPolicyUrl": "https://your-landing-page.com/privacy-policy",
   "termsOfServiceUrl": "https://your-landing-page.com/terms-of-service",
   "stripeEnabled": false,
   "onboardingFlow": "B2C",
   "cloudViews": false,
}

We can see that my app has been assigned an id number in the Nblocks space and a set of other parameters with their default values. The id and domain properties are unique to an app and are a read-only parameter. The others described below can be changed.

Property	Type	Explanation
name	string	The name of your app. This name is displayed in all user communications and UI.
uiUrl	string	A URL to your Nblocks powered frontend.Change this if your backend is running somewhere else than http://localhost:8080 Used in some links the backend creates. For example for email templates
defaultRole	string	This is the default role that new users get when being invited. Must be a valid role from the roles list.
roles	Map<string, string[]>	A list of roles and their privileges. The privileges are used to grant access to application features using RBAC.
businessModel	BusinessModel	This is the pricing plan. Here you set up different plans and taxes that customers can subscribe to. You’ll be able to show or restrict access to application features based on the plans.
logo	string	A URL to an image. This will be used as your logo in all user communication and UI.
websiteUrl	string	A URL to your landing page. Used in all user communication.
privacyPolicyUrl	string	A URL to your privacy policy. Part of the user onboarding process. Users will need to agree with the privacy policy.
termsOfServiceUrl	string	A URL to your terms of service. Part of the user onboarding process. Users will need to agree with the privacy policy.
onboardingFlow	OnboardingFlow {‘B2C’, ‘B2B’}	Configure how users will be onboarded. B2B users will have to set up Tenant branding, B2C users get a shorter and simplified onboarding.
cloudViews	boolean	With cloudViews enabled Nblocks will redirect users to our own hosted frontend instead of uiUrl.

As mentioned, all these properties can be changed by you. Let’s use an example and change some of them.

Altering some settings that change steps in the signup flow.

The code example you can clone is an app showing company sales statistics. And our users can invite others team members to access their organisations’ sales data.

The Nblocks sensible defaults provide a simple onboarding process where users can sign up and login. However, we want to add a couple of steps to this.

We want the adapt the signup flow so that the first user that signs up user becomes the account owner and can name their organisation or team. We also have to make sure that only the first user that first signs up for the account has the privilege to alter account settings.

We are also going to let the user choose different payment plans upon signup, so we’ll need to add a pricing model. 

We will need to make the following changes in the app profile to meet our user story

1. To let the account owner name their team or organisation during onboarding, we need to change “onboardingFlow” from B2C to B2B.
2. The only role setup in the app profile is “Owner”. We need to add a new role: Manager. And limit its privileges. 
3. New team members should be Managers by default. Only the users that signup for the organisation account should be owners.
4. By adding two pricing plans on “businessModel” the account owner will be able to select plans during signup.

Step 1. Add your API key to the project

If you haven’t already, you need to assign your project a Nblocks api key. 

Create a new file and name it main.env and place it into the project path nblocks/config/main.env. An example file can be seen here.

Step 2

Open the file

nblocks/config/app-configuration.json.

Change the onboardingFlow property from B2C to B2B. This will add a step to the onboardingFlow where name their team or organisation.

"onboardingFlow": "B2B",

Step 3

Add a new role, “Manager”, to the roles list. As you see below Managers have less privileges than the Owner and are only granted the privileges to read user and tenant data but not change anything. That is a grant we only want Owners to have.

 "roles": {
   "OWNER": [
     "AUTHENTICATED",
     "USER_READ",
     "USER_WRITE",
     "TENANT_READ",
     "TENANT_WRITE"
   ],
   "MANAGER": [
     "AUTHENTICATED", 
     "USER_READ", 
     "TENANT_READ"
   ]
 },

Step 4

New invited users should be Managers from the start. This is done by altering the defaultRole property.

"defaultRole": "MANAGER",

The default role will not change during initial signup, This will always be an Owner with full privileges. This setting only applies when users are invited from within the app.

Step 5

Add two plans which the customers can subscribe to. A free plan and a paid plan. This is something the Owner will be able to choose between during the onboarding process.

"businessModel": {
   "plans": [
     {
       "name": "Free",
       "prices": [
         {
           "region": "DEFAULT",
           "amount": 0,
           "currency": "EUR",
           "recurrenceInterval": "month"
         }
       ]
     },
     {
       "name": "PREMIUM",
       "prices": [
         {
           "region": "DEFAULT",
           "amount": 50,
           "currency": "EUR",
           "recurrenceInterval": "month"
         }
       ]
     }
   ],
   "taxes": []
 },

Final configuration object

Putting these changes together into the app-configuration.json file the result looks like this.

{
 "id": "63c705c33808d900083b2cbe",
 "name": "Oscars app",
 "domain": "CLOUD_VIEWS_TEST_1_79CC",
 "apiUrl": "http://localhost:3000",
 "uiUrl": "http://localhost:8080",
 "defaultRole": "MANAGER",
 "roles": {
   "OWNER": [
     "AUTHENTICATED",
     "USER_READ",
     "USER_WRITE",
     "TENANT_READ",
     "TENANT_WRITE"
   ],
   "MANAGER": [
     "AUTHENTICATED", 
     "USER_READ", 
     "TENANT_READ"
   ]
 },
 "businessModel": {
   "plans": [
     {
       "name": "Free",
       "prices": [
         {
           "region": "DEFAULT",
           "amount": 0,
           "currency": "EUR",
           "recurrenceInterval": "month"
         }
       ]
     },
     {
       "name": "PREMIUM",
       "prices": [
         {
           "region": "DEFAULT",
           "amount": 50,
           "currency": "EUR",
           "recurrenceInterval": "month"
         }
       ]
     }
   ],
   "taxes": []
 },
 "logo": "https://public.nblocks.dev/assets/logos/nblocks-logo-purple.png",
 "websiteUrl": "https://your-landing-page.com",
 "privacyPolicyUrl": "https://your-landing-page.com/privacy-policy",
 "termsOfServiceUrl": "https://your-landing-page.com/terms-of-service",
 "stripeEnabled": false,
 "onboardingFlow": "B2B",
 "cloudViews": false
}

Alright, we’re ready to commit the changes. Our terminal tool takes care of that. Run the following command:

npx @nebulr-group/nblocks-plugin-tool push-app

That’s all we needed to do. The changes have been saved and are live immediately.

Testing it out

The configuration has been saved and It’s time for us to see the changes. Let’s fire up a frontend project that connects to our backend so that we go through it step by step.

Start the servers

1. Clone our example frontend project and start it.

git clone git@github.com:nebulr-group/nblocks-react-example.git

cd nblocks-react-example

npm install && npm run dev

2. Go into the backend project and start it

npm run start:dev

Navigate to the frontend

1. Sign up for a new tenant and log in.
2. During the signup process you should see two additional steps. One where you will name your organisation and the second where you choose a payment plan.
   The first new step is a consequence of us changing “onboardingFlow” to B2B. And the second step is added since we created payment plans. 
3. Name your organisation and select one of the plans and you should arrive at the starting point of the app.
4. Click Users in the sidebar.
5. Add a new user.
6. The new user will be a Manager just like we configured.

Conclusion

You have now seen some of the configurations that Nblocks provide, how to change them and what effect they have.

As you have seen some of the configurations like “onboardingFlow” and “businessModel” make big changes to the signup flow without any code requirements.

To take this one step further and let your users pay for the plans you need to integrate with a payment provider. You can follow the initial steps in this tutorial to integrate with Stripe. 

Some of the configurations like pricing plans and roles have been shown briefly here and you can find more detail on how to configure by having a look at the following posts

—

Who am I?

My name is Oscar and I’m the CTO of Nebulr, the company behind Nblocks. I’ve dreamt about building stuff since I was a kid and when I started programming as a teenager I got stuck.

As a programmer by heart, with 15 years in the tech industry and experience from more than 50+ projects under my belt I’ve seen and learnt a lot about scoping and solving problems in a pragmatic way.

I enjoy identifying real-world problems as much as exploring new technologies and I thrive when finding a connection between these two. 

I’m a firm believer that you never know where you’re going to end up, before you’ve put it in the hands of your users. This is what we practice at Nebulr.