7.4 APEXlang Project Structure

APEXlang applications use a standardized project structure to organize application files, deployment settings, and compiler metadata.

This structure enables:

  • consistent application exports
  • automated validation and deployment
  • version control integration
  • environment-specific configuration management

The following sections describe the directory layout, deployment configuration files, and internal metadata used by SQLcl and the APEXlang compiler.

7.4.1 Directory Structure

APEXlang applications use a defined directory structure to ensure consistency and support deployment and metadata management.

  • Application files are placed in a parent directory using the application's alias property.
  • Deployment configuration files are stored in the deployments/ directory.

  • The hidden .apex/ directory contains internal metadata or configuration files that should not be modified.

    An example of the directory structure:

    .
└── <app-alias>/
    ├── pages/
    │   ├── p00001.apx
    │   ├── p00002.apx
    │   └── ...
    ├── shared_components/
    │   ├── lists.apx
    │   └── ...
    ├── supporting_objects/
    ├── deployments/
    │   └── default.json
    ├── .apex/
    │   └── apexlang.json
    ├── application.apx
    └── page_groups.apx

SQLcl Projects Directory Structure

To maintain consistency across SQLcl APEX and Projects commands, APEX application directories in SQLcl Projects follow this structure: 

f<appId>/<app-alias>/

As part of this change, the SQLcl Projects command includes logic during database export to remove the previous directory structure automatically.

Example:

.
├── .dbtools/
│   ├── project.config.json
│   └── ...
├── artifact/
├── dist/
└── src/
    └── database/
        ├── mySchema/
        │   └── apex_apps/
        │       └── f100/
        │           ├── f100.sql
        │           └── brookstrut/
        │               ├── pages/
        │               │   ├── p00001.apx
        │               │   ├── p00002.apx
        │               │   └── ...
        │               ├── shared_components/
        │               │   ├── lists.apx
        │               │   └── ...
        │               ├── supporting_objects/
        │               ├── .apex/
        │               │   └── apexlang.json
        │               ├── deployments/
        │               │   └── default.json
        │               ├── page_groups.apx
        │               └── application.apx
        └── sys/
            └── ...

7.4.2 Deployment File

APEXlang uses a deployment file to define application and workspace settings used during validation and import. It provides default values such as application ID, workspace, and other import settings. These values can be overridden using command options.

Deployment files are generated during apex export or created when running apex generate.

Example

{
  "app": {
    "id": 1020,
    "name": "Customer Portal",
    "alias": "customer-portal",
    "databaseSession": {
      "parsingSchema": "CUST_PORTAL_APP"
    },
    "availability": {
      "buildStatus": "runAndBuild"
    },
    "runtime": {
      "logging": true,
      "debugging": false
    },
     "proxy": {
      "proxyServer": "proxy.corp.example.com",
      "noProxyDomains": "localhost,internal.example.com"
    },
     "staticFiles": {
      "appFilesPath": "/u01/apex/apps/customer-portal/files",
      "apexFilesPath": "/u01/apex/shared/files"
    } 
  },
  "workspace": {
    "name": "CUSTOMER_PORTAL"
  },
  "theme": {
    "advanced": {
      "filePrefix": "i"
    }
  }
}

Property Descriptions

The deployment file defines values used during validation and import.

Property Description
app.id Specifies the target Application ID to use when importing the application.
app.name Defines the display name of the application.
app.alias Sets the unique alias used in application URLs.
app.databaseSession.parsingSchema Identifies the database schema used to parse and execute the application.
app.availability.buildStatus Controls application availability. Supported values: runAndBuild (application is editable and runnable) and runOnly (application is runtime-only).
app.runtime.logging Enables page view logging for the application.
app.runtime.debugging Enables application debugging.
app.proxy.proxyServer Specifies the proxy server used for outbound network requests.
app.proxy.noProxyDomains Lists domains that bypass the configured proxy server.
app.staticFiles.appFilesPath Defines the file system or URL path for application-specific static files.
app.staticFiles.apexFilesPath Defines the path for shared APEX static resources (images, JavaScript, CSS).
workspace.name Specifies the target workspace into which the application is imported.
theme.advanced.filePrefix Sets the file prefix used by the application theme for resolving static resources.

Property Resolution Order

When the same property is defined in multiple sources, APEXlang resolves the value by using a defined order of precedence.

The following sections describe how this resolution process applies to specific property groups.

Application ID Resolution

APEXlang determines the application ID using the following order of precedence:

  1. Use the application ID provided through a command option.
  2. Use the app.id value from a deployment file specified through a command option.
  3. Use the application ID defined in the APEX session.
  4. Use the app.id value from the default deployment file in the input path.
  5. Generate an available application ID using the database connection.

Workspace Resolution

APEXlang determines the workspace by using the following order of precedence:

  • Use the workspace or workspace ID provided through a command option.
  • Use the workspace defined in the APEX session.
  • Use the workspace.name value from a deployment file specified through a command option.
  • Use the workspace.name value from the default deployment file in the input path.
  • Query the workspace using the database connection.

All Other Property Resolution

All other deployment properties are resolved using the following order of precedence:

  • Use the value provided through an associated command option.
  • Use the value defined in the APEX session, if supported.
  • Use the property value from a deployment file specified through a command option.
  • Use the property value from the default deployment file in the input path.
  • If no value is found, the property is not set.

7.4.3 Hidden Configuration Directory

The hidden .apex/ directory contains internal metadata and configuration files used by APEXlang. These files are managed automatically and generally should not be modified manually. Changes to these files may cause unexpected behavior.

The primary file in this directory is .apex/apexlang.json. This file stores the internal configuration used by the APEXlang compiler.

Property Description
mmdVersion

Specifies the version of the MMD (meta meta data) that the APEXlang source files are compatible with. This value is used to initialize the APEXlang compiler. If not specified, the compiler uses the latest supported version. This value must not be modified manually.