Skip to main content
Version: 4.x (maintenance)

awe-101 Your first AWE App

Build a small AWE application in a few minutes. This tutorial starts after the Getting Started quick path and focuses on the first useful steps: generate the app, run it, understand the generated folders, and make one tiny visible change.

Quick path​

  1. Generate a project from an AWE archetype.
  2. Run it locally on http://localhost:18080.
  3. Inspect the generated application/<your-acronym>/ resources.
  4. Change one setting and restart the app.

Before you start​

You need:

  • Java 17 or higher
  • Maven 3.x or higher
  • A terminal and your preferred editor

If you have not generated a project yet, follow Getting Started first.

Step 1: Generate the application​

This example uses the AngularJS archetype because it is the classic AWE starter. If you prefer React, use the same command and replace awe-boot-angular-archetype with awe-boot-react-archetype.

Use the current AWE version from Maven Central: Version

mvn -B archetype:generate \
 -DarchetypeGroupId=com.almis.awe \
 -DarchetypeArtifactId=awe-boot-angular-archetype \
 -DarchetypeVersion=[Archetype version] \
 -DgroupId=com.example.app \
 -DartifactId=my-app \
 -Dversion=1.0-SNAPSHOT

After the command finishes, move into the generated project:

cd my-app

Step 2: Run the application​

Start the generated app:

mvn spring-boot:run

Then open:

http://localhost:18080
info

The generated application is configured with server.port=18080.

Older AWE training notes document test / test credentials for the sample test application. Treat that as version-specific guidance and verify it against the archetype version you generated before relying on it.

Step 3: Understand the generated structure​

You do not need to learn the whole framework on day one. Start with these files and folders:

PathWhy it matters
pom.xmlMain Maven project file.
src/main/resources/application.propertiesApplication name, port, theme, database, and startup settings.
src/main/resources/application/<your-acronym>/global/Shared AWE XML descriptors such as queries, maintain, services, and actions.
src/main/resources/application/<your-acronym>/screen/Screen XML files. This is where UI screens live.
src/main/resources/application/<your-acronym>/menu/Public and private navigation menus.
src/main/resources/application/<your-acronym>/locale/Application text by language.
src/main/resources/application/<your-acronym>/profile/Access rules and profile restrictions.

High-level rule:

  • screen/ defines what users see.
  • menu/ decides how users reach those screens.
  • global/ contains shared backend-facing XML definitions.
  • locale/ stores translatable labels.

If you want a fuller explanation later, continue with Project Structure.

Step 4: Make one tiny first customization​

For the smallest safe first change, update the generated theme.

  1. Open src/main/resources/application.properties.

  2. Find the awe.application.theme= line. The generated value depends on the archetype:

    # Angular archetype
    awe.application.theme=sunset

    # React archetype
    awe.application.theme=default

  3. Replace the current value with another theme name from the AWE demo theme list referenced in that same file comment.

  4. Stop the app and run mvn spring-boot:run again.

  5. Refresh the browser and confirm the application style changed.

This is a good first edit because it is visible, easy to revert, and helps you confirm that the generated project is now yours.

What to explore next​

When you are ready for the next step, open these folders in order:

  1. src/main/resources/application/<your-acronym>/menu/
  2. src/main/resources/application/<your-acronym>/screen/
  3. src/main/resources/application/<your-acronym>/global/

That path matches the way most AWE application work grows: navigation first, then screens, then shared logic.

Video reference​

If you prefer to see the setup flow in an IDE, you can still use the original IntelliJ walkthrough video: