Gradle tasks and dependency configurations

This section details the Gradle tasks available for building, testing, and deploying your ALFA project, as well as the dependency configurations used to manage external libraries. Understanding these tasks and configurations is crucial for efficiently managing your ALFA project's lifecycle.

Tasks

You can execute the following Gradle tasks from your IDE, the command line, or a build automation tool like Jenkins or Azure DevOps.

Task	Description
buildAuthzDomain	Compiles the authorization domain into a single YAML file (build/alfa/ads/domain.yaml) suitable for ADS or to include in a container image
compileAlfa	Compiles all ALFA policies to XACML and writes the output to build/alfa/domain/xacmlSpecifications.
compileAlfaToPackage	Compiles all ALFA policies to XACML and bundles them into a policy package (build/alfa/domain/package/policy_package.zip), which you can upload to Authorization Hub or legacy Axiomatics Services Manager (ASM) version 6 and 7.
stageDeployment	Prepares the ADS deployment within the build/install/deployment/ads directory. This deployment package includes the ADS binaries, domain.yaml, deployment.yaml, the software license, custom attribute connectors, extra runtime dependencies, and extra resources (from src/extra/). This directory serves as the root build context for creating container images using tools like Docker, Buildah, Podman, Kaniko, or BuildKit. A list of environment variables used in the domain is also written to build/install/deployment/.env.generated.
runAds	Runs the latest ADS locally using the authorization domain from src/ and the deployment descriptor from deployment.yaml. NOTE: You need a valid software license in license/ to run ADS. Press Ctrl+C to stop the service. IMPORTANT: Structure the deployment.yaml file according to the DomainOpens in a new tab section of the latest Access Decision Service documentation.
test	Runs all unit, integration, and system tests and generates test reports in build/reports/tests/. The reports indicate which tests passed or failed and provide output and stack traces. Also provides a visual trace of the policy evaluation.
generateAlfaDictionaryFromYaml	Generates src/authorizationDomain/alfaSpecifications/attribute.alfa based on src/authorizationDomain/attributes.yaml. It is recommended to keep the attributes.yaml authorative and generate attributes.alfa
generateJavaDictionaryFromYaml	Generate src/test/java/apd/Dictionary.java based on src/authorizationDomain/attributes.yaml. The Java dictionary can be used in your test and also given to PEP/consumers.
generateYamlDictionaryFromAlfa	Generates src/authorizationDomain/attributes.yaml based on src/authorizationDomain/alfaSpecifications/attribute.alfa.
createEnvFile	Generates build/.env.generated and build/.env.generate.info with environment variables used in the authorization domain. Can be used as a template for setting up a container runtime environment (env file, Secret or ConfigMap)

Project configuration

The alfa block in build.gradle controls project-wide settings that several APD tasks depend on.

build.gradle

alfa {
    namespace "MyProject"
    mainpolicy "acme.Main"
}

Setting	Description
namespace	A unique name for your authorization domain project.
mainpolicy	Required. The fully qualified name of the top-level policy that ADS evaluates. System tests, remote test execution, and visual tracing all require this to be set. Without it, APD cannot distinguish system tests from unit tests, and remote test tasks will not execute correctly.

Typical workflow

Most development and CI/CD workflows follow this sequence:

1. generateAlfaDictionaryFromYaml and generateJavaDictionaryFromYaml

   After adding or changing attributes in attributes.yaml, regenerate the ALFA and Java dictionaries. Commit the generated files.

2. compileAlfa

   Compile ALFA policies to check for syntax errors.

3. test

   Run all unit, integration, and system tests. This also compiles the authorization domain automatically.

4. stageDeployment

   Prepare the ADS build context for image creation (only after tests pass).

When you run stageDeployment, Gradle executes the full dependency chain automatically and you do not need to run each step manually. During active policy development, running test continuously is sufficient.

Build a container image with ADS

Axiomatics Policy DevOps (APD) does not include a task for building a container image with latest ADS binaries. Instead, use the stageDeployment task to prepare the build context in the build/install/deployment/ads directory.

Once prepared, call your preferred image build tool to create the image. The files Dockerfile and deployment.yaml will be automatically copied into this build context directory. Tailor it to your needs if needed.

Dependency configurations

Gradle's dependency configurations manage the classpath for different tasks. The following configurations help manage dependencies for your ALFA project:

Configuration	Description
pip	Add any extra attribute connector dependencies. This configuration already includes Axiomatics' Table, SQL, LDAP, HTTP, and Parser attribute connectors.
testImplementation	Add any additional dependencies required for executing tests.
adsCompile	Add any extra dependencies needed for compilation.
policy	Include any external ALFA policies.

To add a dependency, use the following syntax in your build.gradle file:

build.gradle

    dependencies {
        pip '<group>:<name>:<version>'
    }

JDBC drivers

The most common need for configuring dependencies are when the SQL or Table Attribute connectors are used. These attribute connectors needs the correct JDBC driver for your database. No JDBC drivers are included by Axiomatics.

You do not need to download or add the driver JAR file yourself. Instead you specify the name and version (Maven coordinates) and the JAR file will be automatically downloaded by APD.

Contact your database administrator to get the Maven coordinates (artifact name and version) you should use to connect to the database. You can also search at public maven repos such as Maven Central RepositoryOpens in a new tab. Search for your database vendor + JDBC to locate a potential driver that matches your database vendor and version.

Once you have the coordinates, add them as a dependency in /build.gradle. The example below shows a JDBC driver for Oracle. pip is a keyword specifying a classpath that is used by Axiomatics Attribute Connectors.

 dependencies {
        pip "com.oracle.database.jdbc:ojdbc10:19.31.0.0"
    }

Important

APD projects can contain two build.gradle files. Ensure you are editing the correct one located in the project root (/build.gradle). Files under buildSrc/ should not be modified.