Beginner guide to Identity Manager Angular Portal Customizations #1

[UPBEAT MUSIC] All the videos of this Identity Manager Web Portal Customization series will be based on this document. Before first video, we assume that the first step, preparing environment, is completed, where Identity Manager is installed and configured and all development tools are also installed and configured. This current video will demonstrate how to prepare Angular portal for work. Source code is allocated in One Identity GitHub. So first thing we need to do is to create a fork. And we created already North American Presales fork. And here, it points to the origin of this fork. So now we need to create a work environment. First step would be to just create a folder where source code will be located. Here is a command. And go to that location and initiate git. And we can see this git initiated. Now we need to clone repository to get the source code into our local directory. We need to get to this website and click on this green button, Code, and copy link. Now it's copied. And here, we just say git clone and copied URL. It retrieves all the source codes for the Web Portal or our local directory. And we can see it here-- imxweb, projects, all the components, and portal, and password portal, landing page. Everything is here. We can create a new branch of the project. But in our case, it's already created. We can see it here under UNITE/Start. And when we switch to it, it says that branch is up to date with this branch, version 9.1. Now we can set up Visual Studio, VS Code. Open VS Code. Open folder. And we need to browse to that folder that we just created-- projects, web portal, imxweb. Select folder. And we need to set this Start branch to be our current branch locally. For that, we go to remotes. Open the Start. And click on this rounded arrow, Switch to Branch. Here, we need to press Enter to confirm that we want to switch to this branch. Now we go to Branches. And we see that UNITE/Start branch is our current branch. This checkbox points to the fact that it's current. Now we need to check which version of Angular was used to create our source code. That way, switch to Explorer and go to package.json file. Open it. And we can see that Angular version was 13.3. Now we can check which version is installed, if there's any version installed locally. We open the terminal. Click here on the terminal menu, New Terminal, and type g, dash, dash version. And it works. And it shows that the version installed is 13.3.10, which is pretty compatible version. If it wasn't installed, we can always run this command, install g for "globally," Angular. And version is 13.3. After Angular is installed, we need to install all the components. These are components used for building our web Angular portal. And they're just mentioned in package.json. But they're not really installed locally yet. For that, we run command npm install. And it starts installation. After a while, the installation finishes. And now we need to build libraries. Libraries needs to be built in specific order. First, we need to build two static libraries, qbm and qer, and then rest of the libraries that depend on these two libraries. These are called dynamic libraries. And then we build applications, like landing page or portal. First, we run npm run build qbm. Then we'll go qer, tsb, and portal. After the library is built, it shows here where it is located. It's in the imxweb folder dist tbm distribution. We can see it here. This is a newly built library. And now we will go with qer. Qer is done. We can see it here. The next one is tsb. Tsb is finished. And now we need to do-- to build a portal-- tr. Now Web Portal is built and is ready to run. To run Web Portal locally, we need to run API server locally. For that, we have imxclient.exe. It is distributed with installation. And it will host the API server locally. To run it locally, we open command prompt and run this command, imxclient.exe. Run the API server. When it will pop up a prompt to log in as a system user, we should make sure that server name is called as a server name, not as localhost because localhost will create problems later on. We log in as a system user. And now API server runs locally. We can see components being loaded dynamically. And we will see results of execution of the API server. We can see that local API server runs on localhost 8182. We can browse to that location. And we'll see a normal landing page for API server. But it runs locally. Now we need to run app portal from Visual Studio. Command npm run start qer app portal [INAUDIBLE]. Oh, it's compiled successfully and says that Angular development server is listening on localhost 4200. We can open browser for this location. And we can see that our local portal is running. And here's our locally run Web Portal using locally run API server. In this video, we will demonstrate most of the operations necessary when customizing Web Portal, which includes finding a component code to modify in the source code, running project in debug mode, modifying code, and deploying compiled modified code to the production server. First, we need to find the component we want to modify. And we can do it in installed Web Portal. We log in. And let's say we want to modify a user account's membership form. And we want to add a column here. We need to right-click on the data in this table and click on Inspect. Inspector opens in the cell level. And then we can go up to the row level and the table level until we find something identifiable, some name that can be identifying some component in this page. And this is the perfect name, Identity.Membership table. It's identifier for the imx data table, which is our custom component. So we copy the identifier. And now we can switch to the Visual Studio. We go to the Search menu, right here, and paste this identifier to the text box. And Visual Studio finds for us a file where this identifier is used. We double-click on it. We see that it is a HTML file. We see where this identifier is used. And now we can switch to the Explorer to see where this file is located. So this file belongs to the tsb module. And it has a corresponding TS file. In Angular, all components consist of TS, TypeScript, file, and corresponding HTML file. Sometimes, they don't. But in most cases, they do. They have the same name with different extensions, .ts versus .html. TypeScript file contains all the logic and data that is being displayed on the-- in the HTML form. And all the actions that happen on the HTML form are being executed on the .ts, in the TypeScript file. We need to put a breakpoint somewhere in the code. We need to find the line that we're interested in where we know the code will go through, and it will stop at the breakpoint. So here, we have a function called getData. It's a common function. It retrieves data from the service, from the API server. And this getData is being called from the on init function. This init function runs every time the component loads. So this getData function will definitely be executed every time the component loads. And to put a breakpoint, we just need to click to the left of the line number. And red dot represents the breakpoint. The run library in the static mode-- it needs to be built in a development environment if it's a static library. And we can see the list of static libraries here. It's qbm and qer, or in dynamic configuration, it's for plugin or dynamic libraries. These are the-- all the dynamic libraries. And there are different commands for static or for dynamic libraries. Right now, in our project, we're modifying the tsb module, which is dynamic module. We need to run it in dynamic configuration. To do so, we run the following command-- npm run build watch dynamic tsb. Tsb is for the name of the module, library. Module is built. It's placed in the HTML folder. We can see it here, the HTML folder and tsb. Now we need to run the Web Portal itself. To do so, we need to add another terminal window. Click on Add New Terminal. We can rename the terminal so it's more meaningful. We'll call it Portal. And run command npm run start qer app portal. We can see these commands in the package.json file. We can see configuration dynamic, build watch dynamic, configuration development, just build watch, and other commands. Now portal is listening on the port 4200. Know this watching file, tsb file. And now we need to run our API server, local API server. Local API server is running. We need to switch to Run in Debug menu in the Visual Studio. And here we see a list of various configurations. We can see the code behind these configurations if we click on Open [INAUDIBLE] JSON file. And here we see a list of configurations. We can manually add more configurations that will work with various browsers and various applications. But for now, we have one that we need, App Portal with Chrome. And we just click on this green button. And here we can see side by side portal and the output from the local API server. We'll log in as Ben Erdman. And we can see if we use Erdman, Ben-- logged in, authenticated. Now we go to our component, where we'll put a breakpoint. And we can see that code stopped at this breakpoint. It stopped right at the call to the account service to get account. We just press F10 to go over this line of code. And as we click F10, code actually went to account server, to API server, and retrieved data and placed it into this constant. We can view the data that was retrieved right here in the pop-up window, or we can see it in a separate window, Variables. On the left-hand side, see this group for Identity. And here, we have the same variable here. We can open it up and see what kind of data is stored in this variable-- entity, columns, account name. And this is what we see-- what was retrieved. When we press F5, code just keeps going to the end, or we can use these buttons-- Step Over, Step Into, and here's F5, Continue. When module is built in the dynamic mode, it is being watched. Actually, it says right here watching for file changes, which means as soon as we change the code in the component, the component is being recompiled and rebuilt. And it gets placed to the HTML folder right here. This functionality is configurable. We can change it in the Visual Studio configuration so it will not run right away. It will wait until we save file. Then we can do multiple changes, and then save file. And they will all get compiled. But by default, it works right away. So let's switch to HTML file. And I'll just enter just a space, empty space. And it starts compiling right away. Now, let's modify this file to see how the changes will appear on the web page. Here I will add a html tag-- basically, some text saying-- testing modifications of the dynamic component. And we see the tsb module got compiled right away. And also, portal gets compiled. We just didn't see it. And we can see our Web Portal page-- if it picked up changes. And here's our changes. And it stops on a breakpoint. We'll press F5 to continue running code. And we see that our change right away appeared on our Web Portal page. To deploy our changes to the API server to the production server, we need to build it in the production configuration. Static libraries qbm and qer don't need to be deployed because their code is baked into the other components. And we can see it here, which components depend on the qer and qbm pretty much all of them. And also, the applications, the Web Portal itself, the landing page, also the qmb and qer code, gets baked right into them. So we don't need to deploy them if we change them. But we'll need to deploy all the components that depend on them. And in our case, it's a dynamic library. We need to build it in the production mode. First, we need to stop components. Press Control-C. Yes, we terminate the job. We stop a portal also-- Control-C. Control-C-- yes, terminate. And then we run command npm run build lib tsb. Our component is built. And it's placed into the dist folder. Here it is. And now we need to zip all the files and folders inside of that component folder. We go to right-click and say reveal File Explorer. This is our tsb module. And everything inside of it needs to go into the zip file. So select all. Right-click 7-Zip, Add to Archive, and rename it with html, underscore, and then the name of the module, dot zip. Here is the file. And now we need to deploy this file to the production server, which is installed here in the same machine in the [INAUDIBLE]. root dpa server them imxweb. Inside of imxweb, we need to create, if it doesn't already exist, custom folder and place this zipped component here. We don't need to delete all component file because the portal will pick up files from this custom folder and just leave originals. Now it's been deployed. I just run IAS reset just in case. Now we can test it. Log in and go to Membership. And here, we see our modification. We see it right under installed production server. In real world, deployment to the production server will need to go through the software loader. We will not demonstrate it in our video here. But it is described in details in the accompanying document where it just describes step by step. All data used in Web Portal comes from Identity Manager Database via API server. API server exposes REST API for clients to use for reading and writing data. REST API contains hundreds of methods. To document various methods and to test them, API server uses Swagger UI. Swagger UI gives each method a visual representation and capability to execute it with parameters and view results. To get to Swagger API, we need to go to the API server landing page. We need to make sure that server name is the correct name of this server where the API server is installed. Here is the Swagger UI. First thing we need to do is to log in because none of the methods will work without correct login. And there are multiple login methods here. There are methods per project and per authentication module. So password reset dynamic person, password reset role-based ADS account, portal, ADS account, portal dynamic person-- but there is one login method that is universal. It works with all projects. And we'll try that. Click on imx login, app ID-- need to click on "Try it out." Select the right application-- portal, in our case. We do need XSRF protection disabled. And here is the login string we need to pass. We're using role-based person module and username and password. Click on Execute. And here is the correct response. Now we can find and try to run method. So let's find a method called Portal Person All. This method returns person records. And it can be filtered, sorted, and return additional columns. So let's try it out. If we just click on Execute, it returns all users. And we can tell that for each user, it returns a set number of columns, which includes default email address, identity type, and then some ID and x fields. If we need to return additional columns or filter this result, we need to pass these values in the request. So to filter records, we need to pass a filter string in a specific format. It is described in the commentation for API server. Here, we filter column Last Name, where last name is like E and percent sign, meaning where last name starts with E. So let's do that. Here is a filter. And run the result. Run the request. And one more time-- an error processing request. Of course, we have word filter in front of it. Execute. And now we have a list of users where last name starts with E-- Ebert, Ebert. If we need to return extra columns, we need to pass a list of extra columns we want to retrieve to this request. We'll put it in-- with properties field. And it's comma-separated list of column names we want to retrieve. And now we see that every user has a central account, first name, and last name. Postman can also be used to test API servers. [INAUDIBLE] We can open Postman. And we can import collection Identity Manager API Samples. It is distributed with One Identity. But here, I expanded it, added more methods. And it is distributed in the template under UNITE API server folder. Here it is, Postman collection. After importing collection, it can be edited. It should be edited. And the variables for URL needs to be replaced with our server name/API server. To log in, click on "Log in to any app." It's pre-populated. We can see what this variable shows. The current is pointing to our local server. And you can see how role-based person authentication module is placed in the URL. And in the body, we just passed a username and password. Click on Send, and we see a response, the same response as [AUDIO OUT]. Now to test the same method as we did with Swagger, you need to click on reading from the person table. And here we see the same method. URL is pointing to all our local server, portal person all, and filter-- it shows the filter where last name equals to Erdman. And there's nobody. We send a request. And here we get the response, [INAUDIBLE] columns. And this is a list of standard columns. And now let's add request for additional columns. At the end of the URL, we add-- and with properties, with properties equals last name, first name, central account. Click on Send. And here we see central account, first name, and last name return. This concludes working with API server chapter. We will use these methods to check which columns, which additional columns, we can request from the API server for existing methods, and also for testing our custom methods when we get to creating custom methods. Thank you. [UPBEAT MUSIC]