Gradle tasks and dependency configurations

This page lists the Gradle tasks of an APD project, the settings in its build.gradle, and the dependency configurations for adding libraries.

Tasks

You can execute the following Gradle tasks from your IDE, the command line, or a build server such as Jenkins or Azure DevOps.

Task	Description
test	Compiles the ALFA policies and runs all tests. The test reports are in build/reports/tests/: which tests passed or failed, with their output and stack traces. Also writes a visual trace of each policy evaluation, see Visual tracing.
compileAlfa	Compiles all ALFA policies to XACML and writes the output to build/alfa/domain/xacmlSpecifications.
buildAuthzDomain	Compiles the authorization domain into a single YAML file (build/alfa/domain/ads/domain.yaml) for ADS or to include in a container image. Fails when mainpolicy is not a top-level policy or policy set of the domain.
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 the legacy Axiomatics Services Manager (ASM) version 6 and 7.
stageDeployment	Prepares the ADS deployment in build/install/deployment/ads/: the ADS binaries, domain.yaml, deployment.yaml, the license, the Dockerfile, the attribute connector libraries and your own Java code in lib/, and the files of src/extra/. This directory is the build context for creating a container image with tools such as Docker, Buildah, Podman, Kaniko, or BuildKit. Also writes the .env files of createEnvFile to build/install/deployment/. Does not run the tests.
runAds	Runs ADS locally with the authorization domain built from src/ and the settings in deployment.yaml. Requires a valid license in license/. Press Ctrl+C to stop it. For the settings in deployment.yaml, see the ADS configurationOpens in a new tab documentation.
generateAlfaDictionaryFromYaml	Generates src/authorizationDomain/alfaSpecifications/attributes.alfa from src/authorizationDomain/attributes.yaml. Keep attributes.yaml authoritative and generate attributes.alfa from it.
generateJavaDictionaryFromYaml	Generates src/test/java/apd/Dictionary.java from src/authorizationDomain/attributes.yaml. Use the Java dictionary in your tests, or give it to the developers of your applications (PEPs).
generateYamlDictionaryFromAlfa	Generates src/authorizationDomain/attributes.yaml from src/authorizationDomain/alfaSpecifications/attributes.alfa.
createEnvFile	Lists the environment variables that ADS needs, in build/.env.generated (without values), build/.env.generated.defaults (with default values), and build/.env.generated.info (how to load the file). Use them as a template for the runtime environment of ADS, such as an env file, a Kubernetes Secret, or a ConfigMap. See .env file generation.
upgradeAuthzDomain	Upgrades legacy content of the authorization domain to the current format: today, attribute connectors in the legacy format (className and an XML configurationString). Refuses to run unless all files are committed in Git. To run anyway, add -Dapd.allowUnsafe=true. See Upgrade legacy attribute connectors.
checkAuthzDomainUpgrade	Only reports what upgradeAuthzDomain would upgrade, without changing files. Never fails.
printHubConnections	Prints, for each remote in alfa { repositories { } }, the settings an ADS needs to load the remote's domain (client id, token URI and domain URL), and the identity and metadata of the domain stored there. See Configure ADS to load the domain from Authorization Hub.
runAdsV1, buildAdsDockerImage	Deprecated, removed in APD 27.1: the tasks for the legacy ADS 1. See Version-specific notes for ADS.

The tasks that push to, pull from and promote between Authorization Hub or ASM environments, and the tasks that run ADS and the tests with a remote domain, are created for each remote in alfa { repositories { } }. See Authorization Hub integration.

Project configuration

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

build.gradle

alfa {
    mainpolicy "acme.Main"
}

Setting	Description
mainpolicy	Required. The fully qualified name of the top-level policy that ADS evaluates. Tests without withMainPolicy evaluate this policy, and against a running ADS only the tests of this policy run, see Test policies in depth. It must be a top-level policy or policy set of the built domain. Otherwise, buildAuthzDomain fails with Main policy … not found. Found policies ….
namespace, project	Deprecated since 26.2, removed in 27.1. The Authorization Hub or ASM project. Set project inside each remote instead. See Authorization Hub integration.

Typical workflow

