Creating a new OneCX Angular App

General Overview

After setting up the onecx-environment locally, you can begin creating your own application within this environment. This guide walks through the process of building a simple "Hello World" Angular app and integrating it into the OneCX environment. To integrate an application into the OneCX environment, it should follow the standard architecture consisting of three main services (ui, bff and svc). These services are consumed by the OneCX shell, which orchestrates and displays the UI components within the broader platform.

Creating the UI

1. Create the basic UI structure

We start with creating the UI structure of our "Hello World" App by running the following commands using the custom OneCX generator.

Please check the prerequisites for using the generator before starting.

Setup New Angular Workspace

First, we can generate the basic project structure and required files for the application. This includes necessary configuration and build files, initial Angular source code, generated API services, translation assets, Swagger specifications, environment settings and Helm deployment configurations.

We can set up the new Angular workspace by running:

npx @onecx/create-workspace ngrx hello-world
Details to generating a new OneCX Angular workspace can be found here.

Navigate into the newly created hello-world directory and install the packages with npm install.

Add a Feature Module

Now we want to add a feature module to our application, that encapsulates the functionality of our new feature "hello". Therefore a new folder with the name of the feature module will be created in the /src/app/ directory.

This will be generated by running the following command:

nx generate @onecx/nx-plugin:feature hello
Details to generating a feature module can be found here.

Add a Search Page

Additionally we can add a search feature, that includes a table and allows users to search for an item in a certain column. The search page can be generated in the same way as the feature module:

nx generate @onecx/nx-plugin:search hello
Details to generating a search page can be found here.

Add a Details Page

Now we can also create a details page for the items in the search results by running:

nx generate @onecx/nx-plugin:details hello
Details to generating a details page can be found here.

Add a Create-Update Dialog

Additionally we can add a create and update dialog for creating and updating items on the page by running:

nx generate @onecx/nx-plugin:create-update hello
Details to generating a create-update dialog can be found here.

The application can now be built, tested and started by running npm run build, npm run test and npm start.

For further customization of the app, you can refer to the general OneCX generator documentation.

2. Include application in OneCX environment

Now let’s integrate the "Hello World" app into the OneCX environment using the onecx-local-env. This section assumes your local environment is already set up and running.

Synchronization

In your hello-world UI folder, sync the app with your local environment (adjust the path to your onecx-local-env):

npx @onecx/local-env-cli sync ui hello-world /hello-world ./helm/values.yaml -e /path/to/onecx-local-env -n hello-world-ui

In this command:

  • hello-world refers to the product name.

  • /hello-world specifies the product’s base path.

  • ./helm/values.yaml is the path to the application’s values.yaml file.

  • -e /path/to/onecx-local-env should be adjusted to the path of your local onecx-local-env repository.

  • -n hello-world-ui specifies the name of the microfrontend service.

This command will adjust the files in your onecx-local-env to include the necessary information about the new application’s UI.

Add Menu Entry

Add a menu entry for the new application in the OneCX environment by running (adjust the path to your onecx-local-env again):

npx @onecx/local-env-cli menu create hello-world-ui /hello-world/hello "Hello World" -e /path/to/onecx-local-env

This command will create a new menu entry "Hello World" under Custom Applications with the path to the applications feature module /hello-world/hello.

Add the UI to Docker Compose

Add the UI as an image to the docker-compose.yaml of your onecx-local-env with the following command (adjust the path to your onecx-local-env again):

npx @onecx/local-env-cli docker hello-world create hello-world helloWorld -e /path/to/onecx-local-env -s ui

In this command: - hello-world after docker refers to the name of the custom docker compose that will be created. - hello-world after create references the product name. - helloWorld is the name of the UI path as defined in the values.yaml of the application UI. In this case it is helloWorld as the routing path in the values.yaml is /mfe/helloWorld/. - -e /path/to/onecx-local-env should be adjusted to the path of your local onecx-local-env repository. - -s ui specifies that the service to be added is the UI.

Now a hello-world.docker-compose.yaml should be created in the onecx-local-env containing an image for hello-world-ui.

More details to the onecx-local-env-cli can be found here.

Creating the BFF

First clone the bff repository: https://github.com/onecx/onecx-hello-world-bff.git and navigate into the folder.

As we did for the UI, we can sync the app with your local environment for the bff and add the bff to our hello-world.docker-compose.yaml as well. The src/main/helm/values.yaml path refers to the values.yaml file of the bff.

npx @onecx/local-env-cli sync bff hello-world /hello-world src/main/helm/values.yaml -e /path/to/onecx-local-env
npx @onecx/local-env-cli docker hello-world create hello-world helloWorld -e /path/to/onecx-local-env -s bff

Creating the SVC

Now we can clone the svc repository: https://github.com/onecx/onecx-hello-world-svc and navigate into the folder.

The same way as for the UI and BFF, we can sync the app with your local environment for the svc and add the svc to our hello-world.docker-compose.yaml as well. The src/main/helm/values.yaml path refers to the values.yaml file of the svc.

npx @onecx/local-env-cli sync svc hello-world /hello-world src/main/helm/values.yaml -e /path/to/onecx-local-env
npx @onecx/local-env-cli docker hello-world create hello-world helloWorld -e /path/to/onecx-local-env -s svc

Now that the services are created, the application can be run in the OneCX environment as described here.