Now that you’re Getting Started and Creating Applications on ASG-Zenith, it’s time to start thinking about the Portal. Let’s cover a few basics before we get started:

What is “The Portal”?

In the simplest terms, the Portal is where your application is used. Once you have developed and tested an application within the ASG Studio, the Portal is the next step. But what really is the Portal? Officially, it is “server based web application that you can install and implement within your enterprise environment to deploy and manage apps that are designed using ASG-Studio for various ASG-Zenith digital automation platform services.” The Portal contains many functions for managing users, applications, datasources, and things called Contexts. The Portal is the end-all-be-all of user interaction with Zenith-produced applications and services. This interaction takes place in a web browser (both on Desktop and Mobile) in the same way you’d expect to use tools like Salesforce or Confluence.

Managing the Portal

Contexts

In a basic sense, a context is a way to provision an environment for multiple categories of applications or services. For example, if a company runs a portal, they could have a context for human resources, maybe another context for billing, and another for support ticket management. The human resource context would contain applications that handle hiring or employee complaints, while the billing context would have applications built around submitting an invoice, or requesting funding for a project.

Users and Roles

Managing users and roles can get a bit complex when you’re managing multiple contexts with applications. Simply put, the users of the Portal can each have one or more assigned roles. Roles are defined in applications and are assigned to contexts, giving users access to those contexts and their applications.

When it comes to roles, each context must have at least one role, and the same goes for an application. The roles in your application must bind to roles in the context to give access to a group of users.

If you’re confused as I was, think of it this way: a user can exist on their own, but can’t access any applications or contexts without a role. To give a user a role, you must create a role in the context, and that role must also be mapped to an application.

We’ll see this in action when we deploy our application to a portal.

Maintaining Applications

As you may or may not know by now, each application can have multiple data sources, roles, UI models, server scripts, etc., that can be managed and configured within the administrator screens in the Portal. After uploading an app, you will be able to access all the different parts of the app that you have created in the Studio. This includes changing data source values to connect to a production data source or tweaking which role matches with which role in a context.

The Types of Portal: On Premise vs. SaaS

Currently, On Premise and SaaS are the two types of portals. In this blog, we’ll be using only the On Premise version. I’ll talk about some of the most basic differences between the two.

User Interface

The biggest difference between the two versions is the User Interface. The SaaS UI is similar to what you see in other SaaS applications with a navigation bar on the left end of the screen that is used for all navigation. Take a look here.The On Premise version is split into two parts writing papers: one for administration, and another for end user use. The administration side manages everything about the Portal. Administration can only be accessed by an administrator at the following URL: my.portal.com:6030/. (we will discuss creating administrators later) The end user side of things can be accessed at my.portal.com:6030/web/ with any user that has been assigned to a context. This side of things has three menus available for users after logging on: Application, Inbox, and Context. The application menu will show you the available applications for your currently selected Context. The Inbox will show the currently logged in user what items are/have been assigned to them. The context menu is a drop-down of contexts the logged-in user can access.

User Management

User management differs a bit between the two in major ways. For On Premise, you can specify what method you want for user management (referred to as Identity Providers). The current options are Active Directory and a Custom Database. The two options aren’t mutually exclusive, you can use both at the same time. When defining Active Directory, you must configure Portal to look for a configured instance of Active Directory and provide it with connection details to be able to fetch the users. When using a custom database, you must create a table that contains the proper user information that the Portal requires. This is the methodology we will be using for our installation later, so if this is confusing, don’t worry.

In SaaS, the Users are managed by the ASG team. You must contact them to add and delete new users.

Overall, the SaaS Portal caters more towards ease of use, while for our purposes, the On Premise Portal’s strength resides in flexibility. Going forward, we will be using the On Premise Portal.

Installing the On Premise Portal

Installing the On Premise Portal is straightforward. Here are the steps I took:

1. Verify that your system is properly configured for the Portal

• For a successful installation, you’ll need the following:
• Microsoft Windows 10 or Microsoft Windows Server 2012 or higher
• A dual core 2.0 GHz processor or better
• 16 GB of RAM or more
• 2GB of free storage space (this will increase with more applications)
• Java Development Kit 8
• Postgresql 10 or higher

For the Portal to run, a Postgresql database is needed. Upon first run, the Portal will create the tables it needs to function, so all it needs is a database ready for use. Additionally, we will use this database to configure users later down the road. 

Before running the Portal, install Postgres 10 or higher and create a database for the Portal.

2. Contact ASG and obtain the archive containing the On Premise Portal and the ASG BotEngine Installer

Within the portal archive, you should receive the following files and folders:

• Readme.pdf
• prs-run.bat
• bin
• config
• Document_Store
• license
• logs
• Web

Additionally, the ASG BotEngine Installer should be an executable .exe that starts with “ZBU_”.

3. Edit the configuration files to point to our newly installed Database

To make sure the Portal can access the database and therefore startup properly, we need to edit the application.yaml file found in the config folder. Find and edit two sections:

databases

This object has 6 properties associated with it that need to be configured, much like the datasource object:

name

The name of this database. This does not map to anything in the Postgres instance, this is used by the Portal. You can leave the default.

host

The host name or IP address of the Postgres install.

port

The port of the Postgres install, default is 6030

databasename

The name of the database that has been configured for the Portal. The same as used in the JDBC driver.

username

The username of the user that has access to the database created for the Portal.

password

The password for the above user.

With this configuration complete, save the application.yaml file and close it. If you would like to do additional configuration, feel free to fish around the file and change what you’d like. 

4. Install the ASG BotEngine