During development:

1. After adding or changing attributes in attributes.yaml, run generateAlfaDictionaryFromYaml and generateJavaDictionaryFromYaml, and commit the generated files. To run them automatically with the tests, see Create the dictionary.
2. Run test while you change policies and tests. It compiles the ALFA policies first, so you do not need to run compileAlfa separately.

In a CI/CD pipeline, run the tests and stage the deployment in one command:

./gradlew test stageDeployment

stageDeployment does not run the tests itself. With both tasks in one command, Gradle runs the tests first, and stops before staging when a test fails.

Build a container image with ADS

APD does not build the container image itself. stageDeployment prepares the build context in build/install/deployment/ads/, with your Dockerfile, as described in the table above. Then build the image with the tool of your pipeline, see Container image.

Custom tasks

You can add your own tasks to build.gradle, for example to package and deliver the output of the APD tasks. The following tasks run the tests, zip the deployment staged by stageDeployment together with the test report, and copy the zip file to a release directory, such as a shared drive:

build.gradle

tasks.register('zipDeployment', Zip) {
    group = 'deployment'
    description = 'Runs the tests, and zips the staged ADS deployment with the test report.'
    from tasks.named('installDeploymentDist')
    from(tasks.named('test').map { it.reports.html.outputLocation }) {
        into 'test-report'
    }
    archiveFileName = "ads-deployment-${project.version}.zip"
    destinationDirectory = layout.buildDirectory.dir('dist')
}

tasks.register('copyDeployment', Copy) {
    group = 'deployment'
    description = 'Copies the zipped ADS deployment to the directory in RELEASE_DIR.'
    from tasks.named('zipDeployment')
    into providers.environmentVariable('RELEASE_DIR').orElse(layout.buildDirectory.dir('release').map { it.asFile.path })
}

The tasks take their input from the output of other tasks, so Gradle runs those first: installDeploymentDist, the task that stageDeployment runs to stage the deployment, and test. ./gradlew copyDeployment copies ads-deployment-<version>.zip to the directory in the environment variable RELEASE_DIR, or to build/release/ when it is not set. The version is the version in build.gradle. The zip file contains the staged deployment (ads/ and the .env files), and the HTML test report in test-report/. When a test fails, the build stops, and no zip file is created or copied.

Put custom tasks in the build.gradle in the project root, not in buildSrc/, which is replaced when you update APD. For more about writing tasks, see the Gradle documentationOpens in a new tab.

Dependency configurations

Gradle's dependency configurations manage the classpath for different tasks. Add libraries to these configurations in your build.gradle:

Configuration	Description
pip	Libraries for the attribute connectors (PIPs) of your APD project: your custom attribute connectors, the libraries they need at runtime, and libraries that the built-in attribute connectors need, such as JDBC drivers. The libraries are added to the tests and to ADS (lib/ of stageDeployment). Do not use implementation for them: those libraries are available in the tests but not in ADS. The built-in Table, SQL, LDAP, HTTP, and Parser attribute connectors are part of ADS and APD. You don't need to add them separately.
testImplementation	Libraries that your tests need.
adsCompile	Libraries needed only to compile your own Java code in src/main/java, such as a custom attribute connector. They are not added to the tests or to ADS: add libraries that your code also needs at runtime to pip. Already includes ads-service of ADS. stageDeployment and runAds build your code into a JAR and add it to ADS.
policy	External ALFA policies to include in the authorization domain.

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

build.gradle

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

JDBC drivers

The most common reason to add a dependency is a JDBC driver for the SQL or Table attribute connectors. Axiomatics does not include any JDBC drivers.

You do not need to download the driver JAR file yourself. Specify its Maven coordinates (group, name, and version), and APD downloads it.

Ask your database administrator for the Maven coordinates of the driver for your database. You can also search a public Maven repository, such as the Maven Central RepositoryOpens in a new tab, for your database vendor and "JDBC".

Add the coordinates as a pip dependency in the build.gradle in the project root. For example, for an Oracle database:

build.gradle

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

warning

APD projects contain two build.gradle files. Edit the one in the project root. Do not modify the files in buildSrc/.