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.

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, that was generated by the OneCX generator

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

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.

Start the Environment and Import Data

First we need to import the initial data to set up the environment correctly:

./import-onecx.sh

Now the service can be started with running the following command:

docker compose -f hello-world.docker-compose.yml --profile base up -d

The frontend of your "Hello World" application is now configured.

Creating the BFF

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.yml as well. The ./helm/values.yaml path refers to the values.yaml file of the bff.

npx @onecx/local-env-cli sync bff hello-world /hello-world ./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

As we did 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.yml as well. The ./helm/values.yaml path refers to the values.yaml file of the svc.

npx @onecx/local-env-cli sync svc hello-world /hello-world ./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