Run the “ZBU_” exe as an administrator, and the installer will install the ASG Bot Engine as well as the ASG Vault service and Certificate installer.

5. Run the Portal with prs-run.bat in an administrator command prompt

Open a command prompt as an administrator and navigate to the files you’ve extracted.
First, you need to run .\prs-run.bat to start the Portal.
Following that, you need to start the ASG BotEngine and the Vault service as Administrators from the shortcuts created for you on the desktop.
The first time may take longer than usual to start. Once it’s running, you can open up your web browser (ASG recommends Chrome) and access the Portal configuration at localhost:6030/. The default username and password are admin/p@sswW0rd.
Now just for some simple user and context configuration, and we’ll be ready to upload our tutorial application!

6. Create users

With the Portal now running, we need to create our users. This table will contain all the information that the Portal needs to authenticate users. In your Postgres installation, create a table within the database you’ve created called “prs_users”. In this table, create the following varchar columns: displayName, email, firstName, lastName, password, username, and phoneNumber. Then, populate the table with 3 users. One for each role that was created in the tutorial application, i.e. Employee and Manager, and one for context administration. What you want to call them is up to you!

With the user database set up, it’s time to get into the Portal and map the table and columns to the Portal for use. Navigate to localhost:6030/ to access the Portal configuration. Login with the admin like we did in the previous step. Conveniently, the first screen we’re greeted with is the Identity Providers screen. 

On the top right side, click the plus icon to create a new Identity Provider. Select Custom Database and give the provider a name, something like “Postgres User Table”. 

Enter “usr” for the Identifier, mark the connection as active, I like to uncheck the JDBC String URL and fill in the provided boxes to verify them all individually. The Portal will create the JDBC string for you. 

Enter the Username and Password, and save the configuration. 

This can get weird, but make sure you have populated the password. Once you have saved the configuration, open the Authentication menu by clicking Authentication on the bottom of the page. This is where you will map the table and it’s columns to the proper data in the Portal. If the table and columns aren’t loading, check your configuration and connection to Postgres. We don’t need to worry about custom mappings or properties at the moment.

Once all of the columns have been mapped to the appropriate data, click save. Close this window and select “Test User” to test that the Portal has received all the Database information properly and can log these users in.

Next, open the Enterprise Users screen by clicking the Enterprise Users button below the highlighted Identity Providers button on the top left corner of the interface.

Here we can edit a user’s information, assign them to contexts, etc. We can’t create or delete users here. This needs to be done where the user information is stored, i.e., your database or AD configuration.

Finally, open the Enterprise Roles screen by clicking the Enterprise Roles button on the top left corner of the interface. From here, we can create, edit, and delete a role, assign them users, and to contexts, etc. We can leave this as is for now, but we will create some rules when uploading our tutorial application.

7. Create a context

While remaining in the Portal, open the Contexts screen by clicking the Contexts button on the top left corner of the interface. 

Here we can create a context by clicking the plus icon on the top of the interface. That should open a menu. Providing a name for your context “Tutorial” is completely fine. Also, assign the admin user you created when populating the user table as the context administrator. Click Save, and your context should be created.

To configure a Context, we must be logged in as that context’s administrator, so go ahead and log out of the Portal, and log back in with the Administrator User’s credentials. Once logged in, navigate back to the Contexts interface. Your context should be there, click the three dots on the context and click Open. This is where we will upload and manage applications for this context.

And just like that your install of the On Premise Portal is fully functional and ready for an application!

Deploying our Tutorial Application

Picking up from where we left off in the last blog, we should have a packaged application ready for download in the studio. Go ahead and download the application.zip file.

Next, within the context we have created, you should see the Applications screen. Click Add on the right side of the interface to add an application, and select the application.zip file you have downloaded. Then, click Upload on the bottom right side of the screen. 

Your application is now uploaded! We just need to map some things to the context for it to work properly.

Navigate to the Enterprise Users interface and assign the other two users to the context we have created, by clicking on the Assign Contexts button and selecting our Context.

Next, Navigate to the Enterprise Roles interface and create the same two roles you created in the tutorial application – Employee and Manager.

With the Users assigned to the context and the Roles creates, we need to edit the context to give these Users the roles.

Navigate to the context configuration, and within the context (not the main configuration) select the Enterprise Roles interface. You should see the two roles we created a moment ago. Assign a user to each of the roles, one for Employee, and another for Manager. Now you’re ready to map these roles to the roles in your tutorial application.

Navigate back to the application interface within the context and open the application with the same three dot menu. Here you should see a menu similar to that of the Application packaging menu, with a list of files, UI Models, Process Models, etc.

Navigate to the roles Page, here you should see a list of roles that exist in the application. To map each role to one in the context, click on one, and select from the list of roles in the context. The names should be the same to make things easy. Do this for both roles.

Finally, because the tutorial application uses an external datasource, we need to look at that configuration and make sure the Portal service can access it as well. Navigate to the datasources page and verify the connection information and test the service.

With all of the configuration complete, It’s time to test the application out in the Portal!

Running the Tutorial Application

Open the User facing side of the Portal at localhost:6030/web and log in with the user that starts the process model off. The screen should have the interface that was mentioned earlier, mostly blank, we need to select a context. Click the “Select context Name” Dropdown and select the context you created. Your application should be shown. (If it isn’t, check your role mapping and application configuration!) Click your application, and your UI Model should open!

Follow the process of the tutorial application by logging out of your employee user and back in as the manager to see in the inbox that an item has been created for them.

And with that, your tutorial application has been deployed to your own On Premise Portal!