# Agent-Ready Projects
Source: https://docs.gradial.com/aci/architecture/agent-native-design
Help people and coding agents make safe ACI changes with repository guidance, typed contracts, and shared checks.
A Gradial ACI (Agentic Content Infrastructure) project gives every contributor the same understandable working surface: JSON content, typed component contracts, framework code, familiar commands, and tests. Generated projects also include repository-local guidance that compatible coding agents can load before they make a change.
There is no separate content model for agents. Work produced with Gradial or a coding assistant must satisfy the same contracts and pass the same review, preview, and release process as work produced manually.
## Guidance travels with the project
The starter places its operating guidance under `.agents/`:
```txt theme={null}
.agents/
├── AGENTS.md
└── skills/
├── aci/
│ └── SKILL.md
├── authoring/
│ └── SKILL.md
└── migration/
└── SKILL.md
```
| Resource | When to use it |
| --------------------------- | ----------------------------------------------------------------- |
| `.agents/AGENTS.md` | Repository-wide conventions and routing to more specific guidance |
| `skills/aci/SKILL.md` | ACI project structure, commands, testing, and troubleshooting |
| `skills/authoring/SKILL.md` | Pages, components, contracts, registration, and design tokens |
| `skills/migration/SKILL.md` | Moving an existing site or design into the ACI project shape |
These files are useful to people as well as agents. Keeping them in the repository means the instructions can evolve alongside the code and be reviewed like any other project change.
Treat the generated guidance as a maintained part of the project. Add your own brand, accessibility, test, and review requirements where contributors will find them before they edit content or components.
## One workflow for every contributor
```mermaid theme={null}
flowchart LR
A["Read repository guidance"] --> B["Inspect content and contracts"]
B --> C["Make a scoped change"]
C --> D["Compile and test"]
D --> E["Review and preview"]
E --> F["Approve, promote, and release"]
```
The shared workflow matters more than which tool made the edit. A component prop added by a developer, a page revised with a coding agent, and content produced through Gradial all meet at the same validation boundary.
### 1. Read the local instructions
Before editing, load `.agents/AGENTS.md` and the relevant skill. The task should also identify the page, component, or route in scope and the checks required before handoff.
### 2. Inspect the source of truth
Agents can reason about the project through ordinary files:
* `.content/` contains pages, fragments, overlays, and site configuration;
* `src/cms/contracts/` defines valid component props and layout regions;
* `src/cms/registry.ts` maps contracts to runtime components;
* `src/components/` contains the frontend implementation; and
* `package.json` defines the project's supported development and verification commands.
This makes the correct boundary visible. A copy-only task may change a page document. A new visual treatment may require a contract, runtime component, registry entry, and tests.
### 3. Make a scoped change
Use the normal project tools. Keep stable page and block IDs when updating existing content, and avoid changing generated output under `.aci/`.
For hosted content work, use a named ACI branch so the change remains isolated until it has been reviewed:
```bash theme={null}
aci branch create campaign-refresh --source-ref main
aci content pull --branch campaign-refresh
# Edit the relevant .content files.
aci content diff --branch campaign-refresh
```
For code work, use your repository's normal Git branch and review process. If the ACI content branch needs the new frontend code for preview, build and link the current Git state:
```bash theme={null}
aci code-build --branch campaign-refresh
```
### 4. Run the shared checks
Generated projects provide a standard local verification loop:
```bash theme={null}
npm run content:compile
npm run typecheck
npm test
npm run build
```
These checks verify content structure, component props, contract-to-runtime mappings, TypeScript code, conformance rules, and the production framework build. Add your own accessibility, visual regression, and policy tests to the same loop.
### 5. Review the result
A passing command is necessary, but it is not the whole review. Before approval:
* inspect the file diff for unintended scope;
* confirm that IDs and references were preserved;
* review the branch preview across relevant routes and viewports;
* check base and personalized experiences when overlays changed; and
* follow your team's content, legal, brand, and release approvals.
Agents do not bypass these controls. The same branch, validation, preview, promotion, and release stages apply regardless of who or what prepared the change.
## Write an effective task
A useful agent task names the outcome, source files, constraints, and proof of completion. For example:
```txt theme={null}
Read .agents/AGENTS.md and .agents/skills/authoring/SKILL.md first.
Update the existing home-page hero copy for the fall campaign.
- Change only .content/pages/home/_index.json.
- Preserve the page ID and hero block ID.
- Keep the props valid for the home_hero contract.
- Do not edit generated files under .aci/.
Run npm run content:compile and report the changed file and result.
```
This gives the contributor room to do the work while making scope and verification explicit.
## Guardrails worth keeping in the repository
Add instructions that are specific enough to verify:
| Area | Example guardrail |
| ---------------- | ----------------------------------------------------------------------- |
| Content scope | Change only the named page and its directly referenced fragment |
| Stable identity | Preserve existing page, block, audience, and experiment IDs |
| Contracts | Update schema, runtime component, registry, content, and tests together |
| Generated output | Never edit `.aci/` by hand |
| Personalization | Keep a complete base experience and verify the fallback |
| Quality | Run compile, type, test, and build commands before handoff |
| Release | Preview and obtain the required approval before landing or promotion |
Prefer rules that describe observable outcomes. A contributor can verify “no raw color values” with a lint rule; “make it polished” leaves the important constraint open to interpretation.
## Use the same CLI safely
Coding agents can invoke the same project scripts and ACI commands available to a developer. Grant only the access required for the task, and keep production activation as an explicit step in your release process.
For a content branch, a safe handoff sequence is:
```bash theme={null}
aci content validate
aci content diff --branch campaign-refresh
aci content push --branch campaign-refresh --dry-run
```
The dry run gives the reviewer a concrete change plan. Applying the push, landing the branch, promoting paths, and activating a release can remain separate approvals based on your team's operating model.
## What stays consistent
Whether a change is made by a person, through Gradial, or with a compatible coding agent, ACI evaluates the resulting project rather than trusting the authoring tool:
* content is structured and reference-aware;
* props are checked against code-owned schemas;
* branches isolate in-progress work;
* previews show the branch's linked content and code; and
* approved content is promoted and released through explicit steps.
That consistency is what makes agent-assisted work practical: the project is easy to understand, and correctness does not depend on a separate agent-only interface.
***
*Next: [Personalization Quickstart →](/aci/personalization/quickstart)*
# Content Versioning
Source: https://docs.gradial.com/aci/architecture/content-versioning
How ACI uses branches, immutable versions, and separate approved and published states to keep content changes reviewable.
ACI preserves content as a versioned history. Teams make changes on branches, land approved work on `main`, and promote selected paths to `live`. Each transition is deliberate, so saving or approving content does not change the live site by itself.
## The content states
```mermaid theme={null}
flowchart LR
A["Branch
Define an audience or experiment, then add overlays for the pages or fragments that should change.
ACI resolves overlays, references, layouts, and component contracts. A release is blocked if a resolved variant is invalid.
The base artifact, variant artifacts, and selection metadata are staged together. Preview uses that exact release.
The delivery layer evaluates available request facts, consented audience membership, and experiment assignment. It selects one exact compiled artifact before returning the response.
For static delivery, the selected artifact is complete HTML. For supported Next.js SSR delivery, ACI selects a compiled page graph and the application renders that exact selection. Audience matching and fallback do not move into application code.
## Safe fallback behavior
ACI returns the base experience when:
* no audience or experiment matches;
* consented identity is unavailable for behavior-based targeting;
* a targeting fact is missing;
* a resource is disabled or not part of the active release; or
* selection cannot produce a valid variant.
This makes fallback an authored behavior, not an error screen. Review the base path whenever you review a personalized path.
## Collection and consent
Request-based targeting can use facts available on the current request. Behavioral audiences require consented first-party events and a usable visitor identity. ACI's browser collector connects those events to the same versioned audience definitions used by the compiler.
Consent remains part of the delivery decision. Without the required consent, ACI does not use identity-dependent audience membership and returns the base experience. Experiments configured for anonymous participation follow their own assignment and measurement policy while respecting supported privacy signals.
ACI provides the technical consent controls described here. Your organization is responsible for configuring them to match its privacy policy and legal requirements.
## Releases, caching, and rollback
Variants are immutable within a release. The delivery layer can cache them by release and artifact identity because visitors selecting the same artifact receive the same compiled result. Visitor identity and raw consent data are not part of the content artifact.
Activation switches the complete release: base content, variants, and selection metadata move together. A release rollback restores the previous set together as well.
## Start building
Create a behavior-based audience and your first overlay.
Learn how focused patches resolve against base content.
Connect a consent provider and capture first-party events.
Define goals, allocate arms, and evaluate outcomes.
***
*Next: [Hosting and Delivery →](/aci/platform/hosting)*
# Content Compilation
Source: https://docs.gradial.com/aci/architecture/pre-compile-pipeline
How ACI validates content against frontend contracts and prepares base and variant artifacts before release.
Content compilation is the release safety gate in ACI. It checks a specific content version against a specific code build, resolves the site into known routes, and prepares the artifacts that delivery will use.
The same compiler supports local development, branch review, and release publishing. A branch preview can help you review the result, but content must still compile successfully before it can be released.
## Compiler inputs
ACI compiles two versioned inputs together:
Pages, fragments, site configuration, asset references, and overlays from a branch or the `live` content state.
Component and layout contracts, their registries, and the rendering implementation from the linked code build.
Pairing these inputs makes compatibility testable. A valid page is not just valid JSON; its components and layout must match what the selected frontend build accepts.
## What compilation checks
ACI checks each document type and its required fields. Page metadata, regions, component blocks, and configuration must use the expected shape.
Component props, asset slots, layout regions, and slot defaults are checked against the contracts exported by the frontend project.
References to fragments, assets, and other content must point to valid targets. A broken or incompatible reference stops compilation.
ACI resolves page paths and records which shared content contributes to each route so the complete release can be prepared consistently.
Locale, audience, and experiment overlays are applied over valid base content. Every resulting experience must satisfy the same frontend contracts.
ACI produces one base artifact and the finite set of configured variant artifacts needed for each route.
When compilation fails, diagnostics identify the content path and problem so you can correct the source and run the same check again.
ACI starter projects include `npm run content:compile` for the local content compilation loop. See the [CLI Reference](/aci/developers/cli-reference) for direct CLI workflows.
## Base content and variants
Personalization changes which compiled artifact a visitor receives; it does not bypass compilation.
```mermaid theme={null}
flowchart LR
A["Base page"] --> C["Compile"]
B["Audience and locale overlays"] --> C
C --> D["Base artifact"]
C --> E["Variant A"]
C --> F["Variant B"]
D --> G["Edge selection"]
E --> G
F --> G
G --> H["Deliver exact result"]
style C fill:#6366f1,color:#fff
style G fill:#8b5cf6,color:#fff
```
If no audience or locale variant applies, delivery uses the base artifact. This fallback is part of the content model and should always be reviewed alongside personalized variants.
## Static and server-rendered output
ACI uses one content compiler for supported delivery modes. The final artifact shape differs only at the rendering boundary.
| Delivery mode | What ACI prepares |
| ---------------------------------- | ------------------------------------------------------------------------------------------- |
| Static delivery | Complete HTML for the base route and each configured variant |
| Supported Next.js server rendering | Validated page data for each result; ACI selects the exact result before Next.js renders it |
In the server-rendered mode, the frontend receives the selected page result. Personalization matching and fallback do not move into application code.
## Changing a contract safely
When a component or layout contract changes:
1. Link a branch to the updated code build.
2. Compile existing content against the new contract.
3. Update each incompatible content path.
4. Preview representative routes and variants.
5. Land and promote the compatible content with the intended code build.
6. Stage and activate the release.
This workflow makes contract changes visible before release and keeps content fixes reviewable with the code that requires them.
***
*Next: [Publishing & Releases →](/aci/architecture/publishing-and-releases)*
# Preview
Source: https://docs.gradial.com/aci/architecture/preview
How ACI renders a branch with its linked code build for review without changing the active release.
ACI preview gives reviewers a branch-specific view of saved content and its linked frontend code. Opening or refreshing a preview does not promote content, stage a release, or change the live site.
## What a preview represents
A preview combines:
* The current saved version of one content branch
* The code build linked to that branch
* The requested site route
* The base experience or a selected personalization context
That pairing matters when content and code evolve together. A reviewer sees the component contracts and rendering implementation intended for the branch, rather than an unrelated production build.
## Preview a branch
Make sure the branch contains the version you want reviewers to see.
If the work depends on new or updated components, link the branch to the compatible code build before reviewing it.
Request the preview through your ACI workflow. ACI returns a branch-addressed preview URL and keeps the requested route in the URL.
Check page content, shared fragments, navigation, responsive behavior, and any relevant base or personalized experiences.
Resolve visual issues and compiler diagnostics before the branch is approved and landed.
A preview URL follows the branch state, so reviewers can refresh after new saved changes. If the linked code build changes, verify the branch again against that new pairing.
## Preview and release are different checks
| Preview answers... | Compilation answers... |
| ----------------------------------------------------------- | -------------------------------------------------------------- |
| Does this page look and behave as intended? | Does the content satisfy its contracts and resolve correctly? |
| Does the linked code render the proposed content correctly? | Can every included route and variant be prepared for delivery? |
| Are the base and targeted experiences appropriate? | Are overlay targets, fallbacks, and outputs valid? |
Preview supports review, but it is not a substitute for compilation. A release must pass the compiler even if its preview looked correct.
## Isolation from the live site
Branch previews use a separate delivery path from the active release. They do not update `main`, `live`, or the active release, and they do not require a release activation.
Treat preview URLs as review links and share them according to your organization's access policy. Avoid using a preview URL as a production endpoint.
## Common review cases
Preview updated copy or structure with the branch's current linked code build.
Link the updated code build, fix incompatible content on the same branch, and review the combined result.
Review several routes that reference the changed fragment, not only the page where the edit began.
Review the base experience and each intended audience or experiment result before promotion.
***
*Next: [Personalization Architecture →](/aci/architecture/personalization)*
# Publishing & Releases
Source: https://docs.gradial.com/aci/architecture/publishing-and-releases
How ACI separates content promotion, release staging, activation, and rollback.
ACI separates choosing content for publication from changing the release visitors receive. This gives teams a review point before each transition and keeps the active site on one consistent release.
## The publishing sequence
```mermaid theme={null}
flowchart LR
A["main
Use release rollback when the active site as a whole should return to an earlier staged release. No content history is rewritten.
Use content history and promotion when one page or fragment should be restored. Promote the intended version to `live`, then stage and activate a new release.
A release rollback restores the complete earlier release, including the code and content that were compiled together. A later correction can be staged and activated through the normal workflow.
## Hosting support
ACI release delivery integrates with CloudFront and Vercel. Local delivery supports development and verification before a hosted release.
Hosting configuration controls domains and platform-specific delivery settings, while ACI keeps promotion, compilation, activation, and rollback consistent across supported integrations.
See [Hosting](/aci/platform/hosting) for setup considerations.
***
*Next: [Preview →](/aci/architecture/preview)*
# CLI Reference
Source: https://docs.gradial.com/aci/developers/cli-reference
Use the ACI CLI for local development, content branches, promotion, and releases.
The Gradial ACI (Agentic Content Infrastructure) CLI connects local frontend work to the same content and release workflow used by the hosted product. Use it to scaffold projects, compile and validate content, work on branches, promote approved paths, and manage releases.
## Run the CLI
ACI starters install the `aci` binary through `@gradial/aci`. Check the project-local version with:
```bash theme={null}
npm exec -- aci --version
npm exec -- aci --help
```
The examples below use `aci` for readability. From a project where the binary is not already on your shell path, prefix a command with `npm exec --`:
```bash theme={null}
npm exec -- aci content validate
```
Use the starter's package scripts for routine local work. They keep the command and SDK version aligned:
```bash theme={null}
npm run dev
npm run content:compile
npm run typecheck
npm test
npm run build
```
## Command map
```txt theme={null}
aci
├── init
├── dev
├── validate
├── content
│ ├── pull
│ ├── push
│ ├── compile
│ ├── diff
│ └── validate
├── branch
│ ├── list
│ ├── get
│ ├── create
│ ├── delete
│ ├── changes
│ ├── patch
│ ├── rebase
│ ├── refresh-code
│ └── land
├── code-build
├── promote
├── drift
├── release
│ ├── publish
│ ├── activate
│ ├── rollback
│ └── status
└── dam
├── upload
├── upload-version
└── download
```
Run `aci --help` for the flags available in your installed SDK.
## Global options
| Option | Purpose |
| ----------------------- | ---------------------------------------------------- |
| `-s, --site-dir ` | Use the project containing the specified `.aci.yaml` |
| `-d, --domain ` | Override the configured site domain |
| `-v, --verbose` | Show additional command output |
| `-h, --help` | Show command help |
| `--version` | Show the installed CLI version |
Hosted commands use your organization's ACI API URL and access token. Set them in the environment to avoid placing credentials in shell history:
```bash theme={null}
export ACI_API_URL="https://your-tenant-api.example"
export ACI_API_TOKEN="your-access-token"
```
Your Gradial team provides the correct API URL and access method for each environment. Do not commit tokens to the repository.
## Create a project
### `aci init`
Create an Astro site with sample content:
```bash theme={null}
npx @gradial/aci init my-site --template astro-starter --with-starter-content
```
Create a Next.js site without sample pages or components:
```bash theme={null}
npx @gradial/aci init my-site --template next-starter
```
List the templates provided by the installed package:
```bash theme={null}
npx @gradial/aci init --list
```
Astro is the standard starter for a new site. `--with-starter-content` adds sample content, components, assets, and stories; without it, the project starts with empty registries and the required integration structure.
## Develop locally
### `aci dev`
Compile local content, watch it for changes, and run the configured framework development server:
```bash theme={null}
aci dev
```
Override the framework's development port when needed:
```bash theme={null}
aci dev --port 4400
```
The generated `npm run dev` script is the usual entrypoint for a starter project.
## Work with content
### `aci content compile`
Compile authored content into the generated local output:
```bash theme={null}
aci content compile --content ./.content --out ./.aci/compiled
```
If you run the command from the site root, the CLI can discover these paths from the project configuration:
```bash theme={null}
aci content compile
```
### `aci content validate`
Validate content structure and, when run inside a configured site, component prop schemas:
```bash theme={null}
aci content validate
```
Use an explicit source directory outside a configured project:
```bash theme={null}
aci content validate --content ./content-export
```
Running from the site root performs the most complete check because the CLI can load the component and layout contracts.
### `aci validate`
Validate the coherence of the complete content snapshot for the configured site. Every content document is parsed and checked against the project's contracts, and referenced assets are resolved:
```bash theme={null}
aci validate
```
The command exits non-zero when errors are found, which makes it suitable for CI gates. Use `--format json` for machine-readable output.
### `aci content pull`
Pull a branch's content into the local content directory:
```bash theme={null}
aci content pull --branch campaign-refresh
```
Pull replaces the local runtime content tree with the selected remote branch. Commit, stash, or otherwise preserve local edits before you run it.
### `aci content diff`
Compare local content with a remote branch before pushing:
```bash theme={null}
aci content diff --branch campaign-refresh
```
### `aci content push`
Preview the changes that would be sent to a content branch:
```bash theme={null}
aci content push --branch campaign-refresh --dry-run
```
After reviewing the plan, push the changes:
```bash theme={null}
aci content push --branch campaign-refresh
```
Use `--files` for a targeted initial seed or update. Repeat the option as needed and review a dry run first:
```bash theme={null}
aci content push \
--branch campaign-refresh \
--files .content/pages/campaign \
--dry-run
```
## Work with branches
ACI branches isolate content and its linked code while work is in progress. Landing a reviewed branch updates `main`, the approved content trunk. It does not put the change live.
### Inspect and create branches
```bash theme={null}
aci branch list
aci branch get campaign-refresh
aci branch create campaign-refresh --source-ref main
```
### Rebase and land
Read the branch and target state first, then pass the observed heads when you rebase or land. These checks prevent an update from silently overwriting newer work.
```bash theme={null}
aci branch rebase campaign-refresh \
--target-ref main \
--expected-head "$BRANCH_HEAD" \
--expected-target-head "$MAIN_HEAD"
aci branch land campaign-refresh \
--target-ref main \
--expected-head "$REBASED_BRANCH_HEAD" \
--expected-target-head "$CURRENT_MAIN_HEAD"
```
### Other branch operations
| Command | Use |
| ------------------------------ | ------------------------------------------------------------------------- |
| `aci branch changes NAME` | Apply an explicit multi-file JSON change set with an expected branch head |
| `aci branch patch NAME PATH` | Apply an RFC 6902 patch to one content file |
| `aci branch refresh-code NAME` | Refresh a branch's linked code and layouts from another ref |
| `aci branch delete NAME` | Close a branch when it is no longer needed |
For normal local authoring, `content pull`, file edits, `content diff`, and `content push` provide the clearest workflow. Use `changes` and `patch` for structured integrations that already manage branch concurrency.
## Build code for a branch
### `aci code-build`
Build the current Git state and link the resulting code to a non-main content branch:
```bash theme={null}
aci code-build --branch campaign-refresh
```
Run this after a component, contract, layout, or other frontend code change that the branch needs for preview. The source repository must already be connected and accessible to your ACI environment.
For a site inside a monorepo, use `--folder` if the CLI cannot infer the site directory:
```bash theme={null}
aci code-build --branch campaign-refresh --folder apps/marketing
```
## Promote approved content
Landing and publishing are separate operations:
```mermaid theme={null}
flowchart LR
A["Working branch"] -->|"review and land"| B["main: approved"]
B -->|"promote selected paths"| C["live: publishable"]
C -->|"stage and activate"| D["Active release"]
```
### `aci drift`
List paths whose approved state on `main` differs from their published state on `live`:
```bash theme={null}
aci drift
```
Use this before a promotion to see what is approved but not yet live.
### `aci promote`
Preview a path-scoped promotion:
```bash theme={null}
aci promote --path /pages/pricing/_index.json --dry-run
```
Promote one or more paths after reviewing the plan:
```bash theme={null}
aci promote \
--path /pages/pricing/_index.json \
--path /fragments/pricing-cta/_index.json \
--note "Publish approved pricing update" \
--yes
```
The CLI always evaluates the plan first. It reports conflicts and warns when the selected files were approved together with paths you did not select. `--yes` is required to apply the promotion.
## Stage and activate releases
Promotion updates the publishable content state. Release commands build that state into an immutable release, give you a preview to review, and then make the approved release live.
### `aci release publish`
Stage a release:
```bash theme={null}
aci release publish
```
The command returns the new release ID and preview URL. It also reports the currently active release and its generation; keep those values for activation.
Pass `--activate` to stage and activate in one step. Keep the steps separate when the release needs review at its preview URL before activation.
### `aci release status`
Check a staged release:
```bash theme={null}
aci release status "$RELEASE_ID"
```
### `aci release activate`
After reviewing the preview, activate the staged release with the active state returned by `release publish`:
```bash theme={null}
aci release activate "$RELEASE_ID" \
--expected-release "$CURRENT_RELEASE_ID" \
--expected-generation "$CURRENT_GENERATION"
```
On the first activation, the returned current release may be empty. Pass the value exactly as returned, including `--expected-release ""` when it is empty.
### `aci release rollback`
Switch the whole site back to a previous release:
```bash theme={null}
aci release rollback "$PREVIOUS_RELEASE_ID" \
--expected-release "$CURRENT_RELEASE_ID" \
--expected-generation "$CURRENT_GENERATION"
```
The expected release and generation protect both activation and rollback from racing with another release change. Refresh the active state and retry if either value is stale.
Use `aci promote` with an older source when you need to roll back selected content paths. Use `aci release rollback` when you need to switch the complete site to an earlier release.
## Manage asset binaries
The `dam` commands move asset binaries. Asset metadata remains part of the content tree and follows the normal branch workflow.
```bash theme={null}
aci dam upload ./hero.jpg --folder /campaigns/summer
aci dam upload-version "$ASSET_ID" ./hero-v2.jpg
aci dam download "$ASSET_ID" --out ./hero.jpg
```
Use `aci dam --help` to inspect the file and asset arguments supported by your installed CLI.
## Recommended workflows
### Local frontend change
```bash theme={null}
npm run dev
npm run content:compile
npm run typecheck
npm test
npm run build
```
### Content branch
```bash theme={null}
aci branch create campaign-refresh --source-ref main
aci content pull --branch campaign-refresh
# Edit .content files.
aci content validate
aci content diff --branch campaign-refresh
aci content push --branch campaign-refresh --dry-run
aci content push --branch campaign-refresh
```
### Approved change to production
```bash theme={null}
aci drift
aci promote --path /pages/pricing/_index.json --dry-run
aci promote --path /pages/pricing/_index.json --yes
aci release publish
# Review the returned preview URL.
aci release activate "$RELEASE_ID" \
--expected-release "$CURRENT_RELEASE_ID" \
--expected-generation "$CURRENT_GENERATION"
```
***
*Next: [Agent-ready projects →](/aci/architecture/agent-native-design)*
# Framework Guides
Source: https://docs.gradial.com/aci/developers/framework-guides
Choose and configure the supported Astro or Next.js integration for an ACI site.
Gradial ACI (Agentic Content Infrastructure) supports Astro and Next.js. Both integrations use the same content files, component contracts, layout contracts, and registry shape, so your content model stays consistent when the rendering framework changes.
## Choose a framework
| | Astro | Next.js |
| ------------------------ | ---------------------------------- | -------------------------------------------------- |
| Best starting point | New ACI sites | Sites with a Next.js requirement |
| Primary strength | Focused, content-oriented frontend | React and App Router ecosystem |
| Runtime components | Astro components | React components |
| ACI integration | `@gradial/aci/astro` | `@gradial/aci/next` and `@gradial/aci/next/config` |
| Local URL in the starter | `http://localhost:4321` | `http://localhost:3000` |
Astro is the standard choice for a new customer site. Choose Next.js when the project depends on its ecosystem or needs its framework-specific server-rendering path.
Astro and Next.js are the supported framework integrations. If you are migrating a site on another framework, work with your Gradial team to plan the frontend transition.
## Start with a generated project
The initializer creates the required routes, adapters, tests, and build configuration. This is the fastest and safest setup for either framework.
```bash Astro theme={null}
npx @gradial/aci init my-site --template astro-starter --with-starter-content
```
```bash Next.js theme={null}
npx @gradial/aci init my-site --template next-starter --with-starter-content
```
Then install dependencies and start the framework:
```bash theme={null}
cd my-site
npm install
npm run dev
```
Remove `--with-starter-content` when you want the integration, empty registries, design system, and project guidance without the sample pages and components.
## Shared project contract
Both starters use this structure:
```txt theme={null}
.aci.yaml
.content/
src/cms/contracts/components/
src/cms/contracts/layouts/
src/cms/registry.ts
src/components/
tests/
```
Contract files import framework-neutral APIs from the package root:
```ts theme={null}
import {
defineComponentContract,
defineLayoutContract,
slot,
} from '@gradial/aci';
```
Framework integration code uses explicit subpaths:
| Import | Use |
| -------------------------- | ---------------------------------------------------- |
| `@gradial/aci/astro` | Astro integration, content loading, and page helpers |
| `@gradial/aci/next` | Next.js App Router page helpers |
| `@gradial/aci/next/config` | Next.js configuration wrapper |
| `@gradial/aci/react` | Shared React bindings |
Keeping framework imports out of contract files lets ACI extract and validate the same content model independently of the runtime component implementation.
## Astro
The Astro starter configures ACI as an Astro integration and renders CMS-managed routes through a catch-all page.
### Astro site configuration
```yaml theme={null}
version: "1"
siteId: "my-astro-site"
domain: "meridian.local"
framework: astro
source:
root: "./"
outDir: "dist"
publicDir: "public"
componentRegistry: ./src/cms/contracts/components/index.ts
layoutRegistry: ./src/cms/contracts/layouts/index.ts
routes:
cmsManaged: "/[...slug]"
rendererProtocol: stdio-json
```
`rendererProtocol` is starter-managed integration configuration. Keep the generated value unless your Gradial team directs otherwise.
### Astro integration
`astro.config.mjs` includes `withAci()` alongside the rest of your Astro configuration:
```js theme={null}
import { defineConfig } from 'astro/config';
import { withAci } from '@gradial/aci/astro';
export default defineConfig({
integrations: [withAci()],
trailingSlash: 'always',
});
```
The generated configuration also preserves the output and adapter settings ACI needs when it builds a deployable code artifact. Extend that file in place instead of replacing it with the abbreviated example above.
### Catch-all page
The generated `src/pages/[...slug].astro` uses ACI's Astro helpers to:
* enumerate known routes for a static build;
* load and normalize the page for the current route;
* resolve layout slots and default fragments;
* map content blocks through `src/cms/registry.ts`; and
* handle an unknown route through the project's authored 404 page.
Keep `src/pages/404.astro` in place when you customize routing. It is part of the starter's not-found behavior.
### Register an Astro component
```ts theme={null}
// src/cms/registry.ts
import { createRegistry } from '@gradial/aci';
import { homeHeroContract } from './contracts/components/homeHero.contract';
import HomeHero from '../components/sections/HomeHero.astro';
export const registry = createRegistry([
[homeHeroContract, HomeHero],
]);
```
The Astro component can use framework features, CSS, and client islands as usual. Its contract remains a framework-neutral schema.
## Next.js
The Next.js starter connects ACI to the App Router. Use it when Next.js is already a project requirement or your application depends on its React ecosystem.
### Next.js site configuration
```yaml theme={null}
version: "1"
siteId: "my-next-site"
domain: "meridian.local"
framework: next
source:
root: "./"
componentRegistry: ./src/cms/contracts/components/index.ts
layoutRegistry: ./src/cms/contracts/layouts/index.ts
routes:
cmsManaged: "/[...slug]"
rendererProtocol: stdio-json
```
`rendererProtocol` is starter-managed integration configuration. Keep the generated value unless your Gradial team directs otherwise.
### Next.js configuration
Wrap the project configuration with `withAci()`:
```js theme={null}
// next.config.mjs
import { withAci } from '@gradial/aci/next/config';
export default withAci();
```
If your site already exports a Next.js configuration, pass it to the wrapper and retain your existing settings according to the generated starter for your SDK version.
The Next.js integration currently uses webpack. Run `next dev` and `next build` without `--turbopack`; the generated package scripts are configured correctly.
### App Router page
The generated catch-all route delegates content loading, metadata, and rendering to the ACI page helper:
```tsx theme={null}
// src/app/[[...slug]]/page.tsx
import { createPage } from '@gradial/aci/next';
import { registry } from '@/cms/registry';
const page = createPage(registry);
export const dynamic = 'force-dynamic';
export const generateMetadata = page.generateMetadata;
export default page.default;
```
Keep this route server-rendered. ACI selects the exact page experience before the framework renders it; your React components receive the selected, validated page graph.
### Register a React component
```ts theme={null}
// src/cms/registry.ts
import { createRegistry } from '@gradial/aci';
import { homeHeroContract } from './contracts/components/homeHero.contract';
import { HomeHero } from '@/components/sections/HomeHero';
export const registry = createRegistry([
[homeHeroContract, HomeHero],
]);
```
## Add ACI to an existing frontend
For an existing Astro or Next.js site, generate a clean reference project with the same framework first:
```bash theme={null}
npx @gradial/aci init aci-reference --template astro-starter
```
Use `next-starter` for Next.js. Then:
1. Install `@gradial/aci` and Zod 4 in the existing project.
2. Add `.aci.yaml` and the `src/cms/` contract and registry structure.
3. Add the framework integration and CMS-managed catch-all route from the reference project.
4. Map your existing components to new contracts in `src/cms/registry.ts`.
5. Add content under `.content/`.
6. Bring over the generated conformance tests and relevant build scripts.
7. Run the complete verification loop.
Do not copy integration files from an older project without comparing them to a starter generated by your installed SDK. The starter is the reference for that SDK's routes, build hooks, and error-page behavior.
## Development and build commands
Both starters provide the same core scripts:
```bash theme={null}
npm run dev # Compile, watch content, and start the framework
npm run content:compile # Compile .content into .aci/compiled
npm run typecheck # Check framework and TypeScript code
npm test # Run project conformance tests
npm run build # Create a production build
```
Astro also includes `npm run preview` for its local production preview. The generated package scripts carry the required ACI environment and build hooks, so prefer them over recreating the underlying commands in CI.
## Framework migration checklist
If you move between Astro and Next.js, the content and contract layer can remain unchanged. Review these framework-owned pieces:
* runtime component implementations;
* `src/cms/registry.ts` imports;
* the catch-all route;
* framework configuration and build scripts;
* error-page components; and
* framework-specific tests and deployment settings.
Run a full content compile after the new registry is in place. A successful TypeScript build alone does not prove that every authored block still has a valid runtime mapping.
***
*Next: [CLI reference →](/aci/developers/cli-reference)*
# Frontend Contract
Source: https://docs.gradial.com/aci/developers/frontend-contract
Connect ACI content to your site with configuration, typed contracts, and a framework registry.
Your frontend remains your code. Gradial ACI (Agentic Content Infrastructure) connects to it through a small, explicit contract that defines where content belongs, which props each component accepts, and which runtime component renders each block.
That boundary gives content teams flexibility without asking the CMS to understand framework internals. It also gives developers a reliable place to enforce component and layout rules.
## The contract at a glance
`.aci.yaml` identifies the framework, source directories, contract registries, and CMS-managed route.
Zod schemas define stable component IDs and the props content may supply.
Layouts define the regions a page can fill and optional fragment defaults.
The registry pairs each component contract with the Astro or React component that renders it.
## Configure the site
The `.aci.yaml` file lives at the project root. A generated Astro project starts with this shape:
```yaml theme={null}
version: "1"
siteId: "my-site"
domain: "meridian.local"
framework: astro
source:
root: "./"
outDir: "dist"
publicDir: "public"
componentRegistry: ./src/cms/contracts/components/index.ts
layoutRegistry: ./src/cms/contracts/layouts/index.ts
routes:
cmsManaged: "/[...slug]"
rendererProtocol: stdio-json
```
The generated starter owns the framework integration around this file. In most projects, you only need to change the site identity, domain, source paths, or registry paths.
| Field | Purpose |
| ------------------- | -------------------------------------------------------------------------------------------------------- |
| `siteId` | Stable identifier for the site |
| `domain` | Domain associated with the site configuration |
| `framework` | `astro` or `next` |
| `source` | Project root and framework output locations |
| `componentRegistry` | Compile-time list of component contracts |
| `layoutRegistry` | Compile-time list of layout contracts |
| `routes.cmsManaged` | Catch-all route served from ACI content |
| `rendererProtocol` | Starter-managed renderer connection; keep the generated value unless your Gradial team directs otherwise |
Keep `siteId` stable after the project is connected to an ACI site. Coordinate a change with your Gradial team so local configuration and hosted resources remain aligned.
## Define a component contract
A component contract gives a content block a stable ID and validates its props. Keep the schema in a contract file that does not import your runtime component.
```ts theme={null}
// src/cms/contracts/components/homeHero.contract.ts
import { defineComponentContract, ImageSchema } from '@gradial/aci';
import { z } from 'zod';
export const schema = z.object({
eyebrow: z.string().optional(),
headline: z.string().min(1),
description: z.string().optional(),
ctaLabel: z.string().min(1),
ctaHref: z.string().min(1),
image: ImageSchema.optional(),
});
export type ContentProps = z.infer;
export const homeHeroContract = defineComponentContract({
id: 'home_hero',
props: schema,
imageSlots: {
image: {
formats: ['image/avif', 'image/webp', 'image/jpeg'],
sizes: '100vw',
outputs: [
{
aspectRatio: '16:9',
widths: [768, 1280, 1920],
media: '(min-width: 768px)',
},
{
aspectRatio: '3:4',
widths: [480, 720, 960],
media: '(max-width: 767px)',
},
],
},
},
});
```
Use IDs that describe the component's role and keep them stable. Content documents refer to `home_hero` directly, so renaming the ID is a content migration rather than a cosmetic code change.
Export the contract from the component contract registry:
```ts theme={null}
// src/cms/contracts/components/index.ts
import { homeHeroContract } from './homeHero.contract';
const componentContracts = [homeHeroContract];
export default componentContracts;
```
## Keep contracts and runtime code separate
Contract extraction runs without loading your application runtime. That makes validation predictable across local development, preview, and publish.
| Location | May import | Avoid importing |
| ---------------------- | --------------------------------------------------------- | -------------------------------------------- |
| `src/cms/contracts/**` | `@gradial/aci`, Zod, shared schema helpers | Astro or React components, CSS, browser APIs |
| `src/components/**` | Framework code, design-system code, CSS, browser behavior | Nothing is restricted by contract extraction |
| `src/cms/registry.ts` | Contracts and runtime components | Side effects unrelated to registration |
This separation does not duplicate your prop model. Export the inferred TypeScript type from the contract and use it in the runtime component.
```astro theme={null}
---
// src/components/sections/HomeHero.astro
import type { ContentProps } from '../../cms/contracts/components/homeHero.contract';
const { eyebrow, headline, description, ctaLabel, ctaHref } = Astro.props as ContentProps;
---
{eyebrow && {eyebrow}
}
{headline}
{description && {description}
}
{ctaLabel}
```
## Register the runtime component
The runtime registry pairs each contract with its implementation:
```ts theme={null}
// src/cms/registry.ts
import { createRegistry } from '@gradial/aci';
import { homeHeroContract } from './contracts/components/homeHero.contract';
import HomeHero from '../components/sections/HomeHero.astro';
export const registry = createRegistry([
[homeHeroContract, HomeHero],
]);
```
The contract registry and runtime registry serve different jobs:
* `src/cms/contracts/components/index.ts` exposes schemas for compilation and validation.
* `src/cms/registry.ts` tells the framework which component to render after content has passed validation.
## Define a layout contract
Layouts name the regions available to a page. Mark a slot as required by passing `true` as the second argument to `slot`.
```ts theme={null}
// src/cms/contracts/layouts/index.ts
import {
defineLayoutContract,
fragmentDefault,
slot,
} from '@gradial/aci';
const layoutContracts = [
defineLayoutContract({
name: 'default',
slots: [
slot('header', false),
slot('main', true),
slot('footer', false),
],
defaults: {
header: [fragmentDefault('navbar')],
footer: [fragmentDefault('site-footer')],
},
}),
];
export default layoutContracts;
```
Here, every page must provide a `main` region. If a page does not provide `header` or `footer`, ACI uses the named fragments as defaults.
## Author content against the contract
A page names the layout, then places registered component blocks in its regions:
```json theme={null}
{
"$type": "page",
"id": "home",
"status": "published",
"layout": "default",
"metadata": {
"title": "Welcome",
"description": "The home page for our site."
},
"regions": {
"main": [
{
"$type": "component",
"id": "hero",
"component": "home_hero",
"props": {
"eyebrow": "Welcome",
"headline": "A clear path from content to experience.",
"description": "Every block is checked before it reaches your site.",
"ctaLabel": "Learn more",
"ctaHref": "/about/"
}
}
]
}
}
```
During compilation, ACI checks that:
* the layout exists;
* region names match layout slots;
* required regions are present;
* component IDs exist in the contract registry;
* props satisfy the component's Zod schema; and
* referenced fragments and assets can be resolved.
Run the same checks locally:
```bash theme={null}
npm run content:compile
npm run typecheck
npm test
```
## Evolve a contract safely
Adding an optional prop is usually backward compatible. Making a field required, narrowing allowed values, or renaming a component ID can invalidate existing content.
For a breaking change:
1. Update the contract and runtime component together.
2. Update every affected page, fragment, and overlay.
3. Compile the full content tree.
4. Run the project's type and conformance checks.
5. Preview the change before it is approved and published.
This keeps the frontend contract useful as a release boundary, not just a TypeScript convenience.
***
*Next: [Framework guides →](/aci/developers/framework-guides)*
# Quickstart
Source: https://docs.gradial.com/aci/developers/quickstart
Create an Astro site, edit typed content locally, and verify your first ACI build.
In this guide, you'll create a Gradial ACI (Agentic Content Infrastructure) Astro site with sample content, run it locally, make a safe content change, and verify the project before you commit.
Access: Must be enabled for your organization. Contact your Gradial team to get access.
## Prerequisites
* Node.js 22 or later
* npm 10 or later
* A terminal and code editor
## 1. Create the starter
Run the ACI initializer with the Astro starter and sample content:
```bash theme={null}
npx @gradial/aci init my-site --template astro-starter --with-starter-content
cd my-site
npm install
```
Astro is the standard starting point for new ACI sites. The sample content gives you working pages, contracts, components, and tests to explore.
Run `npx @gradial/aci init --list` to see the currently available starters. Use the Next.js starter when your site needs the Next.js ecosystem or its server-rendering model.
## 2. Start the site
```bash theme={null}
npm run dev
```
Open [http://localhost:4321](http://localhost:4321). The development server compiles content on startup, watches `.content/` for changes, and refreshes the browser as you work.
## 3. Tour the project
The starter keeps authored content, compile-time contracts, and runtime components in clear locations:
```txt theme={null}
.aci.yaml Site and framework configuration
.content/ Authored JSON content
config/site.json Site-wide settings
pages/**/_index.json Pages
fragments/**/_index.json Reusable content
src/cms/contracts/components/ Component IDs and Zod prop schemas
src/cms/contracts/layouts/ Layout slots and defaults
src/cms/registry.ts Contract-to-component mappings
src/components/ Runtime Astro components
src/design-system/ Design tokens and global styles
.agents/ Repository guidance for people and agents
.aci/ Generated output; do not edit directly
```
Three pieces work together:
1. A page document names a component and supplies its props.
2. A component contract validates those props.
3. The registry maps the contract to the Astro component that renders it.
## 4. Make your first content change
Open `.content/pages/home/_index.json` and find the block whose `id` is `hero`. Change its `headline` while leaving the component ID and the other props in place:
```json theme={null}
{
"$type": "component",
"id": "hero",
"component": "home_hero",
"props": {
"eyebrow": "Global satellite internet",
"headline": "Connect from anywhere on Earth — right on schedule.",
"description": "Meridian delivers low-latency broadband to homes, businesses, and remote operations in over 40 countries. No ground infrastructure required.",
"ctaLabel": "Explore plans",
"ctaHref": "/plans/",
"image": {
"$type": "dam.assetRef",
"assetId": "ast_site_home_hero",
"alt": "Light abstract hero background with satellite constellation"
}
}
}
```
Save the file and return to the browser. The development server recompiles the content and displays the update.
The stable block `id` matters. ACI uses it to address that block across edits and personalized experiences. Keep an existing ID when you are updating the same block; use a new, unique ID when you add a different block.
## 5. Run the checks
Before you commit, compile the content and run the starter's verification commands:
```bash theme={null}
npm run content:compile
npm run typecheck
npm test
npm run build
```
These commands catch malformed content, props that do not match a component contract, TypeScript errors, conformance failures, and production build problems.
`npm run dev` already compiles and watches content for local development. Run `npm run content:compile` when you want a one-time compile, such as in CI or before a separate framework command.
## How page files map to routes
Pages live under `.content/pages/`:
| Content file | Route |
| -------------------------------------------- | ------------------- |
| `.content/pages/home/_index.json` | `/` |
| `.content/pages/about/_index.json` | `/about/` |
| `.content/pages/products/widget/_index.json` | `/products/widget/` |
A page document identifies its layout and fills the layout's named regions:
```json theme={null}
{
"$type": "page",
"id": "about",
"status": "published",
"layout": "default",
"metadata": {
"title": "About us",
"description": "Learn more about our team."
},
"regions": {
"main": [
{
"$type": "component",
"id": "about-hero",
"component": "home_hero",
"props": {
"eyebrow": "About us",
"headline": "Meet the team behind the work.",
"description": "We help teams build dependable content operations.",
"ctaLabel": "Contact us",
"ctaHref": "/contact/"
}
}
]
}
}
```
The `component` value must match a registered contract ID. Its `props` must satisfy that contract's Zod schema.
## Common issues
### The CLI is not available
Install the starter dependencies first:
```bash theme={null}
npm install
npm exec -- aci --help
```
Project scripts are the preferred interface for routine local work because they use the SDK version declared by the starter.
### A content change does not appear
Check that:
* the JSON file was saved;
* the terminal running `npm run dev` has no compile error;
* the page file is under `.content/pages/`; and
* the block's `component` value matches a contract exported by the component contract registry.
If needed, stop and restart `npm run dev`, then run `npm run content:compile` to see the validation output directly.
### Content compilation fails
Read the first reported file path and field error. Common causes are invalid JSON, a missing required prop, an unknown component ID, or a region that is not declared by the selected layout.
## Next steps
Learn how configuration, contracts, runtime components, and the registry fit together.
Compare the Astro and Next.js integrations.
Work with local content, branches, promotion, and releases.
See how repository guidance helps people and coding agents follow the same workflow.
***
*Next: [Frontend contract →](/aci/developers/frontend-contract)*
# Core Concepts
Source: https://docs.gradial.com/aci/getting-started/core-concepts
The terms that define authoring, approval, personalization, and delivery in Gradial ACI.
These concepts form the working model for Gradial ACI. The most important distinction is between work in progress, approved work, content selected for publication, and the release currently serving visitors.
## Content and frontend concepts
| Concept | Meaning |
| ---------------------- | ------------------------------------------------------------------------------------------------ |
| **Page** | A route-backed content document composed from a layout and ordered component blocks |
| **Fragment** | Reusable content referenced by one or more pages or layouts |
| **Component contract** | A typed definition of the props and asset slots a component accepts |
| **Layout contract** | A typed definition of a page layout, including its regions, slots, and defaults |
| **Registry** | The project mapping that pairs contracts with their Astro or React runtime components |
| **Overlay** | A targeted change applied over base content for a dimension such as locale or audience |
| **Code build** | A versioned build of the frontend that can be linked to a branch and used for preview or release |
Content contracts stay framework-neutral. Runtime components own framework imports, styling, and rendering behavior.
## Versioning and approval concepts
| Concept | Meaning |
| ----------- | ----------------------------------------------------------------------------------------------------- |
| **Version** | An immutable saved state in ACI's content history |
| **Branch** | An isolated line of work with its own content versions |
| **`main`** | The approved content trunk. Landing a branch here records approval but does not make the content live |
| **Land** | Apply an approved branch's changes to `main` after conflicts and validation are resolved |
| **`live`** | The content trunk selected for the next site release |
| **Promote** | Move selected paths from `main` to `live` |
| **Drift** | The approved content in `main` that has not yet been promoted to `live` |
A branch is not a version, and `main` is not the live website. Those distinctions make it possible to review a series of changes together, approve them, and still control when individual paths become public.
## Compilation and delivery concepts
| Concept | Meaning |
| -------------------- | -------------------------------------------------------------------------------------------- |
| **Compilation** | Validation and preparation of content against a specific code build |
| **Release** | An immutable, deployable set of site artifacts produced from `live` content and a code build |
| **Stage** | Prepare a release alongside the release currently serving traffic |
| **Activate** | Make a staged release current |
| **Release rollback** | Return traffic to a previously staged release as a whole |
| **Preview** | A branch-specific rendering of saved content with that branch's linked code build |
A content rollback and a release rollback solve different problems. To restore an individual path, select the intended earlier content version and publish a new release. To restore the entire site state, roll back the active release.
## Personalization concepts
| Concept | Meaning |
| ------------------- | --------------------------------------------------------------------------------------- |
| **Base experience** | The default content served when no personalization applies |
| **Segment** | Membership criteria evaluated from allowed visitor signals |
| **Audience** | A targetable group used to select an experience |
| **Experience** | The content a visitor should receive for an audience or experiment arm |
| **Variant** | A compiled release artifact produced from a base experience plus its applicable overlay |
| **Experiment arm** | One of the experiences compared within an experiment |
ACI evaluates audience eligibility at request time, but it does not build personalized content at request time. Base and variant artifacts are prepared during release compilation. Unknown, unconsented, or unmatched visitors receive the base experience.
## Three boundaries to remember
They have separate histories and are paired deliberately for preview and release.
Landing moves work to `main`; promotion selects content for `live`; activation changes the site visitors receive.
ACI determines an eligible variant at the edge, then serves or renders that exact compiled artifact.
***
*Next: [Developer Quickstart →](/aci/developers/quickstart)*
# How Gradial ACI Works
Source: https://docs.gradial.com/aci/getting-started/how-aci-works
Follow an ACI change from an isolated branch through validation, approval, promotion, and release.
ACI keeps authoring, approval, and delivery separate. A team can iterate on content and code without affecting the live site, then move only approved work through a controlled release.
## The path from draft to live
```mermaid theme={null}
flowchart LR
A["Work on a branch"] --> B["Validate and preview"]
B --> C["Land on main
Access: Must be enabled for your organization. Contact your Gradial team to get access.
## What ACI provides
Pages, shared fragments, site configuration, and personalization overlays use a consistent file-based model with a reviewable history.
Component and layout contracts define which content your site accepts. ACI validates content against those contracts before release.
Branches isolate work in progress. Each branch can be previewed with its linked code before changes are approved.
Approved changes are promoted deliberately, staged as a release, and activated as one consistent site version.
ACI supports both standard site content and personalized experiences. It compiles a base experience and any configured variants before delivery. At request time, ACI selects an eligible variant at the edge and falls back to the base experience when no variant applies.
## How ACI fits into your stack
```mermaid theme={null}
flowchart LR
A["Content teams
Create and review content in branches, preview the result, and decide which approved changes should go live.
Own frontend code, design-system components, and the contracts that describe valid content.
Configure content storage and supported hosting while retaining a consistent release workflow.
The contract between content and code is especially important. When a component changes, ACI can validate affected content before the new combination is released. When content changes, developers do not need to rebuild the contract unless its shape has changed.
## Governance without a separate authoring model
ACI uses the same content model and validation path for work created through Gradial, project files, or compatible tooling. Teams do not need one set of rules for human edits and another for automated work.
Every accepted change belongs to a versioned branch. Reviewers can inspect and preview that branch before landing it. Approved content still does not become public until it is promoted and included in an activated release.
## Designed for content-heavy sites
ACI is a strong fit when your organization:
* Operates many pages, shared fragments, locales, or audience experiences
* Needs coordinated work across content, engineering, and marketing operations
* Wants changes to be reviewable before they affect the live site
* Values portable, structured content and an independently operable export
* Uses Astro or Next.js for its frontend
* Needs personalization with a defined default experience and consent-aware behavior
ACI does not replace your frontend repository or design system. It gives both a governed content layer and a release process that work with them.
***
*Next: [How Gradial ACI Works →](/aci/getting-started/how-aci-works)*
# Audiences and Segments
Source: https://docs.gradial.com/aci/personalization/audiences-and-segments
Define behavior-based and request-based targeting with clear priorities and a safe base fallback.
An **audience** names who an experience is for. A **segment** describes the first-party behavior that qualifies a visitor for that audience. For targeting that depends only on the current request, an audience can reference a request rule instead.
## Resource locations
```text theme={null}
.content/
├── audiences/{audience-id}/_index.json
├── segments/{segment-id}/_index.json
└── rules/{rule-id}/_index.json
```
Each resource ID must be one path-safe segment and match its directory name.
## Define a behavior-based segment
This segment qualifies a visitor who viewed `/pricing` at least three times in the last seven days but has not completed the demo-request goal:
```json theme={null}
{
"$type": "segment",
"props": {
"id": "high-intent",
"displayName": "High-intent visitors",
"status": "enabled",
"priority": 200,
"criteria": {
"all": [
{
"type": "event_count",
"event": "rum.page_view",
"path": "/pricing",
"minCount": 3,
"withinDays": 7
}
],
"none": [
{
"type": "event_exists",
"event": "custom.demo-request"
}
]
}
}
}
```
Criteria groups use these rules:
* every condition in `all` must match;
* at least one condition in `any` must match;
* no condition in `none` may match; and
* the segment must include at least one positive `all` or `any` condition.
### Condition types
| Type | Use it when | Required fields |
| -------------- | -------------------------------------------------- | ------------------- |
| `event_count` | An event must occur a minimum number of times | `event`, `minCount` |
| `event_exists` | At least one matching event is enough | `event` |
| `event_latest` | The latest matching event must satisfy the filters | `event` |
All three types can filter by `path`, `referrer`, scalar `properties`, an experiment and arm, or a positive `withinDays` window. A trailing `*` performs prefix matching for `path`, `referrer`, and string property values.
Use canonical event names in criteria: built-in events use namespaces such as `rum.*`; custom events use `custom.*`.
## Connect the segment to an audience
```json theme={null}
{
"$type": "audience",
"props": {
"id": "high-intent",
"displayName": "High-intent visitors",
"status": "enabled",
"priority": 200,
"membershipSource": "segment",
"segmentRef": "$ref:segments/high-intent"
}
}
```
Both resources must be enabled for the audience to participate in selection. A draft or disabled resource remains versioned but is not eligible for live delivery.
## Define a request-based audience
Request rules are useful when the current request provides everything needed for a decision, such as campaign parameters. They do not require a stored behavior history.
Create `.content/rules/enterprise-campaign/_index.json`:
```json theme={null}
{
"$type": "audience_rule",
"props": {
"id": "enterprise-campaign",
"status": "enabled",
"description": "Enterprise campaign traffic",
"expression": {
"all": [
{
"field": "utm.campaign",
"operator": "startsWith",
"value": "enterprise-"
}
]
}
}
}
```
Then reference it from an audience:
```json theme={null}
{
"$type": "audience",
"props": {
"id": "enterprise-campaign",
"displayName": "Enterprise campaign visitors",
"status": "enabled",
"priority": 100,
"membershipSource": "rule",
"ruleRef": "$ref:rules/enterprise-campaign"
}
}
```
Request rules support `query.*`, `utm.*`, `header.*`, `cookie.*`, trusted `geo.*` facts, and `referrer`. Supported operators are `equals`, `contains`, `startsWith`, and `exists`.
Header, geographic, and device facts depend on the configured hosting adapter. Confirm the available trusted facts for your deployment before using them in customer-facing targeting.
## Priority and fallback
When several audiences match the same request, the higher audience priority wins. Give overlapping audiences distinct priorities so the intended result is easy to review.
ACI uses the base experience when no audience matches or when a required fact, reference, or consented identity is unavailable. Build the base page as a complete, valid experience and test it alongside every audience variant.
## Validate a change
```bash theme={null}
npm run content:compile
npm run typecheck
npm test
```
Compilation validates criteria shapes, resource status, references, overlay targets, and each resolved variant before the change reaches a release.
***
*Next: [Experiences and Overlays →](/aci/personalization/experiences-and-overlays)*
# Collection and Consent
Source: https://docs.gradial.com/aci/personalization/collection-and-consent
Connect consent, enable first-party collection, and capture events for audiences and experiments.
ACI's browser collector captures first-party events used by behavior-based audiences, experiments, and reporting. It is served from your site at `/_aci/aci.js` and sends events to the same-origin `/collect` endpoint.
Access: Must be enabled for your organization. Contact your Gradial team to get access.
Collection requires a personalization-enabled Gradial edge binding. A standalone framework server can render the script tag, but it does not provide the hosted collector endpoint or visitor identity.
## Enable collection
Add or update the `personalization` block in `.content/config/site.json`:
```json theme={null}
{
"personalization": {
"collect": true,
"consentPreset": "c15t",
"consentCategories": "measurement,marketing"
}
}
```
ACI's Astro and Next.js integrations emit the collector tag automatically:
```html theme={null}
```
Do not add a second copy to an ACI-rendered site. If you maintain a custom renderer, emit the tag once in the document head and keep the stable `/_aci/aci.js` path.
## Choose a consent integration
ACI supports these consent presets:
| Preset | Use it when |
| ----------- | ------------------------------------------------------------------------ |
| `c15t` | Your site already exposes consent through c15t |
| `onetrust` | OneTrust is the consent authority |
| `cookiebot` | Cookiebot is the consent authority |
| `trustarc` | TrustArc is the consent authority |
| `manual` | Your application will send consent decisions through the ACI browser API |
`consentCategories` maps the categories used by your consent manager to ACI's personalization purpose. A preset connects to a consent manager already running on the page; it does not install a banner or define your policy.
### Use ACI's consent banner
If a site does not use another consent manager, select `manual` and mount the supplied banner from your layout. In Astro, place this script near the end of the document body:
```astro theme={null}
```
The component exposes ACI CSS classes so you can style the banner to match your site. Review its copy and behavior with your privacy team before deployment.
### Send consent manually
With `consentPreset: "manual"`, grant the personalization purpose after a visitor opts in:
```js theme={null}
window.aci('consent', {
p: ['personalization'],
src: 'privacy-center'
});
```
Withdraw consent with an empty purpose list:
```js theme={null}
window.aci('consent', {
p: [],
src: 'privacy-center'
});
```
If your privacy UI can run before the deferred collector loads, define a small queue first:
```html theme={null}
```
Manual consent calls are only authoritative in manual mode. For a named preset, update consent through that provider.
## Track a custom event
Use the browser API for application-driven events:
```js theme={null}
window.aci('track', 'request-demo', {
placement: 'enterprise-hero',
plan: 'enterprise'
});
```
ACI records the canonical name as `custom.request-demo`.
For markup-driven interactions, use data attributes:
```html theme={null}
Request a demo
```
Track the first time an element becomes visible with `data-aci-on="visible"`:
```html theme={null}
```
`data-aci-on` supports `click` and `visible`; `click` is the default. Attribute properties are sent as strings.
## Built-in events
The collector records supported browser events such as page views, link clicks, variation views, and web-vital measurements. Use custom events for business actions that your audience criteria or goals need to identify explicitly.
Keep event names stable and describe one observable action. Prefer `request-demo` over a UI-specific name such as `blue-button-clicked`.
## Consent and targeting behavior
Behavior-based audience membership requires the configured consent and a usable first-party identity. If either is unavailable, ACI returns the base audience experience.
Anonymous experiments can be configured to assign and measure visitors without creating a personalization profile. Supported browser privacy signals, including Global Privacy Control and Do Not Track, suppress identity-dependent processing.
ACI provides the technical controls; your organization remains responsible for selecting purposes, categories, retention, disclosure, and deletion behavior that match its policy and legal obligations.
## Export or erase an audience profile
ACI provides authenticated operations for a first-party profile identified by its ACI ID. Resolve and verify that ID through the privacy-request workflow agreed during onboarding; do not substitute an email address or another application identifier.
Use the read operation to export the profile and confirm it belongs to the intended visitor:
```bash theme={null}
export ACI_ID="the-visitor-aci-id"
curl \
"$ACI_API_URL/v1/audience/memberships/$ACI_ID" \
--header "Authorization: Bearer $ACI_API_TOKEN"
```
Use the delete operation to erase that profile and its associated personalization data:
Profile erasure through this endpoint cannot be undone. Confirm the ACI ID, authorization, and required record of approval before sending the request.
```bash theme={null}
curl --request DELETE \
"$ACI_API_URL/v1/audience/memberships/$ACI_ID" \
--header "Authorization: Bearer $ACI_API_TOKEN"
```
Export requires read permission; erasure requires write permission. Treat exported profile data as sensitive, record the request according to your organization's process, and verify the returned erasure result before closing the request.
## Verify the integration
Confirm there is exactly one `/_aci/aci.js` script and that its consent preset and categories match site configuration.
Grant and withdraw through your configured consent manager or manual integration. Confirm the UI returns to the expected state on a new page load.
Use a test interaction with `data-aci-event` or `aci('track', ...)` and confirm the page remains functional even if collection is unavailable.
After consent, use browser developer tools to confirm same-origin requests to `/collect`. A local framework server does not prove this step.
Repeat the journey without consent and confirm identity-dependent audience content is not selected.
## Troubleshooting
Confirm the site is using its personalization-enabled Gradial edge binding. The route is not supplied by an ordinary framework server.
Confirm `personalization.collect` is `true` and that your ACI layout uses the current Astro or Next.js integration. Custom renderers must emit the tag once.
Confirm `consentPreset` is `manual`. A named consent provider remains authoritative when its preset is selected.
Check consent first, then confirm the expected event reached `/collect`, the segment and audience are enabled, and the updated membership is present on a later request.
***
*Next: [Experiments and Reporting →](/aci/personalization/experiments-and-reporting)*
# Experiences and Overlays
Source: https://docs.gradial.com/aci/personalization/experiences-and-overlays
Personalize pages and fragments with focused patches to validated base content.
An ACI experience is an overlay applied to a base page, fragment, or data document. The base stays complete and publishable. The overlay contains only what changes for an audience or experiment arm.
## Audience overlay paths
```text theme={null}
.content/overlays/audience/{audience-id}/pages/{page-id}/_index.json
.content/overlays/audience/{audience-id}/fragments/{fragment-id}/_index.json
.content/overlays/audience/{audience-id}/data/{data-path}/_index.json
```
The target document must exist in the base tree, and the audience must exist and be enabled.
## Patch a component block
Suppose `.content/pages/home/_index.json` contains this base block:
```json theme={null}
{
"$type": "component",
"id": "hero",
"component": "home_hero",
"props": {
"eyebrow": "Agentic Content Infrastructure",
"headline": "Build better digital experiences.",
"description": "Validated content, delivered safely.",
"ctaLabel": "Learn more",
"ctaHref": "/platform/"
}
}
```
Create `.content/overlays/audience/enterprise/pages/home/_index.json`:
```json theme={null}
{
"$type": "page-overlay",
"metadata": {
"title": "Enterprise Content Infrastructure"
},
"regions": {
"main": {
"hero": {
"props": {
"eyebrow": "For enterprise teams",
"headline": "Governed content operations at enterprise scale."
}
}
}
}
}
```
`hero` is the base block's `id`, not its component contract name. ACI patches that block in place and retains the base description and call to action.
Keep block IDs stable and unique within a region. Renaming a base block without updating its overlays leaves those patches without a target.
## Merge behavior
| Overlay value | Result |
| ------------------------------- | --------------------------------------------------------- |
| Object | Deep-merges into the corresponding base object |
| Region object keyed by block ID | Patches matching blocks in place |
| Region array | Replaces the complete region |
| `null` | Removes that field or region from the resolved experience |
Prefer narrow field patches. Replace a full region only when the personalized experience needs a different composition and you intend to own the complete replacement.
Only remove optional fields. The resolved result must still satisfy its component and layout contracts.
## Personalize a shared fragment
Fragments use the same pattern. To personalize `.content/fragments/navigation/_index.json`, create:
```text theme={null}
.content/overlays/audience/enterprise/fragments/navigation/_index.json
```
```json theme={null}
{
"$type": "fragment-overlay",
"props": {
"utilityLabel": "Enterprise support",
"utilityHref": "/enterprise/support/"
}
}
```
Every page that references the fragment can receive the resolved audience variant without duplicating the navigation content.
## Combine locale and audience
When site configuration includes:
```json theme={null}
{
"overlayResolution": ["locale", "audience"]
}
```
ACI can apply a locale overlay, an audience overlay, and a more specific combined overlay. A combined Spanish enterprise page uses:
```text theme={null}
.content/overlays/locale/es/audience/enterprise/pages/home/_index.json
```
The combined overlay applies after the individual dimensions and only needs to express what is different from the already resolved result.
## Validate and review
```bash theme={null}
npm run content:compile
npm run typecheck
npm run build
```
Then compare the base and selected experience on an ACI preview:
```text theme={null}
/
/?aci_audience=enterprise
```
Review the full result, including metadata, shared fragments, responsive layout, links, and fallback—not only the fields changed by the overlay.
## Troubleshooting
Confirm the audience is enabled, `audience` appears in `overlayResolution`, the target page ID is correct, and the region key matches the base block's `id`.
Check whether the overlay supplies an array. Arrays replace regions; an object keyed by block ID patches selected blocks.
A `null` value removes the field. If the component contract requires it, provide a valid replacement instead.
Review the locale-only overlay, audience-only overlay, and combined overlay in that order. The combined path is most specific and applies last.
***
*Next: [Collection and Consent →](/aci/personalization/collection-and-consent)*
# Experiments and Reporting
Source: https://docs.gradial.com/aci/personalization/experiments-and-reporting
Define an A/B or A/B/n experiment, measure a goal, and promote a reviewed winner.
ACI experiments use the same compiled-variant and immutable-release model as audience experiences. The base content is the control. Each variant arm adds an overlay, and ACI selects a stable assignment before returning the response.
## Experiment resources
```text theme={null}
.content/
├── data/
│ ├── goals/{goal-id}/_index.json
│ └── experiments/{experiment-id}/_index.json
└── overlays/
└── experiment/{experiment-id}/experimentArm/{arm-id}/
└── pages/{page-id}/_index.json
```
Site configuration must include both experiment dimensions. Preserve any existing locale and audience dimensions:
```json theme={null}
{
"overlayResolution": [
"locale",
"audience",
"experiment",
"experimentArm"
]
}
```
## 1. Define the goal
Create `.content/data/goals/request-demo/_index.json`:
```json theme={null}
{
"$type": "goal",
"props": {
"id": "request-demo",
"displayName": "Demo requested",
"status": "enabled",
"eventName": "custom.request-demo"
}
}
```
The event name must match the canonical name captured by the browser collector. For example:
```html theme={null}
Request a demo
```
See [Collection and Consent](/aci/personalization/collection-and-consent) for JavaScript and markup tracking.
## 2. Define the experiment
Create `.content/data/experiments/home-hero/_index.json`:
```json theme={null}
{
"$type": "experiment",
"props": {
"id": "home-hero",
"displayName": "Homepage hero message",
"status": "draft",
"kind": "ab",
"priority": 100,
"allocationVersion": "v1",
"salt": "home-hero-v1",
"scope": {
"routes": ["home"]
},
"primaryGoalRef": "$ref:data/goals/request-demo",
"arms": [
{
"id": "control",
"displayName": "Current message",
"role": "control",
"allocationBasisPoints": 5000
},
{
"id": "outcome-led",
"displayName": "Outcome-led message",
"role": "variant",
"allocationBasisPoints": 5000
}
]
}
}
```
Key rules:
* `ab` and `abn` experiments require at least two arms and exactly one control;
* allocation uses basis points and must total `10000`;
* `scope.routes` contains ACI page IDs, not public URL paths;
* `allocationVersion` and `salt` keep randomized assignment stable; do not change them after an experiment starts; and
* higher priority resolves conflicts when experiment scopes overlap.
The `xt` kind supports rule-based experience testing. Use it when arms have explicit request rules instead of randomized allocation.
## 3. Add a variant overlay
The control uses the base page. Create an overlay only for the variant at `.content/overlays/experiment/home-hero/experimentArm/outcome-led/pages/home/_index.json`:
```json theme={null}
{
"$type": "page-overlay",
"regions": {
"main": {
"hero": {
"props": {
"headline": "Move approved content from idea to production.",
"description": "Build, review, personalize, and publish through one governed workflow."
}
}
}
}
}
```
The resolved arm must satisfy the same component contracts as the control.
## 4. Compile and preview both arms
```bash theme={null}
npm run content:compile
npm run typecheck
npm test
npm run build
```
Push the draft to a branch, then use explicit dimensions on the ACI preview surface:
```text theme={null}
/?aci_experiment=home-hero&aci_experimentArm=control
/?aci_experiment=home-hero&aci_experimentArm=outcome-led
```
These selectors are preview controls. Live traffic follows the experiment definition and assignment policy.
Review content, metadata, links, responsive layout, consent behavior, and the goal interaction on both arms before landing the branch.
## 5. Start the experiment
After the experiment and goal are approved on `main`, use the experiment API to transition the draft to `running`. Start with a dry run:
```bash theme={null}
curl --request POST \
"$ACI_API_URL/v1/experiments/home-hero/status" \
--header "Authorization: Bearer $ACI_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"status": "running",
"operationId": "start-home-hero-v1",
"dryRun": true
}'
```
Repeat with `"dryRun": false` after reviewing the response. Then promote the experiment, goal, and overlay paths required for the run to `live`. Stage a release, review it, and activate it.
The supported operational transitions are:
```text theme={null}
draft → running
running → paused
paused → running
```
Use a new operation ID for a new action. Reuse the same operation ID only when retrying that action.
## 6. Read the experiment report
```bash theme={null}
curl \
"$ACI_API_URL/v1/reports/experiments/home-hero" \
--header "Authorization: Bearer $ACI_API_TOKEN"
```
The report groups exposure and conversion results by arm and includes the primary-goal statistics used for winner evaluation. Interpret a result only after checking:
* exposure volume and data quality;
* whether the sample is sufficient;
* the control and variant conversion rates;
* confidence information for the primary goal; and
* whether consent or collection changes affected the measurement window.
Secondary goals are useful context, but choose and review the primary goal before starting the experiment.
## 7. Pause or promote
Pause through the status endpoint when traffic should stop entering the experiment. Existing release history remains available for investigation.
When an arm has been approved as the winner, dry-run winner promotion:
```bash theme={null}
curl --request POST \
"$ACI_API_URL/v1/experiments/home-hero/promote-winner" \
--header "Authorization: Bearer $ACI_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"armId": "outcome-led",
"operationId": "promote-home-hero-outcome-led",
"dryRun": true,
"note": "Approved after experiment review"
}'
```
The dry run lists the base content that will change and the experiment overlays that will be removed. Repeat with `"dryRun": false` only after that plan is correct.
Winner promotion requires write, promote, and publish permissions. It merges the selected arm into the base content, marks the experiment promoted, advances the affected paths to `live`, and publishes the resulting release as one operation.
Winner promotion changes live content. Record the active release before the operation and complete the same post-publish checks you use for a normal release.
## Common problems
Confirm there is exactly one control, at least one variant, and all `allocationBasisPoints` values total `10000`.
Confirm the overlay path contains the exact experiment and arm IDs, and that its block IDs exist in the base page. A control arm normally has no overlay.
Confirm its scoped page or fragment exists, every arm compiles, the goal resolves, and both experiment dimensions appear in `overlayResolution`.
Confirm the goal's canonical event name matches collection, the interaction occurs after assignment, and the relevant consent and collection path is working.
***
*Next: [Preview, Publish, and Roll Back →](/aci/personalization/preview-publish-and-rollback)*
# Preview, Publish, and Roll Back
Source: https://docs.gradial.com/aci/personalization/preview-publish-and-rollback
Validate every personalized outcome, promote approved paths, activate a release, and recover safely.
Personalization follows the same branch, promotion, and immutable-release workflow as other ACI content. The additional requirement is a decision matrix: review the base experience and every targeted outcome before activation.
## What each environment proves
| Environment | What it proves |
| -------------------------- | ------------------------------------------------------------------------------------------------ |
| **Local compile** | Resource shapes, references, overlay merges, contracts, and compiled variants |
| **Local framework server** | Base rendering, component behavior, and responsive layout |
| **Branch preview** | Branch content with its linked code, plus explicit variant selection; collection is disabled |
| **Staged release preview** | The exact immutable release intended for activation |
| **Active site** | Production delivery, consent, identity, collection, and natural audience or experiment selection |
A successful local render does not prove request-time selection or collection. Complete those checks on the appropriate ACI preview and active-site surfaces.
## 1. Run local validation
```bash theme={null}
npm run content:compile
npm run typecheck
npm test
npm run build
```
Fix every compilation error before pushing. ACI validates the complete resolved variant, so a small overlay can reveal a missing required prop or reference in the final experience.
## 2. Dry-run the branch update
Use the credentials and API URL supplied for your site:
```bash theme={null}
npm exec -- aci branch create personalization-enterprise \
--source-ref main
npm exec -- aci content push \
--branch personalization-enterprise \
--dry-run
```
Review every path in the plan, then push:
```bash theme={null}
npm exec -- aci content push \
--branch personalization-enterprise
```
Site configuration at `/config/site.json` is code-owned and is not overwritten by `content push`. If the change adds an overlay dimension or collection setting, include it in the linked code build and confirm the remote site configuration before publishing.
## 3. Review the branch preview
For an audience experience, compare at least:
```text theme={null}
/
/?aci_audience=enterprise
```
For an experiment, select both dimensions:
```text theme={null}
/?aci_experiment=home-hero&aci_experimentArm=control
/?aci_experiment=home-hero&aci_experimentArm=outcome-led
```
Explicit `aci_*` dimensions are authoring-preview controls. They select an existing compiled variant without changing production targeting.
Branch preview disables visitor collection, which keeps author review traffic out of measurement. Verify the collector separately on an edge-backed active environment.
For each outcome, review:
* page and shared-fragment content;
* metadata, canonical URL, and structured data;
* navigation and calls to action;
* mobile and desktop layout;
* base fallback when no selector is present; and
* any locale and audience combinations in scope.
## 4. Land the approved branch
Read the current branch and target state, then land with the observed heads. The expected-head check prevents the land from silently overwriting newer work on either side:
```bash theme={null}
npm exec -- aci branch land personalization-enterprise \
--target-ref main \
--expected-head "$BRANCH_HEAD" \
--expected-target-head "$MAIN_HEAD"
```
Landing moves the approved change to `main`. It does not put the change on the live site.
If the branch is behind `main`, rebase it, resolve any path conflicts, rerun the checks, and review the updated preview before landing.
## 5. Promote approved paths to `live`
Use `aci drift` to see approved changes that are not yet live:
```bash theme={null}
npm exec -- aci drift
```
Promote the audience, segment, and overlay as one reviewed set:
```bash theme={null}
npm exec -- aci promote \
--path /segments/high-intent/_index.json \
--path /audiences/high-intent/_index.json \
--path /overlays/audience/high-intent/pages/home/_index.json \
--note "Publish high-intent homepage experience" \
--yes
```
`aci promote` always validates and prints a dry-run plan first. Without `--yes`, it stops after that plan. Review co-change warnings before continuing so related paths do not get separated accidentally.
## 6. Stage the release
```bash theme={null}
npm exec -- aci release publish
```
Keep these values from the output:
```text theme={null}
releaseId:
previewUrl:
currentReleaseId:
currentActiveGeneration:
```
Open the staged preview and repeat the complete decision matrix. Do not use `release publish --activate` when you need a separate review gate.
## 7. Activate with the observed state
Activation requires the active release and generation observed when the new release was staged:
```bash theme={null}
npm exec -- aci release activate \
--expected-release \
--expected-generation
```
For a site's first activation, pass an empty expected release:
```bash theme={null}
npm exec -- aci release activate \
--expected-release "" \
--expected-generation 0
```
If the active state changed during review, activation stops. Inspect the newer release, then restage or retry with newly observed values rather than overwriting someone else's activation.
## 8. Verify live behavior
Immediately after activation:
1. open the base route without preview selectors;
2. exercise each natural request rule in scope;
3. verify consented behavior-based targeting with a test identity;
4. confirm the collector and goal event on an active edge-backed page; and
5. confirm unrelated routes still use the expected active release.
## 9. Roll back if verification fails
Rollback selects a previously staged immutable release without rebuilding it:
```bash theme={null}
npm exec -- aci release rollback \
--expected-release \
--expected-generation
```
Use the active release and generation observed by your ACI workflow. These values protect rollback from replacing a newer activation. After rollback, verify the live base page and the targeting paths that triggered recovery. The replaced release remains available for investigation and correction.
Release rollback restores the whole previous release. To reverse selected content paths while keeping other approved work, promote an older revision of those paths to `live`, then publish a new release.
## Review checklist
* [ ] Content compile, typecheck, tests, and build passed
* [ ] Base experience passed
* [ ] Every audience and experiment arm passed
* [ ] Missing-signal and no-consent fallbacks passed
* [ ] Locale combinations and shared fragments passed
* [ ] Branch preview contained no unexpected paths
* [ ] Promoted paths and co-change warnings were reviewed
* [ ] Staged release passed before activation
* [ ] Active release and generation were recorded
* [ ] Live targeting and collection passed after activation
* [ ] Previous release ID is available for rollback
***
*Next: [Content Versioning →](/aci/architecture/content-versioning)*
# Personalization Quickstart
Source: https://docs.gradial.com/aci/personalization/quickstart
Run the ACI starter, understand its behavior-based audience, and prepare a personalized experience for preview.
This guide gives you a working personalization path: a visitor records a preference, ACI evaluates that consented event, and a later request can receive the matching compiled experience. Visitors without a matching membership continue to receive the base page.
Access: Must be enabled for your organization. Contact your Gradial team to get access.
## Prerequisites
* Node.js 22 or newer
* npm 10 or newer
* A personalization-enabled ACI site for hosted preview
Local development does not require an ACI account. It verifies content, contracts, overlays, and rendering. Hosted preview is required to verify consented identity and request-time selection.
## 1. Create the starter site
Astro is the shortest path to a new ACI project:
```bash theme={null}
npx @gradial/aci init my-site \
--template astro-starter \
--with-starter-content
cd my-site
npm install
npm run dev
```
Open the local URL printed by Astro. The starter compiles `.content/` on startup and refreshes the page when content changes.
## 2. Find the personalization resources
The starter includes one complete example:
```text theme={null}
.content/
├── audiences/
│ └── preference-blue/_index.json
├── segments/
│ └── preference-blue/_index.json
├── overlays/
│ └── audience/preference-blue/pages/home/_index.json
├── pages/home/_index.json
└── config/site.json
```
The base homepage contains a component block with a stable ID:
```json theme={null}
{
"$type": "component",
"id": "personalization-choice",
"component": "personalization_choice",
"props": {
"title": "Choose your connection preference",
"description": "Select a preference, allow the update to process, then refresh personalization.",
"redLabel": "Choose Red",
"blueLabel": "Choose Blue",
"refreshLabel": "Refresh personalization"
}
}
```
The rendered buttons record a custom event without application-specific analytics code:
```html theme={null}
Choose Blue
```
ACI normalizes that event to `custom.preference`.
## 3. Understand the segment
`.content/segments/preference-blue/_index.json` defines the behavior that qualifies:
```json theme={null}
{
"$type": "segment",
"props": {
"id": "preference-blue",
"displayName": "Latest preference is Blue",
"status": "enabled",
"priority": 100,
"criteria": {
"all": [
{
"type": "event_latest",
"event": "custom.preference",
"properties": {
"color": "blue"
}
}
]
}
}
}
```
`event_latest` evaluates the most recent event with that name. Here, the `color` property must be `blue`.
## 4. Connect the segment to an audience
`.content/audiences/preference-blue/_index.json` gives that membership a stable target:
```json theme={null}
{
"$type": "audience",
"props": {
"id": "preference-blue",
"displayName": "Blue preference",
"status": "enabled",
"priority": 100,
"membershipSource": "segment",
"segmentRef": "$ref:segments/preference-blue"
}
}
```
The segment decides membership. The audience decides which experience can be selected. Keeping them separate lets you reuse targeting logic across content.
## 5. Inspect the experience overlay
`.content/overlays/audience/preference-blue/pages/home/_index.json` patches the base block by its ID:
```json theme={null}
{
"$type": "page-overlay",
"regions": {
"main": {
"personalization-choice": {
"props": {
"title": "Blue preference active",
"description": "Your latest preference is Blue. Choose Red to replace it."
}
}
}
}
}
```
Only the two changed fields appear in the overlay. ACI retains the remaining props from the base component and validates the resolved experience against the same contract.
## 6. Confirm site configuration
The starter's `.content/config/site.json` includes the audience dimension and enables collection:
```json theme={null}
{
"overlayResolution": ["locale", "audience"],
"personalization": {
"collect": true,
"consentPreset": "c15t",
"consentCategories": "measurement,marketing"
}
}
```
The preset connects to an existing consent manager; it does not define your privacy policy. See [Collection and Consent](/aci/personalization/collection-and-consent) before using real traffic.
## 7. Run the local gates
```bash theme={null}
npm run content:compile
npm run typecheck
npm test
npm run build
```
A successful compile proves that the segment, audience reference, overlay, base page, and component contract resolve together. A successful local render does not prove hosted identity or edge selection.
## 8. Preview the selected experience
Push the reviewed content to an ACI branch, then open the branch preview supplied for your site:
```bash theme={null}
npm exec -- aci branch create personalization-preference \
--source-ref main
npm exec -- aci content push \
--branch personalization-preference \
--dry-run
npm exec -- aci content push \
--branch personalization-preference
```
On the ACI preview surface, compare:
```text theme={null}
/
/?aci_audience=preference-blue
```
The first request must show the base experience. The second explicitly selects the compiled audience variant for preview. The `aci_audience` selector is a preview control; production selection follows authored targeting and consented membership.
When both paths are correct, continue with [Preview, Publish, and Roll Back](/aci/personalization/preview-publish-and-rollback).
***
*Next: [Audiences and Segments →](/aci/personalization/audiences-and-segments)*
# Data Ownership and Portability
Source: https://docs.gradial.com/aci/platform/customer-owned-data
How ACI keeps versioned content portable across managed and direct storage modes.
ACI records content in a versioned ledger with a portable object-storage format. This gives your organization an independently operable copy of its content history without requiring the managed authoring service to use object storage as its live coordination layer.
## Storage modes
| Mode | How it works | Object-storage role |
| ------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Gradial-managed** | A tenant-isolated operational ledger supports concurrent authoring, validation, permissions, and search. | Immutable history is exported in ACI's portable ledger format to the storage configured for your deployment. |
| **Direct object storage** | The ACI engine reads and writes the portable ledger directly. | Object storage is the active content repository under a single-writer workflow. |
Do not write to the same repository through managed and direct modes at the same time. Coordinate a mode change with your Gradial team to avoid divergent histories.
## What the portable ledger provides
The portable ledger contains the versioned content state and history required to reconstruct a selected revision. It uses canonical, machine-readable objects protected by content hashes.
Use supported ACI export, import, and direct-engine tooling to inspect or operate the ledger. Do not edit storage objects by hand; changing an object outside ACI can break the integrity relationships that make the history verifiable.
The portable format supports:
* independently validating exported content;
* reconstructing branches and historical revisions;
* importing the ledger into a compatible ACI deployment; and
* operating through the direct engine when a repository has been moved to direct mode.
## Managed-service data
The Gradial-managed service stores the operational ledger and supporting data needed for concurrent workflows. It can also maintain rebuildable views for validation, search, permissions, and publishing.
In managed mode, Gradial processes and stores the tenant-isolated data required to provide the service while maintaining the configured portable export.
## Deployment-specific controls
Storage ownership and cloud topology vary by deployment. During onboarding, confirm:
* where the managed ledger and portable export are stored;
* which cloud account and region apply to each store;
* encryption and key-management responsibilities;
* retention, backup, and deletion settings;
* the permissions granted to Gradial; and
* how export health and recovery are verified.
A customer-owned bucket does not necessarily make every ACI service, database, or delivery resource customer-owned. Use the architecture agreed for your deployment as the source of truth.
## Recovery planning
A recovery plan should identify the revision you expect to recover and confirm that it is present in the portable export. A typical handoff includes:
1. verify the export through supported ACI tooling;
2. stop managed writes;
3. switch the repository to direct mode;
4. designate a single writer;
5. validate the recovered content and references; and
6. publish through a supported hosting adapter.
Contact your Gradial team before beginning this process so the final managed revision and direct repository start from the same state.
Data ownership and storage location do not by themselves establish compliance with a regulation or standard. Evaluate storage, access, consent, retention, and deletion controls against your organization's requirements.
***
*Back to [What is Gradial ACI?](/aci/getting-started/what-is-gradial-aci)*
# Hosting and Delivery
Source: https://docs.gradial.com/aci/platform/hosting
How ACI stages immutable releases for CloudFront, Vercel, and local development.
ACI separates content authoring and release management from the infrastructure that serves your site. A hosting adapter stages each immutable release, exposes a preview, and activates the reviewed release on your delivery platform.
## Supported delivery targets
| Target | Best fit | Release output |
| ------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **AWS CloudFront** | Static sites delivered through AWS | Complete HTML and assets, with request-time selection among compiled variants when personalization is enabled |
| **Vercel** | Next.js applications that need supported SSR delivery | Static HTML or a compiled page graph selected before the application renders it |
| **Local** | Development and release smoke tests | The same release model on a local filesystem and server |
Access: Must be enabled for your organization. Contact your Gradial team to get access.
## One release contract
The delivery target changes the final output format, not the workflow:
1. ACI compiles the approved content and linked code version.
2. The adapter stages a complete, immutable release.
3. Your team reviews the release at its preview URL.
4. Activation makes that release current.
5. Rollback selects a previously staged release.
```mermaid theme={null}
flowchart LR
A["Approved live content"] --> B["Compile release"]
B --> C["Hosting adapter"]
C --> D["Staged preview"]
D --> E["Activate"]
E --> F["Customer traffic"]
```
## Static and SSR delivery
ACI produces complete HTML for each route and eligible variant. The hosting adapter deploys those artifacts and the routing metadata required to select them.
For supported Next.js configurations, ACI produces a normalized page graph for each eligible variant. The delivery layer selects the exact graph first, then the application renders it. Your page code does not implement audience resolution or content fallback.
Both modes use the same component contracts, content validation, preview, activation, and rollback lifecycle.
## Personalization boundary
Personalization and first-party collection require a Gradial edge binding for the selected hosting target. The binding serves the ACI browser collector, applies the active release's decision rules, and selects a compiled artifact before the response is returned.
Do not add audience-selection logic to application components. That would create a second decision path that can disagree with preview and release validation.
## Operational responsibilities
Your deployment configuration determines the cloud account, domain, certificates, and provider-level controls used by the adapter. Gradial manages the ACI release workflow and the integration required to stage and activate artifacts.
During onboarding, confirm:
* the target and delivery mode;
* the production and preview domains;
* the code build connected to the site;
* the permissions required by the adapter; and
* whether personalization and collection are enabled.
See [Publishing and Releases](/aci/architecture/publishing-and-releases) for the complete workflow.
***
*Next: [Data Ownership and Portability →](/aci/platform/customer-owned-data)*
# Asset Operations
Source: https://docs.gradial.com/docs/asset-management/asset-operations
Step-by-step reference for uploading assets, updating alt-text, managing metadata, and swapping assets in your DAM using Gradial.
Gradial's asset operations handle the repetitive DAM tasks that slow down content production — uploads, alt-text, metadata updates, and asset swaps — applying your naming conventions, taxonomy, and metadata standards automatically.
***
## Upload Asset
Upload images, PDFs, and other assets to your DAM with automatic metadata enrichment.
### How it works
1. **Create a task** describing what you want to upload and any relevant context (campaign, brand, usage).
2. **Attach your assets** to the task request.
3. **Gradial processes the upload** — assets are uploaded, naming conventions applied and metadata populated, then validated against your guidelines before anything is finalized.
4. **Review the results** in the Artifact Preview panel.
### What Gradial does automatically
| Action | Description |
| ------------------------------ | ------------------------------------------------------------------------------------------------------ |
| **Applies naming conventions** | Renames files to match your DAM standards (e.g., `Coca-Cola-Global-HolidaySanta-2025`) |
| **Generates descriptions** | Creates searchable descriptions based on image content |
| **Tags from your taxonomy** | Applies relevant tags from your controlled vocabulary — brand, campaign, season, asset type, geography |
| **Detects duplicates** | Identifies if an asset already exists and marks it as "Reused from DAM" instead of creating duplicates |
| **Sets DAM location** | Places assets in the correct folder path based on brand and campaign |
### Asset status badges
In the Artifact Preview, each asset displays a status badge:
* **Newly Uploaded** — Asset was added to the DAM for the first time
* **Reused from DAM** — Asset already existed; Gradial linked to the existing version instead of duplicating
### Viewing asset details
Click any asset in the Artifact Preview to see file information, auto-generated description, applied tags, DAM folder path, created date, and a direct link to open the asset in your DAM.
### Example
> "Upload these holiday assets for our Holiday campaign 2025"
Gradial uploads with proper naming (e.g., `Brand-Global-HolidayHero-2025`), generates descriptions from image content, and applies 10–15 taxonomy tags including brand, campaign, season, theme, asset type, and geography.
***
## Update / Validate Alt-Text
Ensure your image assets have accurate, accessibility-compliant alt-text.
### How it works
1. **Create a task** requesting alt-text validation or generation for specific assets or folders.
2. **Gradial scans the assets** to identify missing or inadequate alt-text.
3. **Alt-text is generated** following accessibility best practices.
4. **Review and approve** the generated alt-text before it's applied.
### Alt-text standards
Gradial generates alt-text that:
* Describes the content and function of the image
* Stays concise (under 125 characters when possible)
* Avoids redundant phrases like "image of" or "picture showing"
* Includes visible text and brand elements
* Distinguishes informative images from decorative ones
**Example output:**
> "Product bottle held against red background with seasonal decorations; Holiday Campaign 2025 key visual."
***
## Update Asset Metadata
Keep your DAM metadata accurate and consistent with bulk updates and automated governance.
### How it works
1. **Create a task** describing the metadata changes needed.
2. **Specify the scope** — individual assets, folders, or assets matching certain criteria.
3. **Gradial updates the metadata** according to your request and taxonomy.
4. **Review changes** in the task results.
### Common use cases
* **Campaign ended** — Update campaign status metadata across all related assets
* **Taxonomy change** — Replace old terms with new controlled vocabulary
* **Rights expiration** — Flag or archive assets approaching license expiration
* **Missing fields** — Populate required metadata fields left blank on ingestion
* **Bulk corrections** — Fix inconsistent tagging across a set of assets
Gradial can update any metadata field in your DAM schema: title, description, keywords, tags, brand and campaign associations, usage rights and licensing, geographic and language targeting, asset type, and custom fields.
***
## Asset Swap
Replace an existing asset with a new version while preserving all DAM links, metadata relationships, and downstream references.
### How it works
1. **Create a task** identifying the asset to replace and providing the new asset.
2. **Gradial validates** that the new asset meets specifications.
3. **The swap is executed** — DAM link/Asset ID preserved, metadata reviewed and updated, alt-text regenerated for the new image.
4. **Downstream systems** receive the updated asset automatically.
### Swap options
**Upload New File** — Attach the replacement asset directly to your task. Gradial uploads it as a new version of the existing asset.
**Link to Existing DAM Asset** — Reference another asset already in your DAM. Gradial creates a redirect from the old Asset ID to the new one.
### What Gradial handles
| Aspect | How it's managed |
| ------------------- | ------------------------------------------ |
| **DAM link** | Preserved — existing URLs continue to work |
| **Alt-text** | Regenerated for the new image content |
| **Metadata** | Carried forward with option to update |
| **Relationships** | Updated across linked/derivative assets |
| **Version history** | Previous version retained for rollback |
After a swap, Gradial confirms the new asset renders correctly, alt-text is present and accurate, metadata is complete, and the asset is accessible via its original DAM link.
***
## Asset Search
For finding and acting on assets at scale — building brand-matched campaign matrices and detecting visual duplicates — see [Asset Search](/docs/asset-management/asset-search).
***
## Tips for best results
**Be specific in your task requests.** Include campaign names, brand guidelines, and any special requirements so Gradial can apply the right metadata.
**Use consistent terminology.** Reference campaigns, brands, and asset types using the same terms defined in your taxonomy.
**Review before publishing.** Always review generated metadata and alt-text before final approval.
**Check for duplicates.** Watch for the "Reused from DAM" badge — it means Gradial found an existing match and avoided creating a duplicate.
**Review in bulk, not one at a time.** When an operation spans a large delivery, ask Grady for a [custom app](/docs/insights/custom-apps) — an image QA dashboard showing what passed, what failed, and what's missing alt text across the whole batch is far faster than opening assets individually.
***
*For how Gradial governs asset quality and rights exposure, see [Digital Asset Management](/docs/asset-management/digital-asset-management).*
# Asset Search
Source: https://docs.gradial.com/docs/asset-management/asset-search
Index your DAM and use Gradial to build brand-matched campaign Asset Packs and detect visual duplicates across your entire asset library.
## Why This Matters
Every enterprise DAM has the same two problems. The first: you know the right asset exists, but the metadata is inconsistent enough that you can't find it — so you either spend twenty minutes searching or you use something else. The second: the library has quietly accumulated near-duplicates of the same image at different crops, from different shoots, with different rights status, and nobody can tell which one is approved.
Both problems get worse with scale, and both are why campaign teams end up requesting new assets that already exist.
Asset Search indexes your DAM so Gradial can retrieve, match, and act on assets at scale — by what an asset actually is, not just what someone typed in a field.
***
Asset Search indexes your connected DAM so Gradial can retrieve, match, and act on assets at scale. Once indexed, you can build full campaign matrices populated from your own assets and clean up duplicate content across your library.
Asset Search needs your DAM indexed before the steps on this page will return results. Your Gradial team configures and runs the initial index.
***
## What You Can Do
### Brand-Matched Asset Packs
Drop in a campaign brief, pick your audiences, and Gradial fills the full audience × treatment × channel matrix with imagery pulled from your indexed DAM. Different audiences get different visuals, and every cell stays on brand.
> "Build a campaign matrix for our Q3 product launch targeting enterprise and SMB audiences."
***
### Visual Duplicate Detection
Gradial groups every visual duplicate and near-duplicate in your DAM into a single cluster — including re-exports, re-crops, and color edits that a file-hash check would miss. Pick a canonical version and Gradial replaces stale variants across every site that references them.
***
### Structured, Actionable Results
Every search returns asset paths, titles, and asset IDs the agent can act on directly — not just a list to triage manually.
***
### Visual Workflow Mapping
A live graph shows every task in flight, every matrix cell or cluster completed, and anything stuck upstream.
***
### Human-in-the-Loop Approvals
Workflows pause at QA checkpoints. Nothing ships, replaces, or activates until brand and compliance sign off.
***
## How It Works
Your Gradial team sets up and runs indexing jobs over your connected asset libraries. Asset Search results are only available after indexing is complete.
Choose to build an Asset Pack from a brief, or open the duplicate cluster view to audit and clean up your library.
Describe what you want done. Gradial plans the fan-out and shows matched assets, matrix cells, or duplicate clusters before acting.
Review Asset Pack cells or replacement plans. Promote to live when you're ready.
***
## Getting Started
1. **Connect your DAM.** Add your AEM asset library from the integrations page if you haven't already — see [AEM setup](/docs/integrations-administration-and-setup/integrations/aem/aem-overview).
2. **Contact your Gradial team** to schedule indexing for your connected DAM.
3. **Build your first Asset Pack or run a duplicate audit.** Once indexing is complete, describe the task in Gradial Chat.
***
*Also need to find and update content across your site pages? See [Site Search & Find-and-Replace](/docs/updating-existing-experiences-i-e-content-updates/site-search) for site-wide content operations.*
***
## Who this is for
| Role | What Gradial handles |
| :------------------------------------ | :-------------------------------------------------------------------------------------------------------- |
| **Campaign Manager** | A populated campaign matrix built from approved assets, instead of a request to the creative team |
| **DAM Librarian / Asset Manager** | Visual duplicates surfaced across the library, and a searchable index that survives inconsistent metadata |
| **Creative Director / Brand Manager** | Brand-matched selections rather than whatever came up in a keyword search |
| **Web Producer** | The right approved asset found in seconds, with rights status confirmed before it's placed |
| **Regional / Local Marketer** | Finding what already exists for your market before commissioning something new |
***
## Availability
**Access:** Must be enabled for your organization, and your DAM must be indexed before you can search it. Contact your Gradial team to get access.
# Digital Asset Management
Source: https://docs.gradial.com/docs/asset-management/digital-asset-management
How Gradial handles asset governance at scale across every connected DAM — schema-aware tagging, workflow context, rights enforcement, and retrieval for every other job.
## The DAM Librarian
A DAM Librarian's job is to make sure the right assets are findable, correctly described, properly governed, and reliably available to everyone who needs them — across campaigns, regions, brands, and teams.
In practice that means ingesting and tagging thousands of assets from campaign shoots and agency deliveries, maintaining a metadata schema against a controlled vocabulary, managing rights records and expiry dates, auditing for duplicates, and ensuring that content and personalization teams can actually find and use what they need. A major campaign shoot can produce 600 assets. An agency delivery might arrive with inconsistent naming, missing metadata, and no campaign tags.
Gradial is built for that pace — and for that job.
***
## What generic AI tagging misses
Most enterprise DAMs now have built-in AI tagging — objects, scenes, colors, settings. These are useful for describing what's visually in an image. But the metadata that matters most for governance — campaign name, product association, regional restrictions, rights status, approval state, embargo date — is not visible in the image. It lives in the brief, the job ticket, and the rights contract.
Generic AI tags what it can see. Gradial tags what actually governs the asset.
***
## How Gradial handles it
**Schema-aware tagging.** Gradial is configured against your actual DAM metadata schema. Tags land in the right fields with the right controlled vocabulary values — not in a free-text pile that requires remediation. Assets come into the DAM correctly structured from day one.
**Workflow-context tagging.** When assets are produced as part of a campaign managed in Workfront, Jira, or Wrike, the job ticket holds the governance metadata: campaign name and ID, product line, market, go-live date, and rights summary. Gradial reads that ticket and carries its context forward into DAM metadata automatically. Campaign and rights data travels with the asset from the moment of ingestion.
**Rights and expiry governance.** Expired or rights-restricted assets being published carries real legal and financial exposure. Gradial's QA capabilities surface assets in the CMS that are flagged as expired or rights-restricted in the DAM — catching non-compliant assets before they go live. On the ingestion side, rights metadata is captured at the point the asset enters the system.
**Bulk ingestion and remediation.** A major campaign delivery shouldn't require a week of manual data entry. Gradial handles bulk ingestion jobs — reading a batch of incoming assets, applying schema-aware tags, pulling workflow context, and populating required fields — so the librarian reviews exceptions rather than starting from scratch on every asset. The same applies to remediation: existing DAM libraries with incomplete metadata can be processed at scale.
**Retrieval for every other job.** Asset work doesn't only happen when assets arrive. When another job needs an asset — a new page being built, a campaign email being assembled, a regional variant being localized — Gradial retrieves it: searching by the criteria that matter, confirming rights status, and handing the correct asset to the task. Assets that are correctly tagged are also correctly retrievable when needed.
***
## Where Gradial does this
Asset work is native in each of the systems below — Gradial reads and writes them directly, using each platform's own metadata schema and controlled vocabularies.
| System | What Gradial does there |
| :----------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
| **AEM Assets** | Full asset lifecycle — upload, folders, metadata, alt text, renditions, moves, publishing, and rights checks against content in the CMS |
| **Sitecore Content Hub** | Asset search and discovery, entity and taxonomy tagging, uploads, and campaign asset association |
| **Bynder** | Assets, metadata, collections, uploads, transformations, usage, automations, and tags |
| **Aprimo** | Upload of Gradial-created assets and artifacts into the configured destination, with record verification |
| **Box** | Browse, search, read, download, create folders, and upload — scoped to the folders a Box admin shares, and never able to delete |
| **SharePoint** | Browse sites and libraries, read file metadata and managed-metadata tags, search, download, create folders, and upload |
| **Google Drive** | Browse, search, read, download, create folders, and upload |
| **Gradial ACI** | Content-addressed binaries managed alongside versioned content, in your own storage |
Availability varies by plan, and not every system is enabled for every organization by default. Your Gradial team can confirm what's available to you.
Semantic **Asset Search** — one searchable index with visual duplicate detection and brand-matched Asset Packs — currently indexes AEM Assets, Gradial ACI, Google Drive, and assets uploaded directly to Gradial. Every other system above is searched through its own connection. See [Asset Search](/docs/asset-management/asset-search).
***
## Roles this supports
| Role | What Gradial handles |
| :---------------------------------- | :------------------------------------------------------------------------------------------------------------------------- |
| **DAM Librarian / Asset Manager** | Bulk ingestion, schema-aware tagging, taxonomy maintenance, duplicate detection, exception review instead of data entry |
| **Brand / Rights Manager** | Rights and expiry metadata captured at ingestion, and flagged in the CMS before anything goes live |
| **Content Producer / Web Producer** | Finding the right approved asset without a request to another team, and swapping assets while links and relationships hold |
| **Campaign Manager** | Campaign and product metadata carried over from the job ticket, so assets arrive already associated with the campaign |
| **Accessibility Lead** | Alt text generated and validated at scale across the library |
| **Creative / Agency** | Deliveries ingested as they arrive, with naming and metadata normalized on the way in |
### How this maps to your function
A single campaign shoot can produce 600 assets, and an agency delivery often arrives with inconsistent naming, missing metadata and no campaign tags. The work that follows isn't judgment — it's typing. Gradial takes the typing: it reads the batch, applies your real schema with your controlled vocabulary, pulls campaign and rights context from the job ticket, and leaves you a short list of exceptions to rule on. The governance decisions stay with you; the data entry doesn't.
Most asset friction shows up downstream: you need an approved hero for a page going live tomorrow, and finding it means searching a library where the metadata is inconsistent, then checking whether the rights have expired. Gradial retrieves the asset as part of the job that needs it, confirms rights status before it's placed, and handles the swap across every page and reference when an asset is replaced.
Publishing an expired or rights-restricted asset carries real exposure, and it usually happens because the rights record lives in the DAM while the risk lives on the page. Gradial connects the two: assets flagged as expired or restricted in the DAM are surfaced in the CMS before content goes live. Alt text is generated and validated across the whole library rather than sampled, which is what WCAG conformance actually requires.
***
## Key outcomes
Assets enter the DAM with schema-compliant metadata on ingestion — no remediation queue.
Campaign, product, rights, and regional metadata populated automatically from the job ticket.
Expired and rights-restricted assets flagged before they reach the CMS.
Bulk ingestion jobs that took days complete in hours. DAM Librarians shift from data entry to governance strategy.
***
## Reporting on your library
Governance needs a view, not just a process. Ask Grady to build a **custom app** and you get a dashboard reading straight from your connected DAM — which assets in a delivery failed QA, what's missing alt text, what's approaching a rights expiry, grouped however your team thinks about it. Because it queries the DAM on refresh, it reflects the library as it stands rather than a snapshot someone exported.
The same applies to intake: a custom form gives requesting teams a structured way to submit asset and metadata requests, with submissions attributed and queued for Grady to work through.
See [Custom Apps](/docs/insights/custom-apps).
***
*For step-by-step instructions on uploading assets, updating alt-text, managing metadata, and swapping assets, see [Asset Operations](/docs/asset-management/asset-operations).*
# Audiences & Personas
Source: https://docs.gradial.com/docs/campaign-management/audience-manager
Define the customer segments Gradial writes for and tests against — so content, campaign matrices and CX audits are built around your real audiences, not generic profiles.
Audiences are where you define and maintain the customer segments Gradial uses across its work. Audiences power persona simulation in CX Optimizer, drive content targeting in content update tasks, and determine which visuals get assigned to which cells in Asset Pack campaign matrices.
***
## What Audiences Enable
Once audiences are configured, they are available across Gradial:
Build a campaign matrix and Gradial assigns different visuals and messaging to each audience segment automatically. See [Asset Search](/docs/asset-management/asset-search).
Run CX analysis from the perspective of your actual customer segments — not generic user profiles. See [CX Optimizer](/docs/insights/optimization).
Reference audience segments when briefing content updates so agents write for the right reader from the start.
Use audiences to scope multi-step campaign execution, ensuring the right content reaches the right segments at every stage.
***
## Setting Up Audiences
In Gradial, go to **Settings → Audiences**.
Click **New Audience** and fill in the audience record:
* **Name** — a short, descriptive label (e.g., "Enterprise IT Decision-Maker")
* **Description** — what this segment represents
* **Demographics** — role, seniority, geography, industry
* **Goals** — what this audience is trying to achieve
* **Pain points** — friction and blockers relevant to this segment
Save the audience. It becomes immediately available across Gradial workflows — in CX Optimizer persona configuration, Asset Pack matrix building, and task briefing.
***
## Tips for Effective Audiences
**Match your real segments.** Audiences work best when they reflect the personas your marketing and strategy teams already use — not generic archetypes. Pull from existing persona documents or brand guidelines if you have them.
**Be specific about goals and pain points.** CX Optimizer and content agents use these fields to evaluate and write for the segment. Vague descriptions produce generic output.
**Keep audiences maintained.** As your product and market evolve, revisit audience definitions so agent output stays accurate.
***
*For running CX analysis across your audience segments, see [CX Optimizer](/docs/insights/optimization). For building brand-matched campaign matrices by audience, see [Asset Search](/docs/asset-management/asset-search).*
***
## Activating audiences in your marketing platform
The audiences on this page shape how Gradial *writes and tests* — which reader a draft is written for, which segment a campaign matrix cell targets, whose perspective a CX audit takes. They are not pushed to your marketing platform.
Building and activating real, addressable segments is separate, and Gradial does that directly in the platform that owns them:
| Platform | What Gradial can build there |
| :---------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| **Adobe Experience Platform** | Create and retrieve audiences, inspect datasets, and activate segments — including into Adobe Journey Optimizer |
| **Braze** | Segments, audience insights, and catalog-driven targeting |
| **Marketo** | Smart list filters, smart campaign flows, and static list membership |
| **HubSpot** | Contact lists and audiences, with contact–company–deal associations |
| **Airship** | Static lists, segments, channels and named users |
| **MoEngage** | Campaign audiences and content-reference offers |
## See [Cross-Channel Campaign Execution](/docs/campaign-management/cross-channel-campaigns) for how audience configuration fits into executing a campaign brief.
## Who this is for
| Role | What Gradial handles |
| :--------------------------- | :------------------------------------------------------------------------------------------ |
| **Campaign Manager** | A reusable set of segments to build campaign matrices against, defined once |
| **Content Strategist** | Content briefed for a specific reader, so the draft arrives written for them |
| **Brand / Product Marketer** | Your existing persona work made operational rather than living in a deck |
| **CX / Insights Lead** | Site audits run from the perspective of real customer segments rather than generic profiles |
***
## Availability
**Access:** Must be enabled for your workspace. Contact your Gradial team to get access.
# CRM & Email
Source: https://docs.gradial.com/docs/campaign-management/crm-email
How Gradial builds and maintains email templates, content variants, journeys, and bulk compliance updates across every connected marketing platform at scale.
## The CRM Email Content Challenge
In marketing, CRM (Customer Relationship Management) refers to how brands communicate directly with customers and prospects through owned channels — primarily email, but also SMS, push notifications, and direct mail. These channels reach people who have already opted in or are existing customers, which makes them high-value — and high-stakes.
Large CRM programs operate at a scale that creates significant content operations complexity:
* 10–50 active automated journeys running simultaneously
* Hundreds of individual email templates across campaigns and triggers
* Personalization tokens and dynamic content blocks that multiply the effective number of variants
* Localized versions for multiple markets, each requiring independent review
The problem is not sending emails — modern CRM platforms handle delivery well. The problem is **keeping the content inside those emails accurate, on-brand, and compliant** as brand standards evolve, products change, and regulatory requirements update.
***
## Why Content Operations Gets Hard Here
### Templates multiply and age
Every campaign, journey, triggered message, and transactional email has its own template. Over time, organizations accumulate hundreds of templates — many of which contain outdated copy, old offers, retired product names, or brand elements that have since changed. Finding and updating all of them manually is slow and error-prone.
### Personalization creates hidden variants
Modern CRM platforms go well beyond inserting a first name into a subject line. Dynamic content blocks render different sections based on segment, behavior, or real-time data — a single "email" can have dozens of active permutations. When brand or compliance standards change, every variant needs to be updated, not just the visible default.
### Compliance changes require bulk updates on short timelines
Regulatory changes — new unsubscribe requirements, updated disclosures, revised data privacy language — require updates across all active templates. For regulated industries (financial services, healthcare, insurance), this is not optional and timelines are often tight. Manually identifying every affected template and updating each one is one of the most operationally expensive recurring tasks CRM teams face.
### Cross-channel consistency breaks down
The content in emails should reflect what's on the website, what's in paid media, and what agents are saying on calls. When messaging changes in one channel, CRM templates often don't get updated at the same time — creating inconsistent experiences for customers who move between channels.
***
## What Gradial Does
### Build email templates from a brief or reference
Give Grady a brief, a Figma file, or a reference URL and Gradial authors a new email template directly within your connected marketing platform — structured correctly for the platform's content model, following your brand guidelines, and ready for review.
### Update templates at scale
Point Gradial at a set of templates — or just describe the change you need — and it updates them across your template library. This is particularly valuable for:
* **Compliance updates**: Apply a new required disclosure or update unsubscribe language across all active templates in a single operation
* **Brand refreshes**: Update logo, color, or copy style across the full template library when brand standards change
* **Offer or product updates**: Replace a discontinued product reference or expired promotion across every template it appears in
### Create variants
Gradial can generate multiple variants of a template for A/B testing, audience segmentation, or regional localization — maintaining consistent structure and brand standards across each variant.
### Governance on every output
Every email Gradial builds or updates is checked against your organization's defined quality standards before it reaches a human reviewer: brand accuracy, required disclosures, link integrity, accessibility, and any custom compliance rules your organization has configured.
Gradial's governance layer catches issues before they go to review — not after they've been sent. This is especially important for regulated industries where a missing disclosure in a live email has real consequences.
### Reusable content blocks
Gradial detects and manages reusable content items natively within each platform's own model — Marketo Snippets and Tokens, Salesforce Marketing Cloud Content Blocks, Braze and MoEngage content blocks, and the equivalent in every other connected platform. When you update a shared element, Gradial surfaces which templates reference it before making changes, so you understand the scope of impact.
See [Working with Reusable Content](/docs/creating-new-experiences/working-with-fragments) for details on how Gradial handles platform-specific content models.
***
## Roles This Supports
| Role | What Gradial handles |
| :------------------------------- | :------------------------------------------------------------------------------------------------------------------------ |
| **CRM / Lifecycle Marketer** | Brief-to-template execution, variant creation, campaign asset management |
| **Email Developer** | Bulk template updates, structural changes across the library |
| **Marketing Automation Manager** | Keeping journey assets current when content standards change; authoring journeys and flows where the platform supports it |
| **Mobile / Push Marketer** | Push and in-app message templates alongside email, from the same brief |
| **Marketing Ops** | Audience segments and lists built in the platform itself, not requested from another team |
| **Compliance / Legal** | Bulk disclosure updates, audit trail for every change made |
***
## Supported Platforms
Gradial connects natively to the platforms below — no custom development required. See each integration guide for setup instructions.
Programs, smart campaigns, smart lists, email templates, landing pages, forms, snippets, tokens, fragments, and the lead database. OAuth 2.0 Client Credentials via LaunchPoint.
Content Builder emails and templates, template slot authoring, content blocks, image uploads, campaigns, Journey Builder authoring, and Data Extension reads. OAuth 2.0 Server-to-Server via Installed Package.
Marketing emails built from a campaign brief, branded template cloning, contact lists and audiences, forms and submissions, and CRM records. OAuth to a connected portal.
Campaigns, Canvases, segments, content blocks, templates, catalogs, audience insights, and controlled sends.
Templates, push notifications, schedules, channels, named users, static lists, segments, and cross-channel pipelines.
Campaigns, email templates, content blocks, content-reference offers, and cross-channel engagement flows.
Email and design workflows — templates, designs, and sends.
**Access:** Must be enabled for your organization. Contact your Gradial team to get access.
Leads, contacts, accounts and opportunities; lead routing to queues and users; allowlisted record creates and updates.
**Access:** Must be enabled for your organization. Contact your Gradial team to get access.
Running something else? Gradial also connects through **your own REST API** using its OpenAPI spec, or a **secure MCP server** — see [Custom MCP](/docs/integrations-administration-and-setup/integrations/custom-mcp). Your Gradial team can confirm the best route for your platform.
# Cross-Channel Campaign Execution
Source: https://docs.gradial.com/docs/campaign-management/cross-channel-campaigns
How Gradial turns a campaign brief into fully built assets across web, email, and every other channel — automatically, from one input.
## The Campaign Execution Problem
A campaign brief arrives. The strategy is solid. The asks are clear: a new product page, an email to the active list, audience segments set up in the marketing platform, paid social live on day one, offer updates on the homepage. Across channels, coordinated, live by Friday.
What follows is rarely as clean as the brief. Every deliverable belongs to a different system, a different team, and a different queue. The web team takes the page. Email development takes the template. Ops handles the audience. Paid waits on final creative. Someone remembers the homepage updates at the end. Coordination becomes the job — and coordination doesn't ship content.
Then the dates move. A legal note comes back on the disclaimer, so the email needs rebuilding and the page copy needs to match. The regional teams ask for their own versions. Every one of those changes re-enters the same queues in the same order, and the launch slips again.
The result: campaigns launch late, assets land in market inconsistently, and the brief that took a week to write drives another week of operational overhead before anything goes live.
***
## What Gradial Does
Gradial treats a campaign brief as an input to a fully automated execution workflow. Hand Grady a brief — a document, a prompt, a set of creative inputs from an agency — and Gradial:
1. **Parses the brief** and identifies every deliverable: which pages to create, which emails to build, which content to update, which assets are needed, which audiences to configure, which channels to publish to
2. **Structures the work** by channel, content type, and dependency — in the right order, with the right sequencing
3. **Executes across every channel at once** — simultaneously, not one queue after another
4. **Delivers governed outputs** across every deliverable, with brand, accessibility, and compliance checks applied automatically before anything reaches a human reviewer
The same brief that used to generate a week of coordination generates a set of ready-to-review assets in hours.
***
## How It Works
Attach a creative brief document, paste a prompt describing the campaign, or share a work request from an agency. Gradial accepts briefs in natural language — no structured template required.
Grady extracts the full set of deliverables: page builds, email templates, content updates, audience configurations, social and paid assets, asset requirements. Those become a plan with dependencies defined — so work that must happen in sequence does, and work that can run in parallel does. Review the plan before execution starts.
The product or landing page gets built in your CMS. The email is authored in your marketing platform. Homepage and offer changes are applied. Audience segments and lists are created where the brief calls for them. Social and paid assets are drafted against your brand standards.
All of it runs simultaneously. A campaign that requires five deliverables across three systems doesn't take five times as long — it takes as long as the most complex individual deliverable.
Brand accuracy, accessibility, compliance, and any custom QA rules are checked automatically on every deliverable before it reaches a human reviewer. Not sampled. Not spot-checked. Every output, every time.
Your team receives a set of governed, ready-to-review assets across every channel. Review at whatever level of oversight is configured — full approval, spot-check, or auto-publish for trusted task types. Status updates log back to your connected ticketing system.
***
## What Gets Built
A single campaign brief can produce deliverables across every channel your team manages:
Product pages, landing pages, campaign hub pages — built to spec from the brief, using your existing CMS structure, component patterns, and brand standards. Ready to publish.
**Native in:** AEM, SitecoreAI CMS, Sitecore XP, Contentful, Contentstack, Sanity, Drupal, WordPress, Gradial ACI
Ready-to-send templates authored directly in your marketing platform — copy, structure, personalization tokens, and all required compliance disclosures included. Journeys and multi-step flows where the platform supports them.
**Native in:** Marketo, Salesforce Marketing Cloud, HubSpot, Braze, Airship, MoEngage, SendGrid
Homepage offers, navigation promotions, CTAs, product descriptions — updated across every page the campaign brief calls out, in a single operation.
**Native in:** every connected CMS
Segments, lists, and audience definitions built directly in your marketing platform — no separate ops request, and no custom development required.
**Native in:** Adobe Experience Platform (with activation to Adobe Journey Optimizer), Braze, Marketo smart lists and static lists, HubSpot lists, Airship, MoEngage
Organic posts and paid campaign structures drafted against your brand standards. Campaigns are created paused, and enabling delivery, changing bids, or setting budgets always requires explicit human approval.
**Native in:** LinkedIn (organic and Ads), X, Google Ads, Reddit Ads
Product detail pages, merchandising copy, collections, promotions, and storefront content built from the same brief that drives the campaign.
**Native in:** Shopify, Salesforce B2C Commerce
**When your stack includes something else**
The systems above are native — Gradial connects to them directly, with no custom development. For anything else, Gradial's orchestration engine also connects through **your own REST API** (point Gradial at its OpenAPI spec) or a **secure MCP server**, and that work is included in campaign execution automatically alongside everything else.
[Custom API →](/docs/integrations-administration-and-setup/integrations/get-started-with-integrations) · [Custom MCP →](/docs/integrations-administration-and-setup/integrations/custom-mcp)
***
## An Autonomous Content Supply Chain
The shift this enables isn't just speed. It's a different operating model.
In a traditional campaign workflow, a brief creates work — work that humans then distribute, track, execute, and coordinate across every channel. The brief is the start of a long manual process.
In Gradial, the brief is the instruction. Gradial handles the distribution, the execution, and the coordination. Humans govern the output and direct the strategy. The content supply chain runs autonomously from brief to live.
A single brief drives execution across every channel — no per-channel tasking required.
All channels build simultaneously. A five-deliverable campaign doesn't take five times as long.
Brand, accessibility, and compliance checks run automatically on every output before review.
***
## Who This Is For
| Role | What Gradial handles |
| :------------------------------ | :---------------------------------------------------------------------------------------------------------------------- |
| **Campaign Manager / Marketer** | Submit the brief, review the outputs — skip the coordination and ticketing overhead in between |
| **Content Strategist** | Define what good looks like; Gradial applies it consistently across every channel, every campaign |
| **Email / CRM Developer** | Brief-to-template execution in your marketing platform without manual authoring |
| **Marketing Ops** | Audience and segment configuration in the platform itself, triggered automatically from the campaign brief |
| **Demand Gen / Paid Media** | Paid campaign structures drafted from the same brief — created paused, with spend changes always gated on your approval |
| **Social / Content Marketing** | Organic posts drafted against brand standards, ready to schedule alongside the rest of the campaign |
| **Ecommerce / Merchandising** | Product pages, collections and promotions built from the campaign brief, not a separate request |
| **Creative / Agency** | Submit creative inputs directly — Gradial translates them into production assets without a handoff layer |
### How this maps to your function
Strategic decisions — a new product launch, an EMEA expansion, a repositioning — cascade into dozens of content deliverables across web, email, social, paid and every other channel. Traditionally, that cascade takes weeks of coordination before anything goes live. Gradial makes the execution automatic: the brief is the instruction, and Gradial handles the rest. For teams pursuing personalization as a strategic priority, this matters even more — Gradial can produce the multiple audience variants that personalization requires at a pace that matches strategic ambition, not operational capacity.
A single campaign plan can generate 50–200 individual assets — each requiring briefing, creation, review, approval, and publishing. That's where timelines compress and backlogs build. Gradial removes the bottleneck between the brief and the published asset: once the brief is submitted, execution runs across all channels without the per-deliverable coordination that typically consumes campaign managers and content ops teams. DesignOps teams benefit directly from Gradial closing the handoff gap — design files from Figma drive CMS authoring without manual re-entry or developer involvement.
The gap between what designers create in Figma and what gets published in the CMS is one of the most persistent pain points in enterprise marketing — often weeks of delay, and frequent drift from the original design. Gradial closes that gap: it reads Figma files and drives the CMS authoring process, populating content into existing component structures at speed without manual re-entry. For agencies delivering campaign creative, this means handoffs become inputs to automated execution rather than the start of another coordination cycle. Brand and accessibility governance runs automatically on every published output, so creative standards don't erode at the publishing layer.
***
## Related
* [CRM & Email →](/docs/campaign-management/crm-email) — How Gradial builds and maintains email across every connected marketing platform
* [New Page Workflow →](/docs/creating-new-experiences/new-page) — How new web pages get built from a brief, Figma file, or reference URL
* [Content Updates →](/docs/updating-existing-experiences-i-e-content-updates/content-updates) — How Gradial executes updates across existing web pages
* [Custom Apps →](/docs/insights/custom-apps) — Build a dashboard showing campaign progress across web, email, and social in one view
* [Custom MCP →](/docs/integrations-administration-and-setup/integrations/custom-mcp) — Connecting additional systems and tools to Gradial's orchestration engine
# Make & Edit Office Documents
Source: https://docs.gradial.com/docs/campaign-management/office-docs
Use Gradial to create and edit Word, Excel and PowerPoint files — campaign briefs, copy docs, trackers, QA analyses and readout decks — directly from your content workflows.
## Why This Matters
A surprising share of marketing work isn't content in a CMS — it's the documents around it. The brief that kicks off a campaign. The copy doc legal marks up. The spreadsheet tracking 200 pages through review. The QA summary someone assembles by hand before a launch readout. The deck that goes to the leadership meeting.
These artifacts get built manually, usually by the person with the least time, and they go stale the moment the underlying work moves on. Worse, they're the interface to everyone outside the content team — legal, brand, leadership — so when they're out of date, decisions get made on old information.
Gradial produces these documents as part of the work itself, populated from what actually happened rather than from someone's notes.
***
Gradial can create and edit Microsoft Office files as part of your content workflows — **Word** documents, **Excel** workbooks and **PowerPoint** decks. Ask Grady to build a campaign brief, produce a copy document from a live page, generate a formatted QA analysis, assemble a tracker, or turn a set of findings into a readout deck.
Gradial can also **read** these files. Attach a brief, a copy deck, a spreadsheet of changes or an existing presentation, and Grady works from its contents — which is usually the fastest way to start a piece of work.
***
## What You Can Create
Generate a structured brief from a prompt, a set of pages, or an existing strategy document. Includes audiences, messaging pillars, channel breakdown, and timelines.
Pull copy from live CMS pages into a formatted Word document — useful for legal review, translation handoff, or stakeholder sign-off.
Produce a custom QA report as a formatted document, summarizing findings, issues, and recommended fixes for sharing outside the platform.
Turn campaign results, a QA or accessibility summary, a CX Optimizer report or GEO findings into a PowerPoint deck — built from your own template so it arrives on-brand, with speaker notes where they help.
Any tabular or structured content — status trackers, campaign matrices, approval checklists, per-page change lists — assembled into an Excel workbook, ready to filter and sort.
Anything else you'd otherwise put together by hand, in whichever of the three formats suits the audience.
### Working from your own template
For decks and documents that represent the company, point Gradial at an existing file — your standard deck template, a previous quarter's readout, a brief in your house format. Gradial builds the new one to match it, so layouts, fonts and brand treatment carry over rather than being approximated.
***
## How It Works
Office document creation works through Gradial Chat or as part of a larger workflow. Describe what you need and Gradial produces the document:
```
"Create a campaign brief for our Q3 product launch targeting enterprise buyers.
Include messaging pillars, audience segments, and a channel breakdown."
```
```
"Pull the copy from [page URL] into a Word document formatted for legal review."
```
```
"Build an Excel tracker for this batch of content updates with columns for
page URL, status, assignee, and go-live date."
```
```
"Turn the accessibility report for this launch into a deck for Monday's
review. Use the attached template. One slide per severity level, and a
summary slide up front with the counts."
```
```
"Read the attached Q2 readout deck and build the Q3 version using the same
structure, with this quarter's numbers."
```
Gradial returns the completed file attached to the task, ready to download. Decks and documents can also be previewed in Gradial before anyone downloads them.
***
## Common Use Cases
**Translation handoff.** Extract copy from live pages into a clean Word document formatted for your translation vendor — no manual copy-paste from the CMS.
**Legal and compliance review.** Generate a Word document containing all regulated copy across a set of pages for legal sign-off before a campaign launches.
**Campaign matrix trackers.** Produce an Excel file tracking every asset, page, and deliverable across a campaign — auto-populated from the task data Gradial already has.
**Stakeholder briefings.** Assemble a structured brief or summary document from a strategy doc, a set of Gradial findings, or a CX Optimizer report.
**Leadership readouts and QBRs.** Turn a quarter's activity, a launch retrospective, or a set of QA, accessibility and GEO findings into a deck on your own template — so the slide build stops being the reason the readout is late.
**Working from an inbound deck.** A stakeholder sends a deck with the campaign concept in it. Attach it and ask Grady to work from it directly, rather than retyping the relevant slides into a brief.
***
*Files created by Gradial can be attached to tasks, shared externally, or fed back into Gradial as source material for future work.*
***
## Who this is for
| Role | What Gradial handles |
| :---------------------------------- | :----------------------------------------------------------------------------------------------- |
| **Campaign Manager** | Briefs and status trackers generated from the work itself, not maintained by hand |
| **Content Strategist / Copywriter** | Copy docs produced from live pages, so review happens on what's actually published |
| **Legal / Compliance Reviewer** | A document to mark up, in the format you already review in |
| **Marketing Leadership** | Readout decks and summaries assembled from real activity rather than from someone's recollection |
| **Marketing Ops** | Per-page and per-asset trackers as spreadsheets, ready to filter and sort |
| **Enablement / Comms** | Briefing and training decks built on the house template, from what actually shipped |
### How this maps to your function
Reviewers outside the content team don't want CMS access — they want a document. Gradial produces a copy doc from the live page, so what legal marks up is what's published, and the changes come back into the same workflow instead of into an email thread. See [Regulated Industries & Compliance Workflows](/docs/governance/regulatory-compliance).
Quarterly readouts and launch retrospectives get assembled by hand from several systems, which is why they're late and approximate. When the underlying record is the work itself, the document — or the deck — is a byproduct rather than a project. Point Gradial at last quarter's version and it will build this one to match.
# Design Pattern Ingestion
Source: https://docs.gradial.com/docs/creating-new-experiences/design-pattern-ingestion
Learn how to set up and manage your Design System patterns in Gradial for consistent, efficient page creation.
***
## Prerequisites
Before ingesting patterns, you'll need **Golden Pages**—fully-authored reference pages that contain all the patterns for each template type. See the [Golden Pages Guide](/docs/creating-new-experiences/golden-pages) for details on creating effective reference pages.
***
## Overview
Design Patterns are the building blocks Gradial uses to create and update your pages. Each pattern represents a reusable component layout from your CMS—things like hero banners, card grids, content blocks, and navigation elements.
By ingesting patterns from your existing pages, you teach Gradial's AI agent exactly how your components work, enabling it to accurately build new pages and update existing ones.
***
## Understanding Design Systems
A **Design System** in Gradial is a collection of patterns organized by page type or template. Think of it as a toolkit specific to each type of page you create.
### Why Organize by Page Type?
Different page types have different needs:
| Page Type | Typical Patterns |
| :------------- | :-------------------------------------------------------- |
| Homepage | Hero carousel, featured content grid, announcement banner |
| Blog Article | Article hero, body content, author bio, related posts |
| Product Detail | Product hero, features grid, specifications, reviews |
| Landing Page | Campaign hero, benefit blocks, testimonials, CTA sections |
Each page type has specific component structures and patterns available to it. Organizing patterns into Design Systems ensures the AI agent uses the right components for each page type.
### Collections
**Collections** let you organize patterns into focused, purpose-built subsets of a Design System. Rather than exposing the full pattern library for every task, Collections allow you to group patterns by use case—such as blog pages, marketing campaigns, or product flows.
Key capabilities:
* A pattern can belong to multiple Collections simultaneously
* Access Collections from the **Collections** tab on the Design System page
* Create, manage, and update Collections by adding or removing patterns
* Reuse Collections across different tasks and workspaces
### Workspace Scoping
Design Systems and Collections can be scoped to specific workspaces, so each team only sees the patterns relevant to their work.
* Associate a Design System with one or more workspaces
* Scope access to particular Collections within a system
* Design systems auto-filter based on the CMS integration URL of each workspace
### Design System Best Practices
* **Create separate Design Systems** for each unique page template in your environment
* **Include all available patterns** for that page type—this gives the agent the full toolkit
* **Use descriptive names** that reflect both the pattern type and its context
* **Use Collections** to create focused subsets for specific use cases or teams
***
## Ingesting Patterns
Follow these steps to add patterns to your Design System.
### Step 1: Create a Design System
Navigate to the **Design Patterns** section in your organization settings and click **+ Create**.
Enter a name and optional description for your new Design System. Choose a name that clearly identifies the page type, such as "Blog Article Patterns" or "Product Page Components."
### Step 2: Add Patterns from a Golden Page
Click **+ Add Patterns** within your Design System.
You'll need a Golden Page URL—this is the reference page you created that contains all the patterns for this template type. The URL should be a fully-formed path to your CMS authoring environment.
**Example URL format** (AEM shown; use the equivalent authoring URL for your platform):
```
https://author-yoursite-stage.example.com/editor.html/content/your-site/en/example-page.html
```
Paste the URL and click **Detect Patterns**. Gradial will analyze the page and identify the component patterns present.
> **Note:** For AEM, the system automatically appends `?wcmmode=default` to put pages in Preview mode during analysis. Other platforms use their own equivalent preview mode.
### Step 3: Name Your Patterns
After detection, you'll see a list of all patterns found on the page. **Rename each pattern** with a unique, descriptive name.
**Important:** Do not accept default pattern names. Each pattern should have a unique name, even if similar layouts appear across different Design Systems.
**Good naming examples:**
* `Blog Article Hero` (not just "Hero")
* `Product Feature Card Grid` (not just "Card Grid")
* `Homepage Announcement Banner` (not just "Banner")
This prevents confusion when the agent selects patterns and ensures accurate component mapping.
### Step 4: Save and Review
Once all patterns are named appropriately, save your Design System. Review the pattern list to ensure everything was captured correctly.
***
## Testing Your Patterns
Before using patterns in production, verify they work correctly.
### Create a Test Task
Set up a test task in a development workspace with a prompt like:
```
Create a blank page at location /content/yoursite/en/test/pattern-test
Add patterns from [Design System Name] onto the new page
Use content from [example source] to populate each pattern
```
### What to Look For
* Patterns render with correct visual structure
* Content populates in the expected fields
* Component hierarchy matches your reference page
* No missing or malformed elements
### If Patterns Don't Render Correctly
Pattern issues typically stem from field classification problems. See the [Field Classification](#field-classification) section below, or contact Gradial support for assistance with pattern refinement.
***
## Field Classification
When patterns are ingested, Gradial captures all attributes associated with each component—both visible content fields and hidden structural properties.
### How Classification Works
Each field is automatically classified as:
| Classification | Meaning | Examples |
| :------------- | :----------------------------------- | :------------------------------------------ |
| **High (H)** | Editable content the author controls | Headlines, body text, image paths, metadata |
| **Low (L)** | Structural/constant values | Component type, layout identifiers |
### When to Adjust Classification
You may need to manually adjust field classifications if:
* Expected content fields aren't being updated
* Structural fields are being incorrectly modified
* Metadata or hidden fields need to be author-editable
### Classification Guidelines
* **Set to High (H):** All visible content elements, plus any hidden fields authors should control (metadata, SEO fields, etc.)
* **Set to Low (L):** Component type identifiers, structural constants, system-generated values
> **Note:** Field classification is an advanced feature. Contact Gradial support if you're unsure how to proceed with classification adjustments.
***
## General Rules & Tips
### Pattern Naming
* Every pattern needs a unique name across your entire organization
* Include the page type or context in the name
* Be specific: `Product Card Grid` and `Blog Card Grid` are better than two patterns both named `Card Grid`
### Environment Considerations
* Patterns are specific to each environment (Stage, Production, etc.)
* If you move from Stage to Production, you'll need to re-ingest patterns in the new environment
### Pattern Selection
When creating or updating pages, you can either:
* **Select specific patterns** in the task configuration
* **Reference the Design System by name** in your prompt (e.g., "Use the Blog Article Patterns")
* **Select a Collection** to use a focused, pre-grouped subset of patterns
Selecting only the needed patterns (or a targeted Collection) helps focus the AI agent and produces better results than loading all available patterns.
### Pattern Inheritance
When working with batch tasks, campaigns, or folders, patterns selected at the **parent level** automatically flow down to child tasks.
* Patterns are inherited by manually created, CSV-uploaded, or agent-generated child tasks
* Pattern selections are saved to task history
* Children capture the parent's selections at creation time—existing children are not retroactively updated
### Draft Patterns
Patterns can be set to **Draft** status to hide them from the authoring agent while you work on them.
| Status | Behavior |
| :--------------------- | :------------------------------------------------------------------ |
| **Released** (default) | Available to the authoring agent for task execution |
| **Draft** | Visible in admin/design system settings only; hidden from the agent |
Toggle a pattern's status from the pattern detail panel in your Design System. Use Draft status for work-in-progress patterns or patterns that need refinement before going live.
### Maintaining Your Design System
* **Add new patterns** when new components are developed
* **Update patterns** if component structures change
* **Remove deprecated patterns** that are no longer in use
* **Use Draft status** to stage patterns before making them available to the agent
* **Test after changes** to verify patterns still work correctly
***
## Troubleshooting
| Issue | Likely Cause | Solution |
| :---------------------------------- | :----------------------------- | :---------------------------------------------- |
| Pattern not detected | Page not in preview mode | Verify URL is correct and accessible |
| Wrong content in fields | Field classification incorrect | Review and adjust H/L classifications |
| Missing visual elements | Pattern incomplete | Re-ingest from a more complete reference page |
| Duplicate pattern names | Non-unique naming | Rename patterns with specific, contextual names |
| Pattern works in Stage but not Prod | Environment mismatch | Re-ingest patterns in Production environment |
***
## Next Steps
Once your Design System is configured:
* [Create new pages using your patterns](/docs/creating-new-experiences/new-page)
* [Migrate content at scale](/docs/creating-new-experiences/migration)
* [Update existing pages](/docs/updating-existing-experiences-i-e-content-updates/content-updates)
* [Run medium and batch operations](/docs/updating-existing-experiences-i-e-content-updates/medium-content-updates-in-gradial)
# Golden Pages
Source: https://docs.gradial.com/docs/creating-new-experiences/golden-pages
Learn how to create reference pages that teach Gradial your component patterns.
***
## Overview
A **Golden Page** is a fully-authored reference page you create in your CMS for each page template type. It contains every content pattern—Hero, Accordion, Card Grid, and so on—that Gradial should be able to use when building or editing pages of that type.
Think of a Golden Page as a comprehensive example that shows Gradial exactly what components are available and how they should be structured.
> **Note:** By "template" we mean the page templates defined in your CMS. In practice, a single page template may be used for multiple content types (for example, a generic "Article" template used for both news articles and blog posts).
***
## How Gradial Uses Golden Pages
When you provide a Golden Page, Gradial runs pattern ingestion to learn from it:
1. **Analyzes** the page and identifies discrete patterns (each within an authorable container)
2. **Captures** the blueprint of each pattern—its structure, configuration, and component relationships
3. **Stores** patterns in a library organized by Design System
4. **Applies** patterns when building new pages, adapting the content to each specific context
### Example in Action
Your Product Detail Page (PDP) Golden Page includes a "Related Products" card grid with placeholder products. Gradial ingests this pattern and learns its structure.
Later, when creating a new PDP for a specific product, Gradial can generate a "Related Products" section using that same pattern—but populated with products actually related to that page's content.
***
## Requirements
Creating effective Golden Pages requires attention to a few key principles.
### One Golden Page Per Template
Create a Golden Page for each page template in your project scope. Common template types include:
* Product Detail Page (PDP)
* Product Listing Page (PLP)
* Article / Blog
* Landing Page
* Category Page
* Homepage
### Include All Patterns
Your Golden Page should contain every pattern you want Gradial to use for that template type. If a pattern isn't on the Golden Page, Gradial won't know it's available.
### Build in the Real Template
Author your Golden Page using the actual page template from your CMS—not a generic or test template. This ensures the patterns you create are fully compatible with production pages.
### Containerize Multi-Component Patterns
When a pattern consists of multiple components working together, group them within a single authorable container. This tells Gradial to treat them as one cohesive unit.
**Example:** A Hero pattern might include a title component, an image component, and a CTA button. By placing all three in one container, Gradial understands they form a single "Hero" pattern rather than three separate elements.
### Use Realistic Placeholder Content
Populate your patterns with production-representative content. This means:
* Realistic text length and structure
* Proper image dimensions and aspect ratios
* Representative data in tables and lists
* Actual (or realistic placeholder) links and CTAs
This helps Gradial understand what kind of content belongs in each pattern.
***
## Common Patterns to Include
While every project is different, most Golden Pages include patterns like these:
| Pattern Type | Description |
| :----------- | :-------------------------------------------------- |
| Hero | Primary page banner with headline, image, and CTA |
| Accordion | Expandable content sections |
| Card Grid | Content cards in 2-col, 3-col, or 4-col layouts |
| Carousel | Rotating content (customer stories, featured items) |
| FAQ Section | Question and answer format |
| Promo / CTA | Promotional blocks and call-to-action sections |
| Data Table | Structured tabular information |
| Text + Media | Content blocks combining copy with images or video |
> **Remember:** A single pattern may contain multiple components. What matters is that related components are grouped together in one container so Gradial ingests them as a single reusable unit.
***
## Handling Pattern Variations
Some components support multiple configurations or visual styles. Here's how to handle them:
### Include Major Variants
If a component can be configured in fundamentally different ways, include each major variant as a separate pattern.
**Example:** A flexible content block that can render as either an accordion or a carousel should appear twice on your Golden Page—once configured as an accordion, once as a carousel.
### Skip Trivial Variants
You don't need to include every possible configuration. Minor variations that don't change the pattern's structure can be handled by Gradial automatically.
**Example:** A carousel with 3 items and a carousel with 5 items use the same pattern—just with different amounts of content. Include it once.
***
## Quality Check: The Copy-Paste Test
Before finalizing your Golden Page, validate each pattern with this simple test:
1. **Copy** a pattern from your Golden Page
2. **Paste** it into another page using the same template
3. **Check** if it renders correctly without manual fixes
**If it works:** The pattern is well-structured and will likely work well with Gradial.
**If it breaks:** The pattern may have dependencies or structural issues that need to be resolved before ingestion.
This test catches problems early and ensures your patterns are truly portable and reusable.
***
## What Not to Include
Your Golden Page should focus on the patterns you actively want Gradial to use. Exclude:
* **Deprecated components** that are being phased out
* **Rarely-used components** that don't justify the added complexity
* **Template-specific structural elements** that aren't meant to be reused
* **Test or experimental components** not ready for production
A focused Golden Page produces better results than one cluttered with every possible component.
***
## Frequently Asked Questions
**How does Gradial know which components belong together?**
By your containerization. Components grouped in one authorable container are treated as one pattern. Components in separate containers are treated as separate patterns.
**Can Gradial modify the patterns it learns?**
Yes. Gradial adapts the content within patterns—changing product names, images, descriptions, and other variable content—while maintaining the structural blueprint from your Golden Page.
**Do I need to update Golden Pages when components change?**
Yes. If a component's structure changes significantly, re-ingest the pattern from an updated Golden Page to ensure Gradial has the current blueprint.
**What if the same component appears on multiple templates?**
Include the component on each relevant Golden Page. Even if the underlying CMS component is the same, having it in each Design System ensures Gradial can use it appropriately for each template type.
***
## Next Steps
Once your Golden Pages are ready:
1. [Ingest patterns into your Design System](/docs/creating-new-experiences/design-pattern-ingestion)
2. [Test patterns in a development environment](/docs/creating-new-experiences/design-pattern-ingestion)
3. [Create new pages using your patterns](/docs/creating-new-experiences/new-page)
4. [Migrate content at scale](/docs/creating-new-experiences/migration)
# Batch Migration
Source: https://docs.gradial.com/docs/creating-new-experiences/migration
Migrate large volumes of content into your new CMS environment using Gradial's batch processing capabilities.
## Why This Is Slow Today
Migrations are where content teams lose quarters. A redesign, a platform move, or a template consolidation means a list of URLs — often hundreds — that each need their content read, mapped onto new components, and rebuilt. The work is identical every time and completely manual, which makes it both expensive and error-prone: page 40 gets built to a slightly different standard than page 4, and nobody notices until an audit.
The usual response is to scope the migration down: move the top 50 pages, leave the rest, and accept a split estate. That decision then costs you for years.
Gradial runs the same page-build process across the whole list at once, using your templates and design system patterns, so the volume stops being the reason to cut scope.
***
## Overview
Batch Migration allows you to create multiple new pages from a set of source URLs and transition them into your new design system. This is ideal for onboarding legacy content, platform migrations, or transitioning pages to updated templates at scale.
Think of batch migration as running many [New Page](/docs/creating-new-experiences/new-page) tasks simultaneously—Gradial reads content from your source pages and recreates them using your CMS templates and Design System patterns.
***
## Prerequisites
Before starting a migration, ensure you have:
1. **Golden Pages** created for each target template type — see [Golden Pages Guide](/docs/creating-new-experiences/golden-pages)
2. **Design System patterns** ingested from those Golden Pages — see [Design Pattern Ingestion](/docs/creating-new-experiences/design-pattern-ingestion)
3. **Target pages created in your CMS** — the destination pages should already exist in your content structure
4. **Source URLs accessible** — Gradial needs to read from your source pages
***
## Migration Workflow Overview
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 1. Prepare │ │ 2. Create │ │ 3. Run │
│ Spreadsheet │ ──▶ │ Batch Task │ ──▶ │ Batch │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
┌─────────────────┐ ┌─────────────────┐ │
│ 5. Promote │ │ 4. Review │ │
│ Launches │ ◀── │ Results │ ◀──────────┘
└─────────────────┘ └─────────────────┘
```
***
## Step 1: Prepare Your Migration Spreadsheet
The migration spreadsheet is the most important part of the process. A well-prepared spreadsheet with detailed instructions produces much more accurate results.
### Required Columns
| Column | Description | Example |
| :--------------------- | :------------------------------------------------------ | :---------------------------------------------------------------------------- |
| **Instructions** | Detailed prompt telling Gradial how to handle this page | See below |
| **Live Link** | Source URL to migrate content from | `https://www.example.com/old-page` |
| **Migrated Page Path** | Content path for the destination in your CMS | `/content/mysite/en/new-page` |
| **Author URL** | Full authoring URL for the destination | `https://author.example.com/editor.html/content/mysite/en/new-page.html` |
| **Preview URL** | Author URL with preview parameter | `https://author.example.com/content/mysite/en/new-page.html?wcmmode=disabled` |
### Optional Columns
Depending on your migration needs, you may include additional columns:
* **Pattern Recommendations** — Specify which Design System patterns to use for each page
* **Site Group** — For sites with dynamic content segmentation
* **Template Reference** — Explicitly specify which template to use
* **Custom metadata** — Any page-specific information the agent should know
### Writing Effective Instructions
The Instructions column is where you tell Gradial exactly how to handle each page. More detail produces better results.
**Example instruction:**
```
Migrate the content from the Live Link URL to the Migrated Page Path.
Use the Article Page Design Patterns for component selection.
Map content as follows:
- Page hero: Use "Article Hero" pattern with the main headline and featured image
- Body content: Use "Rich Text Block" pattern for article text
- Related articles: Use "Card Grid 3-Column" pattern for any linked articles
- CTA section: Use "Promo Banner" pattern for any call-to-action blocks
Preserve all existing images and upload to DAM at /content/dam/mysite/articles/
Do not run the QA agent after completion.
```
### Pattern Recommendations
For each page, specifying which patterns to use and where improves accuracy significantly:
```
Patterns to use:
- "Article Hero" for the top banner section
- "Rich Text Block" for main body content
- "Pull Quote" for any highlighted quotes
- "Image Gallery" for photo collections
- "Related Content Cards" for the bottom section
```
***
## Step 2: Create the Batch Task
### Navigate to Batch Tasks
From the left navigation, select **Batch Tasks**, then click **New Batch** in the top-right corner.
### Configure the Batch
1. Enter a descriptive **name** for the batch (e.g., "Blog Migration - January 2025")
2. Add an optional **description**
3. Verify the correct **Workspace** and **Environment** are selected
> **Tip:** For initial testing, name your batch clearly (e.g., "Blog Migration - TEST RUN") so you can easily identify and clean up test batches later.
### Import Your Spreadsheet
1. Click **Bulk Add** to open the import screen
2. Select **New Page** as the task type
3. Upload your Excel file containing the migration data
4. The first row will be used as headers; each subsequent row becomes a task
### Configure Task Properties
Before creating tasks, you can set properties that apply to all tasks:
* **Assignee** — Who owns these tasks
* **Approver** — Who reviews completed tasks
* **Template** — The CMS template to apply
Setting these during import saves time versus updating each task individually.
### Create Tasks
Click **Create Tasks** (or "Create xx threads"). Each row in your spreadsheet becomes an individual task within the batch.
> **Important:** Creating tasks does not run them. Review the imported tasks before executing the batch.
***
## Step 3: Run a Test Batch First
Before running a large migration, always test with 1-2 pages to validate your setup.
### Why Test First?
* Verify your instructions produce the expected results
* Check that patterns render correctly
* Identify any adjustments needed to your spreadsheet
* Avoid having to fix issues across hundreds of pages
### Running Selected Tasks
1. From the batch task table, select specific tasks using the checkboxes
2. Click **Run Batch** — only selected tasks will execute
3. Review results before running the full batch
### Evaluating Test Results
After test tasks complete:
1. Click into each task to see the instructions and results
2. Open the authoring agent report to see what actions were taken
3. Preview the migrated page in your CMS to verify content and layout
4. Note any adjustments needed for your instructions or pattern recommendations
***
## Step 4: Run the Full Batch
Once satisfied with test results, run the complete migration.
### Execute the Batch
1. Click **Run Batch** from the batch task view
2. The button shows the total number of tasks to process
3. Confirm to start processing
### Monitor Progress
During execution, you'll see:
* **Progress bar** showing overall batch completion percentage
* **Task list** with status indicators for each task:
* 🔵 **Running** — Task is being processed
* 🟢 **Done** — Task completed successfully
* 🔴 **Error** — Task encountered an issue
### Processing Time
Migration tasks take longer than simple content updates because Gradial must:
1. Read and analyze the source page
2. Map content to appropriate patterns
3. Create or update the destination page in your CMS
4. Upload any assets to the DAM
5. Optionally run QA checks
Plan accordingly for large batches.
***
## Step 5: Review and Promote
### Review Completed Tasks
After the batch completes:
1. Navigate back to the task list
2. Click into individual tasks to review:
* The original instructions
* The agent's action report
* Any summary messages or QA findings
### Promote Launches
Migrated pages are created in your CMS's staging layer (an AEM Launch, a workflow state, a draft environment), not published directly. To make them live:
1. Select tasks ready for promotion (individually or use the header checkbox to select all visible)
2. Click **Promote Launches**
3. For batches with multiple pages of tasks, navigate to each page and repeat
> **Note:** Promoting a staged page does NOT publish it. Publication still follows your organization's standard CMS workflow and governance processes.
### Handle Issues
If QA reveals issues with migrated pages:
* Create follow-up tasks in Gradial to make corrections
* Use [Content Updates](/docs/updating-existing-experiences-i-e-content-updates/content-updates) for copy changes, component adjustments, or styling fixes
* Iterate until pages meet quality standards
***
## Best Practices
### Spreadsheet Preparation
* **Be detailed in instructions** — More context produces better results
* **Specify patterns explicitly** — Don't rely on the agent to guess which patterns to use
* **Include all URLs** — Provide both author and preview URLs for easy verification
* **Test your spreadsheet** — Run a small batch first to validate your setup
### Batch Organization
* **Use clear naming conventions** — Makes tracking and cleanup easier
* **Group similar pages** — Batch pages that use the same template and patterns together
* **Keep batches manageable** — Consider splitting very large migrations into multiple batches
### Quality Assurance
* **Review before promoting** — Check migrated pages in your CMS preview
* **Use the QA agent** — Let Gradial flag potential issues automatically
* **Plan for iteration** — Expect some pages will need follow-up adjustments
### Execution
* **Test first, always** — Run 1-2 pages before the full batch
* **Monitor progress** — Watch for errors during batch execution
* **Promote in batches** — Review and promote pages in manageable groups
***
## Troubleshooting
| Issue | Likely Cause | Solution |
| :----------------------- | :------------------------------- | :-------------------------------------------- |
| Tasks fail to run | Source URL inaccessible | Verify source pages are accessible to Gradial |
| Wrong patterns used | Instructions not specific enough | Add explicit pattern recommendations |
| Content missing | Source page structure unexpected | Review source page and update instructions |
| Images not migrated | DAM path not specified | Add DAM upload path to instructions |
| Tasks stuck in "Running" | Processing complex page | Allow more time; check for errors |
***
## Related Resources
* [Golden Pages Guide](/docs/creating-new-experiences/golden-pages) — Creating reference pages for pattern ingestion
* [Design Pattern Ingestion](/docs/creating-new-experiences/design-pattern-ingestion) — Setting up your Design System
* [New Page Workflow](/docs/creating-new-experiences/new-page) — Creating individual new pages
* [Content Updates](/docs/updating-existing-experiences-i-e-content-updates/content-updates) — Making changes to existing pages
* [Batch Updates](/docs/updating-existing-experiences-i-e-content-updates/medium-content-updates-in-gradial) — Updating multiple pages at once
***
## Who this is for
| Role | What Gradial handles |
| :--------------------------- | :-------------------------------------------------------------------------------------------------- |
| **Migration / Program Lead** | Full-estate scope instead of a top-50 subset, with consistent output across the whole list |
| **Web Producer** | Not running the same CMS operation four hundred times |
| **Content Strategist** | Legacy content mapped onto the new design system, with gaps surfaced rather than silently dropped |
| **IT / Platform Owner** | A platform move that doesn't leave a split estate behind |
| **Brand Manager** | Every migrated page built to current standards, not the standard in force when it was first written |
### How this maps to your function
Migrations get scoped down because the per-page cost is high and fixed. Change that cost and the scoping conversation changes with it — you can move the long tail, retire the old platform on schedule, and stop carrying two estates.
Bulk migration is also the best opportunity you will get to raise the floor: every page passes through a process that applies current templates, current patterns and current brand standards. Handled page by page over two years, that consistency never arrives.
# New Page Workflow
Source: https://docs.gradial.com/docs/creating-new-experiences/new-page
Create new pages with Gradial's AI agents — from page duplication to Figma-to-CMS and content migration workflows.
## Why This Is Slow Today
A landing page for next month's launch shouldn't take three weeks. But the path from approved design to live URL runs through a queue: the brief goes to a web producer, the producer opens the CMS, finds the closest existing page, copies it, then re-enters every headline, every body paragraph, every CTA and every image reference by hand — checking against the Figma file as they go.
Then the design review comes back. The hero crops wrong on mobile, the third section uses a component that isn't approved for this template, and the disclaimer is missing. Each fix is another pass through the same queue.
Multiply that by the number of pages a campaign actually needs — a hub, three regional variants, two product pages — and page creation becomes the reason launches slip.
Gradial builds the page from whatever you already have: a design file, a brief, a reference page, or a description. It uses the component patterns your site already uses, so what comes out fits the environment instead of needing to be reworked into it.
***
## Overview
Creating new pages is one of the core workflows in Gradial. Depending on your starting point and requirements, you can choose from several approaches:
| Approach | Best For | Complexity |
| :----------------------------- | :------------------------------- | :------------ |
| Copy Existing Page | Similar pages, quick duplication | ⭐ Easiest |
| From Templates & Patterns | Building from design system | ⭐⭐ Moderate |
| From Copy Doc / Creative Brief | Content-first creation | ⭐⭐⭐ Moderate |
| From Figma Design | Design-to-production | ⭐⭐⭐⭐ Advanced |
***
## Where this works
Page creation is native in every connected CMS: **Adobe AEM** (6.5 and Cloud Service), **SitecoreAI CMS** (XM Cloud), **Sitecore XP**, **Contentful**, **Contentstack**, **Sanity**, **Drupal**, **WordPress**, and **Gradial ACI**.
The mechanics differ by platform — what a template is called, where drafts live, how staging and publishing work — and Gradial uses each platform's own model. Content paths in the examples below use AEM-style paths; substitute the equivalent for your platform. See [Integrations](/docs/integrations-administration-and-setup/integrations/get-started-with-integrations) for the current list of connected platforms.
***
## Option 1: New Page from Existing Reference Page (Copy Page)
**When to Use:** You need to create a page similar to one that already exists. This is the most common and fastest approach.
### Why This Works Best
Most new pages are variations of existing ones. Rather than starting from scratch, copying an existing page gives you a proven structure with all the correct components already in place. You simply update the content.
### How It Works
**Step 1: Identify Your Reference Page**
Find an existing page in your CMS that closely matches what you need. This becomes your template.
**Step 2: Create the Task**
From your Gradial project dashboard, click **New Task** and select the new page option. Provide a task title and select the appropriate brand.
**Step 3: Reference the Existing Page**
In your prompt, specify the reference page location and the new page details:
```
Create a new page at location /content/mysite/en/news/2025/new-article
Use /content/mysite/en/news/2025/existing-article as the reference structure
Update the content with the following:
- Title: [New Title]
- Body content: [New content]
- Hero image: [New image path]
```
**Step 4: Generate and Review**
The agent will create a new page with the same component structure as your reference, populated with your new content.
### Tips for Success
* Choose a reference page that matches your desired layout as closely as possible
* The reference page should use the same template type as your target
* Provide clear content for each section you want updated
***
## Option 2: New Page from Templates & Patterns
**When to Use:** You want to build a page from your design system's established patterns rather than copying a specific existing page.
### Understanding Design Systems & Patterns
Design Systems in Gradial organize your CMS components into reusable patterns grouped by page type. For example, you might have different pattern sets for Homepage, Blog Article, Product Detail, and Landing Page templates.
Each Design System contains the specific component patterns available for that page type, giving the agent a clear reference for what building blocks are available.
### Prerequisites
Before using this approach, you'll need:
1. **Golden Pages** created for your template types — see the [Golden Pages Guide](/docs/creating-new-experiences/golden-pages)
2. **Design System patterns** ingested from those Golden Pages — see [Design Pattern Ingestion](/docs/creating-new-experiences/design-pattern-ingestion)
### How It Works
**Step 1: Create the Task**
From your Gradial project dashboard, click **New Task**. Provide a task title and select the appropriate brand and page template.
**Step 2: Specify the Design System**
In your prompt, reference the specific Design System to use:
```
Create a new page at location /content/mysite/en/products/new-product
Use the Product Detail Design Patterns
Include the following sections:
- Product Hero Banner
- Product Features Grid
- Product Specifications Table
- Related Products Carousel
```
**Step 3: Provide Content Requirements**
Give the agent the content for each pattern:
```
Hero Banner:
- Headline: "Introducing Product X"
- Subheadline: "The next generation of innovation"
- CTA: "Learn More" linking to /content/mysite/en/contact
Features Grid:
- Feature 1: Title, description, icon
- Feature 2: Title, description, icon
[etc.]
```
**Step 4: Generate in Gradial Studio**
Navigate to Gradial Studio and click "Draft with AI." The agent will select appropriate patterns from your Design System and populate them with your content.
### Pattern Selection Best Practices
* Select only the patterns needed for your specific page to avoid overloading agent context
* Alternatively, specify the Design System name directly in your prompt
* Use unique, descriptive pattern names to avoid confusion between similar layouts
***
## Option 3: New Page from Copy Doc or Creative Brief
**When to Use:** You have written content (Word document, Google Doc, creative brief, or transcript) that needs to be structured into a page in your CMS.
### Supported Source Types
* Word documents (.docx)
* PDF documents
* Google Docs (shared link)
* Creative briefs
* Content transcripts
### How It Works
**Step 1: Create the Task**
From your Gradial project dashboard, click **New Task** and select the new page option. Provide a task title and select the appropriate brand and page template.
**Step 2: Attach Your Content Source**
Upload or link your document. Gradial will analyze the content structure.
**Step 3: Create the Task**
Click **Create as Draft** to initialize the page creation task.
**Step 4: Generate in Gradial Studio**
Navigate to Gradial Studio and click "Draft with AI." The agent will:
* Analyze your document's content structure
* Map content to appropriate components from your Design System
* Create a digital copy doc (page blueprint) with:
* Specific components selected for your content
* Content formatted and laid out appropriately
* Suggested image/video/media placements
**Step 5: Review and Refine**
Review the generated digital copy doc in Gradial Studio. Adjust component selections or content placement as needed.
**Step 6: Generate the Page**
Click **Back to Task** and select **Start**. Gradial will:
* Create the new page directly in your CMS
* Upload assets to your DAM
* Configure components as specified
* Ensure consistent formatting
### Tips for Document Preparation
* Use clear headings in your document to help the agent identify content sections
* Include notes about desired layout or component preferences
* Provide image references or paths where visuals should appear
***
## Option 4: New Page from Figma Design
**When to Use:** You have a Figma design file that needs to be translated into a production page in your CMS.
### Prerequisites
* Figma design that visually aligns with your production components
* Design uses components/patterns that exist in your Design System
* Proper Figma access permissions configured
### How It Works
**Step 1: Create the Task**
From your Gradial project dashboard, click **New Task**. Provide a task title, select the brand and page template.
**Step 2: Select Figma as Your Source**
Choose the Figma Design option and provide:
* Figma file URL
* Specific frame or artboard to convert
**Step 3: Create the Task**
Click **Create as Draft** to initialize the task.
**Step 4: Generate in Gradial Studio**
Click "Draft with AI." The agent will:
* Analyze the Figma design visually
* Map design elements to production components in your CMS
* Extract content (text, image references)
* Create a digital copy doc matching the design intent
**Step 5: Review Component Mapping**
This step is critical. Verify that:
* Design elements mapped to the correct components in your CMS
* Layout structure is accurately represented
* Content extracted correctly from the design
**Step 6: Generate the Page**
Once satisfied with the digital copy doc, click **Start** to create the production page.
### Best Practices for Figma-to-CMS
**Design Alignment:** Ensure your Figma design uses visual patterns that correspond to actual components in your CMS. Custom designs that don't match existing components will require additional development.
**Component Recognition:** The agent maps designs based on visual similarity to ingested patterns. Use consistent design patterns that match your Design System.
**Content Extraction:** Text and image placeholders in Figma will be extracted. Use realistic content in your designs for best results.
**Iteration:** Figma-to-CMS often requires iteration. Review the initial output carefully and provide feedback to refine the mapping.
***
## Choosing the Right Approach
```
┌─────────────────────────────────────────────────────────────────┐
│ Which approach should I use? │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────────────┐
│ Do you have a similar │
│ existing page to copy? │
└───────────────────────────────┘
│ │
YES NO
│ │
▼ ▼
┌────────────────┐ ┌──────────────────────────┐
│ Copy Existing │ │ Do you have a Figma │
│ Page │ │ design to implement? │
└────────────────┘ └──────────────────────────┘
│ │
YES NO
│ │
▼ ▼
┌────────────────┐ ┌─────────────────────┐
│ From Figma │ │ Do you have written │
│ Design │ │ content/brief? │
└────────────────┘ └─────────────────────┘
│ │
YES NO
│ │
▼ ▼
┌────────────────┐ ┌────────────────┐
│ From Copy Doc │ │ From Templates │
│ / Brief │ │ & Patterns │
└────────────────┘ └────────────────┘
```
***
## Common Workflow: Starting the Task
Regardless of which approach you choose, all new page tasks follow this general flow:
1. **Create Task** → New Task from project dashboard
2. **Configure** → Set title, brand, template, source
3. **Draft** → Generate in Gradial Studio with AI
4. **Review** → Verify digital copy doc
5. **Generate** → Create page in your CMS
6. **Finalize** → Review in your CMS, publish via standard workflow
***
***
## Who this is for
| Role | What Gradial handles |
| :------------------------------ | :--------------------------------------------------------------------------------------- |
| **Digital Marketing Manager** | Launch dates that hold, because page builds stop being the dependency |
| **Web Producer** | The page built to spec on the first pass, so the work is review rather than data entry |
| **Content Author / Copywriter** | Copy going live as written, without a transcription step in between |
| **Designer / DesignOps** | Designs published as designed — read from the Figma file rather than reinterpreted |
| **Product Marketer** | A one-pager or spec sheet becoming a real product page without a separate request |
| **Agency Partner** | Creative delivered as an input to execution, not the start of another coordination cycle |
### How this maps to your function
Your launch calendar assumes a page build takes a known amount of time, and it usually doesn't — so either the date slips or the scope does. When page creation runs from the brief you already wrote, you can plan the campaign you actually want: a hub plus regional variants plus the product pages, rather than whichever subset fits the production window.
Building a page from a design file is mostly transcription — and transcription is where the errors are. Gradial does that pass and leaves you the judgment: is this the right component for this section, does the hierarchy read correctly, is anything missing. You review a built page instead of building it.
The gap between the Figma file and the published page is where design intent goes missing — usually not through disagreement but through a hundred small interpretation calls made under time pressure. Gradial reads the design directly and populates it into your approved component structures, so what ships is closer to what was designed, and brand and accessibility checks run on the output either way.
# Working with Reusable Content
Source: https://docs.gradial.com/docs/creating-new-experiences/working-with-fragments
How Gradial detects, edits, and governs reusable content blocks and structured content items across platforms.
## Why This Needs Care
Reusable content is the feature that saves the most time and causes the most incidents. A single block — a disclaimer, a promo banner, a product spec table — lives in one place and renders on eighty pages. Update it once and eighty pages are correct. Update it without knowing where it appears, and you've changed eighty pages you didn't intend to, on brands and in regions that weren't part of the request.
Most teams learn this the hard way, then over-correct: reusable content becomes something only two people are allowed to touch, and the time it was supposed to save goes back into the queue.
Gradial's approach is to make the scope visible before the change happens.
***
Most enterprise platforms share a common pattern: some content lives directly on a page, and some is managed centrally and surfaces in many places at once. This second category — reusable content — requires extra care, because a change at the source propagates to every page or asset that references it.
This page covers how Gradial identifies and handles reusable content, what operations are supported, rules you can configure, and governance best practices.
***
## Two Types of Reusable Content
Reusable content across all supported platforms falls into two broad categories.
Content **and** presentation bundled together — a header, footer, promo banner, or CTA section rendered as a complete visual unit. One change affects every page it appears on.
Content **only**, with no layout attached — a set of fields (headline, body, image reference, metadata) consumed and rendered independently by each channel or page.
| | Layout-based block | Structured content item |
| -------------- | -------------------------------- | ------------------------------------ |
| **AEM** | Experience Fragment (XF) | Content Fragment (CF) |
| **Sitecore** | Partial Design | Datasource item |
| **Contentful** | Referenced Entry (layout-driven) | Entry (data source) |
| **Marketo** | Snippet, shared template module | Token, custom object |
| **SFMC** | Content Block | AMPscript snippet, data-driven block |
***
## How Gradial Identifies Reusable Content
You don't need to know whether content lives directly on a page or inside a reusable block. **Gradial detects this automatically.**
When you describe a change — "update the headline in the hero section" — Gradial inspects the page, determines whether that content is sourced from a reusable item, and surfaces that information before applying any changes.
| Scenario | Gradial behavior |
| ------------------------------------------------- | --------------------------------------------------------------------------- |
| Content lives directly on the page | Change is applied to the page |
| Content is sourced from a layout-based block | Gradial identifies the block and applies the change there |
| Content is sourced from a structured content item | Gradial identifies the item and applies the change to the appropriate field |
This means you can point Gradial at a page URL and describe what you want changed — Gradial figures out where to make the edit.
***
## What Gradial Can Do
* **Edit** — Update text, links, images, or field values inside an existing block or item
* **Copy** — Duplicate a reusable block or structured item to create a new variant
* **Move** — Relocate a reusable item to a different folder, path, or location in your content hierarchy
* **List** — Surface all instances where a reusable item is referenced, so you know the blast radius before making a change
* **Replace or reorder** — Swap a component within a layout block, reorder sections, or remove an element
* **Create new** — Build a new reusable block or structured item from a Figma file, Word doc, or URL
* **Place on a page** — Reference a new or updated item from a specific page or set of pages
***
## Safe by Default
Gradial's default behavior when editing reusable content is to **create a launch or variation** rather than modifying the original directly. This means:
* **No unintended propagation** — The original stays unchanged until you explicitly approve and publish
* **Review before it goes live** — Changes can be validated in a staged environment first
* **Rollback capability** — The original version is preserved if changes need to be reverted
Reusable content changes propagate to every page or asset that references the source item. Before running, use Gradial's **List** capability to confirm which pages are affected.
***
## Rules: Simplifying Fragment Management
Gradial allows you to configure rules that reduce the technical knowledge business users need to work with reusable content. Instead of knowing which content model to use, which fields map to which components, or which items require elevated review — users describe what they want, and rules handle the rest.
### Model / Template Selection
**Problem:** Users shouldn't need to know which content model or template to use for different content types.
**Solution:** Rules that automatically select the correct model based on the type of content being created or updated.
| Rule example | Behavior |
| ----------------------------- | ------------------------------------------------------------ |
| "Product description" content | Gradial automatically uses the Product content model |
| FAQ content | Routes to the FAQ model, ensuring consistent field structure |
| Legal disclaimer | Uses the Legal content model and flags for compliance review |
### Naming Conventions
**Problem:** Inconsistent naming makes reusable content hard to find, audit, and govern over time.
**Solution:** Rules that enforce naming patterns automatically when Gradial creates or copies items.
| Content type | Generated name pattern |
| --------------------- | ---------------------------------------------- |
| Product content items | `[product-line]-[product-name]-[content-type]` |
| Campaign blocks | `[campaign-id]-[region]-[component]` |
| Layout blocks | `[site]-[section]-[variant]` |
### Field Mapping
**Problem:** Business users don't know which fields in a content model map to which visible elements on a page.
**Solution:** Rules that translate natural language intent to specific field names.
| User says | Maps to |
| ------------------------ | ---------------------------------------------- |
| "Update the headline" | `fragment.title` field |
| "Change the description" | `fragment.bodyText` field |
| "Update the CTA" | `fragment.ctaText` + `fragment.ctaLink` fields |
### Governance Warnings
**Problem:** Some reusable items require extra review, but users don't always know which ones.
**Solution:** Rules that surface warnings when high-impact items are being modified — without blocking the workflow.
| Rule trigger | Warning shown |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Any item in the `legal-*` namespace | "This content contains legal copy — ensure compliance review before publishing" |
| Site-wide layout blocks (header, footer) | "This block appears across the entire site — verify with the governance team before promoting" |
| Items referenced in more than 20 pages | "This item is referenced in \[N] pages — use List to review impact before running" |
***
## Governance Best Practices
Fragment changes can have wide downstream impact. Establishing clear ownership before you scale Gradial usage on reusable content prevents surprises.
### Ownership by content type
| Content type | Suggested governance |
| --------------------------------------------- | ------------------------------------------------------ |
| Site-wide layout blocks (header, footer, nav) | Senior stakeholder or web governance approval required |
| Campaign-specific blocks | Marketing team ownership with standard review |
| Legal / compliance content | Legal review required before any change |
| Localized variants | Regional team approval plus global oversight |
### Versioning and documentation
* Maintain a changelog for high-impact reusable items
* Document the reason for each significant change
* Set review dates for time-sensitive content (e.g., seasonal promotions)
* Use Gradial's Work Log as your audit trail for agent-made changes
### Cross-team coordination
* Set up notification workflows when changes to shared items are proposed
* Use staging environments to validate impact before promoting
* For high-traffic items, schedule update windows during low-traffic periods
***
## Nesting: The Three-Layer Rule
Reusable content items can reference other reusable items, creating nested structures. While this enables flexibility, excessive nesting creates real problems: slower page rendering, difficult debugging, unpredictable update cascades, and author confusion about where content actually lives.
**Best practice: limit nesting to three layers maximum.**
```
Page
└── Layout block (Layer 1)
└── Structured content item (Layer 2)
└── Nested structured content item (Layer 3) ← MAXIMUM
```
**Signs you've over-nested:**
* Authors can't determine where content originates
* Small changes require tracing through multiple items
* Page previews don't match expectations
* Performance degrades on content-heavy pages
**How to simplify:**
1. Audit the full dependency tree for deep structures
2. Flatten items that are always used together — combine them into one
3. Accept intentional duplication when it's clearer than deep nesting
4. Document any nesting that remains, and why it's necessary
***
## Setting Up Rules in Gradial
Work with your Gradial administrator to configure rules for your environment:
List all content models, templates, and structured item types across your platform and their intended purposes.
Establish naming patterns for each content type — by team, campaign, region, or component type.
Identify how your business users naturally describe content elements, and map those phrases to the underlying field names.
Determine which items require elevated review and define the warning conditions that should surface for them.
Codify the three-layer rule in your team guidelines and configure Gradial to flag structures that exceed it.
***
## Platform Details
Select your platform for targeting conventions, terminology, and tips specific to your environment.
AEM has two distinct types of reusable content. Gradial detects which is in use automatically, but knowing the difference helps you write better prompts and understand impact.
### Experience Fragments (XFs)
Layout-based reusable blocks — components, design, and content bundled together. Stored at `/content/experience-fragments/`. Best for: headers, footers, promotional banners, navigation blocks.
**Gradial behavior:**
* Detects XF usage automatically when you target a page
* Creates a Launch or variation by default — does not edit the original directly
* XFs can have **variations** (e.g., "Web," "Email") — specify which if relevant
* Copy and Move operations respect the XF folder structure
**Targeting tips:**
* XF paths: `/content/experience-fragments/{site}/{locale}/{fragment-name}`
* To list all pages using an XF, ask Gradial to list references before editing
* After editing, preview on multiple representative pages before promoting the Launch
**Example prompts:**
```
Update the promo banner Experience Fragment at
/content/experience-fragments/acme/us/en/promo-banner.
Change the headline to "Experience the future of AI content automation."
List which pages use this XF before making any changes.
---
On the homepage at example.com/home, update the promotional
banner section — change the headline and remove the secondary CTA.
(Gradial will detect the XF automatically.)
---
Copy the Q3 Campaign Experience Fragment and rename it
Q4 Campaign. Update the headline and CTA for the new campaign.
```
***
### Content Fragments (CFs)
Structured content items — fields and data, no layout. Stored in the DAM at `/content/dam/`. Best for: product descriptions, author bios, FAQs, legal disclaimers. May feed web, email, app, and API consumers simultaneously.
**Gradial behavior:**
* Detects CF usage automatically when you target a page
* Creates a variation rather than editing the master by default
* Move and Copy operations preserve CF model associations
* Field mapping rules translate natural language to specific CF fields
**Targeting tips:**
* CF paths: `/content/dam/{project}/{folder}/{fragment-name}`
* Specify the field name when possible ("update the 'bodyText' field")
* Always check headless consumers — CFs may feed more than web pages
* List references before editing to understand full downstream impact
**Example prompts:**
```
In the 'Product Benefits' Content Fragment at
/content/dam/acme/fragments/product-benefits,
update the 'benefitsList' field — change the second bullet
to reflect the new pricing.
---
List all pages and channels that reference the 'Legal Disclaimer'
Content Fragment at /content/dam/acme/legal/disclaimer before
making any changes.
---
Move the seasonal-promo Content Fragment from
/content/dam/acme/campaigns/q3 to /content/dam/acme/campaigns/q4
and update the headline field.
```
Sitecore separates layout reuse from content reuse. Gradial detects which is in use when you target a page, but knowing the distinction helps with targeting precision.
### Partial Designs
Layout-based reusable blocks (SXA) — a named set of components and datasources applied to pages via Page Designs. Best for: headers, footers, shared promotional sections.
**Gradial behavior:**
* Detects Partial Design usage when you target a page and describe a shared section
* Edits are staged before publishing; must be published from the Partial Designs builder
* Copy creates a new named Partial Design; Move updates its location in the design hierarchy
**Targeting tips:**
* Specify by name: "the Global Header Partial Design"
* Confirm which Page Designs include this Partial Design before running
* List which pages use the design before making structural changes
**Example prompts:**
```
In the Global Header Partial Design, update the primary CTA
from "Request Demo" to "Get Started" and update the link to /get-started.
---
List all pages that use the Promotional Banner Partial Design
before I make changes to it.
---
Copy the Q3 Promo Partial Design and rename it Q4 Promo.
Update the headline and background image.
```
***
### Datasource Items
Content tree items that components point to for their data, stored separately from the page. Can be shared (affects many pages) or local (affects only one page).
**Gradial behavior:**
* Detects datasource items automatically when you target a page component
* Distinguishes shared vs. local datasources and surfaces this before editing
* Move operations update the datasource path reference in all components using it
* List shows all components and pages referencing a shared datasource
**Targeting tips:**
* Shared datasources: often at `/sitecore/content/{site-collection}/{site}/Data/`
* Specify the template field name when updating (e.g., "the 'Headline' field")
* Always confirm shared vs. local status before running — ask Gradial to list references first
**Example prompts:**
```
On the /platform page, update the hero component headline
to "The operating system for modern marketing."
(Gradial will detect whether the datasource is shared or local.)
---
List all pages that reference the hero datasource item at
/sitecore/content/acme/home/Data/Hero before editing it.
---
Move the shared CTA datasource from /sitecore/content/acme/Data/CTAs/Q3
to /sitecore/content/acme/Data/CTAs/Q4 and update the link field.
```
Contentful's model is entirely Entry-based. Whether an Entry is "reusable" depends on how many other Entries or pages reference it via Reference fields.
**Gradial behavior:**
* Detects Entry references when you target a page — surfaces how many other pages use the same Entry
* Saves changes as Drafts; explicit publish required
* Copy creates a new Entry with the same content model; Move updates folder/path organization
* List shows all Entries and pages referencing a given Entry
**Targeting tips:**
* Entry IDs are the most reliable targeting method (stable regardless of name changes)
* Find Entry IDs in the Contentful app URL: `app.contentful.com/spaces/{space}/entries/{entry-id}`
* Specify the field name for structured updates ("update the 'legalDisclaimer' field")
* Use the References panel in Contentful or ask Gradial to list references before editing
**Example prompts:**
```
Update Entry ID abc123def. Change the 'headline' field to
"AI-powered content operations for enterprise teams."
First, list how many pages reference this Entry.
---
On the page at example.com/solutions, update the hero banner.
Change the headline and CTA — do not change the background
image Entry reference.
(Gradial will identify the Entry automatically.)
---
Copy the Q3 Hero Banner Entry and create a Q4 version.
Update the headline and CTA fields for the new campaign.
```
Marketo's reusable content is oriented around email and landing page assets.
### Snippets
Centrally managed HTML content placed into emails and landing pages. Updating and re-approving a Snippet propagates to every asset using it.
**Gradial behavior:**
* Creates a draft version before editing if the Snippet is currently approved
* List shows all emails and landing pages using a Snippet
* Copy creates a new Snippet; Move updates its Design Studio location
* After editing, affected assets must be re-approved in Marketo
**Example prompts:**
```
List all emails using the "Q3 Legal Footer" Snippet,
then update the disclaimer text with the version
in the attached document.
---
Copy the Q3 Promotional Snippet and create a Q4 version.
Update the headline and offer details.
---
Move the "Legal Disclaimers" Snippet folder from
Design Studio/Q3 to Design Studio/Archive/Q3.
```
***
### Tokens
Program-scoped variable content (`{{my.headline}}`) inherited by all assets within a program.
**Gradial behavior:**
* Token changes apply to all assets in the program immediately
* List shows all assets in the program that use a given token
* Always specify the program name when targeting
**Example prompts:**
```
In the Q3 Launch Campaign program, list all assets using
{{my.heroHeadline}}, then update the token value to
"Automate your content operations — from brief to live."
```
SFMC's reusable content lives in **Content Builder**, oriented around email and journey assets.
### Content Blocks
Named, centrally stored blocks referenced across multiple emails. Changes render on next preview or send — no separate publish step. Gradial saves a new version rather than overwriting.
**Gradial behavior:**
* Detects Content Block usage when you target an email and describe a shared section
* Copy creates a new Content Block; Move updates its Content Builder folder location
* List shows all emails referencing a Content Block
* For journey-based emails, Gradial edits the content asset — re-activation in Journey Builder stays with your team
**Targeting tips:**
* Reference by name and folder path: "the 'Q3 Legal Footer' block in Compliance/Footers"
* Organize Content Builder into clearly named folders — it makes targeting significantly more reliable
* For blocks in active journeys, coordinate timing carefully — changes render on next execution
**Example prompts:**
```
List all emails using the "Q3 Legal Footer" Content Block
in the Compliance/Footers folder, then update the
disclaimer text with the attached version.
---
In the email "Campaign Q3 Master," update the hero block.
Change the headline to "The future of content operations is here."
(Gradial will identify the Content Block automatically.)
---
Copy the "Q3 Hero Block" from Campaign/Q3 and move it to
Campaign/Q4. Update the headline and CTA link.
```
***
***
## Who this is for
| Role | What Gradial handles |
| :------------------------------ | :--------------------------------------------------------------------------------- |
| **Web Producer** | Knowing what a shared-block change will touch before it touches it |
| **Content Ops** | Reusable content usable by the whole team, not just the two people trusted with it |
| **Legal / Compliance Reviewer** | A disclaimer updated once and correct everywhere it renders |
| **Brand Manager** | Shared components staying consistent as the brand evolves |
| **Regional Marketer** | Your market's overrides preserved when a shared block changes upstream |
# Frequently Asked Questions
Source: https://docs.gradial.com/docs/faqs/faqs
Answers to the most common questions about Gradial — what it is, how it works, integrations, security, and getting your team up and running.
Gradial is the secure marketing harness that turns a fragmented lifecycle into governed execution — a layer that sits across your existing martech stack and executes the jobs between brief and live.
Enterprise organizations already have the right tools: a CMS, a DAM, a ticketing system, design tools, email platforms. The problem is the workflow between them. Every handoff is manual, every tool creates a queue, and quality is inconsistent.
Gradial fills that gap with a coordinated team of specialized AI agents that can author, update, tag, QA, schedule, and publish content end-to-end — across your existing systems, without replacing them, with brand, accessibility, and compliance checks applied to every output.
[Learn more about what Gradial is →](/docs/getting-started/what-is-gradial)
An enterprise marketing harness is the scaffolding around a large language model that makes it actually work: the tools it can call, the integrations into your systems, the context it reasons over, the memory it carries between jobs, the workspace it operates in, and the guardrails that constrain it.
The general concept is also called an *agentic harness* or *agent harness*. What makes one an **enterprise marketing** harness is that all of it is applied to the systems, skills, standards, and approval paths enterprise marketing runs on — which is why Gradial spans the whole lifecycle rather than covering one stage of it.
[What is an enterprise marketing harness? →](/docs/getting-started/what-is-an-agentic-harness)
A point solution gives you depth at one lifecycle stage, but nothing carries between stages — each tool is another contract, integration, and manual handoff. A copilot drafts and suggests inside one application, but a person still performs the work in the system of record.
A harness executes across the whole lifecycle, inside your existing systems, under one set of governed controls. The practical test: can it change something in your CMS, against your standards, with an audit trail, without a person carrying the work across a seam?
[Compare the approaches →](/docs/getting-started/what-is-an-agentic-harness#enterprise-marketing-harness-vs-other-approaches)
No. Gradial is an execution platform, not a chat interface or copilot.
While you can give Gradial tasks using natural language, the platform's agents actually complete the work end-to-end inside your connected systems — navigating your CMS, DAM, ticketing tools, and email platforms the same way a skilled team member would. The output is a published page, a tagged asset, a completed ticket, or a QA report — not a draft sitting in a text box for a human to copy and paste.
Gradial's agents cover a broad range of marketing and content operations work:
* **Content updates** — from a single copy change to bulk updates across hundreds of pages simultaneously
* **New page creation** — from a brief, Figma design, Word doc, or existing page reference
* **Email authoring** — building and publishing emails, variants and journeys in connected platforms including Marketo, Salesforce Marketing Cloud, HubSpot, Braze, Airship and MoEngage
* **Asset management** — uploading, tagging, naming, applying metadata schemas, and retrieving assets across DAMs
* **QA and accessibility** — brand accuracy, WCAG 2.2 AA compliance, SEO, and custom governance rules on every output
* **Translation and localization** — multi-language and multi-region content execution at scale
* **Campaign execution** — turning a campaign brief into a structured set of work across every channel it touches: web, email, social, paid media and commerce
* **GEO analysis** — tracking how your brand appears in AI-generated answers and surfacing optimization opportunities
[See the full scope of Gradial in Action →](/docs/gradial-prompt-library/customer-use-cases)
Four things set Gradial apart:
1. **Execution, not just generation.** Gradial's agents don't hand you a draft — they complete work inside your actual systems.
2. **Orchestration across your full stack.** A single task can touch your CMS, DAM, ticketing system, and email platform without manual handoffs between each.
3. **Built-in governance.** QA, accessibility, brand, and compliance checks run automatically on every output — not sampled occasionally.
4. **Multi-model by design.** Gradial selects the best AI model for each task and continuously evaluates output quality in production — so performance improves over time and you're never locked into a single vendor.
[See what makes Gradial different →](/docs/getting-started/what-is-gradial#what-makes-gradial-different)
***
## Getting Started & Access
* **Existing customers:** Log in at [app.gradial.com](https://app.gradial.com). If you don't have an account yet, ask your Gradial org admin to invite you — see [Manage Team Members](/docs/integrations-administration-and-setup/managing-access/manage-team-members).
* **Evaluating Gradial:** [Request a demo](https://www.gradial.com/request-demo). Demos are run against your actual CMS and content — not a generic sandbox — so you see agents working on your environment.
End-to-end onboarding typically takes **6–12 weeks**, depending on the complexity of your setup and the number of use cases in scope. The process follows four phases:
1. **Environment Discovery** — structured sessions to map your tech stack, workflows, and use case priorities. You can start gathering inputs before any sessions are scheduled.
2. **Credentials & Access** — connecting your CMS, ticketing system, SSO, DAM, and other integrations. The actual configuration is fast once credentials are in hand. This phase is almost always the longest because it depends on your IT team's internal security review and provisioning process, not on Gradial.
3. **Platform Onboarding** — configuring golden pages, design patterns, QA rules, and running end-to-end validation of your use cases with your Gradial onboarding manager.
4. **Training & Graduation** — Gradial trains your core team; your core team trains the wider user group. Onboarding concludes with a formal **Grady's Graduation** sign-off, confirming all use cases are validated, your team is trained, and named owners are in place.
The single biggest lever on timeline is how quickly your organization can issue credentials. Submitting one consolidated request — CMS service account, ticketing API credentials, SSO configuration — rather than spreading asks across multiple tickets can take weeks off Phase 2.
[Onboarding Checklist →](/docs/getting-started/onboarding-checklist)
You'll need one of your own engineers or MarTech architects to handle the integration setup — someone with access to your CMS, ticketing system, and other endpoints who can provision service accounts and configure permissions. This is an internal resource requirement, not a developer engagement.
A Gradial engineer is **not normally required** for setup. The onboarding checklist and integration documentation are designed to be self-service, and your Gradial onboarding manager guides you through each phase. For complex environments or custom configurations, a Gradial engineer is available to support.
Once integrations are live, day-to-day use requires no technical involvement. Content managers, editors, and communications leads run tasks directly — no engineering support needed.
[Onboarding Checklist →](/docs/getting-started/onboarding-checklist) · [Integration Guides →](/docs/integrations-administration-and-setup/integrations/get-started-with-integrations)
Gradial does not provide a generic sandbox environment. Because every customer's CMS, DAM, and content structure is unique, environments are set up as part of your contracted onboarding — not as a shared demo instance.
During Phase 3 of onboarding, your team sets up a dedicated sandbox or testing area within your own CMS so you can run agents and validate outputs safely before going live. Your Gradial onboarding manager guides you through this step.
All tasks also go through a review step before anything is published, so nothing reaches your live site until a human approves it — providing a safety net regardless of environment.
[Onboarding Checklist: Phase 3 →](/docs/getting-started/onboarding-checklist)
Before technical setup begins, you'll want to gather:
* A service account with appropriate CMS permissions (AEM, Sitecore, Contentful, or your connected platform)
* API credentials for your ticketing system (Jira, Workfront, Wrike, or Asana)
* SSO configuration details for your identity provider (Entra ID, Okta, or custom OIDC)
* Example tickets that represent your team's most common task types
* Any brand guidelines, QA checklists, or content standards documents
* Candidate pages for golden page configuration (examples of ideal page structures)
[Phase 1 of the onboarding checklist walks through this in detail →](/docs/getting-started/onboarding-checklist)
Go to **Settings → Team Members** in the Gradial app. You can invite users by email, assign org-level and workspace-level roles, and deactivate users who no longer need access.
[Manage Team Members →](/docs/integrations-administration-and-setup/managing-access/manage-team-members)
Yes. Gradial supports:
* Microsoft Entra ID (Azure AD)
* Okta (OIDC)
* Custom OIDC providers
SSO is configured by your IT or platform admin during initial setup.
[Configure SSO →](/docs/integrations-administration-and-setup/managing-access/sso)
Anyone on your team can be given access — Gradial is designed for content managers, authors, editors, and communications leads, not just technical users.
Permissions are structured at two levels:
* **Organization roles** — control platform-wide access (Owner, Admin, Member, Viewer)
* **Workspace roles** — control what a user can do inside a specific workspace (Owner, Admin, Member, Viewer)
Users with **Org Member** or **Workspace Member** roles can create, edit, and run tasks — which covers the full day-to-day content workflow. Optional additional access — **Brand Manager** (manage rules) and **Designer** (manage design systems, personas, and audiences) — can be added on top of a user's organization role.
Org Admins and Workspace Admins handle configuration and permissions; everyone else just runs work.
[Roles & Permissions →](/docs/integrations-administration-and-setup/managing-access/roles)
Yes — Gradial is designed to be very easy to use. You describe what you want done in plain language, and the agent handles the rest. No CMS navigation, no manual handoffs between tools, no technical knowledge required to run tasks.
Two things make it especially approachable:
* **Natural language input** — describe a task the way you'd describe it to a colleague. "Update the hero headline on this page to reflect our summer campaign" is a complete task brief.
* **Grady** — the in-app AI assistant is available throughout the platform to answer questions in chat, explain features, and help you get more out of any workflow without leaving what you're doing.
Training is covered as part of onboarding (Phase 4), and most users are comfortable running standard content updates within their first session.
[Navigating the Platform →](/docs/getting-started/navigating-the-platform) · [Prompting an AI Agent →](/docs/getting-started/ask-grady)
***
## How Agents Work
When you create a task in Gradial (from the interface, a ticket, or a brief), here is what happens:
1. An agent reads the task description and identifies the target content and systems involved.
2. The agent retrieves relevant context — assets from the DAM, brand guidelines, templates, and content patterns for the relevant page type.
3. The agent executes the work — authoring, updating, tagging, or building — inside your connected systems.
4. Governance runs automatically: QA, accessibility (WCAG 2.2 AA), brand, and compliance checks are applied before the output reaches a human reviewer.
5. Your team reviews the output — with full control over how much oversight is applied, from full review to auto-approve for trusted task types.
6. The task is completed, status is updated in connected systems, and an audit trail is created.
For bulk operations, this cycle runs in parallel across all items simultaneously.
[How Gradial Works →](/docs/getting-started/how-gradial-works)
You don't choose an agent or a mode — you describe the job and Grady does it, drawing on the right expertise and the right connected systems. The jobs teams hand to Gradial most:
| Job | What it covers |
| ---------------------------------------- | --------------------------------------------------------------------------------------------- |
| **Update content that's already live** | Changes across web pages, from a single field to bulk operations across a whole site |
| **Build something new** | Net-new pages from a reference, brief, Word doc, Figma file, or prompt |
| **Make assets findable and usable** | Ingest, tag, name, govern and retrieve assets across connected DAMs |
| **Check the work before anyone sees it** | Brand, accessibility, compliance and custom quality checks on every output |
| **Build and send the campaign** | Emails, templates, variants, journeys and audiences in connected marketing platforms |
| **Turn a brief into executed work** | One campaign brief becomes every deliverable it implies, across every channel |
| **Localize for every market** | Multi-language and multi-region execution across pages, assets and video |
| **Find out what's working, then fix it** | AI-search visibility, CX audits, SEO and analytics — and the content changes that act on them |
| **Publish to channels** | Organic social, paid campaign structures, and commerce and product content |
For jobs that span several of these, Gradial sequences the work automatically — running in parallel what can run in parallel, holding what has to wait, and passing outputs between steps without a handoff.
[The jobs Gradial does →](/docs/getting-started/how-gradial-works) · [Customer Use Cases →](/docs/gradial-prompt-library/customer-use-cases)
Yes. Bulk operations are one of Gradial's core strengths. A single task can run across hundreds of pages simultaneously — with the same QA and governance checks applied to every item in the batch.
Common bulk operations include find-and-replace across a site section, applying a metadata schema update to a large asset library, running accessibility checks across all pages in a locale, and creating localized variants of a campaign landing page across multiple markets.
[Rework Sections and Reusable Content →](/docs/updating-existing-experiences-i-e-content-updates/medium-content-updates-in-gradial)
It depends on how your team configures oversight — and how far along you are in the learning curve.
Teams typically follow this progression:
* **Early:** Agents execute with frequent human review. The platform is calibrating to your standards.
* **Established:** Agents handle a wider range of tasks with lighter oversight. Human review shifts toward edge cases.
* **Advanced:** Agents operate autonomously on routine jobs. Teams focus on directing outcomes, not reviewing execution.
For any task type, you can configure full review, spot-check, or auto-approve. The level of autonomy is always in your control.
The single biggest lever is the quality of your task description. A clear objective, the specific change required, and one concrete example produces dramatically better output than a vague request.
Things that help:
* Describe the *goal*, not just the action (e.g., "Update the hero headline to reflect our Q3 campaign theme — concise, action-oriented, under 8 words" rather than "Change the headline")
* Reference a specific source URL for content updates
* Attach relevant brand guidelines or approved copy as context
* Configure golden pages so agents have a known-good structural reference for new page creation
[Prompting an AI Agent →](/docs/getting-started/ask-grady)
Grady is Gradial's in-app AI assistant, available throughout the platform to help you get more out of the product. You can ask Grady questions about how features work, get guided help creating tasks, or ask for context on any part of the Gradial workflow — directly inside the app, without leaving what you're doing.
***
## Integrations
Gradial supports a broad and growing range of endpoints — CMS platforms, DAMs, ticketing systems, email and marketing automation tools, design tools, analytics platforms, and more. The integration ecosystem is always evolving as new connectors are added.
For the current full list of supported integrations and setup guides, see the integrations documentation.
[Integrations Overview →](/docs/integrations-administration-and-setup/integrations/get-started-with-integrations)
Yes. Gradial supports **native MCP (Model Context Protocol) integration**, which allows teams to connect proprietary knowledge bases, internal AI context layers, or custom workflows directly.
This means you can:
* Connect internal systems that don't have a standard API
* Add proprietary brand or product knowledge as AI context
* Kick off Gradial tasks from Claude, Slack, or other MCP-connected tools without opening the Gradial interface
[Custom MCP Integration →](/docs/integrations-administration-and-setup/integrations/custom-mcp)
No. Gradial is designed as an overlay that works *across* your existing stack — not a replacement for it. Your CMS, DAM, ticketing system, and email platform stay in place. Gradial provides the execution layer that connects them.
***
## Quality & Governance
Every output Gradial produces is automatically checked against your organization's defined quality standards before it reaches a human reviewer. This includes:
* **Brand accuracy** — tone, voice, terminology, and visual standards
* **Accessibility** — WCAG 2.2 AA compliance on every page and component
* **SEO** — metadata, structure, and content quality rules
* **Regulatory and compliance** — custom legal, industry, or internal compliance requirements
* **Custom QA rules** — anything specific to your organization's standards
These checks run on 100% of outputs — not sampled occasionally.
[QA Reports →](/docs/quality-assurance-and-accessibility/qa-report) · [Accessibility Reports →](/docs/quality-assurance-and-accessibility/accessibility-report)
Gradial builds organizational context across four areas over time:
* **Brand voice and editorial standards** — from brand guidelines, tone documents, and editorial standards you bring in
* **QA thresholds** — your organization's specific accessibility, regulatory, and brand accuracy criteria
* **Content patterns** — how your pages are structured, how assets are named, how campaigns are briefed
* **Workflow and team preferences** — review levels, approval routing, publishing automation
As agents complete more tasks and your team reviews outputs, the platform develops a practical working understanding of your standards that goes beyond what a style guide alone can capture.
A golden page is an exemplary page in your CMS that agents reference as a structural and quality standard when creating new pages or templates. By designating golden pages, you give agents a known-good reference — ensuring new pages match the quality, structure, and component patterns already approved for your site.
[Golden Pages →](/docs/creating-new-experiences/golden-pages)
Yes. Gradial's Rules & Skills Manager lets you define organization-specific quality rules — custom brand checks, terminology requirements, legal disclaimers, regulatory compliance rules, or any criteria your team needs to enforce consistently.
[Rules & Skills →](/docs/marketing-brain/managing-skills)
***
## Security & Data
Gradial does not store your content permanently. It reads from and writes to your connected systems — your CMS, DAM, and email platform — which remain your systems of record. Task inputs and outputs are processed in transit; Gradial does not build a separate content repository.
Gradial requires a service account with read/write permissions scoped to the content paths agents are expected to work in. For AEM specifically, this means JCR path-level permissions, which are documented in detail in the integration guide.
Gradial follows the principle of least privilege — service accounts are scoped to only what is required.
[AEM Integration: Permissions →](/docs/integrations-administration-and-setup/integrations/aem/aem-on-prem) · [AEM Cloud →](/docs/integrations-administration-and-setup/integrations/aem/aem-cloud)
If your organization's network policy requires IP allowlisting for outbound connections from Gradial to your internal systems, consult the IP allowlist documentation for the current list of Gradial IP ranges.
[IP Allowlist →](/docs/integrations-administration-and-setup/ip-allowlist)
For detailed security documentation, compliance certifications, and data processing agreements, visit [gradial.com/security](https://www.gradial.com/security) or contact your Gradial account team via the [support portal](https://portal.usepylon.com/gradial).
***
## Troubleshooting & Support
Before re-running the task, check the prompt first. The most common cause of unexpected output is an underspecified task description. Add:
* The specific change you want (not just "update this page")
* The source URL or content item
* Any brand or style context the agent needs
* One example of the output format or tone you want
If the task description is clear and results are still inconsistent, check whether the relevant golden pages or QA rules are configured — agents produce better outputs when they have structural references to work from.
[Prompting Guide →](/docs/getting-started/ask-grady)
Start by verifying:
1. The service account credentials are still valid and haven't expired
2. The service account has the correct permissions on the relevant paths
3. Your organization's network/firewall allows outbound connections from Gradial's IP ranges
4. The integration is listed as active in **Settings → Integrations**
For AEM specifically, OAuth tokens expire and need to be refreshed — this is the most common cause of intermittent failures.
[AEM Troubleshooting →](/docs/integrations-administration-and-setup/integrations/aem/aem-overview) · [IP Allowlist →](/docs/integrations-administration-and-setup/ip-allowlist)
Gradial's security and privacy practices are documented at:
* [gradial.com/security](https://www.gradial.com/security) — security architecture, certifications, and data handling practices
* [gradial.com/privacy](https://www.gradial.com/privacy) — privacy policy and data processing information
For security review documentation, compliance reports, or data processing agreements, contact your Gradial account team or reach out via the [support portal](https://portal.usepylon.com/gradial).
* **Support portal:** [portal.usepylon.com/gradial](https://portal.usepylon.com/gradial) — submit tickets and track status
* **In-app:** Use the **Support** link in the Gradial app to open a ticket directly
* **Grady:** Ask Grady (the in-app AI assistant) for help with platform questions without leaving your current task
[Support Portal →](/support-portal)
The release notes page is updated with each major release — new features, improvements, and changes.
[Release Notes →](/release-notes/overview)
# Ask Grady
Source: https://docs.gradial.com/docs/getting-started/ask-grady
Grady is Gradial's AI agent. Talk to it in plain language to get content work done — no special syntax required.
Grady is the AI agent at the center of Gradial. You talk to it like you'd brief a colleague: describe what you need, point it to the right page or asset, and it takes care of the rest. There's no prompt template to follow and no special syntax to learn.
That said, a bit of clarity goes a long way. The guidance below isn't about learning a prompt format — it's about the same habits that make any good brief effective: say what you want, be specific about sources, and know when to break a big job into smaller ones.
***
## How Ask Grady works
You interact with Grady through the task interface. You can:
* **Describe what you need** in plain language — "Update the hero headline on this page to say X"
* **Attach the brief.** Drag in the Word doc, deck, PDF or spreadsheet you were already sent, and ask Grady to work from it. You don't need to retype a brief into a prompt — attachments are usually the fastest way to start.
* **Use @ to point at things.** Type **@** anywhere to reference a teammate, a workspace, another task, or a connected integration. Grady receives that reference as structured context, so "build this like @Spring Campaign Landing Page" is more precise than describing it. See [Mentions](/docs/platform/mentions).
* **Ask questions** — "What components are on this page?" or "Why did you put the content there?"
* **Iterate** — If the first result isn't right, follow up. "The CTA button is missing — can you add it back?" Grady treats every task as a conversation, not a one-shot instruction.
* **Ask for a plan first** — For complex work, ask Grady to outline its approach before executing. It's easier to correct a plan than a finished deliverable.
Two things worth knowing early: the [Customer Use Cases](/docs/gradial-prompt-library/customer-use-cases) library has real examples across every stage of the marketing lifecycle, each with a prompt you can copy and adapt. And if you find yourself typing the same request every week, save it as a **Prompt Template** — or put the whole task on a schedule with [Scheduled Tasks](/docs/workflow-management/scheduled-tasks) so it just runs.
***
## Ask Grady about your own Gradial data
Grady can answer questions about the work your team has already done in Gradial. Previously it could do the work but couldn't see its own record of it — anything spanning more than one task ("what's waiting on my team?", "who changed this page?") meant opening tasks one at a time.
Now you just ask, and Grady answers in the conversation, drawing on your tasks, artifacts, comments, activity history, and connected systems.
**Access:** Must be enabled for your organization. Contact your Gradial team to get access.
### What you can ask
| Kind of question | Example |
| ---------------------------- | ---------------------------------------------------------------------------------------------------- |
| **Status of work in flight** | "What's waiting for approval?" · "What's been sitting longest?" · "What's assigned to me this week?" |
| **Tracing what happened** | "Which task changed this page, and who ran it?" · "Did anything fail on that migration?" |
| **Across your team** | "What has my team shipped since Monday?" · "Which tasks are blocked and on what?" |
Grady can also act on what it finds rather than just reporting it — for example, locating an environment that already has your CMS configured and switching to it so the work can continue.
### What it can and can't see
* **Reads only.** Answering a question about your data never changes it. Grady queries your record of work; it doesn't edit it.
* **Your permissions apply.** Answers only ever include what everyone in that task can already see. Two people asking the same question can correctly get different answers, because they can see different things.
Be specific about the window and the scope you mean. "What's stuck?" is answerable, but "which tasks in this workspace have been waiting on approval more than three days?" gets you something you can act on directly.
***
### When you want a view, not an answer
If you find yourself asking the same question repeatedly, or you want something a team can look at rather than a reply in a thread, ask Grady to build you a **custom app** — a dashboard, report, or intake form built on the same live data, including the systems Gradial is integrated with.
See [Custom Apps](/docs/insights/custom-apps).
***
## Five habits that get better results
These apply whether you're asking Grady to swap an image or migrate a hundred pages.
### 1. State the objective and success criteria up front
Start with a single sentence: *what* you want and *how you'll know it's right*. "Update the pricing page" is a task title. "Change the monthly price from \$99 to \$89 and add '24/7 support' to the feature list" is something Grady can deliver against.
### 2. Point to exact sources
Name your sources explicitly. The more precise the source, the less Grady has to infer — and most of the time your source is a file or a link you already have.
Any of these work as a source:
* **A document** — attach the campaign brief, copy deck, product one-pager, or the spreadsheet of changes
* **A live URL** — "build this page from `https://www.example.com/products/premium-tier`"
* **A Figma file** — paste the frame link and Grady reads the design
* **A reference page** — "match the structure of our Standard Tier page"
* **An @ mention** — a workspace, another task, or a teammate whose work you want carried forward
```
Build a new product page for Premium Tier.
Source: the attached one-pager (Premium-Tier-Brief.docx)
Reference: match the layout of https://www.example.com/products/standard-tier
Assets: use the hero from the Spring 2026 campaign folder in the DAM
```
If your team works with CMS paths directly, those work too — a content path or DAM path is just as valid a source as a URL.
### 3. Break complex tasks into steps
For multi-stage work, ask for a plan before execution. This surfaces ambiguities early and keeps you aligned before the work starts.
### 4. Specify output format and constraints
Tell Grady how you want the output structured — and what it must and must not contain.
```
Hero section: Premium Product Launch
- Background image: use the approved hero from the Spring 2026 campaign folder
- Headline in title case, under 60 characters
- CTA button text: "Get Started"
- Include the standard pricing disclaimer
```
This applies to deliverables as well as pages. "Give me this as a Word doc I can send to legal", "put the results in a spreadsheet with one row per page", or "build me a slide for the Monday readout" all shape what you get back.
### 5. Use examples and reference pages
Grady is good at pattern matching. Pointing to a reference page that shows the right approach is often more effective than describing it in words.
***
## Where to provide standing instructions
Beyond the task itself, Gradial lets you embed guidance at multiple levels so Grady applies it automatically.
| Level | Use it for |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Skills** (organization or workspace) | Reusable expertise — how your team does its best work: proven workflows, process patterns, institutional know-how. This is where most standing guidance belongs. See [Managing Skills](/docs/marketing-brain/managing-skills) |
| **Foundational Guidelines** | Standards every output must meet — brand voice, legal disclaimers, accessibility criteria — kept in one governed, versioned library. See [Foundational Guidelines](/docs/marketing-brain/foundational-guidelines) |
| **Workspace** | Guidance that applies to a set of related work — preferred styles, available patterns, standard steps for that brand, region or team |
| **Task** | Details unique to one piece of work — the specific page, the specific change |
Alongside these, **[Memory](/docs/marketing-brain/memory)** carries decisions and context forward from completed work automatically, so your team doesn't restate the same things in every request.
**General principle:** start specific at the task level. As you notice yourself repeating guidance, promote it — to the workspace, then to a Skill or a Foundational Guideline.
Organizations that have been using Gradial for a while may still have **Rules** in place. Existing rules remain active; new standing guidance should go into Skills and Foundational Guidelines. See [Managing Rules (Legacy)](/docs/marketing-brain/managing-rules-legacy).
***
## When results aren't right
Grady can often debug itself. A direct follow-up question is usually the fastest path.
**Ask Grady directly:**
* "Why did you place that content in that component?"
* "The hero isn't showing in the preview but I can see it in the CMS editor. Can you debug and tell me what's wrong?"
* "Compare this page to \[reference page] and identify the gaps."
**Use Gradial's visibility tools:**
* **Diff viewer** — Compare before and after states to see exactly what changed
* **Workspace context** — View any additional context being passed in from the workspace
* **Skills panel** — See which organization and workspace Skills and guidelines are active on this run
* **Pattern list** — Each run shows which patterns Grady used, including pattern IDs
**Common edge cases:**
* **Secondary navigation not updating:** "Please fix the secondary sticky nav so it corresponds to the page content."
* **Inherited components not updating:** Some CMS components inherit from a blueprint and won't update until inheritance is broken. Try: "Break inheritance on \[component name]."
* **Ghost components:** Placeholder components after a list edit typically disappear once changes are promoted to production.
***
## Avoid context overload
There's a balance to how much instruction you provide. Too much context — or a very long task thread — can reduce output quality, because all previous output becomes input for each new run.
**Keep instructions focused.** If you find yourself writing a wall of text, break the work into multiple tasks instead.
***
## Getting help
When submitting a support request, include:
* **A clear title** describing the issue type and symptom (e.g., "Migration: Hero not showing" or "Content Update: Eyebrow text not replaced")
* **A short description** of the issue and any debugging steps you've already tried
* **A link to the task** in Gradial
* **Screenshots** from your CMS editor if relevant, since support may not have direct access to your environment
# How Gradial Works
Source: https://docs.gradial.com/docs/getting-started/how-gradial-works
The mental model behind Gradial: how agents receive work, execute it across your stack, and get smarter about your organization over time.
Gradial's operating model can be summarized in three words:
Work comes in from wherever it originates — Gradial's interface, a Jira ticket, a Workfront task, a brief or work request. No change to how you initiate work.
Agents read the task, understand the intent, and execute end-to-end across connected systems — without manual handoffs between tools.
Every output is checked against brand, accessibility, compliance, and QA rules the organization has defined — on every task, every time.
Everything about how Gradial works flows from this model.
***
## The Anatomy of a Task
To make this concrete, here is what a single task lifecycle looks like:
Via Gradial's interface, a connected ticketing system (Jira, Workfront, Wrike), or a brief or work request document. Work can also be pre-scheduled and queued with dependencies set in advance.
Reads the description, identifies the target content, and determines which systems are involved.
Pulls relevant assets from the DAM, references brand rules and guidelines, checks templates and content patterns for the relevant page type.
Authors, updates, tags, builds, or publishes as specified — navigating connected systems the way a skilled team member would.
QA, accessibility (WCAG 2.2 AA), brand, and compliance checks are applied to the output before it reaches a human reviewer.
The team reviews at whatever level of oversight is configured — full review, spot-check, or auto-approve for trusted task types.
Status updated across connected systems. Audit trail created. Follow-on tasks triggered if needed.
This cycle takes minutes for a standard content update. For bulk operations — updating hundreds of pages across a site — the same cycle runs in parallel across all items simultaneously.
***
## The Jobs Gradial Does
You don't pick an agent. You describe the job, and Grady does it — drawing on the right expertise and the right connected systems for the work in front of him. What follows is the range of jobs teams hand to Gradial, not a menu you have to choose from.
A headline, a CTA, an expired offer, a legal phrase across every regional homepage. From a single field to hundreds of pages, inside your CMS's own component structures and publishing rules.
Landing pages, product pages, campaign hubs — built from a Figma file, a Word brief, a reference URL, or a prompt, using the patterns your site already uses.
Ingest a campaign delivery, tag it against your real metadata schema, carry rights and campaign context over from the job ticket, and retrieve the right asset when another job needs it.
Brand accuracy, accessibility, legal and regulatory language, and your own custom criteria — applied to every output, not to a sample.
Emails, templates, variants, journeys and audiences in your marketing platform — with the same brand and compliance checks used on web content.
One campaign brief becomes every deliverable it implies, across every channel it touches, with dependencies sequenced and review gates in the right places.
Translate pages, assets and video in place — respecting inheritance and regional rules — without exports or file handoffs.
AI-search visibility, CX journey audits, SEO and analytics — and then the content changes that act on what they surface.
### One job, many systems
Most real work spans several of the jobs above and several of your systems. Gradial sequences that automatically — running in parallel what can run in parallel, holding what has to wait, and passing outputs between steps without a handoff.
**Example: launch a localized campaign landing page in three markets**
1. The brief is read and broken into work: one page build, three localized variants, QA on all four, and the assets each one needs
2. The primary page is built from the Figma reference
3. Required assets are retrieved from the DAM, rights-checked and tagged
4. Three regional variants are created
5. Brand, accessibility and compliance checks run across all four pages
6. Status is logged back to your work management system and the team is notified for review
What would typically require coordination across multiple tools, teams and handoffs is **one job** in Gradial.
***
## How Gradial Connects to Your Stack
Gradial is integration-first by design. A task that requires finding an asset, updating a CMS page, running a QA check, and logging the completion in a ticketing system is **one task** in Gradial — not four separate steps across four separate tools.
| Category | Supported platforms |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Content management** | Adobe AEM (6.5 and Cloud Service), SitecoreAI CMS (XM Cloud), Sitecore XP, Contentful, Contentstack, Sanity, Drupal, WordPress, Gradial ACI |
| **Digital asset management** | AEM Assets, Bynder, Sitecore Content Hub, Aprimo, Box, SharePoint, Google Drive |
| **Work management & ticketing** | Jira, Workfront, Wrike, Asana, monday.com, Azure DevOps |
| **Email & marketing automation** | Marketo, Salesforce Marketing Cloud, HubSpot, Braze, Airship, MoEngage, SendGrid |
| **CRM** | Salesforce CRM |
| **Audiences & journeys** | Adobe Experience Platform, Adobe Journey Optimizer, Adobe Target |
| **Paid media** | Google Ads, LinkedIn Ads, Reddit Ads |
| **Social** | LinkedIn, X |
| **Commerce** | Shopify, Salesforce B2C Commerce |
| **Creative & DCO** | Figma, DaVinci Commerce (Jivox) |
| **Analytics** | Adobe Analytics, GA4, Adobe Customer Journey Analytics, Google Search Console |
| **Productivity & collaboration** | SharePoint, Box, Google Drive, Slack, Word, Excel, PowerPoint |
| **Custom** | Your own REST API via its OpenAPI spec, or a secure MCP server — connect internal knowledge bases, proprietary data systems, or custom AI context layers |
Integrations are configured once during implementation. Once in place, they're available to every user and every job in the workspace — no per-task configuration required.
Availability varies by plan, and not every integration is enabled for every organization by default. The [Integrations Overview](/docs/integrations-administration-and-setup/integrations/get-started-with-integrations) lists what's currently set up for you; your Gradial team can confirm what's available on your plan.
[See full integration setup documentation →](/docs/integrations-administration-and-setup/integrations/get-started-with-integrations)
***
## Brand Intelligence — How Gradial Gets Smarter Over Time
An agent that can execute work is only as good as its understanding of what *good* looks like for a specific organization. Generic AI outputs are not enterprise outputs.
This is the brand intelligence layer: the encoded knowledge of how your brand sounds, how your content is structured, what your compliance requirements actually mean in practice, and how your team operates. Gradial builds this intelligence from the standards you configure and the work agents do — and applies it on every task, automatically.
Gradial builds organizational brand intelligence across four areas:
Organizations bring their brand guidelines, tone documents, and editorial standards into Gradial. Agents reference these on every content task. Over time, as agents complete more tasks and teams review outputs, the platform develops a working understanding of what on-brand actually means in practice — beyond what a style guide alone can capture.
What passes a QA check at a financial services company is different from what passes at a consumer brand. Gradial learns an organization's specific QA criteria — accessibility standards, regulatory language requirements, brand accuracy rules, custom checks — and applies them consistently. As those thresholds evolve, Gradial evolves with them.
Organizations develop patterns over time — how pages are structured, how assets are named, how campaigns are briefed. Gradial learns these patterns and applies them, so agents produce outputs that fit naturally into the existing environment rather than requiring extensive post-processing.
Some teams prefer agents to draft for review; others want agents to publish directly for certain task types. Some route approvals through specific channels; others use automated sign-off for routine work. Gradial learns these preferences and adjusts how it handles work accordingly.
### The progression most teams follow
| Stage | What it looks like |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Early** | Agents execute with frequent human review. The platform is calibrating to the organization's standards. Every review is input. |
| **Established** | Agents handle a wider range of tasks with lighter oversight. Outputs consistently meet the bar for common task types. Human review shifts toward edge cases. |
| **Advanced** | Agents operate with high autonomy on routine jobs. Teams focus on directing outcomes, not reviewing execution. |
The pace of this progression varies. Some teams move through all three stages in weeks; others take longer. The level of autonomy is always in the team's control.
***
Ready to go deeper? [Request a demo](https://www.gradial.com/request-demo) to see agents running against your actual CMS and content, or [navigate the platform →](/docs/getting-started/navigating-the-platform) to see how these concepts map to the Gradial interface.
# Navigating the Gradial Platform
Source: https://docs.gradial.com/docs/getting-started/navigating-the-platform
Navigate Gradial's AI agent platform for content operations — workspaces, settings, and environment configuration.
***
## Getting Started
Access the Gradial platform at [**app.gradial.com**](http://app.gradial.com). Upon logging in, you'll be greeted with a personalized welcome screen showing your recently visited workspaces and a search bar to quickly find what you need.
***
## Recommended Next Actions
Below the composer on the home page, Gradial surfaces a short list of relevant next actions — up to three concise, full-width suggestion rows. Quick Start remains below them, unchanged.
Recommendations are drawn from your recent work, how your organization is actually using Gradial, your onboarding state, and Gradial-curated highlights.
### What gets recommended
* **Follow-ups on recent work** — threads and tasks that need attention or are ready for review resurface as suggested next steps
* **Features your organization uses that you haven't** — when your org has adopted a capability you personally haven't tried, it can be surfaced to you, along with any onboarding or setup prerequisites
* **Gradial-curated highlights** — timed recommendations such as new releases, which appear while they're relevant and retire on their own
### Acting on a suggestion
Clicking a suggestion either populates the composer with a ready-to-run prompt or routes you directly to the relevant page. Clicking a suggestion does not hide it.
To dismiss one, use its dismiss control. Dismissing is permanent for you, and the next best candidate cycles into its place.
### How the list behaves
* **Permission- and readiness-safe** — suggestions are filtered by your permissions, feature availability, required integrations, and setup prerequisites, so you never see an action you can't take
* **Stable through the day** — the list stays consistent during a session and refreshes over time, so suggestions stay fresh without shifting under you mid-task
Recommended next actions must be enabled for your organization. Contact your Gradial team if you don't see them on your home page.
***
## Main Navigation
The left sidebar is your primary navigation hub, organized into these key sections:
### Top-Level Navigation
* **Home** — Your dashboard with recently visited workspaces and quick access features
* **Workspaces** — View and manage all available project workspaces
* **Design Systems** — Access design-related projects, reusable UI patterns, and component libraries
* **Rules & Skills** — Manage rules and skills for Authoring and QA agents
### Workspaces Panel
Below the main navigation, you'll find your workspaces organized by:
* **Pinned** — Quick access to your frequently used workspaces
* **Private** — Workspaces with restricted access (only you and invited members)
* **Public** — Workspaces accessible to all organization members
***
## Working with Workspaces
### Viewing Workspaces
Click **Workspaces** in the navigation to see all available project workspaces displayed as cards. Each card shows:
* Workspace name and icon
* Privacy status (Public/Private badge)
* Creation date
* Team member avatars
### Pinning Workspaces
Pin your most-used workspaces for quick access:
1. Hover over a workspace in the sidebar or workspaces view
2. Click the **three-dot menu** (⋯)
3. Select **Pin Workspace**
Pinned workspaces appear at the top of your sidebar under the "Pinned" section.
To unpin, follow the same steps and select **Unpin Workspace**.
### Filtering Workspaces
Use the sidebar filters to view workspaces by access type:
* Click **Private** to see only restricted workspaces
* Click **Public** to see organization-wide workspaces
* Click **Pinned** to see your bookmarked workspaces
***
## Inside a Workspace
When you enter a workspace, you'll see a task management view with:
| Column | Description |
| :--------------- | :--------------------------------------------------------- |
| **Title** | Task name and type indicator |
| **Status** | Current state (Planned, Ready for Review, Needs Attention) |
| **Priority** | Task importance level (None, Medium, High) |
| **Assignee** | Team member responsible |
| **Approver** | Person who will review the work |
| **Artifacts** | Associated files and outputs |
| **Date Created** | When the task was added |
### Workspace Actions
From the top-right of any workspace, you can:
* Access **Settings** (gear icon)
* **Create** new tasks or content
* View workspace members
***
## Inside a Task
Larger pieces of work — campaigns, batch operations, multi-step projects — used to make the task view crowded, and left project managers inspecting work one item at a time. The task experience now organizes each task into three focused areas: **Task**, **Subtasks**, and **Artifacts**.
### Task home
The task home puts the request, its inputs, previews of the primary artifacts, and the associated subtasks in one place. From here you can open any output directly in a full-screen preview rather than navigating away.
### Four ways to manage subtasks
Switch between views depending on what you're trying to see:
| View | Best for |
| ------------------- | ----------------------------------------------------------------------------------------- |
| **Workflow canvas** | Seeing the shape of the work — how steps connect and where the flow branches |
| **Table** | Working through dependencies and blockers directly, with interactive controls on each row |
| **Kanban board** | Moving work along — drag and drop a subtask to change its status |
| **Calendar** | Due dates and milestones, and spotting where the schedule is crowded |
### Reviewing artifacts
The two most recent outputs preview directly on the task home. For everything else, open the full artifact grid — inline thumbnails with instant expansion, and no page reload between them.
### Working with Grady alongside the task
Grady lives in its own resizable panel next to the task. You can:
* Resize it to give more room to either side
* Close it entirely to focus on the task
* Expand it into a full-screen chat for longer back-and-forth
* Move it to either side of the screen
### Activity and to-dos
The task activity and to-do list is expandable and handles long histories cleanly, without the stretching and text-wrapping problems of the previous view.
***
## Platform Settings
Access settings by clicking **Settings** at the bottom of the left sidebar.
### User Settings
#### User Profile
Manage your personal account:
* **Avatar** — Upload or change your profile picture
* **Display Name** — How your name appears across the platform
* **Email** — Your account email (read-only)
#### Appearance
Customize your visual experience with theme options:
* **Light** — Bright interface for well-lit environments
* **Dark** — Reduced eye strain for low-light conditions
* **System** — Automatically matches your device settings
### Organization Settings
#### Organization
Configure company-wide settings:
* Organization Name
* Organization Key (unique identifier)
* Logo upload
#### People
Manage team members:
* View all users with their email, role, and status
* Search by name or email
* Invite new members
* Adjust roles (Owner, Admin, Member)
* Monitor status (Active, Pending)
#### Integrations
Connect external tools and services:
* **CMS platforms** — read, author, and publish content
* **DAMs** — search, upload, and manage assets
* **Project management and ticketing** — receive and execute work from your queue
* **Marketing automation and email** — build and stage campaign deliverables
* **Analytics and personalization** — pull performance data and run experiments
* **Design** — import designs as a source for new pages
* **Custom** — MCP Agent for proprietary and internal systems
Existing integrations are displayed with their connection status and can be managed from this panel. See [Integrations](/docs/integrations-administration-and-setup/integrations/get-started-with-integrations) for the platforms available in each category.
#### Environments
Configure deployment environments:
* **Prod** — Production environment for live content
* **Testing** — Staging environments for QA (e.g., SFMC Testing)
***
## Workspace-Specific Settings
Each workspace has its own settings accessible via the **Settings** button in the workspace header.
### General Settings
* **Workspace Icon** — Visual identifier for the workspace
* **Workspace Title** — Name displayed across the platform
* **Description** — Optional details about the workspace purpose
### Access Control
Configure who can view and contribute:
**Public Workspace Toggle**
* **ON** — All organization members can access
* **OFF** — Only invited members can access
**Workspace Members**
* Organization admins and owners automatically have access
* Add specific members with the **Add Members** button
* Assign roles: Owner, Admin, or Member
* View all current members in a searchable table
### Environments
Configure which environments are available for this workspace:
* Select from organization-defined environments (e.g., SFMC Testing, Prod)
* Set the **Default Environment** for new tasks
* Save changes to apply environment configuration
***
## Quick Tips
**Keyboard Navigation**
* Use the search bar ("Ask Gradial...") to quickly find workspaces, tasks, or settings
**Workspace Organization**
* Pin your daily workspaces for one-click access
* Use Private workspaces for sensitive projects
* Use Public workspaces for cross-team collaboration
**Theme Recommendation**
* Try "System" appearance to automatically switch between light and dark modes based on your device settings
***
## Need Help?
* Use the **Ask Gradial** search bar for quick answers
* Contact your organization admin for access issues
* Check the integrations panel to ensure your tools are properly connected
***
# Onboarding Checklist
Source: https://docs.gradial.com/docs/getting-started/onboarding-checklist
Everything you need to do to get your Gradial environment set up and ready to use.
**Your Gradial organization must be provisioned before you can begin.** Contact your Gradial onboarding manager to initiate provisioning. While you wait, you can complete the discovery prep and security review steps in Phase 1 independently.
***
## Phase 1: Environment Discovery
Gradial leads structured discovery to understand your technology environment, content workflows, and use case priorities. Several steps in this phase can be started on your own before any sessions are scheduled.
You can complete this step independently, before discovery sessions begin. Gather:
* Key business objectives and success metrics for the engagement
* A sample of example tickets by type (small content updates, large updates, new page requests) — or an export from your ticketing system
* Workflow documentation for your current content process
* Examples of golden template or reference pages
Having these ready before your first session significantly shortens discovery.
Your IT or security team may need to review and approve Gradial's integration model before any system connections can be made. This is often the longest step in onboarding and is entirely driven by your organization's internal processes — start it as early as possible.
Your Gradial onboarding manager can provide security documentation, architecture diagrams, and compliance information to support this review.
Your Gradial onboarding manager will run structured interviews with your authoring, MarTech, and design leads. Use the inputs you prepared in Step 1. Sessions typically cover current workflows, use case priorities, and CMS/DAM environment specifics.
***
## Pre-Configuration: What to Collect Before Setup
Before connecting your systems in Phase 2, your team needs to gather the technical details that Gradial requires to operate correctly in your environment. Collecting these upfront — ideally in a shared document — prevents back-and-forth during setup and helps your IT team submit a single, complete credential request.
The six categories below cover everything you'll need. Use these as a checklist to work through with your CMS admin, MarTech lead, and IT team before your Phase 2 sessions begin.
One row per system you're connecting. This is what your Gradial onboarding manager will need to configure each integration.
| # | Platform | Endpoint / Connection URL | Status | Notes |
| :- | :------------------------ | :------------------------------------------------ | :----- | :--------------------------------------- |
| 1 | Your CMS (Sites + Assets) | e.g., `https://author.yoursite.com` | | Auth method (OAuth, service account) |
| 2 | Jira | e.g., `https://yourorg.atlassian.net` | | API token or service account credentials |
| 3 | Workfront | e.g., `https://yourorg.my.workfront.com` | | WT / Service Account |
| 4 | Marketo | e.g., `https://xxx-EOX-xxx.mktorest.com` | | REST API — OAuth 2.0 Client Credentials |
| 5 | SFMC | e.g., `https://mcXXX.auth.marketingcloudapis.com` | | OAuth 2.0 Client Credentials |
**What to confirm:** The correct author/API endpoint URL for each environment (sandbox vs. production), the authentication method required, and whether IP allowlisting is needed.
The CMS paths where Gradial's agent will be permitted to read and author content. Define one row per content root or DAM root.
| # | Content Path | Content Type | Scope | Platform | Notes |
| :- | :------------------------ | :----------- | :--------------- | :---------- | :-------------------------------------------- |
| 1 | `/content/your-site/en` | Pages | Path & sub-paths | CMS (Sites) | Site root — agent operates on all child pages |
| 2 | `/content/dam/your-brand` | Assets | Path & sub-paths | DAM | DAM root — all brand assets stored here |
Paths above are AEM-style examples — substitute the equivalent for your platform.
**What to confirm:** Exact content roots for your platform (JCR paths in AEM, and the equivalent elsewhere), which paths are in scope for the initial engagement, and any paths that should be explicitly excluded.
Maps public-facing URLs to their CMS content paths. Gradial uses this to resolve page targets when tasks are submitted with a URL rather than a path.
| # | Public URL | Content Path | Environment | Locale | Notes |
| :- | :----------------------------- | :---------------------- | :---------- | :----- | :------------------------------------------------ |
| 1 | `https://www.yoursite.com/en` | `/content/your-site/en` | Production | en-US | |
| 2 | `https://sandbox.yoursite.com` | `/content/your-site/en` | Sandbox | en-US | No public URL in sandbox — CMS author access only |
**What to confirm:** All environments in scope (sandbox, staging, production) and their corresponding CMS paths, plus any locale or region variations.
The page templates Gradial's agent will use when creating new pages. One row per template type.
| # | Template Name | Template Path | Type | Page Types | Notes |
| :- | :------------ | :---------------------------------------------------- | :------ | :------------------------------------------- | :---------------------------------------------------------- |
| 1 | Content Page | `/conf/your-site/settings/wcm/templates/content-page` | Default | Content pages, landing pages, campaign pages | Primary template — used when no other template is specified |
**What to confirm:** The template paths in your CMS for each page type in scope, which template is the default, and which page types map to which templates.
Golden Pages are the reference pages Gradial uses as a quality and structure benchmark for new page creation. One row per page type you want covered.
| # | Page Name | Content Path | Template Used | Purpose | Notes |
| :- | :----------------------------- | :------------------------------------------ | :------------ | :----------------------------------- | :------------------------------------------ |
| 1 | Homepage (Golden) | `/content/your-site/en/homepage` | Content Page | Brand-standard layout benchmark | Use as structure baseline for all new pages |
| 2 | Campaign Landing Page (Golden) | `/content/your-site/en/campaigns/golden-lp` | Content Page | Reference for campaign page creation | |
**What to confirm:** Which pages your team considers the gold standard for each page type, and that those pages are in a stable, published state accessible to Gradial. See [Golden Pages](/docs/creating-new-experiences/golden-pages) for more.
Specific existing pages used as layout or content references for new page creation tasks — distinct from Golden Pages in that these are real in-production examples rather than curated benchmarks.
| # | Page Name | Content Path | Public URL | Use Case | Notes |
| :- | :----------------- | :------------------------------------------------ | :--------------------------------------------- | :----------------------------- | :----------------------------------------------------- |
| 1 | Sample Campaign LP | `/content/your-site/en/campaigns/sample-campaign` | `https://www.yoursite.com/en/campaigns/sample` | Create new page from reference | Use as layout/content reference for new campaign pages |
**What to confirm:** A representative set of existing pages by page type that the agent can use as copy/structure references when Golden Pages don't exist yet.
Collect this information in a shared spreadsheet before your first Phase 2 session. Your Gradial onboarding manager can provide a template. Having it ready means your IT team only needs to be looped in once for a complete credential request — rather than piecemeal over several weeks.
***
## Phase 2: Credentials & Access
Connect Gradial to your CMS, ticketing system, and other tools. Once your organization is provisioned (Step 1), every subsequent step in this phase is self-service — follow the linked documentation and complete each integration independently.
**This phase is the critical path of your onboarding.** Connecting your systems depends on your IT team provisioning service accounts and completing security reviews — a process that can take anywhere from one week to two months. Start early and submit a single, consolidated credential request rather than individual asks spread out over time.
Your Gradial onboarding manager creates your organization account and sets your initial admin user. Your admin will receive an invite email once this is complete. All steps below can be completed independently after this point.
Log in at [app.gradial.com](https://app.gradial.com) and invite your team members. Identify your core team early — the admin, product owner, and use case leads who will own Gradial day-to-day. See [Manage Team Members](/docs/integrations-administration-and-setup/managing-access/manage-team-members) and [Roles & Permissions](/docs/integrations-administration-and-setup/managing-access/roles).
Connect Gradial to your identity provider (Microsoft Entra ID, Okta, or custom OIDC) to enable SSO. Recommended for all enterprise teams. See [Single Sign-On](/docs/integrations-administration-and-setup/managing-access/sso) for step-by-step configuration.
If your organization restricts inbound connections by IP, you may need to add Gradial's IP ranges to your allowlist before integrations can connect. Contact your Gradial onboarding manager for the current IP address list. This is typically handled by your network or security team alongside the credential provisioning in the steps below.
Connect Gradial to your CMS so agents can read, author, and publish content. Requirements vary by platform — in AEM, for example, two accounts are typically required:
* **A technical account** — used by Gradial to authenticate with the CMS API
* **An authoring account** — a user account with write permissions to the content paths agents will work with
See [Integrations](/docs/integrations-administration-and-setup/integrations/get-started-with-integrations) for supported platforms and detailed setup instructions.
Connect your project management tools — Jira, Workfront, Wrike, or similar — so Gradial agents can receive and execute work directly from your existing workflows. See [Connecting to External Ticketing Systems](/docs/integrations-administration-and-setup/how-gradial-works-with-ticketing-systems/setting-up-ticketing-integrations).
If your team uses Figma for design, connect it using a Personal Access Token (PAT) so agents can source design assets and patterns. See [Figma Integration](/docs/integrations-administration-and-setup/integrations/figma).
If your team uses a DAM, connect it so agents can source and manage assets as part of content workflows. See [Digital Asset Management](/docs/asset-management/digital-asset-management).
***
## Phase 3: Platform Onboarding
Configure Gradial for your environment and run end-to-end use case validation together with your Gradial onboarding manager. Setup steps are self-service; validation is a joint exercise.
Create a dedicated sandbox or testing area within your CMS or DAM. This gives you a safe space to run agents and validate outputs before going live. Refer to your CMS admin for the recommended folder and permission structure, or ask your Gradial onboarding manager for guidance.
Once your CMS and DAM are connected, your Gradial team sets up and runs indexing jobs over your site content and asset libraries. Indexing is what powers site-wide search and bulk operations ([Site Search](/docs/updating-existing-experiences-i-e-content-updates/site-search)) and asset retrieval at scale ([Asset Search](/docs/asset-management/asset-search)) — results are only available after indexing is complete.
* **Sites** — indexing runs over your connected site content within the content paths you defined in pre-configuration.
* **Assets** — indexing runs over your connected DAM roots. Large asset libraries take time to index, so schedule this early rather than waiting until a use case needs it.
Ask your Gradial onboarding manager to schedule these jobs as soon as the relevant integrations are connected. For AEM, you can also configure [journaling-based asset sync](/docs/integrations-administration-and-setup/integrations/aem/advanced-configurations#asset-sync-journaling) so asset changes flow into the index within minutes instead of waiting for the next full re-scan.
Golden Pages are reference pages that Gradial uses as a quality benchmark when creating or updating content. They represent your ideal page structure, component usage, and content standards. Set these up and ensure they are accessible in your CMS. See [Golden Pages](/docs/creating-new-experiences/golden-pages).
If you're using Gradial for page creation or migration, ingest your design system's component patterns so agents understand your component library and can assemble pages correctly. See [Design Pattern Ingestion](/docs/creating-new-experiences/design-pattern-ingestion).
Set up the rules that agents apply when generating and reviewing content — brand voice, legal compliance guardrails, and QA criteria. Rules can be created directly in the Rules Manager or by asking the agent. See [Rules & Skills](/docs/marketing-brain/managing-skills).
Your Gradial onboarding manager will run use case validation sessions with your team — working through each in-scope workflow end-to-end against your real CMS environment. This is a collaborative exercise: your team runs the tasks, your Gradial manager guides the setup and troubleshoots issues together with you.
Validation covers the full range of workflows in scope:
* Copy, image and link changes on a page — see [Change Copy, Links or Images on a Page](/docs/updating-existing-experiences-i-e-content-updates/small-content-updates)
* Component swaps and reusable content — see [Rework Sections and Reusable Content](/docs/updating-existing-experiences-i-e-content-updates/medium-content-updates-in-gradial)
* New page creation from Golden Pages and design patterns — see [New Page Workflow](/docs/creating-new-experiences/new-page)
* QA and accessibility reports — see [QA Reports](/docs/quality-assurance-and-accessibility/qa-report) and [Accessibility Reports](/docs/quality-assurance-and-accessibility/accessibility-report)
* Translation/localization workflows, if applicable — see [Translation](/docs/translation-and-localization/translation) and [Localization & MSM Inheritance](/docs/translation-and-localization/msm)
***
## Phase 4: Use Case Readiness & Training
Training follows a core-first model: Gradial trains your core team, your core team trains the extended user group — with Gradial available to support along the way.
Your Gradial onboarding manager leads a dedicated training session with the people who will own Gradial day-to-day: your admin, product owner, and use case leads. This session covers how to run each validated use case, how to write effective prompts, and how to troubleshoot common issues. By the end, your core team is ready to operate independently and train others.
Use [Navigating the Gradial Platform](/docs/getting-started/navigating-the-platform) and [Prompting an AI Agent](/docs/getting-started/ask-grady) as supporting references.
Your core team leads training sessions for authors, designers, and other operational staff. Gradial is available to support these sessions — answering questions, joining for complex use cases, and helping ensure your extended team leaves with the same confidence as your core group. Running these sessions internally builds long-term organizational capability.
Before go-live, designate specific people responsible for:
* **Prompt maintenance** — keeping prompts up to date as your content needs evolve
* **Evaluation management** — updating QA evals when brand or compliance requirements change
* **Use case evolution** — identifying and onboarding new use cases over time
These don't need to be separate people, but ownership should be explicit.
Know where to go when you need help:
* **Platform issues**: [Customer Support Portal](/support-portal) or [support@gradial.com](mailto:support@gradial.com)
* **Documentation**: You're already here — bookmark the docs and share with your team
* **Onboarding questions**: Your Gradial implementation manager remains your first point of contact until formal graduation
***
## Grady's Graduation
Gradial onboarding concludes with a formal graduation sign-off — a review confirming that all in-scope use cases have been validated end-to-end, your team is trained, named owners are in place, and your support model is agreed. Your Gradial contact will guide you through this step.
***
**Need help?** Your Gradial implementation contact is your first stop for onboarding questions. For ongoing support, visit the [Customer Support Portal](/support-portal).
# Start Here
Source: https://docs.gradial.com/docs/getting-started/start-here
Find what you need in Gradial's documentation — or follow a guided path if you're just getting started.
**Already using Gradial?** Use the search bar above or the tabs to jump directly to what you need — **Setup & Administration** for integrations and access, **Gradial in Action** for workflows and features.
***
## New to Gradial?
Pick the path that fits where you are right now and we'll take you from there.
You want to understand what Gradial does, how it works, and whether it fits your team's needs.
You're an IT admin or technical lead connecting systems, provisioning access, and getting the environment production-ready.
You're a content manager, author, editor, or communications lead running tasks, updating content, and getting pages live.
***
## I'm Evaluating Gradial
You want to understand what Gradial is, what it can do, and how it fits into your team's existing workflows before committing to a full setup. This path gives you the full picture without requiring any credentials or configuration.
Gradial is the secure enterprise marketing harness that turns a fragmented lifecycle into governed execution. This page covers the content supply chain problem, the systems-of-record vs. harness framing, what Gradial's agents actually do, and the architectural decisions that differentiate it.
[What Is Gradial? →](/docs/getting-started/what-is-gradial)
If "harness" is a new term, this page explains what an enterprise marketing harness is made of — tools, integrations, context, memory, workspace, and guardrails — how it differs from a point solution or a copilot, why it spans the whole marketing lifecycle rather than a single stage, and how the learning loop makes each campaign better than the last.
[What is an enterprise marketing harness? →](/docs/getting-started/what-is-an-agentic-harness)
Understand the mental model behind Gradial: how work comes in, the jobs Gradial does, how it executes across your stack, and how it builds a working understanding of your organization over time.
[How Gradial Works →](/docs/getting-started/how-gradial-works)
Gradial connects to the CMS, project management, design, and marketing automation tools your team already uses. Review the full integrations list to confirm your stack is covered.
[Integrations Overview →](/docs/integrations-administration-and-setup/integrations/get-started-with-integrations)
Gradial organizes work into two main categories: updating existing content and creating new experiences. Read both overviews to understand the scope of what agents can handle.
[Content Updates →](/docs/updating-existing-experiences-i-e-content-updates/content-updates) · [New Page Workflow →](/docs/creating-new-experiences/new-page)
One of Gradial's most powerful capabilities is turning a single campaign brief into fully built assets across every channel simultaneously — web pages, email templates, audience configuration, content updates — without per-channel tasking or coordination overhead.
[Cross-Channel Campaign Execution →](/docs/campaign-management/cross-channel-campaigns)
Gradial enforces brand standards, SEO rules, and WCAG 2.2 AA accessibility compliance automatically. This is often a key differentiator for enterprise teams with strict governance requirements.
[QA Reports →](/docs/quality-assurance-and-accessibility/qa-report) · [Accessibility Reports →](/docs/quality-assurance-and-accessibility/accessibility-report)
Check the release notes to see the current pace of product development and what capabilities have been added in recent months.
[Release Notes →](/release-notes/overview)
Ready to go deeper? Request a demo to see Gradial running against your actual CMS and content — not a generic sandbox.
[Request a Demo →](https://www.gradial.com/request-demo)
***
## I'm Setting Up the Platform
You own the technical foundation. Before anyone on your team can use Gradial, you need to connect your systems, configure access, and validate the environment. This path takes you from a freshly provisioned org to production-ready.
**Estimated time:** 1–3 weeks (largely dependent on your IT team's security review process)
Start with how Gradial works — what it connects to, how agents receive and execute work, and what systems are involved — before you touch any credentials.
[How Gradial Works →](/docs/getting-started/how-gradial-works)
Before connecting anything, work through Phase 1 of the onboarding checklist. It tells you exactly what your team needs to gather — example tickets, workflow docs, golden page candidates — before technical setup can begin.
[Onboarding Checklist →](/docs/getting-started/onboarding-checklist)
This is the critical path. Connect Gradial to your primary CMS. Each integration requires specific service accounts and permission configurations — plan for security review time.
OAuth 2.0 or IMS authentication, JCR permissions, technical account setup
XM Cloud, XP, or Content Hub — guided wizard setup
Management and Delivery API tokens, space and environment scoping
API token or service account setup per platform
Also connecting a marketing or email platform? See [Marketo](/docs/integrations-administration-and-setup/integrations/marketo), [Salesforce Marketing Cloud](/docs/integrations-administration-and-setup/integrations/salesforce-marketing-cloud), and [all integrations](/docs/integrations-administration-and-setup/integrations/get-started-with-integrations).
Gradial works directly from tickets in Jira, Workfront, Wrike, and others. Connecting your ticketing system activates the queue automation that makes Gradial most valuable for content teams day-to-day.
[Set Up Ticketing Integrations →](/docs/integrations-administration-and-setup/how-gradial-works-with-ticketing-systems/setting-up-ticketing-integrations)
Connect Gradial to your identity provider to enable single sign-on. Supported: Microsoft Entra ID, Okta OIDC, and custom OIDC.
[Configure SSO →](/docs/integrations-administration-and-setup/managing-access/sso)
Define who can do what. Gradial has organization-level and workspace-level roles. Invite your admins, content leads, and editors, and assign appropriate permissions before handing off to content teams.
[Roles & Permissions →](/docs/integrations-administration-and-setup/managing-access/roles) · [Manage Team Members →](/docs/integrations-administration-and-setup/managing-access/manage-team-members)
Complete Phases 3 and 4 of the onboarding checklist — confirm integrations are live, run sandbox validation, and sign off with your Gradial contact before content teams begin using the platform.
[Onboarding Checklist: Phases 3 & 4 →](/docs/getting-started/onboarding-checklist)
The single most common delay in Gradial onboarding is IT provisioning and security reviews. Submit a single, consolidated credential request rather than individual asks spread out over time — it can cut weeks off your timeline.
***
## I'm Using Gradial Daily
You're a content manager, author, editor, communications lead, or team owner running tasks and getting content live. This path covers the operational skills you need — starting with the basics and building toward more complex workflows and quality configuration.
**Estimated time:** 2–4 hours to get comfortable with the basics; add new workflows as you go
Start by learning how the platform is laid out — where tasks live, how workspaces are organized, and how to navigate between projects.
[Navigating the Platform →](/docs/getting-started/navigating-the-platform)
The quality of what Gradial produces depends heavily on how you describe the task. Read the prompting guide before running your first task — it will save you from multiple re-runs and frustration.
[Prompting an AI Agent →](/docs/getting-started/ask-grady)
Start small: a copy change, a link swap, a styling fix. These are fast, low-risk, and a good way to learn the task loop — brief → run → review → stage → publish.
[Change Copy, Links or Images on a Page →](/docs/updating-existing-experiences-i-e-content-updates/small-content-updates)
Once you're comfortable, tackle more involved work: component swaps, batched changes, find-and-replace across pages, and reusable content blocks that appear in many places.
[Rework Sections and Reusable Content →](/docs/updating-existing-experiences-i-e-content-updates/medium-content-updates-in-gradial)
Learn the four ways to create a new page in Gradial: copying an existing page, using design patterns, working from a Word doc or creative brief, or importing a Figma design.
[New Page Workflow →](/docs/creating-new-experiences/new-page)
Before content publishes, run a QA report to catch brand and compliance issues, and an accessibility report to validate WCAG 2.2 AA conformance.
[QA Reports →](/docs/quality-assurance-and-accessibility/qa-report) · [Accessibility Reports →](/docs/quality-assurance-and-accessibility/accessibility-report)
Once you're comfortable running tasks manually, learn how Gradial picks up tickets from Jira, Workfront, or Wrike automatically — so you can execute directly from your existing workflow without copy-pasting between tools.
[How Gradial Works with Ticketing →](/docs/integrations-administration-and-setup/how-gradial-works-with-ticketing-systems/setting-up-ticketing-integrations)
If you're a content lead or strategist responsible for how agents behave, the next step is setting up golden pages, design patterns, and QA rules. This is what scales quality across your entire team.
[Golden Pages →](/docs/creating-new-experiences/golden-pages) · [Design Pattern Ingestion →](/docs/creating-new-experiences/design-pattern-ingestion) · [QA Rules Manager →](/docs/quality-assurance-and-accessibility/qa-report)
The fastest way to improve output quality is better prompts, not re-running the same task. If a result isn't what you expected, revisit the [Prompting Guide](/docs/getting-started/ask-grady) before trying again — a clearer objective and one concrete example makes more difference than anything else.
# What Is an Enterprise Marketing Harness?
Source: https://docs.gradial.com/docs/getting-started/what-is-an-agentic-harness
An enterprise marketing harness is the scaffolding around an AI model that makes it do real marketing work — tools, integrations, context, memory, workspace, and guardrails. Gradial is that harness, built for enterprise marketing operations.
An **enterprise marketing harness** is the scaffolding around an AI model that turns it into a system capable of doing real marketing work: the tools it can call, the integrations into your martech stack, the context it reasons over, the memory it carries between jobs, the workspace it operates in, and the guardrails that constrain what it may do.
The term is also written **agentic harness** or **agent harness**. The distinction that matters is scope: a general-purpose agentic harness is built for general-purpose work, while an enterprise marketing harness applies the same scaffolding to the systems, standards, and approval paths that enterprise marketing actually runs on — CMS, DAM, marketing automation, brand governance, and regulatory review.
Gradial is an enterprise marketing harness. This page explains what one is made of, how it differs from a point solution or a copilot, and why the harness rather than the model is where the engineering lives.
***
## The model is not the product
Frontier models are extraordinary reasoners and, on their own, not particularly valuable for enterprise marketing work. A model with no connection to your CMS cannot publish a page. A model with no access to your DAM cannot find the approved asset. A model with no knowledge of your brand voice, your regulatory language, or your regional inheritance rules will produce something plausible and wrong. And individual agents connected to those individual systems don't solve your challenge.
What turns a model into a coworker is everything built *around* it.
**An agentic harness is the scaffolding around the LLM and the agent that makes it work correctly and repeatably** — the tools it can call, the context it reasons over, the memory it carries between jobs, the workspace it operates in, and the guardrails that constrain what it is allowed to do. An **enterprise marketing harness** is that same scaffolding, specialized for marketing systems, standards, and approvals.
The harness is where the real engineering lives. It is the difference between a model that can describe how to update a page and an agent that updates the page — in your CMS, using your components, against your standards, with an audit trail.
***
## What a harness is made of
Six things have to be in place before an agent can do real work. Miss any one of them and you have a demo, not a system.
The actions an agent can actually take — author a page, tag an asset, build an audience, run an accessibility scan, publish. Not descriptions of the work: the work itself.
Authenticated, permissioned connections into the systems where your work lives — CMS, DAM, email platform, work management, analytics, commerce.
What the agent needs to know to get this job right: the brief, the brand guidelines, the page patterns your site already uses, the campaign it belongs to, the market it ships to.
What was learned last time — corrections a reviewer made, the phrasing legal insisted on, the structure that performed. Without memory, every job starts from zero.
A place for work in progress: drafts, variants, generated artifacts, review queues, and the state of a job that spans several systems and several days.
The limits. What must be checked before an output moves forward, what requires human sign-off, what an agent may never do on its own — spend money, publish to production unreviewed, alter regulated language.
***
## What makes it an *enterprise marketing* harness
A general-purpose harness is built for general-purpose work. **An enterprise marketing harness is all of the above, applied to the critical systems, skills, and processes marketing actually requires** — and split across the two groups who need to trust it.
| Control layer | Owned by | What it governs |
| --------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Brand and compliance controls** | Marketing, brand, legal | **Brand** — voice, standards, and institutional knowledge. **Context** — briefs, patterns, campaign and market detail. **Guardrails** — QA, accessibility, and regulatory checks, and where humans sign off. |
| **IT controls** | IT, security, platform teams | **Tools** — the actions agents can take. **Integrations** — authenticated, least-privilege access to your systems. **Frontier LLMs** — which models are used, and where data goes. |
This is the reason "secure" is not decoration in how we describe Gradial. Marketing wants the work to sound right; IT and security want to know exactly what an agent can reach, with which credentials, and under what review. A harness worth deploying in an enterprise answers both at the same time — see [Roles & Permissions](/docs/integrations-administration-and-setup/managing-access/roles), [Workspace Categories](/docs/governance/workspace-categories), and [Regulatory Compliance](/docs/governance/regulatory-compliance).
Everything in the brand and compliance column is configurable by the people who own the standards, not by engineers. That is what makes governance scale: it is encoded once and applied on every task, rather than depending on the right reviewer being in the room. See [Marketing Brain](/docs/marketing-brain/learning-system).
***
## The harness spans the whole lifecycle
Point solutions cover a stage. A harness covers the lifecycle — which is where the time actually goes, because most of the cost of marketing execution is in the handoffs *between* stages.
| | Stage | What happens here |
| -- | --------------- | ------------------------------------------------------------------ |
| 01 | **Strategy** | Campaign plans, messaging frameworks, brief creation |
| 02 | **Planning** | Briefs turned into work — task breakdowns, dependencies, timelines |
| 03 | **Creative** | Copy, images, pages, variants, localization |
| 04 | **Assets** | Tagging, metadata, brand compliance, organization |
| 05 | **Channels** | Web, email, social, paid, journeys |
| 06 | **Authoring** | Page updates, new pages, bulk edits in your CMS |
| 07 | **Review / QA** | QA checks, accessibility, brand audits |
| 08 | **Launch** | Bulk publish, find and replace, scheduled sends |
| 09 | **Analyze** | SEO, GEO, performance, A/B testing |
Gradial executes across all nine, which is what makes the handoffs disappear. A brief does not get emailed to a creative team, exported to a copy doc, pasted into a CMS, and screenshotted for review — it moves through one system that can act at every stage. See [How Gradial Works](/docs/getting-started/how-gradial-works) for what that looks like task by task, and [Cross-Channel Campaigns](/docs/campaign-management/cross-channel-campaigns) for a brief that fans out across channels in a single job.
**Your team still owns the strategy.** The harness does not decide what campaign to run or what the brand should stand for. It takes the brief your team writes and carries it to live — the stages in the middle, which are the ones that take weeks.
***
## The recursive learning loop
The reason a harness compounds — and a point solution does not — is the loop back to the beginning.
An agent authors the page, tags the assets, runs the checks, ships the campaign.
Performance data, QA findings, accessibility results, and reviewer corrections all land in the same system that did the work.
What worked becomes brand and pattern knowledge. What was corrected becomes a standard. What failed a check becomes a rule.
The next brief is executed against a richer understanding of your brand, your standards, and your audience than the last one was.
Because execution, governance, and insight live in one harness rather than three tools, this loop closes automatically. Instead of starting from zero, every campaign starts from what worked — see [Learning System](/docs/marketing-brain/learning-system), [Memory](/docs/marketing-brain/memory), and [Evals](/docs/evals/evals).
***
## Why this matters commercially
Framing the problem as a harness rather than a feature set has three practical consequences for enterprise teams.
Every stage of the lifecycle now has an AI point solution available for it — an AI copy tool, an AI tagging tool, an AI QA tool. Each one is a new contract, a new integration, a new login, and a new seam where work stalls waiting for a human to carry it across.
A harness that spans the lifecycle collapses that stack. The work moves between stages inside one system, under one set of controls, with one audit trail.
Model and tool spend scattered across a dozen team-level AI subscriptions is impossible to govern and impossible to forecast. Consolidated in a harness, model usage is centrally managed, and Gradial routes each job to the model that performs best for that task type rather than paying frontier prices for everything.
Because model selection sits in the harness rather than in your workflows, you benefit from better and cheaper models as they arrive — with no migration and no vendor lock-in.
When guardrails live in the harness, they run on every output automatically — brand, accessibility, and regulatory checks applied to all of the work rather than a sample of it. Approval gates are part of the motion instead of a queue bolted onto the end.
That is what makes speed acceptable to a risk function: throughput goes up and coverage goes up at the same time.
***
## Enterprise marketing harness vs. other approaches
The term earns its keep by describing something the alternatives are not. Four approaches get compared to a harness most often.
| Approach | What it gives you | What it doesn't |
| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| **AI point solution** (AI copywriter, AI tagger, AI QA tool) | Depth at one lifecycle stage | Nothing carries between stages — each tool is a new contract, integration, and manual handoff |
| **Copilot or chat assistant** | Drafting and suggestions inside one application | It advises rather than executes; a person still performs the work in the system of record |
| **DIY agent orchestration** (building on an agent framework) | Full control | You build and maintain the tools, integrations, memory, guardrails, and audit trail yourself |
| **System of record** (CMS, DAM, marketing automation) | The durable store of your content and data | It holds the work; it doesn't do the work between brief and live |
| **Enterprise marketing harness** | Execution across the whole lifecycle, in your existing systems, under one set of governed controls | It doesn't set strategy — your team still decides what to run and what the brand stands for |
The practical test: can it change something in your CMS, against your standards, with an audit trail, without a person carrying the work across a seam? Advice is not execution, and one stage is not a lifecycle.
***
## Frequently asked questions
An enterprise marketing harness is the scaffolding around an AI model that lets it perform real marketing work: tools it can call, authenticated integrations into your martech stack, the context and brand standards it reasons over, memory of prior work, a workspace for work in progress, and guardrails governing what it may do without human sign-off. Gradial is an enterprise marketing harness.
Yes. "Agentic harness," "agent harness," and "AI agent harness" all describe the same concept — the engineered layer around a model and its agents. "Enterprise marketing harness" specifies the domain that layer is built for.
An agent is the thing that acts. The harness is everything that makes acting reliable: what the agent is allowed to call, what it knows, what it remembers, where it works, and what it must not do alone. A single agent with no harness can produce plausible output but cannot be trusted to change production systems repeatably.
Because marketing's constraints are specific: brand voice, regulatory language, regional inheritance rules, accessibility standards, and approval paths that span marketing, legal, and IT. A general-purpose harness has no opinion about any of those. An enterprise marketing harness encodes them once and applies them to every task, which is what lets governance scale with throughput instead of against it.
No. Those remain your systems of record. The harness works across them — reading, authoring, and publishing through authenticated, least-privilege connections — so you consolidate the execution layer rather than migrating your content.
Six: tools (the actions available), integrations (permissioned access to your systems), context (what the agent needs to know for this job), memory (what was learned last time), workspace (where work in progress lives), and guardrails (what must be checked and what requires human approval). Missing any one produces a demo rather than a system.
***
## Where to go next
The harness applied: what Gradial executes, what makes it different, and the outcomes teams see in production.
The mental model — how work comes in, how agents execute it across your stack, and how governance runs on every task.
The context, memory, and standards layer — how Gradial builds a working understanding of your organization.
Real examples organized by lifecycle stage, each with a prompt you can copy and adapt.
# What Is Gradial?
Source: https://docs.gradial.com/docs/getting-started/what-is-gradial
Gradial is the secure enterprise marketing harness that turns a fragmented lifecycle into governed execution — across your existing stack, from brief to live.
Gradial is a secure **enterprise marketing harness**: a layer that sits across your existing martech stack and executes the jobs between brief and live, under your brand, accessibility, and compliance controls.
New to the term? [What is an enterprise marketing harness? →](/docs/getting-started/what-is-an-agentic-harness) covers the concept — the tools, context, memory, workspace, and guardrails that turn a model into a coworker — and why a harness spans the lifecycle instead of covering a stage.
***
## The Gap Between Idea and Execution
Enterprise teams are not short on tools. Most large organizations run a CMS, a DAM, a work management platform, an email platform, design tools, analytics, a ticketing system, and more. These systems hold real value — they store content, track assets, and structure process.
And yet the same problem keeps showing up at every organization:
Work takes months. Publishing takes weeks. Quality is inconsistent. Creative work gets buried under operational work. **The tools are not the problem. The workflow between them is.**
Think of everything that has to happen between a brief and a live web page, email, or communication:
* Brief written and approved
* Copy drafted, reviewed, revised
* Assets sourced or created, uploaded, tagged, optimized
* Page or content item authored in the CMS
* QA run against brand, accessibility, and compliance rules
* Approval workflow completed
* Variants created for different audiences, regions, or channels
* Launch scheduled and coordinated
Every step touches a different system. Every handoff is manual. Every tool creates a queue. The workflow is slow, expensive, and fragile at every seam.
This is not a people problem. Teams are working hard. It is a **structural problem**: the systems they depend on were built to store and manage work, not to execute it — and certainly not at the speed and scale the AI era now demands.
***
## Systems of Record vs. the Harness
This framing is the key to understanding where Gradial fits:
| | Systems of Record | The Harness |
| ----------------- | ------------------------------------ | -------------------------------------------------------------------- |
| **What they do** | Store information, manage process | Execute outcomes |
| **Examples** | CMS, DAM, CRM, ticketing, analytics | Gradial |
| **Who acts** | Humans navigate tools to do the work | Agents do the work; humans govern and direct |
| **In the AI era** | Become endpoints and data sources | Becomes the platform with the necessary to execute & govern the work |
Enterprise organizations have built a strong ecosystem of systems of record. These investments have value and aren't going anywhere. What has been missing is the **harness** that sits across all of them — the layer that can execute the jobs between brief and live, at the scale and consistency AI now makes possible, without loosening a single control.
That is the gap Gradial fills.
***
## What Gradial Is
**Gradial is the secure marketing harness that turns a fragmented lifecycle into governed execution.** It connects to the systems you already run, executes the work between brief and live with digital coworkers, and applies your brand, accessibility, and compliance standards to every output — automatically.
Three words carry the weight:
Least-privilege integrations, roles and workspace boundaries, full audit trails, and hard limits on what agents can do unsupervised — spend changes and production publishes stay gated on human approval. IT and security govern the tools, access, and models; marketing governs the standards.
Not a chatbot, not a copilot, not another point solution for one stage. The scaffolding around frontier models — tools, integrations, context, memory, workspace, guardrails — purpose-built for the systems and processes enterprise marketing actually runs on.
The work gets done, end to end, and every output is checked before it moves. Governance is part of the motion rather than a queue bolted onto the end, so throughput and coverage go up together.
### From fragmented lifecycle to one motion
The lifecycle is fragmented because each stage lives in a different tool, and the cost sits in the handoffs between them. Gradial executes across the whole span — strategy and planning, creative, assets, channels, authoring, review and QA, launch, and analysis — so a brief moves to live inside one system instead of being carried across nine.
Your team still owns the strategy. Gradial takes the brief and carries it through the stages that take weeks.
The key word is *execution*. Gradial's digital coworkers create, author, schedule, govern, optimize, and operate end-to-end — across the full range of jobs marketing, communications, and digital teams need to get done.
### What Gradial's agents handle
Turn a brief into a structured, prioritized set of tasks. Pre-schedule and sequence work across teams and systems. Manage the workflow from brief to live — with AI-reviewed steps, human-reviewed steps, and shared approval queues that keep the right people in the loop at the right moment.
Automate website updates of any size. Build landing pages, product pages, internal resource pages, and homepage experiences from a brief, Figma file, or prompt. Author emails, announcements, and communications. Create variants for different audiences and regions. Migrate content across platforms. Produce structured artifacts — copy docs, update logs, briefing sheets — alongside every execution.
Upload, name, tag, and retrieve assets across multiple DAMs simultaneously. Apply metadata at scale. Swap assets while preserving links and relationships. Auto-generate and validate alt-text for accessibility.
QA, accessibility, brand, and compliance checks on every piece of content, every time, automatically. Gradial's built-in brand intelligence layer encodes your standards, voice, and institutional knowledge — and applies them on every task, not just when the right person is in the room.
GEO analysis, site audits, and CX optimization — agents that review your content before it goes live and continue optimizing flows after publish. AI that doesn't just surface recommendations: it acts on them.
Publish and schedule organic social, and build paid campaign structures for search and social — created paused, with spend changes always gated on human approval. Merchandising and product content in your commerce platform from the same brief.
Create page variants and run experiments with real-time data. Native Adobe Target integration closes the loop between insight and action — browse, create, preview and activate activities without leaving Gradial.
**Want the range in concrete terms?** The [Customer Use Cases](/docs/gradial-prompt-library/customer-use-cases) library has real examples organized by where you are in the marketing lifecycle — strategy, planning, creative, assets, channel orchestration, authoring, review, launch, and optimization — each with a prompt you can copy and adapt.
***
## What Makes Gradial Different
Four architectural decisions set Gradial apart from other AI tools in the market.
Most AI tools assist individuals. Gradial orchestrates work across entire teams — coordinating humans and agents in a shared workflow where each step can be AI-executed, human-reviewed, or both.
Approval flows aren't a bolt-on. Every task in Gradial can have AI-reviewed checkpoints and human sign-off gates, so governance doesn't slow execution — it's built into the motion. Teams stay in control of what matters while agents handle the operational work at scale.
* AI-reviewed and human-reviewed steps in the same workflow
* Shared task queues across teams and systems
* Structured artifacts — copy docs, spreadsheets, audit logs — produced alongside every execution
* Ticketing system integration so work moves through the tools already in place
Enterprise organizations use Figma, SharePoint, multiple CMS platforms, multiple DAMs, Workfront, Jira, Salesforce Marketing Cloud, Marketo, and more. Any platform that works with only some of those tools creates new silos.
Gradial connects natively across the full stack: CMS platforms, DAMs, email and marketing automation platforms, ticketing systems, paid media, social, commerce, CRM and analytics. See [Integrations](/docs/integrations-administration-and-setup/integrations/get-started-with-integrations) for the current list. Assets are searchable across connected repositories, with one semantic index over your primary DAM.
For internal systems and custom tooling, Gradial supports **native MCP integration** — meaning teams can connect proprietary knowledge bases, internal AI context layers, or custom workflows directly. Campaigns can be kicked off from Claude, from Slack, or from any MCP-connected internal tool. No new interfaces required.
* No rip-and-replace. No digital transformation required
* Works across all your marketing systems, whatever they are
* Your own REST API or a secure MCP server: connect internal systems and kick off work from Slack or Claude
Most analytics tools surface recommendations and stop there. Acting on those recommendations still requires manual work across multiple systems.
Gradial closes that gap. GEO analysis, site audits, and CX optimization agents don't just report — they execute. An agent that identifies a content gap can author and publish the fix. An agent that spots an accessibility violation can remediate it. The insight and the action live in the same platform.
* GEO analysis that feeds directly into content execution
* Site audit agents that flag issues and fix them
* CX optimization agents that review content before go-live and tune flows after publish
* Experimentation integrated natively with Adobe Target
Most AI tools make a bet on a single model from a single provider. That creates a ceiling: performance is capped by what that one model does well today, with no flexibility as the landscape changes.
Gradial is multi-model by design. The platform uses the best-performing model for each task and switches as better options emerge. An evals framework continuously measures output quality across task types — so model selection improves over time based on real production results, not benchmarks.
* Gradial selects the right model for each job automatically
* A built-in evals system measures and improves output quality continuously
* Your organization benefits from model improvements without migration or retraining
* No AI vendor lock-in, ever
***
## Outcomes in Production
When organizations use Gradial, the results are measurable:
Content that took months now takes hours. From brief to live, faster.
Teams execute more work without adding headcount. The same people who managed queues now direct outcomes — at a scale that wasn't possible before.
Brand, accessibility, and compliance checks run on every output, automatically — not sampled occasionally.
Higher throughput means more campaigns in market, more audience segments served, and more personalized experiences — driving measurable top-line growth.
***
## Getting Access
Log in at **app.gradial.com**. If you don't have an account yet, ask your Gradial org admin to invite you — see [Manage Team Members](/docs/integrations-administration-and-setup/managing-access/manage-team-members). Once invited, follow your org's login method (SSO or email/password).
[Request a demo](https://www.gradial.com/request-demo) to see Gradial running against your actual CMS and content — not a generic sandbox.
***
## Where to Go Next
The concept behind the positioning: what a harness is made of, why it spans the lifecycle, and how the learning loop makes each campaign better than the last.
The mental model: how work comes in, how it gets executed across your stack, and how Gradial builds a working understanding of your organization.
What to actually ask for, organized by the marketing lifecycle — with copy-and-adapt prompts for each one.
Guided paths for evaluating Gradial, setting up the platform, or getting productive day-to-day.
# Regulated Industries & Compliance Workflows
Source: https://docs.gradial.com/docs/governance/regulatory-compliance
How Gradial supports content governance in regulated industries — automated compliance checks, legal review workflows, and a full audit trail on every output.
Enterprise teams in financial services, insurance, healthcare, telecom, and other regulated industries operate under strict content review requirements. A single missing disclaimer, an unsubstantiated claim, or outdated regulatory language can create material legal exposure. Manual review doesn't scale with the volume of content modern teams produce.
Gradial is designed to work within these environments — enforcing compliance rules automatically, supporting legal review workflows, and creating the audit trail regulated organizations need.
***
## Automated Compliance Checking
Gradial can be configured to check every piece of content against your organization's compliance rules before it reaches a human reviewer.
Rules can enforce requirements such as:
* **Required disclosures and disclaimers** — verify that specific legal language is present in the correct location on every page, email, or asset
* **Prohibited or restricted claims** — flag content that makes claims requiring substantiation, or that deviates from approved language
* **Standard regulatory language** — ensure boilerplate text (terms, privacy notices, offer conditions) matches the approved version exactly
* **Trademark and IP usage** — check that brand marks are correctly formatted and licensed assets are used appropriately
* **Accessibility** — WCAG 2.2 AA compliance checks on every output, automatically — a growing area of regulatory risk in the US and EU
Rules are defined once and applied consistently across every task — not sampled, not manual. See [Rules & Skills](/docs/marketing-brain/managing-skills) for how to configure them.
***
## Working with Legal-Marked Documents
Legal teams often return content with tracked changes, annotations, and redlines. Gradial can ingest these marked-up documents directly as task context — so agents understand what legal has flagged and apply the corrections accurately, without requiring manual interpretation or re-keying of changes.
**Supported inputs for legal review context:**
* Annotated Word documents (.docx with tracked changes or comments)
* PDF files with markup and annotations
* Redlined copy docs
* Structured spreadsheets mapping approved vs. revised language
Attaching the marked-up source file to a Gradial task gives the agent the full context of what legal reviewed and what was approved — improving accuracy and reducing the iteration loop.
***
## Review, Annotation, and Approval Workflows
Gradial is designed to support the review cycles that regulated environments require — not bypass them.
Reviewers can add comments and annotations directly within Gradial tasks. Legal, compliance, and marketing teams can discuss specific content changes in context — without switching to email or a separate tool. Comments are attached to the task and preserved in the audit trail.
Gradial maintains a clear before/after view of every change — showing exactly what the agent modified against the original content. This side-by-side view supports compliance review and sign-off without requiring reviewers to diff content manually.
Content and change records can be exported to PDF for formal regulatory review, filing support, or record-keeping. This is particularly useful for teams that need to submit content for external review or maintain a signed-off record of what was approved and when.
Gradial never writes directly to your production environment by default. All outputs are staged for review before anything goes live. This means compliance or legal review happens before publication — not after. See [Content Updates](/docs/updating-existing-experiences-i-e-content-updates/content-updates) for how staging works per platform.
***
## Audit Trail and Traceability
Every action Gradial takes is logged:
* What was changed, and what was left unchanged
* Which rules were applied and what they checked
* Which user initiated the task and when
* What the agent's output was, and what was approved or rejected
This audit trail supports internal compliance sign-off, external regulatory inquiries, and post-publication review — without requiring manual documentation of what changed.
***
## Common Use Cases in Regulated Environments
Automatically verify that required legal language is present across every page, email, or asset — at scale. When standard disclaimer language changes, update it across hundreds of pages in a single batch task.
Ingest a legal-marked document and let agents apply the approved changes accurately — preserving context and reducing manual re-keying.
Run a compliance QA scan across all content before a campaign or site section goes live — catching missing disclosures, prohibited language, or accessibility issues automatically.
Export a side-by-side before/after PDF of content changes for formal regulatory review or internal sign-off — without manual documentation.
***
## What Gradial Doesn't Do
Gradial is a content execution and governance platform — not a regulatory compliance certification service.
Gradial does not provide certifications or guarantees of compliance with specific regulatory regimes (such as HIPAA, FINRA, GDPR, or others). Compliance with applicable regulations is your organization's responsibility.
Gradial **supports** compliant content workflows by enforcing the rules your legal and compliance teams define — but the rules themselves, and the final review and sign-off, remain with your team.
For questions about Gradial's data handling, security posture, and vendor risk documentation, contact [support@gradial.com](mailto:support@gradial.com) or reach out to your Gradial onboarding manager.
***
## Related
* [Rules & Skills](/docs/marketing-brain/managing-skills) — Configuring the compliance rules Gradial enforces automatically
* [QA Reports](/docs/quality-assurance-and-accessibility/qa-report) — Reading and acting on QA findings
* [Accessibility Reports](/docs/quality-assurance-and-accessibility/accessibility-report) — WCAG 2.2 AA compliance checking
* [Batch Migration](/docs/creating-new-experiences/migration) — Updating disclaimer language across hundreds of pages at once
# Workspace Categories
Source: https://docs.gradial.com/docs/governance/workspace-categories
Organize and filter workspaces with reusable category labels — so large teams can navigate dozens of workspaces without scrolling past everything unrelated.
Categories help organizations with a large number of workspaces organize and group them effectively. Once you're running dozens of workspaces, the flat Workspaces list becomes hard to navigate — categories give admins a way to label workspaces by brand, region, team, or lifecycle stage, and give every user a way to filter and sort the list down to just the workspaces they care about.
Think of it as:
* **Workspace** — one project or initiative the team works in
* **Category** — a reusable label admins use to group workspaces together (`Brand: T-Mobile`, `Region: EMEA`, `Q2 Launch`)
* **Workspaces page** — the index where category filtering, search, sort, and pinning come together
Categories are defined once at the org level and reused across every workspace, so the grouping scales as the customer adds more.
## What you can do
With Workspace Categories enabled, teams can:
* Apply categories to any workspace, such as `Brand: T-Mobile`, `Region: EMEA`, `Q2 Launch`, or `Compliance Review`
* Filter the Workspaces page by one or more categories from the **Filters → Categories** menu
* Sort the Workspaces table by the Categories column ascending or descending
* Combine categories with the existing search box and status filters (`Pinned`, `Public`, `Private`) to narrow a long list quickly
Managing the org-wide category catalog (rename, delete) is limited to org **Owners** and **Admins** via the **Manage Categories** button on the Workspaces page. Workspace-level Owners and Admins can apply existing categories and create new ones inline from their workspace row.
## How it works
An org Admin or Owner opens the Workspaces page and clicks **Manage Categories** to create the initial catalog — for example: brand names, regions, or lifecycle stages.
A workspace Owner or Admin opens the Categories cell on their workspace row and selects one or more existing categories, or types a new name to create one inline.
Anyone with access to the Workspaces page can use the **Filters** dropdown to narrow the list to one or more categories, layer in `Pinned` / `Public` / `Private` status, and sort the Categories column.
Pins and the search box continue to work alongside categories, so a user can pin their most-used workspaces and still slice the rest by category.
## Where search, status, and pins fit
Use categories when you want a stable, reusable label. Use status filters and pins when you want to surface a specific subset within that label.
**Example:**
* Category: `Brand: T-Mobile`
* Status filters: `Pinned`, `Public`, `Private`
That lets a team:
* View every T-Mobile workspace for a portfolio review
* Show only the **pinned** T-Mobile workspaces during a daily standup
* Filter to **Private** T-Mobile workspaces when auditing access
* Use the search box on top of the category filter to jump to a specific workspace name
## Use cases
Apply brand categories such as `Brand: T-Mobile`, `Brand: Metro`, or `Brand: Mint` so each team can filter down to just the brand they own.
This directly solves the "25+ workspaces are unmanageable" problem and lets a brand lead jump straight to their portfolio without scrolling past unrelated work.
Create categories like `Region: NA`, `Region: EMEA`, or `Region: APAC` so regional teams can scope the Workspaces page to their geography.
Useful for global accounts where the same brand spans multiple regions — keeps regional standups and reviews focused on relevant workspaces only.
Group workspaces by stage such as `In Discovery`, `In Build`, `Launched`, or `Q2 Launch`.
Gives PMs and CSMs a fast way to pull the "what's shipping this quarter" view, and makes QBRs and launch readiness reviews easier to prep.
Create categories per major customer, opportunity, or account team for shared org instances.
Helps SE and CS teams keep one customer's workspaces visually grouped — useful when one Gradial org supports several end customers or sub-brands.
Use categories like `Compliance Review`, `Legal Hold`, or `Restricted` for workspaces with extra governance requirements.
Lets admins quickly pull every workspace that needs a review pass. Pairs naturally with the existing `Private` status filter for access audits.
## Things to keep in mind
* Categories are **org-scoped**, not workspace-scoped — renaming or deleting a category in **Manage Categories** affects every workspace it's applied to.
* Only org-level **Owners** and **Admins** can rename or delete categories from the org catalog. Workspace-level Owners and Admins can apply existing categories and create new ones inline.
* Category names are capped at **120 characters**.
* A single filter selection caps at **50 active values**.
* Categories work alongside the existing search box, status filters, and pinning behavior — they complement pins, not replace them.
***
## Availability
**Access:** Must be enabled for your organization. Contact your Gradial team to get access.
# Customer Use Cases
Source: https://docs.gradial.com/docs/gradial-prompt-library/customer-use-cases
Ideas and examples for what to ask Grady, organized by where you are in the marketing lifecycle.
## What can I ask Grady?
A lot. The examples below are organized around the marketing lifecycle — from setting strategy through to analyzing results. The goal is to spark ideas based on where you are right now, not to prescribe a fixed workflow.
You don't need to use these word-for-word. Describe what you need in plain language and Grady will work out the steps. These are starting points.
Where your environment has specific paths configured (e.g., a known AEM content root or DAM path), substitute your actual paths in place of the generic placeholders shown here.
***
Campaign goals, messaging frameworks, market planning
Briefs, task breakdowns, timelines, localization scope
Copy generation, image creation, smart cropping
Tagging, metadata, brand compliance, asset organization
Email campaigns, journeys, multi-channel Email campaigns, journeys, newsletters, multi-channel publishing
Page updates, new pages, fragments, bulk edits
QA checks, accessibility, brand audits, compliance
Publishing, bulk rollouts, find-and-replace, scheduled sends
Performance reporting, SEO, GEO, A/B testing, CX
***
Setting direction — what to build, who to target, and how to position it. Grady can help you turn raw thinking into structured campaign plans and messaging frameworks.
**Complexity:** Complex | **Scope:** Multi-platform | **Platform:** All
Build a full campaign plan with a timeline, asset list, and task breakdown — ready to execute or hand off to the team.
**Sample Prompt**
```text theme={null}
Plan a launch campaign for [product name] across web, email, and social. Target launch date: [date]. Include: a messaging framework, channel-by-channel asset list, go-live timeline, and a task breakdown I can execute in Gradial.
```
**Complexity:** Complex | **Scope:** Multi-platform | **Platform:** All
Generate a structured content calendar for the quarter, mapped to campaigns, channels, and owners.
**Sample Prompt**
```text theme={null}
Build a Q3 content calendar for [team / brand]. Include web pages, emails, and social posts mapped to our campaign themes: [theme 1], [theme 2], [theme 3]. Align to key dates: [list of dates or events]. Format it so I can use it to kick off tasks in Gradial.
```
**Complexity:** Complex | **Scope:** Multi-platform | **Platform:** All
Use a proven campaign as the foundation — updating messaging, assets, and dates for the new cycle without rebuilding from scratch.
**Sample Prompt**
```text theme={null}
Take our [campaign name] campaign from [year] and adapt it for [this year / new product / new market]. Update the messaging for [new context], refresh the assets, and rebuild the task list. Reference the original brief here: [link or attached file].
```
**Complexity:** Medium | **Scope:** Single deliverable | **Platform:** All
Turn a product brief into a structured messaging framework — positioning statement, key messages by audience, and proof points.
**Sample Prompt**
```text theme={null}
Draft a messaging framework for the launch of [product name]. Include: a one-sentence positioning statement, three key messages for each of these audiences: [audience 1], [audience 2], [audience 3], and two proof points per message. Reference the attached product brief.
```
**Complexity:** Medium | **Scope:** Multi-market | **Platform:** All
Scope out what localization, asset adaptation, and compliance work is needed to expand an existing campaign into new regions.
**Sample Prompt**
```text theme={null}
We want to launch [campaign name] in these 5 new markets: [market 1], [market 2], [market 3], [market 4], [market 5]. For each, outline what needs to be localized (copy, assets, compliance), what can be reused, and what net-new work is required.
```
**Complexity:** Medium | **Scope:** Research | **Platform:** All
Research how key competitors are positioning themselves on a topic or product area, then identify where your messaging is weaker, stronger, or missing entirely.
**Sample Prompt**
```text theme={null}
Research how [competitor 1], [competitor 2], and [competitor 3] are positioning themselves on [topic / product category]. Compare their messaging to ours at [our page URL or attached doc]. Identify: where we're stronger, where we're weaker, and any positioning angles they're using that we're not addressing.
```
**Complexity:** Medium | **Scope:** Ongoing monitoring | **Platform:** All
Set up a recurring check on competitor pages so you know whenever a rival updates their positioning, pricing, or key claims.
**Sample Prompt**
```text theme={null}
Monitor the following competitor pages on a [weekly / monthly] basis: [URL 1], [URL 2], [URL 3]. Alert me whenever copy, pricing, or key messaging changes significantly. Summarize what changed and flag anything that affects our positioning.
```
**Complexity:** Medium | **Scope:** Research | **Platform:** All
Identify the AI search queries where competitors are being cited but your brand isn't — so you know where to close the gap.
**Sample Prompt**
```text theme={null}
Run a set of AI search queries for [topic / product category] on [ChatGPT / Perplexity / Google AI Overviews]. For each query, note which competitors are cited and whether we appear. Identify the 5 queries where we're most absent and competitors are most present, and recommend what content changes would improve our visibility.
```
**Complexity:** Medium | **Scope:** Research | **Platform:** All
Look across your top-performing pages and identify patterns in topic, format, length, and structure — so you can replicate what works.
**Sample Prompt**
```text theme={null}
Analyze our top [N] performing pages by [metric: organic traffic / conversions / engagement] over the last [time period]. Identify what they have in common: topic type, content length, heading structure, use of visuals, and CTAs. Summarize the patterns and recommend how to apply them to new content.
```
Breaking strategy into executable work — briefs, task lists, timelines, and scoping. This includes working with your connected ticketing systems (Jira, Workfront, Wrike, Azure DevOps) to query what's in flight, intake new requests, and turn planning decisions into tracked work.
**Complexity:** Complex | **Scope:** Multi-platform | **Platform:** All
Upload a campaign brief and have Grady decompose and execute it across channels — web, email, and assets — following your configured Campaign Execution Guidance.
**Sample Prompt**
```text theme={null}
Run this campaign end-to-end per the attached brief and workflow diagram, following the Campaign Execution Guidance.
```
**Complexity:** Medium | **Scope:** Multi-platform | **Platform:** All
Adjust an in-flight campaign plan when the timeline shifts — re-sequencing tasks, updating deadlines, and flagging what needs to change.
**Sample Prompt**
```text theme={null}
Our campaign launch date has moved from [original date] to [new date]. Review the current plan and re-sequence all tasks, asset deadlines, and go-live dates accordingly. Flag anything that can no longer be completed in time.
```
**Complexity:** Complex | **Scope:** Multi-platform | **Platform:** All
Take a high-level creative idea and flesh it out into an actionable brief with channel assignments, dependencies, and a task breakdown.
**Sample Prompt**
```text theme={null}
Turn this creative concept into a full campaign brief: [describe concept]. Include: campaign goal, target audience, channel plan (web, email, social, paid), asset list, key messages, and a task breakdown I can use to kick off work in Gradial.
```
**Complexity:** Complex | **Scope:** Multi-page | **Platform:** All
Generate personalized landing pages at scale using CRM data — one per prospect, each customized with their name, company, and relevant content.
**Sample Prompt**
```text theme={null}
Using this page as a template: [reference page URL], create personalized landing pages for each row in the attached CSV. Substitute [first name], [company], and [use case] into the hero and body copy for each.
```
**Complexity:** Complex | **Scope:** Multi-page | **Platform:** All
Duplicate an existing site section into a new locale or region, then prepare it for localized content.
**Sample Prompt**
```text theme={null}
Clone the page structure under [source folder path] into the [target locale/region path, e.g., /content/site/en-gb/]. Carry over the templates and components, then flag which pages need content localization before they can go live.
```
**Complexity:** Small | **Scope:** Ticketing | **Platform:** Jira / Workfront / Wrike
Query your connected ticketing system for a live status summary across all in-flight campaigns — without opening the board.
**Sample Prompt**
```text theme={null}
In [Jira / Workfront / Wrike], give me a status summary of all active campaign tasks. Show: what's in progress, what's overdue, what's blocked and why, and what's ready for review. Group by campaign.
```
**Complexity:** Medium | **Scope:** Ticketing | **Platform:** Jira / Workfront / Wrike
Take an unstructured request — a Slack message, email, or brief — scope it, and create properly structured tickets in your connected system.
**Sample Prompt**
```text theme={null}
Intake this request: [paste or attach the request]. Scope it into discrete tasks, estimate complexity for each, and create tickets in [Jira / Workfront / Wrike] under [project / board name]. Assign to [team / person] and set the target date to [date].
```
**Complexity:** Complex | **Scope:** Ticketing | **Platform:** Jira
Set up a routing rule so that web update tickets in Jira automatically trigger Gradial tasks — no manual handoff required.
**Sample Prompt**
```text theme={null}
Set up automation so that any Jira ticket in [project key] with label [label name] or request type [type] automatically creates a corresponding Gradial task. Map the ticket fields [summary, description, URL, assignee] to the Gradial task fields.
```
**Complexity:** Small | **Scope:** Ticketing | **Platform:** Jira / Workfront / Wrike
Pull a focused view of the tickets in your current sprint that are blocked on or waiting for a content or web change.
**Sample Prompt**
```text theme={null}
In [Jira / Workfront / Wrike], show me all tickets in the current sprint that are waiting on a web content change. Include: ticket ID, title, who owns it, how long it's been waiting, and any linked pages or assets.
```
**Complexity:** Small | **Scope:** Workflow | **Platform:** All
Wire up a notification so you're pinged automatically when Grady completes a task and the page is staged for review — no manual checking required.
**Sample Prompt**
```text theme={null}
When this task is complete and the page is ready for review, send me a Slack notification in [channel name] with a link to the staged page and a summary of what changed.
```
**Complexity:** Medium | **Scope:** Workflow | **Platform:** All
Configure a review gate that routes completed tasks to a specific approver before they can go live — applied to a page type, folder, or tag.
**Sample Prompt**
```text theme={null}
Set up an approval workflow so that any task affecting pages in [folder path / tagged as compliance] requires sign-off from [legal reviewer role / person] before publishing. Route the review notification to [email / Slack channel].
```
Generating the content and imagery — copy, pages, product descriptions, hero images, and creative variants. Split into editorial and image work.
**Editorial**
**Complexity:** Complex | **Scope:** Single Page | **Platform:** All
Take a short source document and expand it into a fully structured web page — adding supporting sections, FAQs drawn from the source, and a clear call to action.
**Sample Prompt**
```text theme={null}
Using this attached one-pager as the source, create a full web page at [target path] using [reference page URL] as the structural template. Add an FAQ section based on the most likely customer questions from the content, and include a CTA to [desired action / URL].
```
**Complexity:** Complex | **Scope:** Single Page | **Platform:** All
Generate a complete landing page — copy, structure, and imagery — for a new product or campaign, staying within brand guidelines.
**Sample Prompt**
```text theme={null}
Build a new landing page for [product / campaign name] at [target path]. Use this page as a structural reference: [reference URL]. Write the headline, subhead, body copy, and CTA based on these key messages: [message 1], [message 2], [message 3]. Source on-brand hero and supporting images from the DAM at [folder path] or suggest alternatives.
```
**Complexity:** Complex | **Scope:** Multi-page | **Platform:** All
Update a set of older posts with current data, references, and on-page SEO improvements — then publish the refreshed versions.
**Sample Prompt**
```text theme={null}
Review all blog posts under [folder path] published in [year]. For each one: update outdated statistics with current figures, refresh any references to products or features that have since changed, and improve the meta description. Re-publish each post with today's date once updated.
```
**Complexity:** Medium | **Scope:** Single Page | **Platform:** All
Generate a relevant FAQ by mining your existing support documentation, then add it to the page as a structured component.
**Sample Prompt**
```text theme={null}
Add an FAQ section to this page: [page URL]. Source the questions and answers from our support docs at [URL or folder path]. Select the 5–8 questions most relevant to the page topic and add them using the [FAQ component name] component.
```
**Complexity:** Complex | **Scope:** Single Page | **Platform:** All
Build a fully populated product detail page from a spec sheet — mapping content to the right components automatically.
**Sample Prompt**
```text theme={null}
Create a new product detail page for [product name / SKU] at [target path]. Use this PDP as a structural reference: [reference URL]. Populate it with content from the attached spec sheet. Use the DAM at [folder path] for product images.
```
**Complexity:** Complex | **Scope:** Multi-page | **Platform:** All
Translate and locally adapt a page or content set for multiple markets — adjusting not just language but regional messaging, offers, and compliance.
**Sample Prompt**
```text theme={null}
Create localized versions of this page: [source page URL] for the following markets: [market 1 / language], [market 2 / language], [market 3 / language]. Translate the copy, adapt any region-specific pricing or offers, and ensure compliance text is included for each market. Place each at [target path structure].
```
**Complexity:** Medium | **Scope:** Multi-page | **Platform:** All
Identify low-quality pages that rank but deliver little value, and rewrite them with substantive, query-matching content.
**Sample Prompt**
```text theme={null}
Review these pages: [list of URLs]. For each one, identify the primary search query it's targeting, assess whether the current content adequately answers it, and rewrite any page that falls short. Prioritize factual depth, clear structure, and direct answers.
```
**Image Creation**
**Complexity:** Medium | **Scope:** Single Page | **Platform:** All
Produce AI-generated hero imagery that matches your brand guidelines and campaign brief, ready to drop into a page or store in the DAM.
**Sample Prompt**
```text theme={null}
Generate a hero image for this campaign page: [page URL or campaign name]. Style: [describe visual style, e.g., clean product shot on white, lifestyle photography, abstract gradient]. Brand colors: [primary / secondary]. Dimensions: [e.g., 1440×600]. Save the output to [DAM folder path].
```
**Complexity:** Small | **Scope:** Multi-asset | **Platform:** All
Take a single source image and produce correctly cropped variants for every breakpoint and channel — no manual editing required.
**Sample Prompt**
```text theme={null}
Smart-crop this image: [DAM path] for the following breakpoints and placements:
- Desktop hero: 1440×600 (keep subject centered)
- Mobile hero: 390×520 (keep subject in upper third)
- Social share: 1200×630 (square-safe zone)
- Instagram square: 1080×1080
Save all outputs to [DAM folder path].
```
**Complexity:** Complex | **Scope:** Multi-asset | **Platform:** All
Create a set of AI-generated lifestyle images showing the product in context — for use across PDPs, campaigns, and social.
**Sample Prompt**
```text theme={null}
Generate [number] lifestyle images for [product name] based on this brief: [describe scene, setting, target audience, mood]. Reference our brand style guide at [URL or attached file]. Output at [dimensions] and save to [DAM folder path]. Flag any outputs that don't meet brand standards for review.
```
**Complexity:** Medium | **Scope:** Multi-asset | **Platform:** All
Produce audience-specific variants of a single creative — adjusting copy overlays, color treatment, or composition to suit each segment.
**Sample Prompt**
```text theme={null}
Take this source image: [DAM path] and create variants for the following audience segments: [segment 1 — describe], [segment 2 — describe], [segment 3 — describe]. Adjust [copy overlay / color treatment / background] per segment while keeping the core composition. Save each variant to [DAM folder path] with segment name in the filename.
```
Getting assets organized, tagged, and compliant before they're used. The cleaner your DAM, the faster Grady can find and use the right asset.
**Complexity:** Small | **Scope:** DAM | **Platform:** DAM
Add new tags to the tagging taxonomy for organizing and classifying content, pages, or other assets.
**Sample Prompt**
```text theme={null}
Add the following tags to the tagging taxonomy: [tag1] under [category, e.g., Content Type], [tag2] under [category, e.g., Page Classification], and [tag3] under [category, e.g., Campaign Theme]. Apply them to [content type, e.g., Campaign Theme, blog posts].
```
**Complexity:** Small | **Scope:** DAM | **Platform:** DAM
Modify or update existing tags within the tagging taxonomy to reflect revised naming, categorization, or structure.
**Sample Prompt**
```text theme={null}
In the tagging taxonomy, rename the tag [old tag name] under [category] to [new tag name]. Also, move the tag [tag name] from [old parent category] to [new parent category] to reflect the updated classification structure.
```
**Complexity:** Small | **Scope:** Single asset | **Platform:** All
Update the metadata associated with an asset — description, tags, and other attributes.
**Sample Prompt**
```text theme={null}
For this asset: [asset path or name], update the description to [new description] and add the following tags: [tag1, tag2, tag3].
```
**Complexity:** Complex | **Scope:** Multi-asset | **Platform:** DAM
Bulk-classify a backlog of untagged assets using content recognition — applying consistent taxonomy without manual review of each file.
**Sample Prompt**
```text theme={null}
Review all untagged assets in [DAM folder path] and apply appropriate tags from our taxonomy. Use the asset content and filename to infer type, campaign, region, and subject matter. Flag any assets you're uncertain about for manual review.
```
**Complexity:** Medium | **Scope:** Multi-page | **Platform:** All
Locate every instance of a deprecated asset across the site and in active campaigns, then replace them with the updated version.
**Sample Prompt**
```text theme={null}
Find every page and active email campaign using the old logo at [old DAM path] and replace it with the updated version at [new DAM path]. Report a list of everything changed.
```
**Complexity:** Medium | **Scope:** Multi-page | **Platform:** All
Audit live pages against a list of assets with expired or restricted licenses and surface anything that needs to be replaced.
**Sample Prompt**
```text theme={null}
Cross-reference the assets used on our live pages against this list of expired-license images: [attached CSV or list of DAM paths]. Flag every page that contains one and queue them for image replacement.
```
**Complexity:** Medium | **Scope:** Multi-asset | **Platform:** DAM
Auto-generate a set of social share images from blog post content, applying brand templates and storing the outputs in the DAM.
**Sample Prompt**
```text theme={null}
Create social share cards for these 10 blog posts: [list of URLs]. Use the [social card template name] template, pull the headline and hero image from each post, and save the outputs to [DAM folder path].
```
Getting the right content to the right audiences across email, web, and other channels. Grady can build, schedule, and personalize campaigns end-to-end.
**Complexity:** Medium | **Scope:** Single email | **Platform:** Email
Add or remove content modules within an existing Marketo or SFMC email to adjust its layout and structure.
**Sample Prompt**
```text theme={null}
In this Marketo email: [email name or ID], add a [module name, e.g., Text + Image] module below the [existing module name or position]. Then delete the [module name or description] module that is no longer needed.
```
**Complexity:** Medium | **Scope:** Single campaign | **Platform:** Email
Duplicate an existing Marketo or SFMC campaign with all its settings — smart list filters, flow steps, and schedule configuration.
**Sample Prompt**
```text theme={null}
In Marketo, clone this campaign: [campaign name or ID] with all of its current settings, including smart list filters, flow steps, and schedule. Name the cloned campaign [new campaign name] and place it in [folder or program path].
```
**Complexity:** Medium | **Scope:** Single campaign | **Platform:** Email
Schedule a Marketo or SFMC batch campaign to run at a specified date and time with defined person qualification rules.
**Sample Prompt**
```text theme={null}
In Marketo, schedule a batch campaign: [campaign name or ID] to run on [date and time, e.g., 2025-04-15 at 9:00 AM EST]. Use the existing smart list and flow settings. Set the person qualification rules to [run each person once / allow re-entry].
```
**Complexity:** Complex | **Scope:** Single email | **Platform:** Email
Create a new email in Marketo or SFMC using a predefined template, populated with provided subject line, header, body copy, CTA, and image content.
**Sample Prompt**
```text theme={null}
In Marketo, create a new email using the [template name] template. Populate it with the following content:
Subject line: [subject line]
Header: [header text]
Body: [body copy]
CTA: [CTA text and link]
Image: [image path or description]
```
**Complexity:** Complex | **Scope:** Multi-email | **Platform:** Email
Design and build a complete onboarding email series — sequenced, timed, and loaded into your MAP — without writing each email from scratch.
**Sample Prompt**
```text theme={null}
Build a 5-email welcome journey in [Marketo / SFMC] for new trial signups. Use our brand voice guidelines and the following content themes:
Email 1 (Day 0): Welcome + getting started
Email 2 (Day 2): Key feature highlight
Email 3 (Day 5): Use case spotlight
Email 4 (Day 10): Community / resources
Email 5 (Day 14): Upgrade nudge
Reference this existing email for tone and structure: [example email name or URL].
```
**Complexity:** Complex | **Scope:** Multi-email | **Platform:** Email
Translate and adapt an email campaign for multiple regional markets, applying locale-specific copy, imagery, and compliance requirements.
**Sample Prompt**
```text theme={null}
Localize this email campaign: [campaign name or ID] for the following markets: [market 1], [market 2], [market 3]. Translate copy, adapt CTAs for regional offers, and ensure each version includes the required footer compliance text for that region.
```
**Complexity:** Medium | **Scope:** Segment | **Platform:** Email
Build and launch a win-back campaign targeting a lapsed segment with a tailored offer, automatically suppressing anyone who re-engages.
**Sample Prompt**
```text theme={null}
In [Marketo / SFMC], build a re-engagement campaign targeting contacts who haven't opened any email in the last 90 days. Use a subject line that acknowledges the gap, offer [incentive or value prop], and suppress anyone who opens or clicks from future re-engagement sends.
```
**Complexity:** Medium | **Scope:** Single email | **Platform:** Email
Draft, build, and schedule the monthly newsletter to segmented lists — from content assembly to send.
**Sample Prompt**
```text theme={null}
Write and schedule this month's newsletter in [Marketo / SFMC]. Pull the top 3 blog posts from [URL or feed], include a spotlight on [product / campaign / event], and send to [list name] on [date] at [time, timezone]. Use the [newsletter template name] template.
```
The hands-on CMS work — updating existing pages, creating new ones, and managing fragments. This is where Grady does the heavy lifting inside your content system.
**Content Updates**
**Complexity:** Small | **Scope:** Single Page | **Platform:** All
Update a single content element on the page — e.g., a hero headline, section title, or CTA label.
**Sample Prompt**
```text theme={null}
On this page: [page URL], update the hero headline to [new headline text].
```
**Complexity:** Small | **Scope:** Single Page | **Platform:** All
Change multiple copy elements on a single page in one pass.
**Sample Prompt**
```text theme={null}
On this page: [page URL], update the hero headline to [new headline] and change the body text in the second section to [new body copy].
```
**Complexity:** Small | **Scope:** Single Page | **Platform:** All
Replace images on a single page using files attached directly to the task.
**Sample Prompt**
```text theme={null}
On this page: [page URL], replace the hero image with the attached file [filename.jpg] and swap the banner image in the promo section with [filename2.png].
```
**Complexity:** Small | **Scope:** Single Page | **Platform:** All
Replace images on a single page by referencing existing assets via their CMS/DAM path.
**Sample Prompt**
```text theme={null}
On this page: [page URL], replace the hero image with the asset located at DAM path [e.g., /content/dam/images/hero-new.jpg].
```
**Complexity:** Small | **Scope:** Single Page | **Platform:** All
Attach an annotated screenshot to the task and have Grady apply the edits described in the annotations.
**Sample Prompt**
```text theme={null}
On this page: [page URL], make the edits shown in the attached annotated screenshot.
```
**Complexity:** Small | **Scope:** Single Page | **Platform:** All
Update the defined style on a given page element — e.g., button style, hero style, or theme variant.
**Sample Prompt**
```text theme={null}
On this page: [page URL], change the hero banner style from [current style] to [new style] and update the CTA button style to [new button style].
```
**Complexity:** Small | **Scope:** Single Page | **Platform:** All
Update hidden page metadata — page title, meta description, SEO description, and keywords.
**Sample Prompt**
```text theme={null}
On this page: [page URL], update the page title to [new title], the meta description to [new description], and the SEO keywords to [new keywords].
```
**Complexity:** Small | **Scope:** Single Page | **Platform:** All
Create a new version of an existing page with specific content changes — e.g., a localized or campaign-specific variant.
**Sample Prompt**
```text theme={null}
Using this page as a reference: [source page URL], create a new variant with the following content changes: [list of localized/updated content].
```
**Complexity:** Medium | **Scope:** Single Page | **Platform:** All
Execute several discrete changes from a single task — updating copy, swapping assets, removing/adding components, and updating links.
**Sample Prompt**
```text theme={null}
On this page: [page URL], make the following changes:
(1) Update the hero headline to [new headline].
(2) Swap the hero image with [DAM path or attached file].
(3) Remove the [component name] section.
(4) Update the CTA link to [new URL].
```
**Complexity:** Complex | **Scope:** Single Page | **Platform:** All
Add a component to an existing page by specifying the component type and where it should be placed.
**Sample Prompt**
```text theme={null}
On this page: [page URL], add a [component name, e.g., Text + Image] component below the [existing component name or position] with the following content: [content details].
```
**Complexity:** Complex | **Scope:** Single Page | **Platform:** All
Remove a component from an existing page, identified either by name or by description of its position.
**Sample Prompt**
```text theme={null}
On this page: [page URL], remove the [component name or description, e.g., the promotional banner below the hero section].
```
**New Page**
**Complexity:** Complex | **Scope:** Single Page | **Platform:** All
Create a new CMS page using a Word document as the content source, with an existing page as the structural reference.
**Sample Prompt**
```text theme={null}
Create a new [page type, e.g., Article] page using this page as a reference: [reference page URL]. Populate it with the content from the attached Word document [filename.docx].
```
**Complexity:** Complex | **Scope:** Single Page | **Platform:** All
Create a new CMS page using a Figma design file as the content and layout source.
**Sample Prompt**
```text theme={null}
Create a new [page type, e.g., Landing Page] page using this page as a reference: [reference page URL]. Use the content and layout from this Figma link: [Figma URL].
```
**Complexity:** Complex | **Scope:** Single Page | **Platform:** All
Create a new CMS page by pulling content from a public URL, with an existing page as the structural reference.
**Sample Prompt**
```text theme={null}
Create a new [page type, e.g., Product Page] page using this page as a reference: [reference page URL]. Pull the content from this public URL: [source URL].
```
**Complexity:** Complex | **Scope:** Single Page | **Platform:** All
Create a new CMS page using only a text prompt for content, with an existing page as the structural reference.
**Sample Prompt**
```text theme={null}
Create a new [page type, e.g., Campaign Page] page using this page as a reference: [reference page URL]. Use the following content:
Headline: [headline]
Body: [body text]
CTA: [CTA text and link]
Image: [image description or DAM path]
```
**Fragments** *(AEM)*
**Complexity:** Small | **Scope:** Single fragment | **Platform:** AEM
Update a single field on an existing content fragment.
**Sample Prompt**
```text theme={null}
On this content fragment: [content fragment path], update the [field name] to [new value].
```
**Complexity:** Small | **Scope:** Single fragment | **Platform:** AEM
Update a single content element on an existing experience fragment.
**Sample Prompt**
```text theme={null}
On this experience fragment: [experience fragment path], update the [element name] to [new text].
```
**Complexity:** Medium | **Scope:** Single fragment | **Platform:** AEM
Create a new content fragment with specified field values.
**Sample Prompt**
```text theme={null}
Create a new content fragment at [path] with the following fields:
[field1]: [value1]
[field2]: [value2]
[field3]: [value3]
```
**Complexity:** Medium | **Scope:** Single fragment | **Platform:** AEM
Create a new experience fragment based on an existing reference fragment.
**Sample Prompt**
```text theme={null}
Create a new experience fragment at [path] using this reference: [reference XF path]. Update the content to: [new content details].
```
Checking work before it ships — QA, accessibility, brand compliance, and legal review. Grady can run these checks automatically so nothing goes live with issues.
**Complexity:** Small | **Scope:** Single Page | **Platform:** All
Check a page for broken links, rendering issues, missing metadata, and component errors before publishing.
**Sample Prompt**
```text theme={null}
Run a QA check on this page before it goes live: [page URL or staging URL]. Check for: broken links, missing images, metadata completeness, component rendering errors, and mobile display issues. Return a pass/fail summary with details on anything that needs fixing.
```
**Complexity:** Complex | **Scope:** Multi-page | **Platform:** All
Audit pages against WCAG standards, surface violations, and create a remediation task list.
**Sample Prompt**
```text theme={null}
Run an accessibility audit on [page URL / site section]. Check against WCAG 2.1 AA standards. Return a list of violations organized by severity, and create tasks in Gradial for each fix.
```
**Complexity:** Complex | **Scope:** Multi-page | **Platform:** All
Audit the site against an updated brand guideline and apply corrections across all affected pages in a single pass.
**Sample Prompt**
```text theme={null}
Find every page where we're using [old brand element, e.g., the old logo / deprecated color / outdated typeface] and replace it with the updated version per our brand guidelines at [guidelines URL or attached doc].
```
**Complexity:** Medium | **Scope:** Multi-page | **Platform:** All | **Suggested cadence:** Monthly
Audit a set of key pages against brand guidelines and flag anything off-brand for review.
**Sample Prompt**
```text theme={null}
Audit the following pages against our brand guidelines: [page URL 1], [page URL 2], [page URL 3]. Flag any copy, imagery, or styling that is off-brand and summarize the issues found.
```
**Complexity:** Medium | **Scope:** Multi-page | **Platform:** All
Apply consistent structure, heading hierarchy, and formatting to a set of policy pages that have drifted from the standard.
**Sample Prompt**
```text theme={null}
Standardize the formatting on all pages in [folder path, e.g., /legal/]. Apply consistent H1/H2/H3 hierarchy, paragraph spacing, and link styling per our style guide. Flag any pages with content that needs human review before changes are applied.
```
**Complexity:** Medium | **Scope:** Multi-page | **Platform:** All
Bulk-insert a required legal element across a regional page set without touching each page individually.
**Sample Prompt**
```text theme={null}
Add the following EU compliance disclaimer to the footer of every product page under [regional folder path]: "[disclaimer text]". Apply only to pages that don't already include it.
```
Getting content live — bulk publishing, find-and-replace across pages, scheduled sends, and rollout operations.
**Complexity:** Medium | **Scope:** Single Page | **Platform:** All
Find specific terms within a single page and replace all instances with a new term.
**Sample Prompt**
```text theme={null}
On this page: [page URL], find all instances of [old term] and replace them with [new term].
```
**Complexity:** Medium | **Scope:** Multi-page | **Platform:** All
Find specific terms across multiple pages and replace all instances with a new term.
**Sample Prompt**
```text theme={null}
Across the following pages: [page URL 1], [page URL 2], [page URL 3] — find all instances of [old term] and replace them with [new term].
```
**Complexity:** Medium | **Scope:** Multi-page | **Platform:** All
Update copy across multiple pages. Can be run via prompt with a page list or as a Batch Task — batch is preferred for large sets.
**Sample Prompt**
```text theme={null}
Across the following pages: [page URL 1], [page URL 2], [page URL 3] — update [content element, e.g., component name] from [old value] to [new value]. Apply this as a batch task.
```
**Complexity:** Medium | **Scope:** Multi-page | **Platform:** All
Update asset references across multiple pages. Can use attached uploaded assets or existing DAM paths. Preferred as a batch task for large sets.
**Sample Prompt**
```text theme={null}
Across the following pages: [page URL 1], [page URL 2], [page URL 3] — replace the [component name] image with the asset at [DAM path or attached file]. Apply this as a batch task.
```
**Complexity:** Medium | **Scope:** Multi-page | **Platform:** All
Push a new promotional banner to every regional homepage simultaneously.
**Sample Prompt**
```text theme={null}
Swap the hero banner on all regional homepages to the [holiday/seasonal] promo using the asset at [DAM path]. Apply to: [list of locale URLs or folder path].
```
**Complexity:** Medium | **Scope:** Multi-page | **Platform:** All | **Suggested cadence:** Weekly or monthly
Periodically catch outdated terms — a deprecated product name, old legal phrasing, or a rebranded term — across a page set.
**Sample Prompt**
```text theme={null}
Across the following pages: [page URL 1], [page URL 2], [page URL 3] — find any instances of [outdated term] and replace them with [approved term]. Report which pages were changed.
```
**Complexity:** Medium | **Scope:** Single campaign | **Platform:** Email | **Suggested cadence:** Weekly
Run a recurring Marketo or SFMC batch campaign on a fixed weekly schedule using existing list and flow settings.
**Sample Prompt**
```text theme={null}
In Marketo, run the batch campaign [campaign name or ID] using the existing smart list and flow settings. Confirm the number of people who qualified and the send status.
```
Understanding what worked, fixing what didn't, and continuously improving — from performance reports to SEO, GEO, and A/B testing.
**Insights & Analytics**
**Complexity:** Medium | **Scope:** Site-wide | **Platform:** All
Identify pages where organic traffic is declining and surface the likely causes.
**Sample Prompt**
```text theme={null}
Analyze traffic trends across our site over the last 6 months and identify pages where month-over-month organic traffic has declined by more than [X]%. For each, note the probable cause and recommend whether to update, consolidate, or retire the page.
```
**Complexity:** Medium | **Scope:** Site-wide | **Platform:** All
Pull the key performance metrics for the quarter and package them into a concise, exec-ready summary.
**Sample Prompt**
```text theme={null}
Summarize web marketing performance for [Q / date range]. Include: total traffic and trend, top-performing pages, conversion rates, and the top 3 initiatives that drove results. Format it as a one-page board summary.
```
**Complexity:** Medium | **Scope:** Multi-channel | **Platform:** All
Analyze pipeline attribution across channels and surface which ones are delivering the best-quality leads.
**Sample Prompt**
```text theme={null}
Analyze pipeline attribution for [time period]. Compare channels by: lead volume, opportunity conversion rate, average deal size, and time to close. Identify which channel is driving the highest-quality pipeline and recommend where to shift investment.
```
**Complexity:** Medium | **Scope:** Multi-page | **Platform:** All | **Suggested cadence:** Weekly
Run a recurring GEO visibility report so the team sees brand and competitor movement on a regular rhythm.
**Sample Prompt**
```text theme={null}
Run a GEO report on [yourwebsite.com] and summarize how our brand visibility has changed since the last report.
```
**SEO & GEO**
**Complexity:** Medium | **Scope:** Site-wide | **Platform:** All
Run a full technical SEO audit and get a prioritized list of issues — from crawlability and indexing to metadata gaps and redirect chains.
**Sample Prompt**
```text theme={null}
Run a technical SEO audit on [domain URL]. Check for: crawlability issues, missing or duplicate meta titles and descriptions, broken internal links, redirect chains, pages blocked from indexing, and missing schema markup. Return a prioritized list of issues to fix.
```
**Complexity:** Medium | **Scope:** Multi-page | **Platform:** All
Identify pages with missing or duplicate metadata and generate on-brand, keyword-relevant replacements in bulk.
**Sample Prompt**
```text theme={null}
Find every page in [folder path or site section] that is missing a meta title or meta description. Write SEO-optimized versions for each, using our brand voice and targeting the primary keyword for each page. Apply the updates.
```
**Complexity:** Medium | **Scope:** Site-wide | **Platform:** All
Crawl the site, identify broken links and unnecessary redirect hops, and resolve them.
**Sample Prompt**
```text theme={null}
Crawl [domain URL] and identify all broken internal links (404s) and redirect chains (3+ hops). Fix broken links by pointing them to the correct current destination. Simplify redirect chains to a single hop where possible.
```
**Complexity:** Complex | **Scope:** Multi-page | **Platform:** All
Rewrite and restructure content so it's more likely to be cited by generative engines like ChatGPT, Perplexity, and Google AI Overviews.
**Sample Prompt**
```text theme={null}
Optimize our content for generative engine visibility on these topics: [topic 1], [topic 2], [topic 3]. For each, identify the pages most relevant to that topic, rewrite them to include clear factual statements and direct answers, and add structured data where applicable.
```
**Complexity:** Medium | **Scope:** Single Page | **Platform:** All
Optimize a page's content to improve visibility and citation likelihood in AI-powered search engines.
**Sample Prompt**
```text theme={null}
On this page: [page URL], optimize the content for generative engine visibility. Rewrite or supplement the content to include clear, factual statements, direct answers to likely search questions, and well-structured information about [topic or subject matter]. Prioritize clarity and specificity so the content is more likely to be cited by AI search tools.
```
**Complexity:** Medium | **Scope:** Multi-prompt | **Platform:** All
Track brand and competitor visibility across AI search engines as a time series on a recurring cadence.
Because the value comes from the breadth of the set, this isn't a single paste-able prompt. Download the starter set below, fill in your brand and competitors, and bulk-upload it from the **Prompts** tab.
20+ example prompts with topics, personas, and tags — formatted for Bulk Import.
See [GEO Monitoring](/docs/insights/geo-monitoring) for the full setup and how topics, personas, and tags work.
**CX & Performance**
**Complexity:** Medium | **Scope:** Multi-page | **Platform:** All
Walk the full signup journey and surface every point where users can get stuck, hit a broken link, or encounter a non-functional CTA.
**Sample Prompt**
```text theme={null}
Audit our signup flow starting at [entry URL]. Walk every step and identify: broken CTAs, dead ends, form errors, pages that don't load correctly, and any steps where the journey stops unexpectedly. Return a list of issues with page URLs and descriptions.
```
**Complexity:** Medium | **Scope:** Single Page | **Platform:** All
Set up a controlled experiment on a landing page — defining the variant, hypothesis, and success metric.
**Sample Prompt**
```text theme={null}
Set up an A/B test on this page: [page URL]. Create a variant that changes [element, e.g., the hero headline / CTA copy / hero image] to [new version]. Define the success metric as [conversion event] and run the test until we reach statistical significance.
```
**Complexity:** Complex | **Scope:** Multi-page | **Platform:** All
Trace the full conversion path and pinpoint exactly where users abandon.
**Sample Prompt**
```text theme={null}
Map the full journey from [ad entry URL] through to [purchase confirmation URL]. Identify the steps where we see the highest drop-off, and for each one describe what the user experience looks like and what's likely causing the abandonment.
```
**Complexity:** Medium | **Scope:** Multi-page | **Platform:** All
Compare desktop and mobile rendering across key pages and flag the worst breakpoints and missing elements.
**Sample Prompt**
```text theme={null}
Compare the desktop and mobile experience across these key pages: [list of URLs]. Identify the most significant differences in layout, component rendering, and usability. Prioritize issues by impact and provide a fix recommendation for each.
```
**Complexity:** Complex | **Scope:** Multi-page | **Platform:** All
Review completed experiments, identify statistically significant winners, and promote the winning variants.
**Sample Prompt**
```text theme={null}
Review all completed experiments run in the last [time period]. For each one that reached statistical significance, identify the winning variant and apply it to the full page population. Summarize the lift achieved for each.
```
# Audiences
Source: https://docs.gradial.com/docs/insights/audiences
Group personas into named, reusable audiences for CX Optimizer runs — so you never have to rebuild your target audience from scratch.
Audiences add a targeting layer on top of personas for CX Optimizer. Instead of selecting personas one by one for every run, teams can save named audiences, organize personas inside them, and reference those groups directly from chat when launching CX Optimizer.
Think of it as:
* **Persona** — one simulated buyer or user
* **Segment / tag** — metadata used to narrow personas
* **Audience** — a saved group of personas that can be reused across runs
This makes CX Optimizer more repeatable for demos, account planning, and post-launch validation because the target audience definition can be reused instead of rebuilt every time.
## What you can do
When the Audiences feature is enabled, teams can:
* Group existing personas into named audiences such as `Enterprise Buying Committee`, `Healthcare Prospects`, or `Trial-to-Paid Evaluators`
* Keep audiences at the organization level for broad reuse, or scope them to a workspace for team-specific or deal-specific testing
* Move or copy personas between audiences as the target scenario changes
* Reference an audience directly in chat with the Journey Agent when launching a CX Optimizer flow
* Layer segment or tag filters on top of an audience when you want a narrower slice inside the saved group
Creating and editing audiences is limited to Admin and Design roles.
## How it works with CX Optimizer
Build personas that represent real customer types in your organization.
Organize those personas into one or more saved audiences.
Ask CX Optimizer to run against a named audience directly in chat.
The Journey Agent resolves the audience, pulls the matching personas, and launches persona-based journey analysis.
The final report reflects the selected audience rather than a generic user.
If the audience has **5 or fewer personas**, CX Optimizer runs against all of them. If it has **more than 5**, the agent samples up to 5 for a single run so the analysis stays manageable and comparable.
## Where segments fit
Use audiences when you want a stable, reusable group. Use segments or tags when you want to filter within that group.
**Example:**
* Audience: `Enterprise Buying Committee`
* Segments inside it: `security`, `marketing-ops`, `web-owner`, `executive`
That lets a team run:
* The full audience for a broad journey review
* Only the `security` and `web-owner` segments for a technical evaluation flow
* A narrower sub-group without rebuilding the saved audience
## Use cases
Group the personas involved in one deal cycle, then run CX Optimizer against that audience to show where different stakeholders experience friction across the same journey.
**Example audience:** `Enterprise Buying Committee` — Marketing lead, web manager, compliance reviewer, procurement stakeholder
This tells a stronger story than a single generic persona and shows how one site experience lands differently across roles.
Create vertical audiences such as `Healthcare`, `Financial Services`, or `Higher Ed` and test whether the site's messaging and flows work for that industry's expectations.
Useful for industry landing pages, ABM campaigns, and vertical demos — and helps position CX Optimizer as persona-aware rather than one-size-fits-all.
Group personas by journey stage such as `First-Time Evaluators`, `In-Market Buyers`, or `Existing Customer Expansion`.
Lets teams test whether pages support discovery, evaluation, and conversion differently — a good fit for pricing, demo request, onboarding, and support journeys.
Create a workspace-scoped audience for a live opportunity and run CX Optimizer against the exact stakeholder mix that matters for that account.
Keeps the analysis relevant to one prospect or account team. Useful for SE-led workshops and pre-demo prep.
Reuse the same audience after a redesign, launch, or content update to compare how the journey changed for the same target group.
Makes CX Optimizer runs more consistent over time and makes it easier to show before-and-after improvement to customers.
Use a broad audience, then narrow it with segments in chat for a more focused read.
**Example:** Audience: `SMB Prospects` + Segment filter: `mobile-first`
Gives teams a clean way to tailor the story without rebuilding personas every time.
## Sample chat prompts
* "Run CX Optimizer on our pricing flow for the Enterprise Buying Committee audience."
* "Audit the signup journey for the Healthcare audience, using only the security and compliance segments."
* "Run a mobile CXO pass against the SMB Prospects audience."
* "Use the Existing Customer Expansion audience to review our support-to-upsell journey."
## Things to keep in mind
* Audiences are built from existing personas — they are not a replacement for persona design.
* A single CX Optimizer run still caps persona fanout at 5 personas per run.
* Segment or tag filters can be layered onto an audience, but if the filter removes every persona, broaden the selection or run a generic-user analysis instead.
***
## Availability
**Access:** Must be enabled for your organization. Contact your Gradial team to get access.
# Custom Apps
Source: https://docs.gradial.com/docs/insights/custom-apps
Turn a prompt into a governed dashboard, report, or intake form built on your live Gradial and connected system data — authored by Grady, refreshed on demand, and scoped to each viewer's permissions.
## Overview
Every team ends up wanting a view that no standard report gives them: the assets that failed QA this week, a running intake queue for creative requests, campaign progress across web, email, and social in one place.
**Custom apps** are Grady-built applications that answer exactly that. You describe the view you want, and Grady generates a working app — dashboards, reports, and forms built on live data from Gradial and from your connected systems — that lives in the task and refreshes against current data whenever you open or refresh it.
They're not hand-built. You don't configure widgets or write queries. You describe what you need to see, and iterate with Grady until it's right.
**Access:** Must be enabled for your organization. Contact your Gradial team to get access.
***
## What you can build
Surface which assets passed or failed quality and accessibility checks, what's missing alt text, and which items need a human look — reading straight from your connected DAM, across a campaign delivery rather than one asset at a time.
Stand up a request queue in minutes. Teammates submit structured requests through a form, submissions are stored with attribution, and Grady picks the work up from there.
Report against your connected ticketing system — what's open, what's blocked, what's aged past its SLA — without exporting to a spreadsheet or waiting on someone to build a Jira view.
Pull campaign data spanning web, email, and social into one dashboard, drawing on each connected platform, so progress and gaps read at a glance instead of channel by channel.
**The system has to be integrated.** Custom apps read your Gradial data — tasks, artifacts, activity, and shared records — plus data from any system Gradial is connected to, such as an external DAM or your ticketing system. If Gradial isn't integrated with a system, an app can't report on it. See [Integrations](/docs/integrations-administration-and-setup/integrations/get-started-with-integrations) for what's connected today.
***
## The three building blocks
Every custom app is some combination of these.
### Live, governed data
Apps query your tasks, artifacts, activity, and shared records directly — and, where Gradial is integrated with a system, that system's data too — rather than working from a snapshot someone exported. Refreshing an app re-runs its queries against current data.
This is what makes a custom app different from a spreadsheet export: the export is stale the moment it's made, while the app reflects the state of your DAM, ticketing system, or campaign platform at the moment it's refreshed.
Every query is read-only, scoped to the permissions of whoever is viewing, and audited. An app can't change your data — in Gradial or in a connected system — only read and present it.
### Generated interfaces
From a single prompt, Grady builds the interface to match the data: metric strips for headline numbers, responsive tables, and charts, with proper loading and error states rather than a blank panel when something is slow.
### Forms and actions
Apps can collect input as well as display it. Form submissions are stored as attributed shared records — you always know who submitted what and when — and Grady can read those submissions back and act on them.
This is what turns a dashboard into a workflow. An intake form isn't just a record of requests; ask Grady to process the queue and it works from those same submissions. For example, collecting requested DAM metadata rewrites through a form, then asking Grady to apply them.
***
## Building one
Say what you need to see and who it's for. "A dashboard of every asset we uploaded this month that's missing alt text, grouped by campaign" is enough to start.
The app appears in the task. Check that the numbers match what you expect before anyone else relies on it.
Ask for changes the way you'd ask a colleague — add a column, group it differently, chart the trend instead of listing rows.
Teammates open the app and see it rendered against the data they're permitted to see.
***
## Designing apps that work well
**Go aggregate-first.** The queries behind an app are deliberately bounded — read-only, a few seconds, a couple hundred rows. Summary views, counts, groupings, and rollups perform well. A long list of raw records is the wrong shape; ask for the summary and drill in from there.
**Expect results to differ between viewers.** Because every query runs with the viewer's permissions, two people can open the same dashboard and correctly see different numbers. That's the governance model working, not a bug — but it's worth saying out loud when you share an app with a wider group.
**Refresh is on demand.** Apps re-query when someone refreshes them rather than polling continuously, so the data is current as of the last refresh rather than streaming live.
**Submitting and processing are separate steps.** Form submissions are stored immediately, but Grady acts on them when you ask it to. An intake form fills up on its own; working the queue is a request.
***
## Example prompts
```
Build me a dashboard of every asset uploaded to the Spring campaign folder
this month, showing which ones failed QA and which are missing alt text.
Group by sub-campaign and show the totals up top.
```
```
Create an intake form for creative requests — requester, campaign, channel,
deadline, and a description field — and a table underneath showing everything
submitted so far.
```
```
Build a report on our Jira queue this quarter: how many issues are open, how
many are blocked, and which have been waiting longest — grouped by project.
```
```
Give me one dashboard covering our Q3 campaign across web, email, and social —
pull from the CMS, the email platform, and our social data so I can see what's
shipped, what's in review, and what hasn't started.
```
***
## Related
* [Ask Grady →](/docs/getting-started/ask-grady) — asking Grady questions about your Gradial data directly, without building an app
* [Integrations →](/docs/integrations-administration-and-setup/integrations/get-started-with-integrations) — connecting the systems an app can report on
* [Digital Asset Management →](/docs/asset-management/digital-asset-management) — asset governance the QA dashboards report on
* [QA Reports →](/docs/quality-assurance-and-accessibility/qa-report) — the underlying quality checks
* [Cross-Channel Campaign Execution →](/docs/campaign-management/cross-channel-campaigns)
# Generative Engine Optimization (GEO)
Source: https://docs.gradial.com/docs/insights/geo
Score your AI visibility, execute the fixes, and publish into your CMS through your existing review and approval path.
## From Analysis to Action — Without the Bottleneck
Most GEO tools give you a report. Gradial gives you results.
When buyers search in ChatGPT, Claude, Perplexity or other AI search platforms, AI engines decide which brands get named — and most marketing teams can't see it happening, let alone fix it. The tools that do surface this gap hand you a spreadsheet and walk away. That means more work for already-stretched content teams: triaging findings, writing fixes, routing approvals, coordinating with developers, and publishing — all before a single improvement goes live.
Gradial closes that loop. It scores your AI visibility, writes the fixes, validates them against simulated AI personas, and publishes into your CMS through your review and approval path. One person can run an entire GEO program without an agency, a dev queue, or extra headcount.
***
## What Gradial Does Differently
Other platforms stop at the recommendation. Gradial executes it.
| Capability | Gradial | Report-only tools |
| ---------------------------------------------------- | :--------------: | :---------------: |
| GEO scoring & auditing | **✓** | ✓ |
| Recommendations grouped by type with linked evidence | **✓** | ✓ |
| Scored impact, effort and urgency ranking | *In development* | ✓ |
| Executes fixes and stages them for publishing | **✓** | - |
| CMS integration (read/write) | **✓** | - |
| DAM integration | **✓** | - |
| Pre-publish validation with simulated AI personas | **✓** | - |
***
## GEO and SEO, Together
Gradial isn't a replacement for your SEO program — it extends it.
Your SEO team's work remains intact. Gradial publishes GEO-optimized variants alongside your existing SEO pages, so there's no tradeoff between ranking on Google and getting cited by AI search. SEO teams can also use Gradial for traditional optimization recommendations — surfacing content gaps, improving page structure, and strengthening signals that matter across both traditional and AI search.
A strong SEO foundation and strong AI visibility aren't in tension. Gradial helps your team do both from the same platform.
***
## How It Works
Gradial scores your domain live, showing exactly where your brand is and isn't cited across the live monitoring set: ChatGPT, Anthropic Claude, Perplexity, Microsoft Copilot, Google Gemini, Google AI Mode, xAI Grok and DeepSeek. Google AI Overviews is a distinct Google surface from AI Mode and is on the roadmap for Q3 2026. You.com is available with a custom integration request.
Fixes surface grouped by type, each linked back to the page, mention or citation that produced it, with a clear explanation of why it improves AI citation — and traditional SEO opportunities alongside them. No guesswork.
Gradial writes the fix itself, validated against simulated AI personas before it touches your live site. No developer, no ticket queue, no content team bottleneck.
One click to stage in your CMS. Staged for review, full audit trail, rollback-ready. GEO variants publish alongside your SEO originals.
***
## A Day in the Life: Gradial-Enabled vs. Report-Only
Imagine a fintech company — Apex Payments — competing for AI visibility in the "B2B payment processing" category.
Their team runs an audit through a report-only tool. The output: 47 pages flagged for low AI citation, a list of recommended changes, and no path to execution. The content team spends two weeks triaging findings, writing rewrites, getting approvals, and coordinating with developers. By the time changes go live, the competitor who moved faster is already being cited.
The same audit takes hours, not weeks. Gradial identifies the gaps, writes the optimized content, validates it against AI query simulations for their category, and stages it in their CMS. The content team reviews a clean queue of proposed changes and approves them. Two people manage the entire program. Apex Payments starts appearing in AI search answers for their core category within weeks.
The difference isn't the analysis. It's everything that happens after it.
***
## Common Questions
SEO tools track Google rankings. Gradial tracks AI citations — and can enhance your SEO program at the same time. Your buyers are starting in AI search engines now, and traditional SEO tools can't see that channel. These are additive, not competitive.
No. GEO isn't about creating more content. It's about getting your existing content cited by AI engines. Gradial optimizes for AI signals, validates before publishing, and measures what actually moved.
Gradial plugs into your CMS and stages fixes in one click, so they land in your existing review and approval path. Your team keeps doing what they're doing — Gradial adds AI visibility on top without disrupting how work gets done.
That's exactly why the product exists. Gradial runs the audit, writes the fix, and stages it for review. One person can manage the entire GEO program with no agency, no dev resources, and no extra headcount — within your existing review and approval path.
Gradial reports before-and-after citation rate and brand mention rate from scheduled monitoring re-runs bracketing a change, so you can see measured movement on your own prompt set rather than a projection. Per-recommendation attributed lift is in development and will report estimated lift with a stated confidence level rather than causal proof. Contact your Gradial team to build the measurement plan for your use case.
***
## PDF Export
Download your GEO report as a branded PDF directly from Gradial. The export includes all observations, scores, and recommendations formatted for easy sharing with stakeholders. Branded headers and footers appear on overflow pages so content doesn't bleed between sections.
***
## Access
GEO is available upon request. Contact your Gradial team to enable GEO for your organization.
Once enabled, run a GEO analysis directly from Gradial Chat:
```text theme={null}
Run a GEO report on [yourwebsite.com]
```
***
# GEO Monitoring
Source: https://docs.gradial.com/docs/insights/geo-monitoring
Continuous brand and competitor visibility tracking across AI search models — with automated recommendations that turn regressions into executable tasks.
## Overview
GEO Monitoring Dashboard gives enterprise marketing and SEO teams continuous visibility into how their brand and competitors are performing across the live monitoring set: ChatGPT, Anthropic Claude, Perplexity, Microsoft Copilot, Google Gemini, Google AI Mode, xAI Grok and DeepSeek. Instead of running one-off GEO audits manually, teams configure queries once and the dashboard populates with trend data automatically, surfacing regressions and content opportunities as they happen.
Google AI Overviews is a distinct Google surface from AI Mode and is on the roadmap for Q3 2026. You.com is available with a custom integration request.
This feature is for enterprise accounts with active GEO programs who need ongoing brand performance tracking, not just point-in-time snapshots.
***
## How to Use
### Step 1: Configure a dashboard view
Select the brand and URLs you would like to monitor GEO for. The URLs you provide will be scanned for page-health recommendations so include multiple page families.
A brand automatically covers its root domain and every subdomain beneath it — see [Domain and Brand Coverage](#domain-and-brand-coverage) for what a single brand does and doesn't include.
### Step 2: Load your prompts
From the GEO Monitoring Dashboard, assemble the prompts you want tracked over time. Prompts can be bulk-uploaded in the dashboard interface and will need to have a topic in addition to the prompt itself. By default, we will run your prompts against all providers supported in Gradial.
To bulk-upload, open a brand on the GEO dashboard — either **Edit** an existing brand or create a **New Brand** — then open the **Prompts** tab and click **Bulk Import**. The Bulk Import dialog includes a link to download the upload template to fill in your prompts. You can assign each prompt to a topic and specific personas, then upload your spreadsheet through the same dialog. You can also add prompts one at a time with **Add prompt**.
Every prompt has one **topic**, and prompts can also carry **tags** — see [Topics and Tags](#topics-and-tags) for how the two differ and when to use each.
Not sure what to monitor? See [Example monitoring prompts](#example-monitoring-prompts) for a starter set of 20+ prompts you can adapt, plus a downloadable template.
It may still take up to a day for results to appear after triggering a run.
### Step 4: Let the dashboard build over time
The dashboard populates as runs accumulate. Trends sharpen as history builds — the longer you let monitoring run, the richer your trend view becomes.
### Step 5: Open Insights → GEO
Review trend lines, drill into individual responses, and convert page-health recommendations into tasks with one click.
***
## Domain and Brand Coverage
### Adding a root domain covers all of its subdomains
When you add a root domain such as `example.com`, the brand automatically covers **everything ending in `.example.com`** — including non-English subdomains like `in.example.com`. Language doesn't matter: those pages count toward the brand automatically, and you don't need to list each subdomain individually.
These pages always count **toward your brand** — never as a competitor — and they roll up into the brand's overall report.
Subdomain pages are counted when an AI answer **cites** them — GEO measures your brand's presence in AI responses. They roll up into the brand's combined score rather than being broken out by subdomain. There is no per-subdomain or per-region breakdown within a single brand report today.
### A different web address is not covered automatically
Coverage applies only to true subdomains of the domain you added. A separate web address that does **not** end in your root domain is a different site and must be added on its own.
Country sites on a different top-level domain are a common miss. `example.cn` is a **different address** (`.cn`, not `.example.com`), so adding only `example.com` will not capture that country site — its results are missed entirely.
To cover both in this example, add **two domains**: `example.com` (covers all `.example.com` subdomains) and `example.cn` (covers the country site on the separate domain).
## Structuring Brands by Region
For brands with distinct regional sites, set up **one GEO Monitoring configuration per region** — a separate brand run for each — and switch between them with the brand dropdown. For example:
* **Brand US** — `example.com`
* **Brand India** — `in.example.com`
* **Brand China** — `example.cn`
Each is its own independent report with its own prompts. Tailor each brand's prompts to that region's market, pages, and competitors.
**This is a recommended workaround for today.** First-class support for tracking multiple regions within a single brand configuration is on the roadmap; this section will be updated when it lands.
***
## Brand-Level Tracking and Hierarchies
GEO Monitoring can track any brand at its own level — a specific product, sub-brand, division, or business unit — independently of its parent company. Previously, mentions were attributed to the top-level corporate parent, so a product tracked separately from its manufacturer could read a misleading 0% mention rate even when it was clearly named in AI answers. Brand-level tracking fixes that attribution.
**Access:** Brand-level tracking must be enabled for your organization. Contact your Gradial team to get access.
### What it enables
| Capability | Description |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Track any brand at its own level** | Monitor a product, sub-brand, or business unit as its own entity — no need for it to be the corporate parent. |
| **Accurate numbers for product brands** | A brand tracked separately from its parent shows its real mention rate and share of voice instead of reading 0%. |
| **Brand hierarchies** | Group brands under a parent company. View each brand on its own, or rolled up together. |
| **Include child brands on demand** | Toggle **Include child brands** on a parent's dashboard to blend in its direct children, then switch back to see the parent alone. |
| **Honest citation reporting** | A brand with no domain configured shows "—" for citations instead of a false 0%. |
### Setting up a brand hierarchy
Creating and editing monitored brands is an admin capability.
1. In GEO settings, create the brand as its own monitored entity: brand name, optional domain(s), and any aliases it's known by.
2. Optionally assign a **parent brand** from the same organization — for example, a drug brand under its pharmaceutical parent, or a product line under the corporate name.
3. On the parent's dashboard, use the **Include child brands** toggle to view the parent blended with its direct children or on its own.
### Things to know
* **Hierarchies are one level deep** — a parent and its direct children. Arbitrary-depth nesting isn't supported.
* **Citation rate requires a domain.** A brand without a configured domain shows "—" for citations; add the brand's own domain (e.g., a product site) to get citation attribution against the right property.
* **Short brand names match precisely.** Alias matching uses word boundaries, so short names like "EA" or "3M" don't produce false matches inside longer words.
* **Corrected attribution applies going forward.** Results reflect brand-level attribution from the point it's enabled; historical rates for a product brand may understate until backfilled.
***
## Brand Sentiment
GEO Monitoring now surfaces not just whether AI systems mention your brand, but how they describe it. The **Brand Sentiment** section of the dashboard summarizes favorability, recurring perception themes, and supporting evidence so teams can see how their brand is being presented in AI-generated answers.
**Access:** Brand Sentiment must be enabled for your organization. Contact your Gradial team to get access.
### What Brand Sentiment shows
| Capability | Description |
| -------------------------- | --------------------------------------------------------------------------------------------------- |
| **Favorability breakdown** | See the share of monitored brand mentions that are favorable, neutral, or unfavorable. |
| **Perception summary** | A concise narrative of how AI systems are currently describing your brand. |
| **Recurring themes** | Topics and themes that repeatedly appear across monitored AI responses. |
| **Evidence drilldown** | Supporting quotes and examples behind each theme, so findings are traceable to specific AI outputs. |
| **Trend view** | Net favorability charted over time when the trend view is enabled. |
### How to use Brand Sentiment
Brand Sentiment is part of the GEO Monitoring Dashboard — no separate configuration is needed beyond your existing brand and prompt setup. Once enabled for your organization, the section appears automatically and updates as your monitoring runs accumulate.
Use favorability trends alongside your citation and mention data to get a fuller picture: a brand that is frequently cited but mostly described unfavorably faces a different challenge than one that is rarely cited at all.
***
## Working with GEO data in Grady
Everything you can learn from GEO monitoring used to live in the dashboard — a fixed set of views in a fixed shape. Grady can now read your GEO monitoring data directly inside a task, so you can ask for the cut you actually want, in the format you actually need.
**Access:** Must be enabled for your organization, and your organization needs GEO monitoring already configured with collected data. Contact your Gradial team to get access.
### Ask for any cut of your data
Ask in plain language, across whichever brand and time window you care about:
```
Show me a table comparing our share of voice to our top competitor,
broken out by sentiment, over the last 30 days.
```
```
Which topics are we losing citations on this quarter compared to last?
```
Because Grady produces the output rather than a fixed view rendering it, the answer can take whatever shape is useful — a quick table in the chat, a chart, or a boardroom-ready PowerPoint built from the same numbers.
### Change monitoring configuration from the conversation
Grady can also set up and adjust monitoring configurations — creating or changing a monitored brand — without you going into GEO settings.
Configuration changes go through an approval step and are recorded, and editing a monitoring configuration remains an admin capability. Your collected GEO data is never at risk: runs, responses, mentions, and citations cannot be modified by Grady under any circumstances. The worst a configuration change can do is alter what gets monitored going forward.
### Turn an insight into work
Ask Grady what to act on next and it ranks your open page-health recommendations, then hands you the highest-value one as a task card you can launch in one click — closing the gap between noticing a regression and starting the fix.
```
What should we work on next to improve our AI visibility?
```
***
## Example monitoring prompts
GEO Monitoring works best with a **broad set of prompts** — typically 20 or more — that cover the different ways buyers ask AI search engines about your category, your brand, and your competitors. A single prompt only tells you about one question; the value comes from the spread.
The examples below are a starter set you can adapt. Replace `[Your Brand]` and `[Competitor A]` / `[Competitor B]` with real names, and reshape the topics around your market.
**Personas:** The **Personas** column should be filled in with personas that already exist in your organization. Populate it with the names of your pre-existing personas so prompts are attributed to the right audiences — don't invent new persona names in the spreadsheet.
To upload in bulk, download the template, fill in your prompts, and import it from the **Prompts** tab (see [Step 2](#step-2-load-your-prompts)).
20+ example prompts with topics, personas, and tags — formatted for Bulk Import.
A few examples to illustrate the spread of topics — the full set of 20+ is in the download above:
| Prompt | Topic | Tags |
| --------------------------------------------------------------------------- | --------------------------- | ----------------------- |
| What are the best enterprise content operations platforms? | Category Overview | category, enterprise |
| What is the best agentic marketing platform for enterprise teams? | Agentic Marketing Platforms | category, agentic |
| How does `[Your Brand]` compare to `[Competitor A]` for content automation? | Competitive Comparison | competitive, comparison |
| How much does enterprise marketing content automation software cost? | Pricing | pricing, enterprise |
| Does `[Your Brand]` integrate with Adobe Experience Manager? | Integrations | integrations, aem |
| Who are the leaders in AI-powered marketing content operations? | Analyst & Market Position | analyst, leadership |
***
## Topics and Tags
Every monitoring prompt has a **topic**, and prompts can also carry **tags**. They serve different purposes — topics describe what a prompt is *about* and shape the report, while tags are a flexible way to organize and filter your prompts.
| | Topic | Tags |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **What it's for** | Says what a prompt is about (e.g. "Agentic Marketing Platforms") | A labeling layer for organizing and filtering your prompts |
| **How many per prompt** | Exactly one — required on every prompt | Any number — none, one, or many |
| **Reused across prompts** | Each prompt has its own topic; the topic also serves as the prompt's name | Yes — the same tag is reused across prompts and managed at the org level |
| **In the report** | Shown as a sortable **Topic** column in the Prompt Performance table | Used for filtering prompts in Settings; tags don't appear in the report itself |
| **In Grady's analysis** | Sent to Grady as context ("this query is about X"), which can shape how brand and competitor mentions are interpreted | Tags are for your own organization — they don't influence Grady's analysis, so you can label freely without affecting results |
### When to use each
* **Topic** — set the one thing each prompt is about. It names the prompt, appears in the report, and gives Grady context for interpreting results.
* **Tags** — group and slice prompts however your team works: by audience (`enterprise`), intent (`competitive`), campaign (`Q2-launch`), funnel stage (`top-of-funnel`), and so on. In Settings you can then filter to, say, every prompt tagged `enterprise` across all topics.
### Can a prompt be in more than one topic?
No — a prompt has exactly one topic (the topic is a single field that also names the prompt). For example, *"What are the best AI agents for automating marketing campaigns?"* can be `Agentic Marketing Platforms` **or** `Marketing Automation`, but not both.
When you want a prompt to belong to more than one group, that's what **tags** are for: add both `agentic-marketing` and `marketing-automation` as tags, and the prompt surfaces when you filter by either in Settings. Keep in mind that tag filtering happens in Settings — the report groups by topic, so you can't break the report itself down by tag.
# CX Optimizer
Source: https://docs.gradial.com/docs/insights/optimization
An AI agent that audits your website by simulating real user journeys, scoring sentiment, and delivering prioritized optimization reports.
CX Optimizer is an AI agent that audits your website's customer experience by simulating real user journeys. It navigates your site the way a real customer would — clicking, scrolling, evaluating CTAs, reading content — scores the experience at every step, and delivers a prioritized optimization report in minutes.
Unlike analytics dashboards that show *what* happened, or session replay tools that review *past* behavior, CX Optimizer proactively discovers issues in journeys nobody has thought to test. When it finds a problem, Gradial's content platform can fix and publish the update — closing the loop from analysis to execution without leaving the platform.
***
## How It Works
Choose one of three analysis modes: a **single page audit** (deep-dive on any specific page), a **journey analysis** (end-to-end evaluation of a complete user flow like onboarding or checkout), or a **full site exploration** (the agent autonomously discovers and audits across your entire digital property). You can also configure customer personas so the agent evaluates the experience from the perspective of your actual audience segments.
The agent opens a real browser and interacts with your site the way a customer would — clicking buttons, scrolling through content, filling out forms, navigating menus, following CTAs. This is a simulation of actual human behavior. Stakeholders can watch the agent navigate in real time through live observation.
As the agent moves through the site, it continuously scores the experience: content clarity, CTA effectiveness, flow logic, visual hierarchy, navigation intuitiveness, and emotional sentiment. Sentiment scoring runs throughout the journey, not just as a pass/fail at the end.
Unlike analytics or session replay, the agent doesn't wait for problems to happen — it actively seeks them out. Dead-end navigation paths, confusing layouts, broken flows, unclear CTAs, inconsistent messaging — the agent surfaces issues you didn't know to look for.
All findings are assembled into a shareable report with an overall journey health score (0–10), per-persona breakdowns including CX score, goal completion rate, sentiment, and session replay. Recommendations are organized into four categories so different teams can act in parallel immediately. Export the report as a PDF to share with stakeholders.
***
## Analysis Modes
### Single Page Audit
A deep-dive on any specific URL. The agent evaluates content quality, CTA effectiveness, visual hierarchy, accessibility, and sentiment for the target page and captures a structured observation before exiting. Best for focused reviews of high-traffic or high-value pages.
### Journey Analysis
End-to-end evaluation of a complete user flow — onboarding, checkout, a campaign landing sequence, or any multi-step path. The agent navigates the site pursuing a persona's goals through the natural flow, logging every step: page visited, action taken, observation, sentiment annotation, and pain points. When personas are configured, one thread runs per persona in parallel, and findings are synthesized across audience segments.
### Full Site Exploration
The agent autonomously discovers and audits pages across your entire digital property. This mode leverages crawl infrastructure to surface broken links, navigation issues, and structural problems site-wide — covering ground that would take a UX team weeks to complete.
A full site exploration that would take a UX team weeks can run in a single session. For large sites, expect runs of an hour or more.
***
## Persona Simulation
Personas are first-party audience definitions — your actual customer segments with their demographics, goals, and pain points. When personas are enabled, CX Optimizer creates one analysis thread per persona and evaluates the experience from each audience's perspective.
What counts as "clear" or "effective" shifts based on who the audience is. A flow that works for a power user may confuse a first-time visitor. Persona simulation surfaces those gaps by running every persona in parallel and synthesizing cross-persona findings in the final report.
**Configure personas in Settings → Personas.** Each persona record includes name, description, target role, geography, goals, and pain points.
***
## Sentiment Scoring
Sentiment is captured at the journey step level — not aggregated into a single pass/fail score at the end. Each step in a persona's journey is annotated with one of four values:
| Sentiment | Meaning |
| -------------- | --------------------------------------------------------------------- |
| **Positive** | Action completes smoothly; user is satisfied |
| **Neutral** | Action completes without friction but without delight |
| **Negative** | User encounters delays, unclear navigation, or minor usability issues |
| **Frustrated** | User hits blockers, dead ends, or significant confusion |
This produces a sentiment curve across the entire journey, surfacing exactly where the experience degrades. The final report includes an overall **CX Score** (1–10) and **Goal Completion Rate** (0–100%) aggregated across all personas.
***
## Report Output
Every CX Optimizer run produces a structured report with the following components:
* **Overall journey health score** — A 0–10 score summarizing the experience across all tested journeys and personas.
* **Per-persona breakdown** — CX score, goal completion rate, sentiment curve, and session replay for each configured persona.
* **Actionable insights** — Recommendations organized into four categories:
| Category | What it covers |
| -------------------- | --------------------------------------------------------------------- |
| **Tactical Updates** | Quick wins — copy tweaks, CTA adjustments, minor content improvements |
| **Bug Fixes** | Broken functionality and UX issues that block or confuse users |
| **New Content** | Missing information or guidance that users are clearly looking for |
| **Moonshots** | Strategic, higher-effort improvements with significant CX impact |
Each recommendation includes a **Create Ticket** button that converts the finding into a Gradial task. The performance context travels with the task so the executing agent understands what it's optimizing and why.
**PDF export:** Download the full report as a branded PDF to share with stakeholders outside the platform.
***
## Live Observation
While CX Optimizer runs, you can watch the agent navigate your site in real time. The dashboard streams live screenshots and journey step observations with sentiment indicators, showing active thread status and current step.
This is especially useful for demos and stakeholder reviews — decision-makers can see the agent clicking, scrolling, and evaluating their actual site as it happens.
***
## Pre-Publish Simulation
CX Optimizer can run against any URL that loads in a browser — including staging environments. The agent treats staging and production identically, capturing the full experience including page state, interactive elements, and form behavior.
Run CX Optimizer on a staging URL before launch to catch experience issues before they reach customers. Results are stored separately from production data, enabling side-by-side comparison.
***
## AEM Preflight
AEM Preflight is a dedicated pre-launch mode that lets you run a CX analysis on a single AEM page — published or unpublished — before a full campaign goes live.
Unlike standard Pre-Publish Simulation, which requires a publicly accessible staging URL, AEM Preflight connects directly to your AEM environment using browser-to-AEM authentication. This means the agent can access and evaluate pages that haven't been published yet — draft content, launch copies, and staged variants that are invisible to any external URL.
**When to use AEM Preflight:**
* Validate a new page or campaign landing experience before promoting from a launch copy to live
* Catch CX issues in unpublished content before it reaches QA or stakeholder review
* Run a targeted single-page analysis without spinning up a full site or journey audit
**How to run a preflight:**
1. In CX Optimizer, select **Single Page Audit** as your analysis mode.
2. Enter the AEM page path or author URL for the page you want to evaluate.
3. Confirm your AEM connection is authenticated — Preflight uses your connected AEM integration credentials.
4. Run the analysis. The agent accesses the page directly through AEM and produces the standard CX report.
Results from preflight runs are stored separately from production audits, so you can compare the pre-launch experience against the live page after publishing.
***
## The Closed Loop
CX Optimizer is designed to connect directly to Gradial's content execution layer. When the optimizer surfaces an issue, you can create a Gradial task directly from the finding — and the performance context travels with the task. The agent executing the fix understands what it's optimizing and why, not just what to change.
Connect analytics and run CX Optimizer to identify pages with friction, low conversion, or degraded sentiment.
Review the prioritized report. Each recommendation includes the specific element, the problem description, severity, and suggested fix.
Convert a finding into a Gradial task directly. The performance context travels with the task.
The relevant agent executes the update, QA runs automatically, and the output is staged for review. Re-run CX Optimizer post-publish to confirm the change had the intended effect.
***
## Frequently Asked Questions
Runs typically complete in 15 to 60 minutes depending on the depth and breadth of the request. A single page audit is on the shorter end; a full site exploration with multiple personas can take longer.
An overall journey health score (0–10), per-persona breakdowns with CX score, goal completion rate, sentiment, and session replay, and recommendations organized into four categories: Tactical Updates, Bug Fixes, New Content, and Moonshots. Each recommendation has a Create Ticket button to convert it into a Gradial task. Reports can be exported as PDF.
The agent uses a real browser — it clicks, scrolls, and reads just like your customers do. It's not a crawler or a script; it experiences the site authentically, including interactive elements and form behavior.
Analytics tells you *what* happened — bounce rates, conversion funnels, traffic patterns. CX Optimizer tells you *why* — and proactively finds issues in journeys nobody is even looking at. Your analytics dashboard can't tell you that a CTA is confusing or that a flow is illogical. They're complementary, not overlapping.
Session replay reviews what past visitors did. CX Optimizer proactively tests journeys — including ones no visitor has taken yet. It's the difference between reviewing footage and running a safety inspection. CX Optimizer also evaluates from specific customer personas rather than random sessions, and can test pages before they're even live.
No — it multiplies them. Your UX researchers do deep qualitative work that no AI can match. CX Optimizer handles the breadth — full-site coverage, every journey, every page — so your team can focus on the depth. Think of it as giving your UX team dramatically more coverage without adding headcount.
Yes. CX Optimizer can run against any URL that loads in a browser, including staging environments. The agent treats staging and production identically, and results are stored separately to enable side-by-side comparison.
CX Optimizer navigates your public-facing website the same way any customer would. It does not access backend systems, databases, or private data. Gradial is SOC 2 Type 2 certified.
***
## Availability
**Access:** Must be enabled for your workspace. Contact your Gradial team to get access.
# Wrike
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/how-gradial-works-with-ticketing-systems/Wrike-Integration
Connect Gradial to Wrike to automatically ingest tasks and sync results — previews, links, and status updates — back to Wrike.
**What you can do:**
* Automatically ingest Wrike tasks into Gradial workflows
* Filter by space, folder, status, or custom fields to control what gets executed
* Attach source documents directly to Wrike tasks for context
* Write previews, links, and status updates back to Wrike
* Standardize execution pipelines across teams
***
## Prerequisites
**What you'll need:**
* Your **Wrike domain** (e.g., `https://app.wrike.com`)
* A **Wrike service account** — a dedicated user that Gradial acts through
* Must have access to the spaces, folders, and projects you want to sync
* Should be set as the **first assignee** on any task you want Gradial to process
* A **Personal Access Token (PAT)** generated by the service account
* A designated **custom team field** for task routing (e.g., "Gradial Team") — must be a short-text field
***
## Authentication options
| Method | Requirements |
| ------------------------------- | ---------------------------------------------------------------------------------------------- |
| **Personal Access Token (PAT)** | Token generated from the service account's Wrike profile → Apps & Integrations → Access Tokens |
***
## Connect Wrike to Gradial
Go to **Integrations** in the Gradial sidebar, select **Wrike**, and click **Add Integration**.
1. Enter your **Wrike domain**
2. Enter the **service account email** in the Assignee field
3. Enter the **custom team field** label exactly as it appears in Wrike (e.g., `Gradial Team`)
4. Generate a PAT: log in as the service account → profile settings → **Apps & Integrations → Access Tokens → Create new token**
5. Paste the token into **Personal Access Token**
6. Optionally add filters to limit which tasks Gradial ingests (see below)
7. Click **Save**
**Optional filters:**
| Filter | Description |
| ----------------- | ------------------------------------------ |
| **Projects** | Limit to specific project keys or folders |
| **Statuses** | e.g., `In Progress`, `Ready for Execution` |
| **Custom fields** | e.g., task type or priority |
***
## Configure routes
Once connected, create routes to define which Wrike tasks sync into which Gradial workspaces. Wrike supports filtering by space, folder, and status.
[Configure Routes →](/docs/integrations-administration-and-setup/how-gradial-works-with-ticketing-systems/routing-tickets)
***
## How task execution works
Once integrated, the typical flow is:
1. A team member creates a task in a configured Wrike folder with a clear title and any attached reference files
2. The task is assigned to the Gradial service account and set to `In Progress`
3. Gradial ingests the task and executes the request
4. Previews, links, and comments are written back to the Wrike task
5. Task status updates automatically as execution progresses
***
## Troubleshooting
| Issue | Likely cause | Fix |
| --------------------------- | ----------------------------------------- | ------------------------------------------------------------------------ |
| Tasks not being ingested | Service account not set as first assignee | Ensure the Wrike service account is the primary assignee on target tasks |
| Authentication fails | Invalid or expired PAT | Regenerate the token from the service account's Wrike settings |
| Wrong tasks ingested | Filters too broad | Narrow filters by project, status, or custom field |
| Custom field not recognized | Field name mismatch | Confirm the Team Field value matches the exact label in Wrike |
Contact your Gradial onboarding lead or email [support@gradial.com](mailto:support@gradial.com) if issues persist.
# Asana
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/how-gradial-works-with-ticketing-systems/asana
Connect Gradial to Asana to automatically ingest tasks and sync results back to your projects.
**What you can do:**
* Ingest Asana tasks into Gradial with full metadata
* Filter by project, section, assignee, or tag
* Trigger Gradial execution when tasks match your criteria
* Write results — previews, links, comments — back to the Asana task
***
## Prerequisites
### Create a dedicated Gradial service account in Asana
Gradial requires a dedicated Asana user account — do not use a personal or shared account. This service account is what Gradial authenticates as when syncing tasks and posting results back to Asana.
1. Create a new Asana user with an email address dedicated to the integration (e.g., `gradial-integration@yourcompany.com`)
2. Add the service account as a **member of every Asana project** you plan to sync into Gradial
3. Ensure the account has sufficient permissions to read tasks and post comments in those projects
The PAT you generate must come from this dedicated service account, not a personal user. Actions Gradial takes in Asana — such as posting comments — will appear as this account.
**Required permissions for the service account:**
| Scope | Permissions required |
| --------------- | ------------------------------------ |
| **Projects** | Member access to all target projects |
| **Tasks** | Read / Write across all task types |
| **Comments** | Read / Write |
| **Attachments** | Read / Write |
***
## Connect Asana to Gradial
Once the service account is set up, generate a PAT for it and connect to Gradial.
### Step 1 — Generate a Personal Access Token
1. Log in to Asana **as the service account**
2. Go to the Asana Developer Console at [app.asana.com/0/my-apps](https://app.asana.com/0/my-apps)
3. Click **Create new token**, give it a descriptive name (e.g., "Gradial Integration"), and confirm
4. Copy the token immediately — it will not be shown again
Treat your PAT like a password. If it is ever compromised, revoke it from [app.asana.com/0/my-apps](https://app.asana.com/0/my-apps) and generate a new one.
### Step 2 — Add the integration in Gradial
Go to **Integrations** in the Gradial sidebar, find Asana under **Ticket System Integrations**, and click **Connect**.
1. Enter an **Integration Name** to identify this connection (e.g., "Marketing Asana")
2. Paste the token you generated into **Personal Access Token**
3. Click **Validate Connection**
Once saved, credentials are stored securely and cannot be viewed again. To update the token, delete the integration and create a new one.
***
## Configure routes
Once connected, click **Add Route** to define which Asana tasks Gradial ingests and where they go in Gradial.
Each route has two parts: an **Asana Filter** that controls which tasks are fetched, and a **Gradial Destination** that controls where they land.
### Asana Filter
Routes use GIDs — Asana's internal numeric identifiers — not names. You can find GIDs in the URL when viewing a project, section, or workspace in Asana (e.g., `app.asana.com/0/{workspace_gid}/{project_gid}`).
| Field | Required | Description |
| ----------------- | --------------------------------- | ----------------------------------------------------------------------------------------- |
| **Project GIDs** | Optional | Comma-separated list of Asana project GIDs to fetch tasks from |
| **Section GIDs** | Optional | Comma-separated list of section GIDs to narrow to a specific board column or list section |
| **Workspace GID** | Required when using Assignee GID | The GID of your Asana workspace |
| **Assignee GID** | Required when using Workspace GID | Fetch only tasks assigned to a specific user (e.g., the Gradial service account) |
Use **Project GIDs** to pull from one or more specific projects. Use **Workspace GID + Assignee GID** together to pull all tasks assigned to the Gradial service account across your workspace — regardless of project.
Use **Test Query** to preview which tasks the current filter will return before saving.
### Gradial Destination
| Field | Description |
| --------------- | --------------------------------------------------------------- |
| **Project** | The Gradial project where ingested tasks will appear as threads |
| **Environment** | The Gradial environment to execute tasks in |
***
## How task execution works
Once a route is configured, Gradial polls Asana for matching tasks and processes them automatically:
1. A task matching a route's filter criteria is discovered in Asana
2. Gradial ingests the task as a thread, including title, description, and attachments
3. The AI agent executes the requested work
4. Results — previews, links, and comments — are written back to the original Asana task
5. Gradial continues to monitor the task for updates or `@gradial` mentions that trigger follow-up actions
***
## Troubleshooting
| Issue | Likely cause | Fix |
| ----------------------------- | -------------------------------------- | -------------------------------------------------------------------------------- |
| No tasks syncing | Service account missing project access | Confirm the account is a member of all target projects |
| Authentication fails | Invalid or expired token | Regenerate the PAT at [app.asana.com/0/my-apps](https://app.asana.com/0/my-apps) |
| Test Query returns no results | GID incorrect or filter too narrow | Double-check GIDs from the Asana URL; try a Project GID-only filter first |
| Tasks stuck pending | Insufficient task permissions | Ensure the service account has write access to all target tasks |
| Wrong tasks ingested | Filters too broad | Add Section GIDs or an Assignee GID to narrow the route |
Contact your Gradial Product Specialist or email [support@gradial.com](mailto:support@gradial.com) if issues persist.
# Azure DevOps
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/how-gradial-works-with-ticketing-systems/azure-devops
Connect Gradial to Azure DevOps to automatically ingest work items and sync results back to your boards.
**What you can do:**
* Ingest Azure DevOps work items into Gradial with their fields, comments and attachments
* Trigger Gradial execution when work items match your route criteria
* Write results — previews, links, status — back to the originating work item
* Target work items precisely, using structured filters or your own WIQL query
Gradial syncs Azure DevOps on a schedule. New and updated work items are picked up on the next sync cycle rather than instantly.
***
## Why route web work through Azure DevOps
Marketing content requests often arrive in Azure DevOps because that is where the engineering organization already works — a shared board, an existing intake form, a sprint everyone can see. The request lands as a work item, joins a backlog of genuine engineering work, and then waits, because "update the pricing page headline" and "fix the checkout race condition" are competing for the same team's attention.
That's the wrong queue for the work, but the right place for the request. Connecting Azure DevOps keeps intake and reporting exactly where they are, and moves execution out of the engineering backlog.
***
## Prerequisites
### Create a dedicated Gradial service user
Create a service account in Azure DevOps for Gradial rather than using a person's credentials. This keeps the audit trail legible — every comment and update Gradial writes back is clearly attributable — and means the connection survives people changing roles.
The service user needs:
* **Access to each project** Gradial will read work items from
* **Permission to read work items** in those projects
* **Permission to add comments and attachments**, and to edit the fields you want Gradial to update on completion
Grant only the projects Gradial should see. Project membership is the outer boundary on what any route can reach.
***
## Connect Azure DevOps to Gradial
Go to **Settings → Integrations**, find **Azure DevOps** under Ticketing & work management, and select **Connect**. The wizard covers **Connection**, **Routing**, and **Route Summary**.
### Step 1 — Create a personal access token
1. Sign in to Azure DevOps **as the service user**
2. Open **User settings → Personal access tokens**
3. Select **New Token**
4. Scope it to the organization Gradial will work in, set an expiry, and grant **Work Items (Read, write & manage)**
5. Copy the token — Azure DevOps shows it only once
Personal access tokens expire. Note the expiry date when you create the token and set a reminder, because an expired token stops ingestion silently — routes simply return nothing new.
### Step 2 — Configure the connection
1. Enter an **Integration Name** to identify this connection
2. Enter your **Organization URL** — `https://dev.azure.com/{your-organization}`
3. Paste the service user's **personal access token**
4. Select **Validate Connection**
5. Once validated, continue to routing
Once saved, credentials are stored securely and cannot be viewed again. To rotate the token, update the integration with the new value.
### Step 3 — Configure routing
On the **Routing** step, add a route for each set of work items Gradial should ingest. Routes can be toggled on and off independently.
| Field | Required | Description |
| ------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------- |
| **Route Name** | Required | A name to identify this route |
| **Description** | Optional | Notes on what the route is for |
| **Project** | Required | The Azure DevOps project to read from |
| **Work item types** | Optional | Limit to specific types — for example User Story, Task, Bug, Feature, Epic, Issue |
| **Area path** | Optional | Restrict to an area path, which is usually the cleanest way to separate marketing requests from engineering work |
| **Iteration path** | Optional | Restrict to a sprint or release |
| **State** | Optional | Only ingest items in given states — for example New, or Approved |
| **Assigned to** | Optional | Only ingest items assigned to a given user, commonly the Gradial service user itself |
| **Tags** | Optional | Only ingest items carrying given tags |
| **Custom field filters** | Optional | Filter on any other field, including your organization's custom fields |
**Gradial destination:**
| Field | Description |
| --------------- | --------------------------------------------------------------- |
| **Workspace** | The Gradial workspace where ingested work items appear as Tasks |
| **Environment** | The Gradial environment to execute in |
The most reliable intake pattern is **assignment**: have requesters assign the work item to the Gradial service user, and route on `Assigned to`. It makes intake an explicit act rather than a filter that might match more than anyone intended — and it gives requesters an obvious way to opt a single item out.
#### Advanced: routing with WIQL
Where structured filters can't express the selection you need, a route can carry a raw **WIQL** query instead. This is worth reaching for when your intake depends on a combination of custom fields, or on relationships between work items.
```sql theme={null}
SELECT [System.Id]
FROM WorkItems
WHERE [System.TeamProject] = 'Marketing'
AND [System.WorkItemType] = 'Task'
AND [System.AreaPath] UNDER 'Marketing\Web Requests'
AND [System.State] = 'Approved'
AND [System.Tags] CONTAINS 'gradial'
```
Test the query in Azure DevOps first and confirm the result set is what you expect. A WIQL route ingests everything the query returns.
Select **Next** to review the **Route Summary**, and confirm each route pulls in what you expect before finishing.
For ingestion modes and best practices, see [Routing Tickets →](/docs/integrations-administration-and-setup/how-gradial-works-with-ticketing-systems/routing-tickets)
***
## How work item execution works
1. A work item matching a route's criteria is discovered on the next scheduled sync
2. Gradial ingests it as a Task, including its title, description, field values, comments and attachments
3. Gradial executes the requested work
4. Results — previews, links and status — are written back to the originating work item as the service user
5. Gradial keeps watching the work item for changes that should trigger follow-up work
***
## Troubleshooting
| Issue | Likely cause | Fix |
| ---------------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| No work items ingested | The token expired, or the route's filters match nothing | Re-validate the connection, then run the route's filters as a query in Azure DevOps to confirm the result set |
| Some work items ingested, others skipped | The service user lacks access to that project or area path | Check project membership and area-path permissions for the service user |
| Results not written back | The service user cannot comment or edit fields on that project | Grant comment and edit permission, then re-run the Task |
| Attachments missing | The attachment is on a linked item rather than the ingested one | Attach source material to the work item the route targets |
| Far more items ingested than expected | A route filter is broader than intended — commonly an area path with descendants | Narrow the filter, or switch to assignment-based routing |
| Connection rejected on save | The organization URL is wrong, or the token lacks Work Items scope | Confirm the URL is `https://dev.azure.com/{organization}` and regenerate with Work Items (Read, write & manage) |
***
## Who this is for
| Role | What this unlocks |
| :-------------------------- | :--------------------------------------------------------------------------------------- |
| **Marketing Ops** | Content requests leaving the engineering backlog without changing where people file them |
| **Web Producer** | Requests arriving with their context — fields, comments, attachments — already attached |
| **Engineering Manager** | Marketing content work off your team's board |
| **Requester / Stakeholder** | Filing in the tool you already use, and getting the result back on the same work item |
| **Program Manager** | Status visible in Azure DevOps, so existing reporting keeps working |
***
## Availability
**Access:** Must be enabled for your organization. Contact your Gradial team to get access.
# Creating Tickets from Gradial
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/how-gradial-works-with-ticketing-systems/creating-tickets-from-gradial
Create Jira tickets directly from Gradial threads, closing the loop between content execution and project tracking without leaving the platform.
## Overview
The "Create Ticket" feature lets you export work from Gradial to your external ticketing system. This is useful when:
* Work originates in Gradial and needs to be tracked in Jira
* You want to create follow-up tickets based on AI analysis
* You need to batch-create tickets for multiple items
## How It Differs from Ingestion
| Aspect | Normal Ingestion | Create from Gradial |
| :--------------- | :------------------------------ | :------------------------------------- |
| **Direction** | External → Gradial | Gradial → External |
| **Source** | External ticket exists first | Gradial thread exists first |
| **Use case** | Pull existing work into Gradial | Export Gradial work to external system |
| **Link created** | Yes | Yes |
Once created, the external ticket link works the same way—bidirectional sync keeps both sides in sync.
## Requirements
To create external tickets from Gradial:
* You must have an active integration with the target system (currently Jira)
* The Gradial thread must be a native Gradial thread (source = GRADIAL), not an already-synced external ticket
* You need appropriate permissions in the external system to create tickets
***
## Creating a Single Ticket
1. Open a Gradial thread you want to export
2. Click the **Create Jira Ticket** button (or access via the thread menu)
3. Configure the ticket details:
| Field | Description |
| :-------------- | :--------------------------------------------- |
| **Integration** | Select which Jira integration to use |
| **Project** | Choose the target Jira project |
| **Issue Type** | Select the issue type (Story, Task, Bug, etc.) |
| **Assignee** | Optionally assign to a team member |
| **Priority** | Set the ticket priority |
| **Labels** | Add Jira labels |
4. Click **Create Ticket**
Gradial will create the ticket in Jira and establish a bidirectional sync link.
***
## Batch Creating Tickets
For parent threads containing multiple child items (like a campaign or batch), you can create tickets for all children at once:
1. Open the parent thread (folder, batch, or campaign)
2. Click **Create Jira Ticket**
3. Select **Create tickets for each subtask**
4. Configure common settings that will apply to all tickets:
* Target project
* Issue type
* Common labels
5. Review the list of items that will become tickets
6. Click **Create X Tickets**
Each child item will get its own Jira ticket, all with consistent settings.
***
## What Gets Included in the Ticket
When you create a Jira ticket from Gradial:
| Content | Included |
| :-------------- | :----------------------------------------------------------- |
| **Title** | Thread title becomes issue summary |
| **Description** | Thread description/initial message becomes issue description |
| **Attachments** | Thread attachments are uploaded to the Jira ticket |
| **Context** | Link back to Gradial is included in the description |
## After Creating a Ticket
Once the external ticket is created:
* **Sync is active** — Changes in either system will sync to the other
* **Comments sync** — New comments flow both directions
* **AI processing** — If someone @mentions Gradial in the Jira ticket, AI will process the request
* **View in Jira** — Click the external link icon to jump directly to the Jira ticket
***
## Limitations
**Currently supported systems:** Jira only. Wrike and Workfront support for creating tickets from Gradial is planned.
**Attachment sync:** Depending on your Jira authentication method, attachments uploaded from Gradial may not sync to Jira. This is a known limitation with certain auth configurations.
**One-way creation:** You can create a ticket from Gradial, but you cannot "un-link" or reverse the connection once established.
***
## Best Practices
**Use descriptive titles** — The Gradial thread title becomes the Jira summary, so make it clear and actionable.
**Add context in description** — Include relevant background so the Jira ticket is self-contained.
**Choose the right project** — Select the Jira project that matches your team's workflow.
**Set appropriate issue type** — Match the work type (Bug for defects, Story for features, Task for general work).
# Jira
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/how-gradial-works-with-ticketing-systems/jira
Connect Gradial to Jira Cloud or Jira Server / Data Center to automatically ingest issues and sync results back to tickets.
**What you can do:**
* Ingest Jira issues into Gradial with full metadata
* Filter by project, status, issue type, labels, or custom JQL
* Trigger Gradial execution when tickets match your criteria
* Write results — previews, links, comments — back to the Jira ticket
* Sync attachments from Jira into Gradial (Forge OAuth)
Due to Atlassian Forge app limitations, Gradial **cannot upload attachments back to Jira** when using Forge OAuth. Attachments sync Jira → Gradial only, not in reverse.
***
## Prerequisites
**Service account requirements:**
* A dedicated Jira account for integrations — not a personal user
* Must be licensed and discoverable in Jira (so Gradial can assign issues)
* Must have access to all projects and issues you plan to sync
**Required permissions for the service account:**
| Scope | Permissions required |
| ------------------- | --------------------------------------------------------------------- |
| **Project / Space** | Project: Read, Sprint: Read, Board: Read |
| **Issues** | Read / Write across all issue types (Story, Task, Bug, Epic, Subtask) |
| **Comments** | Read / Write / Delete |
| **Attachments** | Read / Write / Delete |
| **Issue Links** | Read |
| **Users** | Read |
Permissions may come from global permissions, project roles, or issue security schemes. See [Atlassian OAuth scopes documentation](https://developer.atlassian.com/cloud/jira/platform/scopes-for-oauth-2-3LO-and-forge-apps) for additional detail.
***
## Authentication options
| Method | Best for | Requirements |
| ------------------------------ | ------------------------------- | --------------------------------------------------------- |
| **Cloud — Email + API Token** | Standard Jira Cloud setups | Email address + API token from Atlassian Account Settings |
| **Cloud — Forge OAuth App** | Enterprise / secure deployments | Gradial Forge App installed on your Jira instance |
| **Server / Data Center — PAT** | Self-hosted Jira deployments | Personal Access Token from the service account |
***
## Connect Jira to Gradial
Go to **Integrations** in the Gradial sidebar, find Jira under **Ticket System Integrations**, and click **Connect**. Then follow the steps for your authentication method.
### Option A — Jira Cloud (Email + API Token)
1. Enter your **Jira Base URL** (e.g., `https://your-company.atlassian.net`)
2. Enter the **Email Address** of your service account
3. Generate an API token at `https://id.atlassian.com/manage-profile/security/api-tokens`
4. Paste the token into **API Token**
5. Click **Validate Connection**
### Option B — Jira Cloud (Forge OAuth App)
1. Select **Jira Cloud (Forge OAuth App)** as your authentication type
2. Enter your **Jira Base URL** and service account **Email Address**
3. Enter an **API Token** to authorize the initial installation
4. Click **Install Forge App** and approve the Gradial app in the Jira permissions dialog
5. Once **Forge App Installed** is confirmed, click **Validate Connection**
### Option C — Jira Server / Data Center (PAT)
1. Enter your **Jira Base URL**
2. Paste the **Personal Access Token** generated from the service account's settings
3. Click **Validate Connection**
***
## Configure routes
Once connected, create routes to define which Jira issues sync into which Gradial workspaces. Jira supports project, issue type, label, and JQL filters.
[Configure Routes →](/docs/integrations-administration-and-setup/how-gradial-works-with-ticketing-systems/routing-tickets)
**Optional — Assign Back to Reporter:** When enabled, Gradial automatically reassigns a Jira issue back to the original reporter upon completion, so tickets don't stay assigned to the service account.
***
## Reporting on your Jira data
With Jira connected, you can ask Grady to build a [custom app](/docs/insights/custom-apps) that reports against it — what's open, what's blocked, and what's been waiting longest, grouped however your team works — without exporting to a spreadsheet or waiting on someone to build a Jira view.
Because the app queries the connected system on refresh, it reflects the current state of Jira rather than a snapshot.
***
## Troubleshooting
| Issue | Likely cause | Fix |
| ------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------- |
| No issues syncing | Service account missing project permissions | Confirm the account has issue Read access for all target projects |
| Authentication fails | Invalid or expired API token | Regenerate the token; confirm the Forge app is authorized if applicable |
| Attachments not syncing to Jira | Forge OAuth limitation | Expected behavior — Forge OAuth syncs Jira → Gradial only |
| Issues stuck pending | Jira service account not licensed | Ensure the account is active and discoverable |
Contact your Gradial Product Specialist if issues persist.
# monday.com
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/how-gradial-works-with-ticketing-systems/monday
Connect Gradial to monday.com to automatically ingest board items and sync results back to your boards.
**What you can do:**
* Ingest monday.com board items into Gradial with full metadata
* Trigger Gradial execution when items match your route criteria
* Write results — previews, links, updates — back to the monday.com item
* Sync files between monday.com items and Gradial
Gradial syncs monday.com on a schedule — real-time webhooks are not yet supported. New and updated items are picked up on the next sync cycle rather than instantly.
***
## Prerequisites
### Create a dedicated Gradial service user in monday.com
monday.com authors every update as the API token owner. Use a dedicated service user named **Grady** or **Gradial Bot** so customer-visible write-backs do not come from a personal employee account.
1. Create a new monday.com user with an email address dedicated to the integration (e.g., `gradial-integration@yourcompany.com`)
2. Name the user **Grady** or **Gradial Bot** — this name appears on every update Gradial posts
3. Add the service user to **every board** you plan to sync into Gradial (for private and shareable boards, the user must be invited as a subscriber)
The API token you generate must come from this dedicated service user, not a personal user. Updates, item changes, and file uploads Gradial makes in monday.com will appear as this account.
**Required token capabilities:**
| Scope | Access required |
| ----------- | -------------------------------------- |
| **Boards** | Read all target boards |
| **Items** | Read / Write (create and update items) |
| **Updates** | Write (post updates to items) |
| **Users** | Read |
| **Files** | Upload |
***
## Connect monday.com to Gradial
Go to **Integrations** in the Gradial sidebar, find monday.com under **Ticket System Integrations**, and click **Connect**. The setup wizard walks through three steps: **Connection**, **Routing**, and **Route Summary**.
### Step 1 — Generate an API token
1. Log in to monday.com **as the service user**
2. Click your profile avatar and select **Developers** to open the Developer Center
3. Go to **My Access Tokens** and click **Show** to reveal the personal API token
4. Copy the token
Treat the API token like a password. If it is ever compromised, regenerate it from the Developer Center and update the integration in Gradial.
### Step 2 — Configure the connection
On the **Connection** step of the wizard:
1. Enter an **Integration Name** to identify this connection (e.g., "My monday.com Instance")
2. Paste the service user's token into **monday.com service user API token**
3. Click **Validate Connection**
4. Once validated, click **Next** to continue to routing
Once saved, credentials are stored securely and cannot be viewed again. To update the token, delete the integration and create a new one.
### Step 3 — Configure routing
On the **Routing** step, click **Add Route** to define which monday.com items Gradial ingests and where they land in Gradial. Each route in the Route Table can be toggled on or off and configured independently.
| Field | Required | Description |
| --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Route Name** | Required | A name to identify this route |
| **Description** | Optional | Notes about what the route is for |
| **Board ID** | Required | The numeric ID of the monday.com board to sync — found in the board URL (e.g., `yourcompany.monday.com/boards/18421333785`) |
| **Search Term** | Optional | A keyword filter — only items matching the search term are ingested |
Each route targets a single monday.com board. To sync more boards, add another route.
**Gradial Destination:**
| Field | Description |
| --------------- | ----------------------------------------------------------------- |
| **Workspace** | The Gradial workspace where ingested items will appear as threads |
| **Environment** | The Gradial environment to execute tasks in |
Click **Next** to review the **Route Summary**, and confirm the routes pull in what you expect before finishing.
For ingestion modes and best practices, see [Routing Tickets →](/docs/integrations-administration-and-setup/how-gradial-works-with-ticketing-systems/routing-tickets)
***
## How item execution works
Once a route is configured, Gradial polls monday.com for matching items and processes them automatically:
1. An item matching a route's filter criteria is discovered on the next scheduled sync
2. Gradial ingests the item as a thread, including its name, updates, column values, and files
3. The AI agent executes the requested work
4. Results — previews, links, and updates — are written back to the original monday.com item as the service user
5. Gradial continues to monitor the item for changes that trigger follow-up actions
***
## Troubleshooting
| Issue | Likely cause | Fix |
| -------------------------------- | --------------------------------------- | ------------------------------------------------------------------------- |
| No items syncing | Service user missing board access | Confirm the service user is subscribed to all target boards |
| Authentication fails | Invalid or regenerated API token | Copy a fresh token from the service user's Developer Center and reconnect |
| Items appear with delay | Scheduled sync, no webhooks | Expected behavior — items sync on the next cycle, not in real time |
| Updates posted by the wrong name | Token generated from a personal account | Regenerate the token from the dedicated Grady / Gradial Bot service user |
| Files not syncing | Token lacks file upload capability | Verify the service user can upload files on the target boards |
Contact your Gradial Product Specialist or email [support@gradial.com](mailto:support@gradial.com) if issues persist.
# Routing Tickets to Gradial Workspaces
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/how-gradial-works-with-ticketing-systems/routing-tickets
Configure routes to control which tickets Gradial ingests from your ticketing system and how they are organized into workspaces.
## What is a Route?
A route is a filter configuration that tells Gradial:
* **Which tickets to ingest** — Based on project, status, labels, or custom queries
* **How to organize them** — Flat (all siblings) or hierarchical (preserving parent-child relationships)
* **Where to place them** — The destination folder in Gradial
## Creating a Route
1. Go to **Organization Settings → Integrations**
2. Select your integration (Jira, Wrike, Workfront, Asana, or monday.com)
3. Click **Add Route**
4. Configure your filters (see system-specific options below)
5. Choose your ingestion mode
6. Click **Save Route**
***
## Ingestion Modes
### Hierarchical Ingestion (Recommended)
Hierarchical ingestion preserves the organizational structure from your external system:
* Parent-child relationships are maintained
* Epics contain their stories, projects contain their tasks
* Context flows from parent to child threads
* Items are automatically classified as folders or tickets
**When to use:** Most production scenarios where organizational context matters.
### Flat Ingestion
Flat ingestion pulls tickets as a simple list:
* All tickets become siblings at the same level
* No parent-child relationships preserved
* Simpler but loses organizational context
**When to use:** Simple use cases where hierarchy doesn't matter, or when testing.
***
## How Hierarchical Classification Works
When using hierarchical ingestion, Gradial automatically determines whether each item is a **folder** (organizational container) or **ticket** (actionable work):
**Classification priority:**
1. **Has children** — Items with child items are always classified as folders
2. **System container types** — Known container types (Epics, Projects, Portfolios) become folders
3. **AI classification** — For ambiguous items, AI analyzes the title and description to determine intent
This means an Epic with Stories will always be a folder containing ticket children, while a standalone Bug will be a ticket.
***
## System-Specific Filter Options
### Jira Filters
| Filter | Description | Example |
| :------------- | :------------------------------------------ | :------------------------------------------ |
| **Project** | Limit to specific Jira projects | `PROJ`, `TEAM` |
| **Issue Type** | Filter by issue type | Epic, Story, Task, Bug |
| **JQL Query** | Advanced filtering with Jira Query Language | `project = PROJ AND status = "In Progress"` |
| **Labels** | Filter by Jira labels | `gradial`, `ai-process` |
**JQL Examples:**
* All open bugs: `project = PROJ AND type = Bug AND status != Done`
* Recently updated: `project = PROJ AND updated >= -7d`
* Specific epic's children: `"Epic Link" = PROJ-123`
### Wrike Filters
| Filter | Description | Example |
| :--------- | :----------------------------- | :--------------------- |
| **Space** | Limit to specific Wrike spaces | Marketing, Engineering |
| **Folder** | Filter to specific folders | Q4 Campaigns |
| **Status** | Filter by task status | Active, Completed |
### monday.com Filters
| Filter | Description | Example |
| :-------------- | :------------------------------------------------ | :------------ |
| **Board ID** | The single monday.com board the route syncs from | `18421333785` |
| **Search Term** | Keyword filter — only matching items are ingested | `homepage` |
Each monday.com route targets exactly one board. To sync multiple boards, create one route per board.
### Workfront Filters
| Filter | Description | Example |
| :------------ | :--------------------------- | :---------------- |
| **Portfolio** | Limit to specific portfolios | 2024 Initiatives |
| **Program** | Filter by program | Product Launch |
| **Project** | Filter by project | Website Redesign |
| **Status** | Filter by task status | Current, Planning |
***
## Route Best Practices
**Start small, expand gradually**
* Begin with a single project or folder
* Verify the ingestion looks correct
* Gradually expand your filter scope
**Use specific filters**
* Avoid overly broad filters that pull in thousands of tickets
* Use labels or status filters to limit scope
* Review the preview before confirming ingestion
**Consider your hierarchy**
* If you use hierarchical ingestion, understand what parent items will be pulled in
* Ancestors of matching items may be fetched to provide context
**Monitor thread counts**
* After initial ingestion, verify you got the expected number of threads
* Check that folders and tickets are classified correctly
***
## Previewing Before Ingestion
Before running an ingestion, Gradial shows a preview of what will be created:
1. **Total item count** — How many threads will be created
2. **Folder vs ticket breakdown** — How items will be classified
3. **Hierarchy tree** — Visual representation of parent-child relationships
Review this preview carefully, especially for hierarchical ingestion. If you see unexpected items or counts, refine your filters before proceeding.
***
## Sync Behavior
Once a route is configured:
* **Initial ingestion** — All matching tickets are pulled into Gradial
* **Ongoing sync** — New and updated tickets are synced automatically (every 5 minutes)
* **Bidirectional updates** — Comments and attachments sync both directions
## Troubleshooting Routes
**Too many tickets ingested**
* Review and narrow your filters
* Add status or label filters to reduce scope
**Missing tickets**
* Check that tickets match your filter criteria
* Verify your service account has access to those tickets
**Wrong classification (folder vs ticket)**
* Tickets with children are always folders
* Check if items have subtasks or child issues
# Connecting to External Ticketing Systems
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/how-gradial-works-with-ticketing-systems/setting-up-ticketing-integrations
Connect Gradial to Jira, Workfront, Wrike, Asana, monday.com, or Azure DevOps to automatically ingest tickets, execute work, and sync results back to your workflow.
Once connected, Gradial monitors your ticketing system for matching tickets, executes the requested work, and writes results — previews, links, status updates — back to the original ticket. Your team keeps working in the tools they already use.
***
## Before you begin
You'll need:
* **Admin access** to your Gradial organization
* **Service account credentials** for the target ticketing system — a dedicated integration account, not a personal user
* **Knowledge of which projects or folders** you want to sync into Gradial
***
## Choose your platform
Supports Jira Cloud (Email + API Token or Forge OAuth) and Jira Server / Data Center (PAT).
Supports API Key and OAuth 2.0 JWT (Server-to-Server) for Adobe-identity environments.
Connects via Personal Access Token generated from the Wrike service account.
Connects via Personal Access Token or OAuth 2.0 from the Asana service account.
Connects via API token generated from a dedicated monday.com service user.
Connects via a personal access token from a dedicated Azure DevOps service user. Routes on project, area path, work item type, state, assignment, tags or WIQL.
***
## After connecting
Once a platform is connected, two things need to be configured:
1. **Routes** — define which tickets Gradial ingests, how they're organized, and where they appear in Gradial workspaces. See [Routing Tickets →](/docs/integrations-administration-and-setup/how-gradial-works-with-ticketing-systems/routing-tickets)
2. **Creating tickets from Gradial** — for work that originates in Gradial and needs to be tracked externally. See [Creating Tickets from Gradial →](/docs/integrations-administration-and-setup/how-gradial-works-with-ticketing-systems/creating-tickets-from-gradial)
# Workfront
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/how-gradial-works-with-ticketing-systems/workfront
Connect Gradial to Adobe Workfront to automatically ingest tasks and sync results back — supporting both API Key and OAuth 2.0 JWT authentication.
**What you can do:**
* Ingest Workfront tasks into Gradial with full context
* Filter tasks by project, program, portfolio, status, or custom fields
* Trigger Gradial execution when tasks match your criteria
* Write results — previews, links, comments, status updates — back to the Workfront task
***
## Prerequisites
**Service account requirements:**
* A dedicated Workfront integration account — not a personal user
* Created and managed by a Workfront system admin
* Must have visibility into all tasks and projects you intend to sync
**Required permissions for the service account:**
| Capability | Minimum access required |
| --------------- | ------------------------------------------------- |
| **Tasks** | Read all relevant fields, including custom fields |
| **Comments** | Read / Write |
| **Assignments** | Ability to reassign tasks when configured |
Permissions are granted through Workfront Access Levels, project- or portfolio-level sharing, or object-level permissions. See Adobe's documentation on Access Levels and Permissions for configuration guidance.
**Authentication-specific requirements:**
| Method | Additional requirements |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **API Key** | API Key generated from the service account's Workfront settings |
| **OAuth 2.0 JWT** | Adobe Workfront OAuth application with JWT flow enabled; Client ID, Client Secret, Customer ID, User ID, and Private Key (PEM) |
Use **API Key** if your Workfront instance has not migrated to Adobe Unified Access. Use **OAuth 2.0 JWT** if your organization enforces Adobe-identity-based authentication.
***
## Authentication options
| Method | Best for | Requirements |
| ----------------- | --------------------------------------- | ------------------------------------------------------------------------------- |
| **API Key** | Standard Workfront setups | Service account email + API Key from Workfront settings |
| **OAuth 2.0 JWT** | Adobe IMS / Unified Access environments | Adobe OAuth app with JWT flow; Client ID, Secret, Customer ID, User ID, PEM key |
***
## Connect Workfront to Gradial
Go to **Integrations** in the Gradial sidebar, select **Adobe Workfront**, and click **Add Integration**. Then follow the steps for your authentication method.
### Option A — API Key
1. Enter your **Workfront Base URL** (e.g., `https://your-company.my.workfront.com`)
2. Enter the **service account email**
3. Paste your **API Key**
4. Click **Validate Connection**
Once saved, credentials are stored securely and cannot be viewed. To update credentials, create a new integration.
### Option B — OAuth 2.0 JWT (Server-to-Server)
1. Select **OAuth 2.0 JWT (Server-to-Server)** as your authentication type
2. Enter your **Client ID** and **Client Secret**
3. Enter the **Customer ID** and **User ID** (service account)
4. Paste the **Private Key (PEM)**
5. Enter your **Workfront Base URL**
6. Click **Validate Connection**
***
## Configure routes
Once connected, create routes to define which Workfront tasks sync into which Gradial workspaces. Workfront supports filtering by portfolio, program, project, status, and custom fields.
[Configure Routes →](/docs/integrations-administration-and-setup/how-gradial-works-with-ticketing-systems/routing-tickets)
***
## Troubleshooting
| Issue | Likely cause | Fix |
| ----------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------- |
| Connection succeeds but no tasks returned | Filters too narrow or service account lacks visibility | Broaden filter criteria; confirm the account can see the target tasks |
| API Key connection fails | Expired or incorrect key | Regenerate the API key; verify the Workfront domain |
| OAuth JWT fails | Misconfigured OAuth app or wrong credentials | Verify the app supports JWT Bearer Flow; confirm all credential fields are correct |
| Service account cannot see tasks | Insufficient Access Level or object sharing | Have a Workfront admin review Access Levels and project sharing |
Contact your Gradial Product Specialist or email [support@gradial.com](mailto:support@gradial.com) if issues persist.
# Adobe Experience Platform
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/adobe-experience-platform
Connect Gradial to Adobe Experience Platform to create and retrieve audiences, inspect datasets, and activate segments across AJO, CJA, and connected systems.
Marketing teams with AEP invest heavily in data — datasets, schemas, audience definitions — but accessing that data typically requires a data engineer or a deep familiarity with the AEP UI. Marketers who want to build a new audience, check segment status, or understand what data is available are often blocked waiting for technical help, or they skip the data entirely and work from intuition.
Connect Adobe Experience Platform and Gradial becomes your natural-language interface for audience management — creating segments, retrieving audience definitions, and feeding them into AJO journeys, CJA analysis, and downstream activation systems. Marketers can describe an audience in plain language, see the definition before anything is created, and move directly into activation — without leaving Gradial or opening a support ticket.
***
## What You Can Do
Describe an audience in plain language and Gradial drafts the segment definition using available AEP datasets. Review the definition before anything is created.
Retrieve existing audiences by name or ID. Inspect audience metadata including namespace, status, evaluation time, profile count, and segment definition.
Use AEP audience context to feed AJO journeys, inform CJA analysis, or activate through Marketo, SFMC, or another connected marketing system.
Query available datasets and schemas to understand what data is in scope before building or refining an audience.
***
## Prerequisites
* An active Adobe Experience Cloud organization with AEP licensed and live
* Access to the **Adobe Developer Console** to create a project and generate server-to-server OAuth credentials
* Your **IMS Org ID** and the **sandbox name** Gradial should connect to
* A product profile with AEP API access configured in Adobe Admin Console
* A Gradial organization **Administrator** role to complete setup
***
## How to Connect
1. Go to [Adobe Developer Console](https://developer.adobe.com/console) and sign in with your Adobe ID.
2. Select your organization from the org switcher.
3. Click **Create new project** and give it a name (e.g., `Gradial – AEP Integration`).
1. Inside your new project, click **Add API**.
2. Filter by **Experience Cloud** and select **Experience Platform**.
3. Choose **OAuth Server-to-Server** as the authentication type and click **Next**.
4. Select or create a **Product Profile** that grants AEP API access.
| Scope | Required | Purpose |
| ----------------------------------------- | -------- | --------------------------------- |
| `AdobeAnalytics` | Yes | Access AEP datasets and schemas |
| `openid` | Yes | Required for OAuth token exchange |
| `read_organizations` | Yes | Resolve IMS org context |
| `additional_info.projectedProductContext` | Yes | Confirm AEP product entitlement |
5. Click **Save configured API**.
From the project's **OAuth Server-to-Server** credential page, copy:
* **Client ID**
* **Client Secret**
* **IMS Org ID**
* **Technical Account ID**
* **Token URL**
Keep the Client Secret secure. It grants API access to your AEP organization and should be treated as a sensitive credential.
1. In Gradial, go to **Settings → Integrations**.
2. Find **Adobe Experience Platform** and click **+ Add**.
3. Fill in the connection details:
| Field | Value |
| ------------------------ | --------------------------------------------------------------------------- |
| **Integration Name** | A display name (e.g., `Acme – AEP Production`) |
| **IMS Org ID** | From step 3 |
| **Client ID** | From step 3 |
| **Client Secret** | From step 3 |
| **Technical Account ID** | From step 3 |
| **Token URL** | From step 3 |
| **Sandbox** | The AEP sandbox Gradial should connect to (e.g., `aep-prod`) |
| **Capabilities** | Select the capabilities to enable: AEP, CJA, AJO, or activation via Marketo |
4. Click **Save**. Gradial validates the credentials before the integration goes live.
1. Go to **Settings → Environments** and select the Gradial Environment where AEP should be available.
2. Add the integration to that Environment. For full Adobe workflow coverage, add AEP, AJO, and CJA integrations to the same Environment.
3. Repeat for any additional Environments.
***
## How It Fits Into Broader Workflows
| Use case | How to use it |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Audience creation** | Describe a target group in plain language — Gradial drafts the segment definition from available datasets and shows it to you before creating anything |
| **Audience retrieval** | Ask Gradial to retrieve an audience by name or ID and surface its full definition, status, profile count, and namespace |
| **Journey activation** | Use an AEP audience as the entry condition for an AJO journey — reference the audience in the same Gradial thread where you're building the journey |
| **Analytics hand-off** | Feed an AEP audience into a CJA analysis thread to understand how that segment behaves across channels |
| **Cross-system activation** | Activate an AEP audience through Marketo, SFMC, or another connected system in the same Gradial thread |
### Audience Management
Use Gradial to create and retrieve Adobe audiences in AEP so marketers can define target groups and reuse them across AJO journeys, campaigns, and CJA analysis.
**Create an audience**
> *"Create an Adobe audience for retail cart abandoners (Gradial Retail Cart Abandoners June 2026) who added items to cart but did not purchase. Use the available retail cart datasets, follow the standard naming convention, and show me the audience definition before creating it."*
**Retrieve an audience**
> *"Retrieve the Adobe audience named retail\_cart\_abandoners. Show me its audience ID, namespace, status, last evaluation time, profile count, and segment definition details if available."*
### Adobe Journey Optimizer
Use Gradial to retrieve AJO journeys, inspect each journey step, view the connected audience and authored email, and prepare safe campaign or content updates for review.
**Retrieve a journey**
> *"Retrieve the AJO journey named Gradial-Retail-Cart-Reminder. Show the journey as steps, including the read audience step and send email step. When I select the email step, render the exact authored email from AJO."*
**Prepare a journey update**
> *"Open the send cart email step in the AJO journey. Show me the current email, then prepare an updated version with a 48-hour free shipping message. Do not publish, send, or activate anything until I approve it."*
### Customer Journey Analytics
Use Gradial to query and analyze CJA data so teams can understand customer behavior, journey performance, and campaign impact across Adobe data sources.
**Analyze journey performance**
> *"Analyze cart abandonment performance in Customer Journey Analytics for June. Show abandonment volume, conversion rate, and the main drop-off points by journey step or channel."*
**Generate a report**
> *"Create a CJA report for the retail cart abandonment journey. Include audience size, email engagement, conversion trends, and key recommendations for improving the journey."*
***
## What's Not Covered Yet
* Real-time event streaming from AEP — Gradial reads processed data, not live event streams.
* Adobe Target experiments — use the Adobe Target integration for A/B and multivariate testing.
***
## Troubleshooting
| Issue | Cause | Solution |
| ---------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------- |
| `401 Unauthorized` | Invalid or expired credentials | Regenerate the Client Secret in Adobe Developer Console and update Gradial |
| `403 Forbidden` | Missing API scopes or product profile access | Confirm the product profile has AEP API permission in Adobe Admin Console |
| Empty audience results | Sandbox mismatch | Verify the sandbox name matches the environment where audiences are defined |
| Token exchange fails | Missing required OAuth scopes | Re-add the API in Adobe Developer Console and confirm all required scopes are selected |
***
## Good to Know
* **One credential set covers the full Adobe suite**: The same OAuth Server-to-Server credentials work across AEP, AJO, and CJA when the product profile has access to all three. You don't need separate Developer Console projects for each Adobe product.
* **Sandbox selection matters**: Audiences, journeys, and datasets are sandbox-scoped. Make sure Gradial is pointed at the sandbox where your working data lives.
* **Pair with AJO and CJA**: AEP is most powerful when combined with the [Adobe Journey Optimizer](/docs/integrations-administration-and-setup/integrations/adobe-journey-optimizer) and [Adobe Customer Journey Analytics](/docs/integrations-administration-and-setup/integrations/customer-journey-analytics) integrations in the same Gradial Environment.
***
## Support
Contact your Gradial onboarding lead or email [support@gradial.com](mailto:support@gradial.com) for help with setup.
# Adobe Journey Optimizer
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/adobe-journey-optimizer
Connect Gradial to Adobe Journey Optimizer to inspect campaigns, journeys, messages, and templates — and execute supported operations across your stack.
AJO gives marketing teams powerful journey orchestration, but acting on it is slow. Inspecting a live journey, understanding what an email looks like, drafting an update, and getting it through review typically means navigating multiple Adobe UIs, pulling in a developer for API work, and managing approvals in a separate tool. By the time a change is ready, the campaign moment may have passed.
Connect Adobe Journey Optimizer once and Gradial becomes your cross-platform execution layer: reading AJO context, reasoning over the marketing task, creating artifacts, and executing in AJO or any connected downstream system. Teams can inspect journeys, draft content updates, and move work through review — in the same thread where the brief was written.
***
## What You Can Do
Inspect AJO campaigns and journeys. View messages, templates, and fragments. Create or update supported objects when APIs and permissions allow.
Read templates and fragments so Gradial can reference them when drafting new messages. Generate content drafts aligned to your existing AJO assets.
Pull AJO tracking datasets and performance context. Turn campaign results into recommendations, content updates, or next-journey plans.
Use AJO context to execute or draft work in SFMC, Marketo, AEM, SMS, push, CMS, or another connected marketing system.
***
## Prerequisites
Before starting setup, confirm the following are in place:
* An active Adobe Experience Cloud organization with AJO licensed and live
* Access to the **Adobe Developer Console** to create a project and generate server-to-server OAuth credentials
* The **IMS Org ID** for your Adobe Experience Cloud organization
* The **sandbox name** (or environment) where Gradial should start — sandbox, staging, or production read-only
* Product profile membership that covers the AJO APIs in scope
* A Gradial organization **Administrator** role to complete setup
***
## How to Connect
1. Go to [Adobe Developer Console](https://developer.adobe.com/console) and sign in with your Adobe ID.
2. Select your organization from the org switcher.
3. Click **Create new project**.
4. Give the project a name (e.g., `Gradial – AJO Integration`).
1. Inside your new project, click **Add API**.
2. Filter by **Experience Cloud** and select **Adobe Journey Optimizer**.
3. Choose **OAuth Server-to-Server** as the authentication type and click **Next**.
4. Select or create a **Product Profile** that grants the API scopes needed:
| Scope | Required | Purpose |
| --------------------- | -------- | --------------------------------- |
| `ajo.campaigns.read` | Yes | Read campaigns |
| `ajo.journeys.read` | Yes | Read journeys |
| `ajo.messages.read` | Yes | Read messages and channel content |
| `ajo.templates.read` | Yes | Read templates and fragments |
| `ajo.campaigns.write` | Optional | Create or update campaigns |
| `ajo.journeys.write` | Optional | Create or update journeys |
5. Click **Save configured API**.
From the project's **OAuth Server-to-Server** credential page, copy:
* **Client ID**
* **Client Secret**
* **IMS Org ID**
* **Technical Account ID**
* **Sandbox name** (the AJO sandbox you authorized)
Keep the Client Secret secure. Anyone with this credential can act on behalf of your Adobe organization within the granted scopes.
1. In Gradial, go to **Settings → Integrations**.
2. Find **Adobe Journey Optimizer** and click **+ Add**.
3. Fill in the connection details:
| Field | Value |
| ------------------------ | ---------------------------------------------- |
| **Integration Name** | A display name (e.g., `Acme – AJO Production`) |
| **IMS Org ID** | From step 3 |
| **Client ID** | From step 3 |
| **Client Secret** | From step 3 |
| **Technical Account ID** | From step 3 |
| **Sandbox Name** | The AJO sandbox Gradial should connect to |
4. Click **Save**. Gradial validates the credentials before the integration goes live.
1. Go to **Settings → Environments** and select the Gradial Environment where AJO should be available.
2. Add the integration to that Environment.
3. Repeat for any additional Environments.
***
## How It Fits Into Broader Workflows
| Use case | How to use it |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Campaign support** | Ask Gradial to inspect an AJO campaign, summarize its current state, and draft an updated message or subject line |
| **Journey planning** | Use Gradial to map an existing journey's structure, identify gaps, and draft the next phase |
| **Insight to content** | Pull AJO tracking data into a Gradial thread and have it generate a performance summary and follow-up content plan |
| **Cross-platform execution** | Use AJO audience and campaign context to execute or draft work in SFMC, Marketo, AEM, SMS, push, or CMS |
| **Migration acceleration** | Inventory source journeys and assets, classify what can be automated, and generate build packets for the destination system |
**Example — Inspect a campaign and draft updated copy:**
1. Ask Gradial to list active AJO campaigns.
2. Select a campaign and have Gradial summarize its messages and performance.
3. Ask Gradial to draft an updated subject line and body copy.
4. Review the draft and publish through AJO when ready.
**Example — Cross-platform activation:**
1. Share an AJO audience or journey with Gradial.
2. Ask Gradial to draft a matching email in Salesforce Marketing Cloud or Marketo.
3. Gradial reads the AJO context, creates the asset in the connected system, and returns a link for review.
***
## What's Not Covered Yet
* Direct send or trigger execution for live journeys — Gradial can draft and inspect, but send execution depends on API availability and your governance policy.
* Authoring new message surfaces or channel configurations — these are managed in the AJO UI.
* Private or beta AJO APIs — Gradial uses publicly available REST APIs only.
* Adobe Analytics or AEP audience context without a separate AEP integration configured.
***
## Customer Information Needed Before Setup
Use this checklist to confirm readiness before the integration meeting:
* [ ] Adobe IMS Org ID, sandbox name, and environment confirmation (sandbox, staging, or production read-only)
* [ ] Adobe Developer Console project with OAuth Server-to-Server credentials and required product profiles
* [ ] AJO context objects Gradial should read: campaigns, journeys, messages, templates, fragments, tracking datasets
* [ ] Active channels in scope: email, push, SMS, in-app, web
* [ ] Sender domains, consent policy, and suppression list configuration (required for any write operations)
* [ ] Adjacent execution systems if cross-platform activation is in scope: SFMC, Marketo, AEM, CMS, or another destination
* [ ] Governance model: who approves drafts, who can publish, who can send, and whether Gradial should start read-only
***
## Troubleshooting
| Issue | Cause | Solution |
| ---------------------- | ------------------------------ | -------------------------------------------------------------------------- |
| `401 Unauthorized` | Invalid or expired credentials | Regenerate the Client Secret in Adobe Developer Console and update Gradial |
| `403 Forbidden` | Missing API scopes | Add the required scopes to the product profile in Adobe Developer Console |
| `404 Not Found` | Incorrect sandbox name | Verify the sandbox name matches your AJO environment exactly |
| Token refresh failures | Client Secret rotated | Update the Client Secret in Gradial Settings → Integrations |
***
## Good to Know
* **Start read-only**: Gradial can deliver immediate value — inspecting campaigns, summarizing journeys, drafting content — without write permissions. Enable write scopes only when governance is confirmed.
* **Sandbox first**: Validate the integration in an AJO sandbox before pointing Gradial at a production environment.
* **Governance is explicit**: Read, draft, write, publish, and send permissions can be scoped separately so each team controls its own activation path.
***
## Support
Contact your Gradial onboarding lead or email [support@gradial.com](mailto:support@gradial.com) for help with setup.
# Adobe Target
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/adobe-target
Connect Gradial to Adobe Target for experimentation and personalization — browse, create, preview, and activate activities without leaving the platform.
Teams can work with Adobe Target activities, audiences, offers, mboxes, properties, and environments directly from Gradial, then preview and launch personalized experiences without switching tools.
***
## What You Can Do
Browse, filter, create, rename, schedule, prioritize, activate, and deactivate Adobe Target activities — including A/B tests and experience targeting — without leaving Gradial.
Preview each experience before launch. When a Default Preview URL is configured, Gradial generates in-context previews directly inside the workflow so PMs and marketers can review outcomes earlier.
Work with audiences, offers, mboxes, properties, and environments. Use the dedicated Adobe Target authoring assistant to shape experiences end to end.
Review performance and order reporting to support optimization decisions, and combine Adobe Analytics insights with Adobe Target execution in a tighter loop.
***
## Prerequisites
Before connecting Adobe Target to Gradial, make sure you have:
* An active **Adobe Experience Cloud** organization
* Access to **Adobe Developer Console** to create or open a project for the correct organization
* **Tenant ID** for your Adobe Target instance (found in the Target URL subdomain after signing in to Adobe Experience Cloud)
* **IMS Organization ID** from your Adobe credential details
* A Gradial organization **Administrator** role to complete setup
The setup pattern is the same as Adobe Analytics. If you have already configured that integration, you can reuse the same Developer Console project and credentials.
***
## How to Connect
1. Go to [Adobe Developer Console](https://developer.adobe.com/console/) and sign in for the correct Experience Cloud organization.
2. Create or open the project you want to use for this integration.
3. Click **Add API** and select **Adobe Target**.
4. Choose **OAuth Server-to-Server** as the credential type.
5. Select the product profiles or workspaces the integration should be allowed to use.
6. From the credential details screen, copy the **Client ID**, **Client Secret**, and **Organization ID**.
Sign in to Adobe Experience Cloud and open Adobe Target. Your Tenant ID appears in the URL after `#/@` (e.g., `https://experience.adobe.com/#/@yourcompany/target` → Tenant ID is `yourcompany`).
The Tenant ID is different from the Target client code. Use the subdomain from the Target URL, not the client code shown in Target's admin settings.
1. In Gradial, go to **Settings → Integrations**.
2. Find **Adobe Target** and click **+ Add**.
3. Fill in the connection details:
| Field | Value |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Integration Name** | A display name (e.g., `My Adobe Target Connection`) |
| **Adobe Target API URL** | Pre-filled as `https://mc.adobe.io` — leave as-is |
| **Authentication Type** | Fixed to **OAuth 2.0 Client Credentials** |
| **Client ID** | From your Adobe Developer Console project |
| **Client Secret** | From your Adobe Developer Console project |
| **Token URL** | Use Adobe's standard token URL unless your Adobe team has specified a different approved value |
| **Scope** | Use Adobe's standard Target scope unless otherwise directed |
| **Tenant ID** | Your Target tenant slug, used in API request paths (e.g., `clientcode123`) |
| **IMS Org ID** | Your Adobe Organization ID ending in `@AdobeOrg` — sent as the IMS organization header on Target API requests |
| **Default Preview URL** *(optional)* | A base URL for your live or preview site. When set, experiment previews auto-load against this URL. Leave blank to be prompted per activity. |
4. Click **Save**.
1. Go to **Settings → Environments** and select the Environment where Adobe Target should be available.
2. Add the Adobe Target integration to that Environment.
3. Repeat for any additional Environments.
***
## How It Fits Into Broader Workflows
| Use case | How to use it |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Analytics → Target loop** | Combine Adobe Analytics insights with Adobe Target execution. Use CX Optimizer to identify where performance is under target, define the next audience, and move straight into a new experiment |
| **Faster personalization cycles** | Preview the experience in context before launch, then activate — cutting the time between identifying an opportunity and going live |
| **End-to-end in Gradial** | Draft offers, shape audiences, preview experiences, and activate activities all from the same workflow without context-switching |
**Example flow:**
1. Start with a performance insight from Adobe Analytics or CX Optimizer.
2. Identify the audience that should receive a different experience.
3. Draft or refine the offer in Gradial using the Adobe Target authoring assistant.
4. Preview each experience variant before launch.
5. Activate the activity and begin learning from results.
***
## Troubleshooting
**"Invalid client" error when saving**
Double-check that the Client ID and Client Secret are copied exactly from Adobe Developer Console with no extra spaces.
**Tenant ID not recognized**
Confirm you are using the subdomain from the Adobe Target URL, not the client code. These are different values and the API requires the subdomain form.
**IMS Org ID error**
The IMS Org ID should end in `@AdobeOrg`. Copy it directly from the Adobe Developer Console credential details screen.
**Previews not loading automatically**
Set a **Default Preview URL** in the integration settings. Without it, Gradial will prompt you for a URL each time you preview an activity.
**Integration not available in a Workspace**
Assign the integration to the correct Environment under **Settings → Environments**.
***
## Support
Contact your Gradial onboarding lead or email [support@gradial.com](mailto:support@gradial.com) for help with setup.
# AEM Integration: Advanced Configurations
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/aem/advanced-configurations
Fine-tune how Gradial connects to AEM — custom authentication scopes, multi-site configurations, and environment-specific settings.
This guide covers the advanced configuration options available in your AEM integration settings. These configurations allow you to fine-tune how Gradial connects to and interacts with your AEM instance.
## Accessing Integration Settings
1. Navigate to **Settings** in your organization
2. Select **Integrations** from the sidebar
3. Click on your **AEM Integration**
4. Use the tabs at the top to navigate between configuration sections
***
## General Settings
The General tab contains core configuration options for your AEM integration.
### Integration URL
The AEM service endpoint URL for this integration. This is the base URL Gradial uses to communicate with your AEM instance.
**Example:** `https://aem-sandbox.gradial.com`
### Mark as Production Instance
Toggle this option to designate your AEM environment as a production instance. When enabled:
* Additional safeguards are applied to prevent accidental changes
* Workflow approvals may be enforced
* Audit logging is enhanced
### Authoring Domain Override
Use this field when your AEM editing environment uses a different URL than the service endpoint.
**Example:** `https://author.example.com`
**When to use:**
* Your AEM author instance is on a different domain than the publish instance
* You have separate authoring and preview environments
### Workflow Type
Choose how content changes are applied to your AEM instance:
| Workflow Type | Description | Best For |
| :-------------- | :--------------------------------------------------------------------------------------------------------- | :-------------------------------------------------- |
| **Launch** | Creates new content using AEM Launches workflow. Changes are staged and can be reviewed before publishing. | Production environments, content requiring approval |
| **Direct Edit** | Edits existing pages directly without launches. Changes are applied immediately. | Development environments, quick updates |
### MSM Inheritance Protection
**Block edits to pages with active MSM inheritance** (Recommended)
When enabled, Gradial will prevent modifications to pages that are managed through AEM's Multi Site Manager (MSM) inheritance. This protects your content governance model by ensuring inherited content isn't accidentally modified.
**Default:** Enabled
***
## Networking
The Networking tab provides options for network configuration and rate limiting.
### Advanced: Network & Proxy Settings
Expand this section to configure:
* Custom proxy servers
* Network timeouts
* SSL/TLS certificate handling
* Custom headers for authentication
### Rate Limiting
Control the frequency of API requests to your AEM instance.
**Enable rate limiting for this connection**
When enabled, you can configure:
* Maximum requests per second
* Burst limits
* Queue behavior for exceeded requests
**Default:** Disabled (uses default resilience settings)
**When to enable:**
* Your AEM instance has strict rate limits
* You're experiencing throttling from AEM
* You need to share capacity with other integrations
***
## Asset Sync (Journaling)
Gradial can keep its asset index in sync with AEM using Adobe's **I/O Events Journaling API**. Without journaling, changes in AEM (new, updated, or deleted assets) are only picked up during periodic full re-scans, which are slow and expensive for large asset libraries. With journaling enabled, Gradial polls a stream of change events from Adobe and applies them incrementally — so asset changes show up in Gradial search within minutes instead of waiting for the next full re-scan.
A scheduled full reconciliation still runs periodically as a safety net.
Journaling-based asset sync must be enabled for your organization. Contact your Gradial team to get access. If journaling is not configured, asset sync continues to work through the existing scheduled re-scans — there is no disruption for integrations that haven't set it up.
### Prerequisites
You'll need an Adobe Developer Console project with an AEM Assets event registration. From that project, gather three values:
| Value | Where to find it |
| :--------------------------------- | :-------------------------------------------------------------------- |
| **Journaling Unique API Endpoint** | Under the **Journaling** section of your Adobe I/O event registration |
| **Client ID** | From the project's **OAuth Server-to-Server** credentials |
| **Client Secret** | From the same credentials page |
### Configuring journaling
Journaling details can be added in two places:
* **AEM onboarding wizard** — when setting up a new AEM integration
* **Integration configuration modal** — for an existing AEM integration, under your integration settings
Enter the Journaling Unique API Endpoint, Client ID, and Client Secret from your Adobe Developer Console project. Once configured, Gradial handles authentication and polling automatically.
***
## Mappings
The Mappings tab configures content paths and templates for your AEM integration.
### Default Experience Fragment Template
Specifies the template used when creating new Experience Fragments.
**Format:** Must start with `/conf/`
**Example:**
```
/conf/wknd/settings/wcm/templates/xf-web-variation
```
**When to configure:**
* You want a consistent template across all XF creations
* To avoid specifying the template every time you create an XF
> **Note:** This is optional. If not set, you'll need to specify the template when creating Experience Fragments.
### Experience Fragment Paths
Define the parent folders where Experience Fragments can be created. AI agents will intelligently select the most appropriate path based on content type and context.
**Format:** Each path must start with `/content/experience-fragments/`
**Examples:**
```
/content/experience-fragments/site/heroes
/content/experience-fragments/site/promos
/content/experience-fragments/site/global
```
**Adding paths:**
1. Enter a path in the input field
2. Click **+ Add** or press **Enter**
3. Repeat for additional paths
**Path Selection Logic:** When multiple paths are configured, the agent:
1. Analyzes the content being created
2. Matches it to the most semantically appropriate path
3. Uses the first path as a fallback if no better match is found
**Best Practices:**
* Use semantic folder names (e.g., `/heroes` not `/folder1`)
* Organize by content type or channel
* Add paths in order of preference (first path is the fallback)
> 📖 For detailed Experience Fragment configuration, see: [Configuring Experience Fragment Defaults](https://www.notion.so/Configuring-Experience-Fragment-Defaults-2e37521d682e813ba989c83c16cd4303)
### Page Mappings
Configure content path mappings for AEM site and DAM operations.
| Field | Description | Example |
| :------------------- | :--------------------------- | :-------------------------- |
| **Site Path** | The content path in AEM | `/content/gradial-core` |
| **DAM Path** | Corresponding DAM asset path | `/content/dam/gradial-core` |
| **Default Template** | Page template for new pages | (Optional) |
**To add a mapping:**
1. Click **+ Add Mapping**
2. Enter the Site Path
3. Enter the corresponding DAM Path
4. Optionally select a default template
5. Click Save
***
## Permissions
The Permissions tab allows you to verify your AEM user has the necessary access rights.
### Permission Testing
Select and run specific permission tests to verify your AEM user has the necessary access. Tests will create temporary artifacts and clean them up automatically.
**Available Tests:**
| Test | Verifies |
| :------------------------- | :---------------------------------------------- |
| **Launch Permission** | Ability to create and manage AEM Launches |
| **Create Page Permission** | Ability to create new pages in configured paths |
| **Asset Permission** | Ability to upload and manage DAM assets |
**Running Tests:**
1. Check the boxes for tests you want to run
2. Click **Run Selected Tests** or **Test All Permissions**
3. Review results for any permission issues
**Troubleshooting Failed Tests:**
* Verify the AEM user credentials are correct
* Check that the user has the required group memberships in AEM
* Review AEM ACL configurations for the configured paths
***
## Domains
The Domains tab configures URL resolution from AEM paths to user-facing domains.
### Domain Mappings
Configure how AEM content paths map to live, user-facing URLs.
| Field | Description | Example |
| :---------------- | :----------------------- | :------------------------------------------- |
| **AEM Path** | The content path in AEM | `/content` |
| **Live Domain** | The public-facing domain | `gradial.com` |
| **Regex Pattern** | Pattern for URL matching | `^(https?:\/\/)?(.*\.)?gradial\.com(\/.*)?$` |
**Adding a Domain Mapping:**
1. Click **+ Add Domain Mapping**
2. Enter the AEM Path (e.g., `/content/mysite`)
3. Enter the Live Domain (e.g., `www.mysite.com`)
4. Configure the regex pattern for URL matching
5. Click Save
**Use Cases:**
* Map AEM content paths to production URLs
* Support multiple domains for different content sections
* Enable URL validation in QA workflows
***
## Validation Rules Summary
### Template Paths
* **Must start with:** `/conf/`
* **Valid:** `/conf/wknd/settings/wcm/templates/xf-web-variation`
* **Invalid:** `/apps/templates/xf`
### Experience Fragment Paths
* **Must start with:** `/content/experience-fragments/`
* **Valid:** `/content/experience-fragments/wknd/heroes`
* **Invalid:** `/content/wknd/xf`
### Site Paths
* **Must start with:** `/content/`
* Exclude `/content/dam/` (use DAM Path field instead)
***
## Related Documentation
* [Navigating Workspaces and Settings in Gradial](https://app.gradial.com/)
* [Configuring Experience Fragment Defaults](https://www.notion.so/Configuring-Experience-Fragment-Defaults-2e37521d682e813ba989c83c16cd4303)
* AEM Multi Site Manager (MSM) Overview
* AEM Launches Documentation
# AMS/AEM as a Cloud Service
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/aem/aem-cloud
How to set up and configure Gradial with Adobe Experience Manager (AEM) as a Cloud Service or Adobe Managed Services
## Overview
This guide explains how to configure a Technical Account in AEM as a Cloud Service for Gradial integration. By generating Service Credentials and adding the Technical Account to your author group(s), you enable Gradial to interact with AEM for creating Launches, managing content, and other operations.
Basic integration steps include:
1. Creating a Technical Account and downloading credentials
2. Providing the credentials to Gradial
3. Assigning appropriate permissions to the Technical Account in AEM
## AEM Cloud Service Authentication
AEM as a Cloud Service uses Adobe's Identity Management System (IMS) for authentication:
Machine-to-machine communication using service credentials and JWT tokens for authentication. No user intervention required.
Access is governed by AEM group memberships that control what operations the Technical Account can perform.
## Prerequisites
Before creating a Technical Account, ensure you have the proper access and team coordination:
### Required Access Roles
* **Adobe IMS Org System Administrator** - Required to create Technical Accounts
* **AEM Administrators IMS Product Profile member** - Required for to assign permissions
### Team Coordination
Typically, the following teams are involved:
* **IT/DevOps Team** - Usually holds System Administrator privileges for Cloud Manager
* **AEM Development Team** - Configures user permissions and group memberships
* **Security Team** - Reviews and approves service account access
Coordinate with your IT and security teams before proceeding. System Administrator access is typically restricted and may require approval workflows.
## Integration Steps
**Who performs this step:** Adobe IMS Org System Administrator (typically IT/DevOps team)
1. Log in to [Adobe Cloud Manager](https://my.cloudmanager.adobe.com/) as a System Administrator for your IMS Org
2. Select the Program containing your target AEM environment
3. Find the AEM environment, click the ellipsis (...), then select **Developer Console**
4. In the Developer Console, navigate to the **Integrations** tab
5. Select the **Technical Accounts** tab
6. Click **Create new technical account**
7. Once created, expand the Technical Account entry
8. Click **View** to download the service credentials JSON file (often named `service token.json`)
**CRITICAL:** Do not modify the downloaded JSON file in any way. Use the file exactly as provided by Adobe. Any modifications will cause authentication failures.
Keep this file secure and never commit it to source control. Store it according to your organization's security policies for sensitive credentials.
**Limits:** Each AEM environment can have up to 10 technical accounts. Service credentials expire every 365 days and will need to be regenerated.
Gradial will:
* Use the `service token.json` to generate and sign a JWT
* Exchange that JWT with Adobe IMS for short-lived access tokens
* Add a Bearer token header to AEM API calls
Share the service token JSON file securely with your Gradial representative.
**Who performs this step:** AEM Administrator
Once the Gradial Technical Account authenticates for the first time, it will appear in AEM as a user (format: `xxxx@techacct.adobe.com`). You’ll then assign it to the right groups so it can create Launches, edit content, and upload assets.
For background on how permissions work in AEM as a Cloud Service, see Adobe’s [Users, Groups and Permissions guide](https://experienceleague.adobe.com/en/docs/experience-manager-learn/cloud-service/accessing/aem-users-groups-and-permissions).
***
### Step 1: Find the Technical Account User
1. In **AEM Author**, go to **Tools → Security → Users**
2. Search for the account ending in `@techacct.adobe.com`
3. If you don’t see it, ask Gradial to trigger an authentication so the account is registered
***
### Step 2: Assign Group Memberships
There are two common approaches:
#### Option A: Add to Existing Author Groups (Quick Start)
* Add the Technical Account to your **standard author/editor group(s)**
* This gives it the same capabilities your authors use: creating pages, editing content, uploading assets, and working with Launches
* Recommended if you want to get started quickly, but you will still need to ensure that the base permissions are available.
#### Option B: Create a Dedicated Service Group (Best Practice)
* Create a new group just for Gradial’s service accounts
* Grant that group the **minimum required permissions**
* Add additional rights only if needed (e.g., replication or workflows)
🔗 For step-by-step instructions on adding a user to a group, see Adobe’s [Managing Users and Groups in AEM](https://experienceleague.adobe.com/docs/experience-manager-cloud-service/content/security/ims-support.html).
For enhanced security, Option 2 is recommended to follow the principle of least privilege.
| Area | Path | JCR Privileges | Why It’s Needed |
| :---------------------------------- | :------------------------------------- | :-------------------------------------------------------------------------------- | :-------------------------------------------------------- |
| **Launches** | `/content/launches` | `jcr:read`, `rep:write`, `jcr:versionManagement` | Create/manage Launches, check-in/out versions |
| **Assets (DAM)** | `/content/dam` (or equivalent) | `jcr:read`, `rep:write`, `jcr:versionManagement, crx:replicate` | Upload/edit assets and metadata, manage versions |
| **Content Fragments** (if separate) | `/content/dam/` | `rep:write`, `jcr:versionManagement` | Create/update Content Fragments |
| **Site Pages** | `/content/` | `jcr:read`, `rep:write`, `jcr:versionManagement` | Create/update pages |
| **Experience Fragments** | `/content/experience-fragments/` | `jcr:read`, `rep:write`, `jcr:versionManagement` | Create/update XFs |
| **Tags** | `/content/cq:tags/` | `jcr:read`, `rep:write`, `jcr:versionManagement`, `crx:replicate` (if publishing) | Apply/create tags, version/tag changes, publish if needed |
| **Publishing (Optional)** | `/content` (scoped) or `/content/dam` | `crx:replicate`, `jcr:addChildNodes` (if asset publishing required) | Needed only if Gradial should publish |
## Important Notes
* The private key in `service token.json` generally expires each year, so you will need to regenerate the Service Credentials JSON before it expires
* Access tokens themselves expire frequently; Gradial automatically fetches new tokens using the private key
## Reference
For additional information, see these Adobe documentation resources:
* [AEM Cloud Service Authentication with Service Credentials](https://experienceleague.adobe.com/en/docs/experience-manager-learn/getting-started-with-aem-headless/authentication/service-credentials)
* [Managing Users and Groups in AEM as a Cloud Service](https://experienceleague.adobe.com/docs/experience-manager-cloud-service/content/security/ims-support.html)
* [AEM Users, Groups and Permissions in Cloud Service](https://experienceleague.adobe.com/en/docs/experience-manager-learn/cloud-service/accessing/aem-users-groups-and-permissions)
## Need Help?
Contact your Gradial representative for additional support with your AEM as a Cloud Service integration.
# AEM Edge Delivery Services
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/aem/aem-edge-delivery
Connect Gradial's AI agents to Adobe Experience Manager Edge Delivery Services for high-performance content delivery.
## Overview
[AEM Edge Delivery Services](https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/edge-delivery/overview) is Adobe's composable approach to building fast, high-impact web experiences. Edge Delivery decouples authoring from delivery, allowing content teams to author in familiar tools (Google Docs, Microsoft Word, or AEM) while serving pages from the edge for maximum performance.
Gradial's AI agents integrate with Edge Delivery Services environments to automate content creation, updates, and quality assurance across your Edge Delivery projects.
## Prerequisites
* An active AEM as a Cloud Service subscription with Edge Delivery Services enabled
* A configured Edge Delivery project (GitHub-backed repository)
* Admin access to Adobe Admin Console for service credential creation
* Gradial account with admin permissions
## Authentication
Edge Delivery Services uses the same **Adobe IMS (Identity Management System)** authentication as AEM as a Cloud Service. You will need a technical account with the appropriate permissions scoped to your Edge Delivery project.
Refer to the [AMS/AEM Cloud Service setup guide](/docs/integrations-administration-and-setup/integrations/aem/aem-cloud) for instructions on generating IMS credentials.
## Configuration Steps
Follow the [AEM Cloud credential setup guide](/docs/integrations-administration-and-setup/integrations/aem/aem-cloud) to create a technical account and download the JSON credentials package from Adobe Developer Console.
In the Gradial app, go to **Settings** and click **Integrations**.
Enter the authoring URL for your Edge Delivery environment. This is typically your AEM Cloud author instance (e.g., `https://author-p{programId}-e{environmentId}.adobeaemcloud.com`).
Choose **AMS/AEM Cloud Service** as the integration type and upload the IMS credentials JSON package.
Select the folder paths within your Edge Delivery project that Gradial will manage. For Edge Delivery, this typically corresponds to your content tree in AEM (e.g., `/content/`).
Use the permission validation tool to confirm Gradial has the correct read/write access to your content paths.
Map your AEM authoring paths to the live Edge Delivery URLs (e.g., `https://----.hlx.page` or your production domain).
Combine your Edge Delivery integration with other integrations (ticketing, design tools) into a Gradial Environment.
Assign the Environment to the appropriate Gradial Workspace to make it available to your content team.
## Need Help?
Contact your Customer Solutions Support team.
# AEM Guides
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/aem/aem-guides
Set up Adobe Experience Manager Guides with Native PDF Publishing on AEM as a Cloud Service.
## Overview
[AEM Guides](https://experienceleague.adobe.com/en/docs/experience-manager-guides) is Adobe's enterprise-grade component content management system (CCMS) built on AEM. It enables structured authoring using the DITA standard, supports multi-channel publishing, and provides robust version control and translation workflows for technical documentation teams.
Gradial's AI agents integrate with AEM Guides to automate content creation, updates, translation tasks, and quality assurance across your DITA-based content libraries.
AEM Guides authoring operations are available only when the AEM Guides feature is enabled for your organization. Contact Gradial Support to request access.
This page covers the full end-to-end setup for **Native PDF Publishing** on AEM as a Cloud Service (AEMaaCS), including the credential and OSGi configuration required to connect AEM author to Adobe's publishing microservice.
***
## What Native PDF Publishing Actually Requires
Three independent things must all be true:
1. **AEM Guides authoring entitlement** on the program — gives you the Web Editor, output presets UI, templates UI, and fmdita JCR setup. This is a paid Adobe add-on sold separately from base AEMaaCS Sites/Assets.
2. **AEM Guides publishing tenant provisioned by Adobe** — the customer-specific Adobe I/O Runtime tenant that renders PDFs. This is a separate Adobe-side provisioning step from #1. Contact your Adobe Customer Success representative to confirm this is in place.
3. **A correctly-scoped IMS service account** in your AEMaaCS environment — the OAuth Server-to-Server credential that AEM author uses to authenticate calls to the publishing tenant. This is the step most often misconfigured.
If any of the three above is missing, PDF generation will silently fail. See [Troubleshooting](#troubleshooting) for the specific symptoms and fixes for each failure mode.
***
## Prerequisites
* An AEMaaCS program with AEM Guides provisioned by Adobe Customer Success
* Admin access to **Adobe Cloud Manager** (`experience.adobe.com`)
* Admin access to **Adobe Developer Console** (`developer.adobe.com/console`)
* Admin access to **Adobe Admin Console** (`adminconsole.adobe.com`)
* Ability to push to the implementation repository's `main` branch and trigger Cloud Manager pipelines
* AEM 6.5 or AEM as a Cloud Service with the AEM Guides add-on installed and licensed
***
## Authentication
AEM Guides runs on top of AEM, so authentication follows the same model as your underlying AEM environment:
* **AEM 6.5 with AEM Guides**: Use OAuth 2.0 authentication — refer to the [AEM 6.5 setup guide](/docs/integrations-administration-and-setup/integrations/aem/aem-on-prem).
* **AEM Cloud with AEM Guides**: Use Adobe IMS authentication — refer to the [AEM Cloud setup guide](/docs/integrations-administration-and-setup/integrations/aem/aem-cloud).
***
## Authoring capabilities
With AEM Guides enabled, Gradial can work directly with your DITA topics, maps, and configured publishing profiles.
| Workflow | What Gradial can do |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Locate and copy a package** | Find a ditamap under an approved DAM path, then copy the map and its referenced assets to a destination folder. Literal filename and content replacements can be applied as part of the copy. |
| **Create and manage assets** | List compatible folder-profile templates, create DITA topics or maps, duplicate assets, rename them, or delete them after AEM Guides validates the change. |
| **Edit topics and maps** | Read and update DITA or DITAMAP XML, apply targeted text replacements, and add or remove map topic references. |
| **Coordinate editing** | Check an asset's lock state, then lock or unlock it before making a change. |
| **Replace topic images** | Upload a replacement image into the topic folder and update the corresponding DITA image reference. |
| **Configure and publish PDF output** | List available presets and templates, create or update Native PDF or DITA-OT PDF presets, and run the selected output preset. |
### Before you publish
* Grant Gradial read access to the Guides folders it needs to inspect and publish, plus create or edit access to every destination folder and asset it will modify.
* Review a copied package in AEM Guides before publishing: confirm the destination map, topics, referenced assets, and map references are the intended ones.
* Select a configured output preset by name. Native PDF is the default; DITA-OT publishing requires a folder profile that includes the required transformation.
***
## End-to-End Setup for Native PDF Publishing
### Phase 1 — Confirm AEM Guides is provisioned
1. In **Cloud Manager → Programs → your program → Solutions and Add-ons**, confirm "AEM Guides" appears.
2. If it doesn't appear, contact your Adobe Customer Success team — AEM Guides is a paid add-on with no self-serve provisioning path.
3. **Verify the publishing tenant exists.** When you fire a publish job, the output history entry's `cloudPublishJobId` field will be populated with a UUID (e.g., `bec82ef6-b151-44f2-9bcc-5db3b8b357d6`). If publishes get stuck in `outputStatus=Waiting` indefinitely, the tenant is not provisioned — open an Adobe Engineering ticket referencing your program ID.
***
### Phase 2 — Adobe Developer Console: OAuth credential
Adobe Developer Console is where you create the IMS service-account credential that AEM author uses to authenticate outbound calls to the publishing microservice.
**Use OAuth Server-to-Server, not JWT.** Adobe deprecated JWT credentials on June 30, 2025.
#### 2.1 Create or open the Developer Console project
1. Go to [https://developer.adobe.com/console](https://developer.adobe.com/console).
2. Confirm the org switcher (top-right) shows the same Adobe org that owns your AEMaaCS environment. If the org is wrong, every credential you create will fail with "different org" errors at runtime.
3. Open or create a project.
#### 2.2 Add APIs to the project
This is the step that causes the most failures. The APIs you add determine which scopes the credential's access tokens carry.
Add these APIs (Add API → search):
| API | Why it's needed |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **I/O Management API** | **Critical for Native PDF Publishing.** Grants `ent_adobeio_sdk` scope, which authorizes calls to `adobeioruntime.net`. Without it, publishing fails with `IMS credentials of different org are used` (Adobe's error message is misleading — the org is correct; the scope is missing). |
| **AEM Assets Author API** | General AEM author API access |
| **AEM CS Sites Content Management** | AEM Sites API access |
#### 2.3 Create the OAuth Server-to-Server credential
1. In the project, click **Add credential → OAuth Server-to-Server**.
2. Associate it with all the APIs added above.
3. Save. You'll receive `CLIENT_ID`, `CLIENT_SECRET`, `TECHNICAL_ACCOUNT_ID`, and scopes.
#### 2.4 Download the project JSON
1. Project overview → **Download** (top-right).
2. **Verify the scopes array contains `ent_adobeio_sdk`** before continuing. If it doesn't, the I/O Management API was not added correctly in step 2.2.
***
### Phase 3 — Cloud Manager: environment secret
1. Cloud Manager → Programs → your program → Environments → your env → **Configuration** tab.
2. Create environment variable **`SERVICE_ACCOUNT_DETAILS`** (type: Secret).
3. Value: paste the **complete contents** of the project JSON file from step 2.4 (the entire `{ "project": { ... } }` wrapper).
4. Save.
If migrating from a deprecated JWT setup, also delete the old `PRIVATE_KEY` variable if it exists.
***
### Phase 4 — Code repository: OSGi configs
Three config files live in `ui.config/src/main/content/jcr_root/apps//osgiconfig/config.author./`. Create the same three files under each environment directory (`dev`, `stage`, `prod`).
**`com.adobe.aem.guides.eventing.ImsConfiguratorService.cfg.json`**
```json theme={null}
{
"service.account.details": "$[secret:SERVICE_ACCOUNT_DETAILS]"
}
```
**`com.adobe.fmdita.publishworkflow.PublishWorkflowConfigurationService.cfg.json`**
```json theme={null}
{
"dxml.publish.microservice.url": "https://adobeioruntime.net/api/v1/web/543112-guidespublisher/default/publishercaller.json",
"dxml.use.publish.microservice": true,
"dxml.use.publish.microservice.native.pdf": true
}
```
**`com.adobe.fmdita.config.ConfigManager.cfg.json`** *(optional)*
```json theme={null}
{
"base.output.path": "/content/dam/fmdita-outputs",
"ignored.post.processing.paths": [
"/content/dam/projects/translation_output"
]
}
```
***
### Phase 5 — Deploy
Commit and push the OSGi config changes. Run a Cloud Manager pipeline to apply. If only the `SERVICE_ACCOUNT_DETAILS` secret was updated (no code changes), restart the AEM author tier via Cloud Manager → Environment → ⋮ → **Restart**.
***
### Phase 6 — AEM Author: templates and presets
#### Native PDF templates
The OOTB Native PDF templates ship with the AEM Guides module itself. Once Adobe enables AEM Guides on your program, three templates are already present in JCR at `/content/dam/dita-templates/pdf/`:
* `Basic`
* `Hi-Tech`
* `Prime`
If templates are missing, create a new one: AEM Author Web Editor → **Templates → Create new template → Native PDF**.
#### Output presets per ditamap
1. Open the ditamap in the Web Editor → **Map console → Output Presets**.
2. Click **+** to add a preset.
3. Configure: **Type: PDF**, **Target: Native PDF**, **Layout → Template**: pick your template.
4. Set the output path and PDF filename.
5. Click **Generate output** to test.
Watch out for stale global presets stored at `/var/dxml/folderprofiles/global-profile/presets/`. If a stale preset with an empty `templatePath` exists, every UI publish will silently use that stale config. Delete stale global presets via CRXDE Lite before relying on per-map presets.
***
## Verification
A successful Native PDF publish progresses through these states (poll `/var/dxml/metadata/outputHistory//.json`):
```
[0s] outputStatus=Waiting, cloudStatus=(none)
[5s] outputStatus=Executing, cloudStatus=Started
[15s] outputStatus=Executing, cloudStatus=Trigger-Successful ← auth working
[5–20m] outputStatus=Finished, cloudStatus=Finished ← rendering complete
```
**Reliable success signals:**
* `ditaotFaliure: false` (Adobe's typo) — this is the authoritative success flag
* `outputStatus: Finished` AND `cloudStatus: Finished`
* `outputPath` is populated
**Note:** `errorsExist: true` can appear even on a successful run (soft warnings about unresolvable hrefs). Do not use it as a failure signal.
***
## Troubleshooting
The Granite workflow engine accepted the job but the publish step is wedged. Most likely cause: the publishing tenant is not provisioned.
**Fix:** Open an Adobe Engineering ticket referencing the program ID and workflow ID, and ask them to confirm the Guides publishing tenant is registered.
Output shows `outputStatus=Finished, cloudStatus=Failed, ditaotFaliure=true`. Despite the error message, the org is almost certainly correct — the actual cause is the credential's access token is missing the `ent_adobeio_sdk` scope because the I/O Management API was not added to the Developer Console project.
**Fix:** Adobe Developer Console → project → **Add API → I/O Management API** → associate with the existing OAuth S2S credential → download the project JSON → paste into Cloud Manager `SERVICE_ACCOUNT_DETAILS` → run a pipeline or restart the author pod.
This is **normal** for Native PDF rendering on a large map. Adobe I/O Runtime has accepted the job and is rendering. For a map with 50+ topics and many images, 10–20 minutes is typical. If it goes beyond 30 minutes, contact Adobe.
The selected output preset has an empty `templatePath`. Usually caused by a stale global preset that referenced a deleted demo ditamap.
**Fix:** Delete the stale global preset at `/var/dxml/folderprofiles/global-profile/presets/` via CRXDE Lite. Create a fresh per-map preset and explicitly select a template.
***
## Support
Contact your Gradial onboarding lead or email [support@gradial.com](mailto:support@gradial.com) for help with setup.
# Working with AEM Launches
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/aem/aem-launches
How Gradial uses AEM Launches to stage content changes for review before publishing to production.
Whether you use Launch or Direct Edit, Gradial's agent authors content only — it does not publish pages unless publishing permissions are explicitly provided. Publishing is otherwise a separate, manual step performed by your team.
## What Are AEM Launches?
[AEM Launches](https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/sites/authoring/launches-for-pages/overview) let you prepare and review content changes without affecting your live site. When Gradial creates or modifies content using the **Launch** workflow type, it writes those changes into a staged launch copy rather than directly to production pages. Your team reviews the launch, then promotes it to the source pages when ready.
The workflow type (Launch vs. Direct Edit) is configured per AEM integration in **Settings → Integrations → AEM → General**. See [Advanced Configurations](/docs/integrations-administration-and-setup/integrations/aem/advanced-configurations) for details.
You can configure the workflow type separately for **Pages**, **Experience Fragments**, and **Content Fragments**:
***
## How Gradial Uses Launches
When the **Launch** workflow type is enabled, every Gradial task that modifies AEM content follows this sequence:
Gradial creates a new AEM Launch scoped to the pages being modified. The launch is a staged copy — your live pages are untouched.
Gradial's agents write all content changes into the launch copy.
Your team reviews the changes in Gradial. Tasks can be iterated at this stage without affecting production.
Once approved, promote the launch from Gradial — individually per task, or in bulk across multiple tasks at once. Gradial pushes the promoted content back to the AEM source pages.
Publish the updated source pages to make changes live.
***
## Promoting Launches
You can promote launches directly from Gradial without going into AEM.
**Promote individually** — open a completed task and promote its launch from the task detail view.
**Promote in bulk** — select multiple completed tasks and promote all of their launches at once. This is useful for coordinated campaign releases where several pages need to go live together.
***
## Nested Launches
If a launch already exists for a page (for example, a campaign branch being worked on by another team), Gradial can create a nested launch — a launch within a launch. This lets multiple workstreams stage changes against the same future content state without overwriting each other's work.
Nested launches are promoted in order: the inner launch must be promoted before the outer one.
***
## Managing Launch Conflicts
When you promote a launch, Gradial automatically checks whether the source page was modified between the time the launch was created and the time of promotion. If a change is detected, Gradial flags the conflict before applying anything — you won't silently overwrite someone else's edits.
You can then decide how to proceed: promote anyway, discard the launch, or coordinate with your team before retrying. No need to go into AEM to detect or investigate the conflict.
***
## Permissions Required
For Gradial to create and promote launches, the configured AEM user needs the following:
| Permission | Path |
| :--------------------------- | :-------------------------------------------- |
| Read, Modify, Create, Delete | `/content/launches` |
| Replicate | Source content paths (e.g. `/content/mysite`) |
You can verify launch permissions are correctly configured under **Settings → Integrations → AEM → Permissions → Launch Permission Test**.
***
## Related
* [Advanced Configurations](/docs/integrations-administration-and-setup/integrations/aem/advanced-configurations) — set the workflow type to Launch or Direct Edit
* [AEM Launches documentation](https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/sites/authoring/launches-for-pages/overview)
# AEM On Prem
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/aem/aem-on-prem
How to set up and configure Gradial with Adobe Experience Manager (AEM) 6.5 using OAuth authentication.
## Overview
## Authentication Methods
AEM 6.5 supports two primary authentication methods for external integrations:
**Recommended approach** offering fine-grained access control through custom OAuth scopes. Provides better security, audit trails, and permission management.
**Secondary option** using username/password credentials. Simpler to implement but less secure and granular than OAuth.
OAuth 2.0 is strongly recommended for production environments due to its superior security model, token-based authentication, and granular permission controls.
## Integration Steps
**What this step does:** Configures AEM to prioritize OAuth authentication over other authentication methods.
### Determine the OAuth Module Ranking
1. Navigate to `:/system/console/jaas`
2. You will see a list of registered LoginModules
3. Note the highest ranking number in the list - you'll need to set the OAuth ranking higher than this value
### Configure the OAuth Handler
1. Navigate to `:/system/console/configMgr`
2. Find "Adobe Granite OAuth Server Authentication Handler" in the list and click to edit
3. Ensure the values are as follows:
* **Path**: `/`
* **jaas.controlFlag**: `sufficient`
* **jaas.realmName**: `jackrabbit.oak`
* **jaas.ranking**: Set this to a value higher than the largest number in the LoginModules list (e.g., if the highest is 2001, use 2002 or higher)
* **Offline Validation**: `checked`
The `jaas.ranking` value must be higher than all other authentication handlers to ensure OAuth takes precedence.
**What this step does:** Configures the system user that AEM uses to manage OAuth token operations and scope validation.
**About the oauthservice User**
The `oauthservice` is a built-in system user provided by Adobe that AEM creates to handle OAuth token operations. This user requires elevated permissions to create and apply permissions for scoped requests.
### Access the Permissions Console
Navigate to `:/security/permissions.html/principal/oauthservice?filter=user`
### Add Required ACEs (Access Control Entries)
Configure the following permissions for the oauthservice user:
`Path: /`
* **Privileges:** `jcr:versionManagement`, `jcr:modifyAccessControl`, `jcr:lockManagement`, `jcr:readAccessControl`, `jcr:read`
`Path: /content`
* **Privileges:** `rep:write`
The oauthservice user must have elevated permissions above the authenticated OAuth token user, as it is responsible for creating and applying permissions for scoped requests.
These permissions are essential for OAuth functionality. Missing permissions will cause OAuth authorization failures.
**What this step does:** Creates the OAuth client configuration that Gradial will use to authenticate with AEM.
### Create the OAuth Client
1. Navigate to `:/libs/granite/oauth/content/clients.html`
2. Click "Create" in the top right corner
3. Enter the following values:
* **Name:** `Gradial`
* **Redirect URI:** `https://www.gradial.com/api/v1/auth/aem65/oauth2/callback`
4. Click "Save"
### Retrieve OAuth Credentials
1. Click into the newly created OAuth Client
2. Note the following values (you'll need to provide these to Gradial):
* **Client ID**
* **Client Secret**
3. Click "Download Private Key" and securely save the file
Keep the Client Secret and Private Key secure. These credentials provide access to your AEM instance and should be treated as sensitive security credentials.
You will need to provide the Client ID, Client Secret, and Private Key to your Gradial representative during the integration setup process.
**What this step does:** Deploys the OAuth scopes that define what permissions Gradial can request from AEM.
### Gradial OAuth Scopes Package
Gradial provides an easy, effective method for deploying and updating OAuth scopes without custom Java development.
**Installation Options:**
1. **GitHub Repository:** [https://github.com/gradial/gradial-65-oauth](https://github.com/gradial/gradial-65-oauth)
2. **Release Package:** [Download Release Installation](https://github.com/gradial/gradial-65-oauth/releases/download/v1.0.0/gradial-65.all-1.0.0.zip)
If you prefer not to use Gradial's package, you can deploy your own custom OAuth scopes as part of your AEM package install. See the GitHub repository for examples of OSGI configuration files.
### Scope Configuration
Each OAuth scope is defined by an OSGI configuration file stored in:
```
ui.config/src/main/content/jcr_root/apps/gradial-65/osgiconfig/config.author
```
You can deploy custom scopes by following the structure of the existing scope OSGI configuration files.
### Default Scopes
By default, Gradial installs a `read_all` scope that provides read access to all system paths required for operation:
* `/apps` - Component and application definitions
* `/libs` - System libraries
* `/etc` - Legacy configurations
* `/conf` - Context-aware configurations
* `/var` - Variable content (optional, required when workflow execution is needed)
We highly recommend keeping the `read_all` scope in place. You can further limit the paths Gradial can access during the onboarding process.
### Gradial OAuth Scope Definitions
The following table defines the standard OAuth scopes provided by Gradial:
| Scope Name | Resource Path | Privileges |
| :--------------- | :------------------------------ | :--------------------------------------------------------------------- |
| `launch_author` | `/content/launches` | `jcr:read`, `rep:write`, `jcr:lockManagement`, `jcr:versionManagement` |
| `publish_assets` | `/content/dam` | `jcr:read`, `jcr:addChildNodes`, `crx:replicate` |
| `read_all` | `/` | `jcr:read` |
| `site_author` | `/content` | `jcr:read`, `rep:write`, `jcr:lockManagement`, `jcr:versionManagement` |
| `site_xf_author` | `/content/experience-fragments` | `jcr:read`, `rep:write`, `jcr:lockManagement`, `jcr:versionManagement` |
| `tags_author` | `/content/cq:tags` | `jcr:read`, `rep:write`, `crx:replicate`, `jcr:versionManagement` |
| `upload_assets` | `/content/dam` | `jcr:read`, `rep:write`, `jcr:lockManagement`, `jcr:versionManagement` |
You must supply jcr:versionManagement for sites and DAM paths. Failure to do so will result in errors when creating and updating pages.
### Custom Scopes for Multi-Site Environments
If you need custom scopes for specific sites or permission boundaries, you can create additional scope configurations. For example:
* Site-specific author scopes: `/content/sitea`, `/content/siteb`
* Experience Fragment scopes: `/content/experience-fragments/sitea`
* Custom content paths: `/content/dam/myproject`
Each scope should align with your user permission structure and content architecture.
If using 3-legged authentication, ensure that authenticating user has JCR permissions matching the OAuth scopes you configure. OAuth authorization will fail if users lack the necessary permissions.
**What this step does:** Validates that your OAuth configuration is working correctly by testing scope authorization.
### Test OAuth Scopes
To test your OAuth configuration and scopes, open the OAuth consent URL in a browser:
```
http://:/oauth/authorize?response_type=code&client_id=CLIENT_ID&scope=SCOPE1 SCOPE2&redirect_uri=REDIRECT_URI
```
**Replace the placeholders:**
* `:` - Your AEM author instance URL
* `CLIENT_ID` - The Client ID from Step 3
* `SCOPE1 SCOPE2` - Space-separated list of scopes to test (e.g., `read_all site_author upload_assets`)
* `REDIRECT_URI` - The redirect URI configured in Step 3
### Expected Behavior
* You should see a consent dialog displaying each requested scope
* After authorizing, the browser should redirect to the redirect URI with an authorization code in the URL
* If the authenticating user lacks permissions for the requested scopes, no authorization code will be returned
Contact your Gradial representative if you need assistance with testing or completing the full OAuth flow to retrieve and use access tokens.
## Need Help?
Contact your Gradial representative for additional support with your AEM 6.5 integration.
# AEM Overview
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/aem/aem-overview
Connect Gradial to Adobe Experience Manager — guides for AEM 6.5 on-premises, AEM as a Cloud Service, AEM Assets, Edge Delivery Services, and AEM Guides.
## Connect Your AEM
Gradial connects with both on-premise AEM 6.5, AMS, Edge Delivery and AEM Cloud environments for both AEM Sites and AEM Assets, as well as AEM Guides.
For instructions on the setup and permissions required for credentials please select one of the options below.
Connect Gradial to Adobe Experience Manager 6.5 (on-premise or AMS) using OAuth 2.0 authentication
Connect Gradial to AMS or AEM Cloud Service using Adobe IMS authentication
Once you have your credentials package from your technology team, you can add the information to Gradial.
In the Gradial app, go to "Settings" and click "Integrations"
## AEM Guides
[AEM Guides](https://experienceleague.adobe.com/en/docs/experience-manager-guides) is Adobe's enterprise-grade component content management system (CCMS) built on AEM. It enables structured authoring using the DITA standard, supports multi-channel publishing, and provides robust version control and translation workflows for technical documentation teams.
Gradial's AI agents integrate with AEM Guides to automate content creation, updates, translation tasks, and quality assurance across your DITA-based content libraries. Authentication follows the same model as your underlying AEM environment — OAuth 2.0 for AEM 6.5 deployments, or Adobe IMS for AEM Cloud deployments.
Connect Gradial to AEM Guides for AI-powered authoring, updates, and QA across your DITA-based content libraries. Requires AEM 6.5 or AEM Cloud with the AEM Guides add-on installed and licensed.
## AEM Edge Delivery Services
[AEM Edge Delivery Services](https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/edge-delivery/overview) is Adobe's composable approach to building fast, high-impact web experiences. Edge Delivery decouples authoring from delivery, allowing content teams to author in familiar tools (Google Docs, Microsoft Word, or AEM) while serving pages from the edge for maximum performance.
Gradial's AI agents integrate with Edge Delivery Services environments to automate content creation, updates, and quality assurance across your Edge Delivery projects. Authentication uses Adobe IMS, the same as AEM as a Cloud Service — you will need a technical account scoped to your Edge Delivery project.
Connect Gradial to AEM Edge Delivery Services for AI-powered content automation on high-performance edge-delivered experiences. Requires an active AEM as a Cloud Service subscription with Edge Delivery Services enabled and a GitHub-backed Edge Delivery project.
## Need Help?
Contact your Customer Solutions Support team.
# Airship
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/airship
Connect Gradial to Airship to draft templates, send notifications, manage audiences, and orchestrate cross-channel campaigns.
Connect an Airship project once and Gradial can draft content templates, send notifications, manage audiences, and orchestrate scheduled sends across email, SMS, mobile push, web push, in-app, and Message Center — from a single flow.
***
## What You Can Do
Draft and update templates for any Airship channel: email, SMS, open channel, app (mobile push), web push, and Message Center. Preview rendered templates inline before sending.
Send notifications immediately or schedule for a future time. View, update, or cancel existing schedules. Target named users, channels, segments, static lists, or audience expressions.
Inspect and update named users and individual channels. Manage static lists and read existing segments. Look up which channels a user is reachable on before drafting a send.
View and manage Airship pipelines — event-triggered automations.
***
## Prerequisites
* Admin access to your Airship project to create credentials
* Your Airship project's regional API host (North America or Europe)
* A Gradial organization **Administrator** role to complete setup
***
## How to Connect
Airship supports three auth methods. Choose the one your security team prefers:
**OAuth Client Credentials (recommended)**
1. Sign in to Airship as a project admin and open **OAuth Clients** in your project settings.
2. Create a dedicated client for Gradial, scoped to the operations the team needs (content templates, schedules, audiences, sends).
3. Copy the **App Key**, **Client ID**, and **Client Secret**.
4. Note your region (NA or EU).
**App Key + Master Secret**
1. Open your Airship project's **Settings → APIs & Integrations**.
2. Copy the **App Key** and **Master Secret**.
The master secret has broad project access. Use this only when OAuth isn't available, and rotate the secret on a regular cadence.
**Base64 Credential Token**
If you already mint a Base64-encoded `appKey:masterSecret` token elsewhere in your tooling, paste it into the API-key-header dialog with the prefix `Basic`.
1. In Gradial, go to **Settings → Integrations**.
2. Find **Airship** and click **+ Add**.
3. Fill in the connection details:
| Field | Value |
| ------------------------- | ------------------------------------------------------------------ |
| **Integration Name** | A display name (e.g., `Acme Marketing — Production`) |
| **Airship API Base URL** | `https://go.urbanairship.com` (NA) or `https://go.airship.eu` (EU) |
| **Authentication Method** | OAuth Client Credentials, App Key + Master Secret, or Base64 Token |
| **Credentials** | From step 2 |
4. Click **Save**. Gradial validates the credentials and region before the integration goes live.
1. Go to **Settings → Environments** and select the Gradial Environment where Airship should be available.
2. Add the Airship integration to that Environment.
3. Repeat for any additional Environments.
***
## How It Fits Into Broader Workflows
| Use case | How to use it |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **Multi-channel campaign moment** | Draft email, push, and in-app templates side-by-side, preview inline, and schedule each channel's send for the same launch time |
| **Audience targeting** | Gradial discovers segments and audiences so the team can confirm targeting before sending — no juggling segment IDs by hand |
| **One-off notifications** | Find a named user or channel, draft the message, and send immediately or schedule |
| **Static list maintenance** | Look up a current static list, update membership, and confirm the change before the next scheduled send |
**Example — Author a multi-channel campaign:**
1. Ask Gradial to draft an email template for the campaign — subject, preheader, and body copy.
2. Have Gradial draft a matching mobile push template and a web push template.
3. Preview all three inline in the thread to QA the creative.
4. Schedule each send for the same launch time, targeting the right segment or static list.
5. Open the Airship artifact for each template to monitor in the Airship dashboard.
***
## Good to Know
* **Region awareness**: NA and EU Airship projects sit on different hostnames. The connection dialog auto-switches the API base URL when the region changes.
* **Sends never auto-retry**: writes (sending a notification, creating a schedule, mutating audiences) intentionally do not retry on failure. A failed send is reported back and stops — the agent never silently double-sends.
* **Inline previews are sanitized**: the preview proxy strips remote fonts, inline scripts, and unsafe CSS. It preserves inline data URIs and inline blobs so legitimate creative still previews correctly.
* **OAuth credential rotation**: when rotating Airship OAuth credentials, Gradial preserves project-level config across the rotation. The old cached token can serve requests until its natural expiry (up to \~60 minutes), so plan for that window for security-motivated rotations.
***
## Support
Contact your Gradial onboarding lead or email [support@gradial.com](mailto:support@gradial.com) for help with setup.
# Adobe Analytics
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/analytics/adobe-analytics
Connect Gradial to Adobe Analytics for enterprise-grade content intelligence, self-serve reporting, and performance-driven workflows.
Once connected, teams can build and run Adobe Analytics reports directly in the Gradial web app, and the same connection powers Gradial's workflow tooling for guided analysis and reporting in broader task flows.
This means Adobe Analytics is not limited to the Report Builder screen. Once connected, Gradial can use the same integration to discover reporting options, pull analytics data, and feed those results into downstream optimization and personalization work.
Before connecting, confirm with your legal, privacy, or data governance team that your organization has approval to share analytics data with Gradial. This includes ensuring the connection complies with any applicable data processing agreements, privacy policies, or regional data regulations.
***
## What You Can Do
Choose a report suite, date range, dimension, and metrics. Apply saved Adobe Analytics segments. Review results in chart and table views — directly in Gradial.
Use the Adobe Analytics connection inside Gradial workflows, not just the reporting screen. Pull segment-specific views, compare performance, and feed results into downstream decisions.
Bring Adobe Analytics performance data directly into CX Optimizer so insights inform what should happen next, instead of living in a separate reporting step.
Discover available report suites, valid dimensions and metrics for a selected suite, and saved segments for filtered analysis.
***
## Prerequisites
Before connecting Adobe Analytics to Gradial, make sure you have:
* An active **Adobe Experience Cloud** organization
* **System Admin** or **Developer** rights in your Adobe organization (required to set up the API integration)
* Access to **Adobe Developer Console** to create a project with OAuth Server-to-Server credentials
* Product profiles assigned that include the report suites, metrics, and dimensions you want Gradial to access
* Your **Global Company ID** for the Adobe Analytics company you want to query
* A Gradial organization **Administrator** role to complete setup
***
## How to Connect
1. Go to [Adobe Developer Console](https://developer.adobe.com/console/) and sign in for the correct Experience Cloud organization.
2. Create or open the project you want to use for this integration.
3. Click **Add API** and select **Adobe Analytics**.
4. Choose **OAuth Server-to-Server** as the credential type. Adobe requires OAuth Server-to-Server for all new server-to-server integrations.
5. Select the **Product Profiles** that include the report suites, metrics, and dimensions Gradial should be able to use.
6. Save the project. Copy the **Client ID** and **Client Secret** from the credential details screen.
The Global Company ID identifies the Adobe Analytics company Gradial will query. Adobe's Discovery API returns this value, and many Adobe teams already track it as part of their Analytics setup. Your Adobe administrator can provide it if you don't have it on hand.
1. In Gradial, go to **Settings → Integrations**.
2. Find **Adobe Analytics** and click **+ Add**.
3. Fill in the connection details:
| Field | Value |
| --------------------------- | ---------------------------------------------------------------------------------------------- |
| **Integration Name** | A display name (e.g., `My Adobe Analytics Connection`) |
| **Adobe Analytics API URL** | Pre-filled as `https://analytics.adobe.io` — leave as-is |
| **Client ID** | From your Adobe Developer Console project |
| **Client Secret** | From your Adobe Developer Console project |
| **Token URL** | Use Adobe's standard token URL unless your Adobe team has specified a different approved value |
| **Scope** | Use Adobe's standard Analytics scope unless otherwise directed |
| **Global Company ID** | Your Adobe Analytics Global Company ID from Step 2 |
4. Click **Save**.
Once setup is complete, Gradial automatically applies the Global Company ID for all report requests — teams do not need to re-enter account identifiers when running reports.
1. Go to **Settings → Environments** and select the Environment where analytics data should be available.
2. Add the Adobe Analytics integration to that Environment.
3. Repeat for any additional Environments.
***
## How It Fits Into Broader Workflows
| Use case | How to use it |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Fast self-serve reporting** | Use Report Builder when a PM or marketer wants a quick view of campaign, page, or segment performance without leaving Gradial |
| **Analytical workflow steps** | Use Gradial's workflow tooling when analytics needs to become part of a larger flow — comparing performance, drafting the next audience, or preparing a personalization decision |
| **CX Optimization** | Bring Adobe Analytics directly into CX Optimizer so performance data informs what should happen next |
| **Team alignment** | Give PM, marketing, and delivery teams a common starting point for optimization work without sending people back into separate analytics tools |
**Example flow:**
1. Pull a report for a campaign, journey, product area, or audience.
2. Compare performance across a dimension (page, channel, or segment).
3. Identify the strongest opportunity or biggest drop-off.
4. Use Gradial's workflow tooling to pull follow-up reporting or segment-specific views.
5. Feed that insight into CX Optimizer or a personalization flow.
6. Launch the next test, audience, or experience with much less back-and-forth.
***
## Troubleshooting
**"Invalid client" error when saving**
Double-check that the Client ID and Client Secret are copied exactly from Adobe Developer Console with no leading or trailing spaces.
**No report suites available**
Confirm the Product Profile linked to your Developer Console credential includes the correct report suites, and that Metrics and Dimensions access is enabled in Adobe Admin Console.
**Global Company ID not recognized**
The Global Company ID is a short alphanumeric string for your Adobe Analytics company. It is not the same as your IMS Organization ID (which ends in `@AdobeOrg`). Use Adobe's Discovery API or ask your Adobe administrator to retrieve it.
**Integration not available in a Workspace**
Assign the integration to the correct Environment under **Settings → Environments**.
***
## Support
Contact your Gradial onboarding lead or email [support@gradial.com](mailto:support@gradial.com) for help with setup or Report Suite configuration.
# Google Analytics
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/analytics/google-analytics
Connect Gradial to Google Analytics to surface content performance data directly inside your workflows.
Connecting Google Analytics to Gradial gives your agents access to real-time and historical performance data — page views, sessions, bounce rates, conversions — so they can make content decisions grounded in how your audience actually behaves.
Before connecting, confirm with your legal, privacy, or data governance team that your organization has approval to share analytics data with Gradial. This includes ensuring the connection complies with any applicable data processing agreements, privacy policies, or regional data regulations.
***
## What You Can Do
| Capability | Description |
| -------------------------- | ---------------------------------------------------------------------------- |
| Performance-informed edits | Surface underperforming pages and trigger content update tasks automatically |
| Traffic data in context | Reference GA metrics when drafting or updating content |
| Optimization workflows | Route low-performing URLs into content review queues |
| Audience signals | Use GA audience and behavior data to guide personalization decisions |
***
## Prerequisites
Before connecting Google Analytics to Gradial, make sure you have:
* A **Google Analytics 4 (GA4)** property (Universal Analytics is not supported)
* A **Google Cloud project** with the **Google Analytics Data API** enabled
* A **service account** with Viewer-level access to the GA4 property, and a JSON key generated for it
* A Gradial organization **Administrator** role to complete setup
***
## How to Connect
In your Google Cloud project, go to **APIs & Services → Library**, search for **Google Analytics Data API**, and enable it.
1. In your Google Cloud project, go to **IAM & Admin → Service Accounts** and click **Create Service Account**.
2. Give it a descriptive name (e.g., `gradial-analytics`).
3. Under **Keys**, select **Add Key → Create new key (JSON)**. Download the JSON file and keep it open — you will paste its contents into Gradial in Step 4.
1. In [Google Analytics](https://analytics.google.com/), open **Admin** for the property you want to connect.
2. Under **Property Access Management**, add the service account email with the **Viewer** role.
1. In Gradial, go to **Settings → Integrations**.
2. Find **Google Analytics** and click **+ Add**.
3. Enter an **Integration Name** (e.g., `My Google Analytics Connection`).
4. The **Google Analytics API URL** is pre-filled as `https://analyticsdata.googleapis.com` — leave this as-is.
5. Under **Authentication Type**, **OAuth 2.0 JWT Bearer** is selected by default.
6. In the **Service Account JSON Key** field, paste the full contents of the JSON key file downloaded in Step 2.
7. The **Scopes** field defaults to `https://www.googleapis.com/auth/analytics.readonly` and **Token Endpoint** defaults to `https://oauth2.googleapis.com/token` — leave both as-is unless directed otherwise.
8. Optionally, enter a **Default GA4 Property ID**. This is the numeric Property ID from **Google Analytics → Admin → Property Settings**. When provided, Gradial uses it automatically when no property is specified in a prompt.
9. Click **Validate Connection** to confirm the credentials work, then click **Validate & Save**.
1. Go to **Settings → Environments** and select the Environment where analytics data should be available.
2. Add the Google Analytics integration to that Environment.
3. Repeat for any additional Environments.
***
## Field Reference
| Field | Description |
| ---------------------------- | -------------------------------------------------------------------------------------- |
| **Integration Name** | A display name for this connection in Gradial (e.g., `My Google Analytics Connection`) |
| **Google Analytics API URL** | Pre-filled as `https://analyticsdata.googleapis.com` — do not change |
| **Authentication Type** | Fixed to **OAuth 2.0 JWT Bearer** |
| **Service Account JSON Key** | Paste the full JSON key content from Google Cloud |
| **Scopes** | Defaults to `https://www.googleapis.com/auth/analytics.readonly` |
| **Token Endpoint** | Defaults to `https://oauth2.googleapis.com/token` (from the JSON key's `token_uri`) |
| **Default GA4 Property ID** | Optional. The numeric GA4 Property ID used when no property is specified in a prompt |
***
## Troubleshooting
**Validation fails with "Permission denied"**
Confirm the service account has been added as a Viewer in **Google Analytics → Admin → Property Access Management** and that the Analytics Data API is enabled in your Cloud project.
**GA4 Property ID not found**
Your Property ID is a numeric string found under **Admin → Property Settings → Property ID**. It is not the same as the Measurement ID (which starts with `G-`).
**Integration not available in a Workspace**
Assign the integration to the correct Environment under **Settings → Environments**.
***
## Support
Contact your Gradial onboarding lead or email [support@gradial.com](mailto:support@gradial.com) for help with setup.
# Google Search Console
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/analytics/google-search-console
Connect Search Console so Gradial can read how your pages actually perform in organic search — and turn queries, impressions and position data into content changes it can execute.
## Why connect Search Console
Search Console holds the one dataset that says what people actually typed to find you, and which of your pages Google decided to show them. It is the most direct signal available about the gap between what your content says and what your market is looking for.
It is also, for most teams, a report someone opens quarterly. The data says a page ranks in position 14 for a query with real volume, or that impressions on a section have been declining for two months, or that a query you should own returns a page that doesn't answer it — and then the finding sits in a slide, because acting on it means briefing, writing, reviewing and publishing a change.
Connecting Search Console puts that data next to the thing that can act on it.
***
## What Grady can do
| Capability | Detail |
| :-------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
| Query organic performance | Clicks, impressions, click-through rate and average position, by query, page, country and device |
| Compare over time | Period-over-period movement, to separate a real decline from normal variance |
| Surface recommendation candidates | Pages and queries where the data suggests a specific content change is worth making |
| Feed the work | Findings become content updates Gradial can execute — new or rewritten copy, metadata, internal links — through your normal review path |
This connection is **read-only** against Search Console. Gradial reads performance data; it does not submit sitemaps, request indexing, or change any Search Console setting.
***
## Prerequisites
* A Search Console property for each site you want Gradial to read
* At least **Restricted** access to that property for the account authorizing the connection
* Permission in your organization to connect a Google account to Gradial
***
## Set up the connection
Note whether each property is a **domain** property (shown as `sc-domain:example.com`) or a **URL-prefix** property (shown as `https://www.example.com/`). Both are supported, and the distinction matters: a domain property covers every subdomain and protocol, a URL-prefix property covers only what its prefix matches.
Go to **Settings → Integrations**, find **Google Search Console** under Analytics, and select **Connect**. Authorize with a Google account that has access to the properties you want to read.
Choose which Search Console properties this connection covers. You can select more than one — a multi-brand or multi-region estate usually wants several.
Only the selected properties are readable. Adding a property later is a change to this integration, not a new connection.
Ask Grady for a summary of organic performance over the last 28 days. If the numbers match what you see in Search Console, the connection is working.
***
## Using it
Search Console data is most useful when the question is specific. Some starting points:
```
Which pages have lost the most organic clicks in the last 90 days
compared to the previous 90? Show me query-level detail for the worst five.
```
```
Find queries where we rank between positions 8 and 20 with over 500
monthly impressions, and the landing page doesn't directly answer the query.
For each, tell me what the page is missing.
```
```
Write meta titles and descriptions for every page in /resources/ that is
missing one, using the top query for that page as the signal.
```
```
Which pages get impressions for queries we shouldn't be ranking for?
That usually means the content is ambiguous about who it's for.
```
The last step in each case is the useful one: Gradial can execute the change it recommends, in your CMS, through your existing review and approval path.
Search Console covers traditional organic search. For how your brand appears in AI answer engines — a different dataset and a different set of fixes — see [Generative Engine Optimization (GEO)](/docs/insights/geo) and [GEO Monitoring](/docs/insights/geo-monitoring). Teams increasingly need both.
***
## Who this is for
| Role | What this unlocks |
| :---------------------------- | :---------------------------------------------------------------------------------------- |
| **SEO Lead / Organic Growth** | Findings that get executed rather than filed, without writing every brief yourself |
| **Content Strategist** | Query data shaping what gets written, and evidence for what should be retired or merged |
| **Content Marketer** | Knowing which existing pages are close to ranking and worth a rewrite |
| **Marketing Leadership** | Organic performance summarized on demand, and tied to the content changes made against it |
| **Web Producer** | Metadata and structural gaps identified in bulk instead of page by page |
***
## Availability
**Access:** Must be enabled for your organization. Contact your Gradial team to get access.
# Aprimo
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/aprimo
Connect Aprimo so Grady can file the assets and documents it produces directly into your DAM — as draft records, in the classification you nominate, ready for a librarian to review.
## Why connect Aprimo
Gradial produces real files. A generated hero image, a smart-cropped variant, a campaign brief, a copy doc, a QA report — all of it comes out of the work as an artifact. Without a DAM connection, getting those files into Aprimo is a download, a re-upload, and a metadata form filled in by hand, which is exactly the manual step the rest of the workflow removed.
Connecting Aprimo closes that gap. Grady uploads what it creates straight into your DAM, in the classification you specify, and confirms the record landed.
This integration is an **upload destination**. Grady files assets into Aprimo and verifies the resulting records — it does not read your existing Aprimo library or search it. For search and retrieval across your asset estate, see [Asset Search](/docs/asset-management/asset-search).
***
## What Grady can do
| Capability | Detail |
| :-------------------------- | :----------------------------------------------------------------------------------- |
| Upload assets and artifacts | Files Gradial created — images, documents, reports — into the configured destination |
| Create records | Each upload becomes an Aprimo record in the classification you nominate |
| Verify the result | Grady confirms the record exists and reports its identifier back into the task |
Records are always created with a **draft** status, so nothing Grady files enters an approved state without a person reviewing it.
***
## Prerequisites
* An Aprimo tenant and the subdomain used to reach it (the part before `.aprimo.com`)
* A **registered client** in Aprimo with a client ID and client secret
* The **classification ID** of the destination you want Grady to file into
* An Aprimo administrator to grant the client permission to create records in that classification
***
## Set up the connection
In Aprimo, create an API client for Gradial and record its **client ID** and **client secret**. Grant it permission to create records in the classification you intend to use as the destination.
Open the destination classification in Aprimo and copy its ID. Gradial accepts either the 32-character form or the hyphenated UUID form.
Go to **Settings → Integrations**, find **Aprimo** under Design & assets, and select **Connect**. Provide:
| Field | Value |
| :--------------------- | :--------------------------------------------------------------------------------------------------- |
| **Tenant** | Your Aprimo subdomain — the part before `.aprimo.com` |
| **Client ID** | From the client you registered |
| **Client secret** | From the client you registered |
| **Classification ID** | The destination classification Grady files into |
| **Allowed file types** | The MIME types Grady may upload, in `type/subtype` form (for example `image/png`, `application/pdf`) |
| **Maximum file size** | The upload ceiling for this connection, up to 250 MiB |
Save the connection. Gradial validates the credentials against your tenant and reports the result immediately. If validation fails, the message names the field at fault.
Keep the allowed file types deliberately narrow. The list is an allowlist, so anything not named is rejected before an upload is attempted — which is the cheapest place to catch a misdirected file.
***
## Rotating credentials
To rotate the client secret, reopen the Aprimo integration in **Settings → Integrations** and enter the new secret. Gradial re-validates on save. The client ID and tenant can be changed in the same step; changing either requires the secret to be re-entered.
***
## Who this is for
| Role | What this unlocks |
| :-------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------- |
| **DAM Librarian / Asset Manager** | Gradial's output arriving in the DAM as draft records in the right classification, instead of as files in someone's downloads folder |
| **Campaign Manager** | Generated and adapted assets filed as part of the campaign, not as a follow-up task |
| **Brand Manager** | A review step preserved by design — everything Grady files is a draft |
| **Creative / Agency** | Deliverables and their variants landing in the system of record automatically |
***
## Availability
**Access:** Must be enabled for your organization. Contact your Gradial team to get access.
# Box
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/box
Connect Box so Grady can search, read, download, file, and clean up documents — scoped to exactly the folders a Box admin shares with it, with deletions gated behind human approval.
## Overview
The Box integration lets Grady work in your Box content: browsing folders, reading file metadata, searching across file content, pulling files into a working session, filing new documents, creating folders, and removing files you no longer need.
Access works the way Box access already works for people. Gradial connects as a dedicated Box **service account**, and that account sees nothing until a Box admin invites it as a collaborator on a folder. Its reach is exactly the folders it's been invited to — enforced by Box itself.
**Access:** Must be enabled for your organization. Contact your Gradial team to get access.
### Why use Gradial with Box
* **Grady finds things by meaning** — full-text search across file content, not just names
* **Documents become inputs** — read a contract, compare two PDFs, extract data from a deck
* **Box becomes a destination** — generated documents get filed into the right folder
* **Folders get organized** — ask Grady to create folders and structure files as your team works
* **Outdated content gets cleaned up** — remove files you no longer need, with human approval required before anything is deleted
* **Access stays in Box's hands** — you grant and revoke Grady's reach with the same collaborator controls you already use, no separate permission model to maintain
***
## What Grady can do
| Capability | What it means |
| ------------------- | ------------------------------------------------------------------------------ |
| **Identify itself** | Report the service account login a Box admin needs to invite as a collaborator |
| **Browse** | Page through a folder's files and subfolders |
| **Read metadata** | File name, size, checksum, parent folder, and timestamps |
| **Search** | Full-text search over file names and content, optionally scoped to a subtree |
| **Download** | Pull a file into the working session to read, parse, compare, or migrate |
| **Upload** | File a document from the working session into a Box folder |
| **Create folders** | Add a folder inside a folder it can write to |
| **Delete** | Remove a file it can reach — always behind an explicit human approval step |
### Deletions require approval
Grady can remove outdated files from Box, but never on its own initiative and never silently. Every deletion pauses for an explicit human approval before it proceeds: Grady tells you what it intends to delete, and nothing is removed until a person approves it.
The same folder boundaries apply as everywhere else — Grady can only delete inside folders the service account has been collaborated on, at a permission level that allows it. Narrowing the service account's collaborator role on a folder narrows what can be deleted there.
Deletion through Grady is subject to Box's own recovery behavior — deleted items go to the Box trash under your enterprise's retention settings rather than disappearing permanently. Treat approval as the real safeguard, and keep the service account's collaborator roles as narrow as the work allows.
### What Grady can never do
Moving, copying, sharing, shared-link creation, and collaboration changes do not exist in the integration — not as blocked actions, but as operations with no implementation. There is no way to phrase a request that relocates or externally shares a Box file through Grady.
Uploads and folder creation also never overwrite. If something with the same name already exists, the operation fails rather than replacing what's there.
***
## How access works
This is the most important thing to understand about the Box integration, and the step teams most often miss.
The connection uses a Box Platform App, which acts as its own Box user — not as the person who set it up. That account has a login like `AutomationUser_…@boxdevedition.com`.
Freshly connected, it can see no files and no folders. It is not an admin account and it does not inherit anyone's access.
To give Grady access to a folder, a Box admin invites the service account to that folder as a collaborator — exactly as they would invite a colleague. Grady's reach is then that folder and everything beneath it.
Because Box enforces this boundary itself, Grady's access is always visible and auditable where your team already looks: the folder's collaborator list in Box. Removing the collaborator revokes Grady's access immediately.
Content the service account isn't collaborated on is reported by Box as simply not existing — so Grady can't confirm or deny whether a file is there, let alone read it.
***
## Before you start
You'll need two people (or one person with both roles):
* **A Gradial organization admin** — connecting an integration requires the Manage settings permission in Gradial
* **A Box administrator** — authorizing the Platform App happens in the Box Admin Console and is protected by two-factor authentication
And from Box, three values:
* **Client ID**
* **Client Secret**
* **Enterprise ID**
The Box Platform App must be authorized in the **Box Admin Console** with the **Read and write all files and folders** application scope before the connection will work. Authorizing the app does not by itself give Grady access to any content — collaboration invites still control that.
***
## Connect Box
A Box admin creates a Box Platform App using client-credentials (server) authentication, then authorizes it in the Box Admin Console with the **Read and write all files and folders** scope. Collect the app's **Client ID**, **Client Secret**, and your **Enterprise ID**.
In Gradial, go to **Settings → Integrations → Connect Integration → Box**, then paste the **Client ID**, **Client Secret**, and **Enterprise ID**.
Gradial verifies the credentials against Box before saving anything. If they're wrong, or the app hasn't been authorized in the Admin Console, the connection is rejected at this point rather than failing silently later.
Once connected, the Box integration row shows the **Service account** login. This is the Box user your admin needs to invite as a collaborator. Copy it.
You can also ask Grady for it at any time — it will report the connected service account's identity.
In Box, for each folder you want Grady to work in:
1. Open the folder and invite a collaborator
2. Paste the service account login
3. Choose a permission level — **Viewer** for read-only work; **Editor** (or another level with upload rights) if Grady should file documents or clean up outdated files there
4. Send the invite
Grady's access begins at the folders you invite it to and extends to everything beneath them. Start with the narrowest folders that cover the work.
Go to **Settings → Environments**, select the Environment you want Box available in, and add the Box integration to it. This makes it available to all Workspaces in that Environment. Repeat for any other Environments that need it.
If a Workspace isn't seeing Box, check this first — an unassigned integration is the most common cause.
### Rotating credentials
Box credentials are rotated by connecting Box again from the integration catalog. Gradial verifies the new credentials and swaps them in a single step, so there's no window where the connection is half-updated. There is no separate edit form — this is deliberate, because it guarantees new credentials are always verified before they take effect.
### Changing what Grady can reach
Add or remove collaborator invites in Box. Nothing needs to change in Gradial — the next thing Grady does reflects the current collaboration state.
***
## Limits
* **Uploads are capped at 50 MB per file.** This is a Box API limit on single-request uploads. Larger files aren't yet supported.
* **Downloads are not artificially capped** — they're bounded only by Box's own per-file maximum.
* **Nothing is overwritten.** A name collision fails; Grady will report it rather than replacing the existing item.
* **Search results can lag.** Box search is eventually consistent, so a document uploaded moments ago may not appear in search yet. Browsing the folder shows it immediately.
***
## Troubleshooting
| What you see | What it means |
| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Grady says an item can't be found** | Almost always "not collaborated." Box reports content the service account can't reach as nonexistent. Invite the service account to the folder in Box. |
| **Grady can read but not upload** | The service account's collaborator role on that folder is read-only. Raise it to a role with upload rights. |
| **A deletion never happened** | Deletions wait on human approval. Check whether the approval step is still pending — nothing is removed until someone approves it. |
| **Grady can't delete a file it can see** | The service account's collaborator role on that folder doesn't permit deletion. Raise it, or delete the file in Box directly. |
| **A just-uploaded file isn't in search results** | Box search indexing lag. Browse the folder instead — the file is there. |
| **An upload fails on the name** | Something with that name already exists. Grady never overwrites; choose a different name or work with the existing file. |
| **Box is throttling requests** | Box rate-limits heavy activity. Grady waits and retries as Box directs. |
| **The connection is reported as broken** | The service-account credentials are no longer valid — for example the Platform App's authorization was revoked in the Box Admin Console. A Gradial admin reconnects Box from **Settings → Integrations**. |
| **A Workspace can't use Box** | The integration isn't assigned to that Workspace's Environment. |
***
## Example prompts
```
Find every PDF in our Box product-launch folder that mentions the old tagline.
```
```
Compare the two contract PDFs in Box under Legal/Vendor Agreements and tell me
what changed.
```
```
Write the Atlas launch summary as a Word document and upload it to our Box
launch folder.
```
```
Pull the approved hero images out of Box and upload them to your CMS.
```
```
Create a folder structure under Box Marketing/2026 Campaigns with one subfolder
per quarter, and file the existing briefs into the right ones.
```
```
Find the superseded drafts in our Box launch folder and delete them — show me
the list before anything is removed.
```
***
## Related
* [SharePoint →](/docs/integrations-administration-and-setup/integrations/sharepoint) — the same document workflows, with a folder allow-list access model
* [Office Docs →](/docs/campaign-management/office-docs) — how Gradial creates and works with Word, Excel, and PowerPoint files
* [Digital Asset Management →](/docs/asset-management/digital-asset-management)
* [Integrations Overview →](/docs/integrations-administration-and-setup/integrations/get-started-with-integrations)
# Braze
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/braze
How to set up and configure Gradial with Braze for audience analysis, campaign management, content operations, and controlled sends.
## Overview
[Braze](https://www.braze.com) is a customer engagement platform used by enterprise brands to orchestrate personalized, cross-channel communications across email, SMS, push notifications, WhatsApp, and more. Marketing and CRM teams use Braze to build audience segments, design lifecycle journeys in Canvas, manage campaign sends, and deliver real-time personalization at scale.
### Why use Gradial with Braze?
Braze is powerful, but activating it at speed — especially across large content programs — requires coordinating audience logic, creative content, send schedules, and performance analysis in ways that are time-consuming to do manually.
Gradial adds an AI agent layer on top of Braze so your team can:
* **Discover and size audiences in plain language** — ask questions about existing segments, inspect membership trends, and get targeting blueprints without writing queries
* **Manage email templates and content blocks at scale** — generate, update, and review reusable content without navigating the dashboard for each change
* **Orchestrate sends and schedules from chat** — trigger API-triggered campaigns and Canvases, review dry-run previews, and confirm live sends from a single conversation
* **Analyze campaign and Canvas performance on demand** — pull analytics data series and summaries directly into your workflow
## Prerequisites
Before a workspace can use Braze in Gradial:
* The Braze integration must be enabled for your workspace (contact your Gradial representative)
* Only an org admin can add a Braze integration in **Settings → Integrations**
* Your Braze REST API key must have sufficient permissions for the workflows you plan to run
## Setup
If your Braze instance restricts API access by IP, you will need to allowlist Gradial's egress IP addresses before connecting. See [IP Allowlisting](/docs/integrations-administration-and-setup/ip-allowlist) for the full list.
### Step 1: Generate a Braze REST API Key
1. Log in to your Braze dashboard
2. Navigate to **Settings** → **API Keys**
3. Click **Create New API Key**
4. Give the key a descriptive name (e.g., `Gradial Integration`)
5. Enable the following permissions at minimum:
| Permission | Required | Purpose |
| :---------------------------------- | :------- | :------------------------------------- |
| `segments.list` | Yes | Required for connection validation |
| `segments.data_series` | Yes | Segment analytics and trend data |
| `segments.details` | Yes | Read segment metadata |
| `users.export.segment` | Optional | Export users from a saved segment |
| `users.export.ids` | Optional | Export users by identifier |
| `users.track` | Yes | Required for connection validation |
| `campaigns.list` | Optional | List campaigns |
| `campaigns.details` | Optional | Read campaign metadata and analytics |
| `campaigns.trigger.send` | Optional | API-triggered campaign sends |
| `campaigns.trigger.schedule.create` | Optional | Schedule campaign triggers |
| `campaigns.trigger.schedule.update` | Optional | Update campaign trigger schedules |
| `campaigns.trigger.schedule.delete` | Optional | Delete campaign trigger schedules |
| `canvas.list` | Optional | List Canvases |
| `canvas.details` | Optional | Read Canvas metadata and analytics |
| `canvas.trigger.send` | Optional | API-triggered Canvas sends |
| `canvas.trigger.schedule.create` | Optional | Schedule Canvas triggers |
| `templates.email.list` | Optional | List email templates |
| `templates.email.info` | Optional | Read email template details |
| `templates.email.create` | Optional | Create email templates |
| `templates.email.update` | Optional | Update email templates |
| `content_blocks.list` | Optional | List content blocks |
| `content_blocks.info` | Optional | Read content block details |
| `content_blocks.create` | Optional | Create content blocks |
| `content_blocks.update` | Optional | Update content blocks |
| `subscription.status.get` | Optional | Read subscription group status |
| `catalogs.get_items` | Optional | Read catalog items for personalization |
6. Click **Save API Key** and copy the key value
> **Important:** Keep your API key secure. Treat it as a sensitive credential. You can revoke and regenerate it from the Braze API Keys settings page at any time.
### Step 2: Configure the Integration in Gradial
1. In Gradial, navigate to **Settings** → **Integrations**
2. Click **Add Braze Integration**
3. Fill in the connection form:
| Field | Required | Value |
| :--------------- | :------- | :--------------------------------------------------------------- |
| Integration Name | Yes | A label for this connection (e.g., `Production Braze`) |
| Braze REST Host | Yes | Your Braze REST endpoint (e.g., `https://rest.iad-01.braze.com`) |
| Auth Type | Yes | `apiKeyHeader` |
| API Key | Yes | The key generated in Step 2 |
| Header Name | Yes | `Authorization` (default) |
| Prefix | Yes | `Bearer` (default) |
4. Click **Save**
> **Note:** Gradial normalizes the Braze REST host and trims any trailing slash. Header Name and Prefix default to `Authorization` and `Bearer` if left blank.
## Testing the Integration
After saving, Gradial validates the connection by:
1. Calling `POST /users/track` with an empty payload to verify auth and general API access
2. Calling `GET /segments/list` to confirm segment read access
Both checks must pass for the integration to show a **Connected** status.
### Common Issues
| Issue | Cause | Solution |
| :----------------------------------- | :--------------------------------------- | :------------------------------------------------------------------------------- |
| Validation fails after auth succeeds | API key lacks `segments/list` permission | Add `segments.list` permission to the key |
| `unauthorized` error | Incorrect API key | Verify the key value in Braze API Keys settings |
| Wrong REST host | Incorrect Braze cluster | Check your Braze instance URL — the cluster is in the subdomain (e.g., `iad-01`) |
### Rotating Credentials
Braze credentials can be updated without rebuilding the connection. Updating the API key preserves the existing host, header settings, and all other connection configuration.
## What Users Can Do in Gradial with Braze
Once set up, the Braze agent is available in chat. Users can ask for audience analysis, campaign reads, content operations, and controlled sends — the agent routes these requests through the Braze toolset.
List and inspect existing segments, read segment trend data, discover audience field names and event names from segment metadata, export users from a saved segment or by identifier, read KPI series (new users, DAU, MAU, uninstalls), and generate a connected-audience blueprint for ad hoc targeting logic.
**Example prompts:**
* `What Braze segments do we already have for loyalty members?`
* `How large is our cart abandoner audience?`
* `List the events we can use for a checkout re-engagement audience.`
* `Build the targeting logic for members who abandoned cart in the last 7 days.`
**Limitation:** Saved segment creation, update, and archive are not supported. When a requested audience does not already exist as a saved segment, the agent produces an API-ready targeting blueprint, but the final saved segment must be created in the Braze dashboard.
List campaigns, read campaign details and analytics, send messages directly, trigger existing API-triggered campaigns, and create, update, or delete trigger schedules.
Send and schedule actions default to **dry-run preview** behavior. Live execution requires explicit confirmation.
**Example prompts:**
* `Show me the analytics for our re-engagement campaign over the last 14 days.`
* `Prepare a dry run for an API-triggered campaign to our VIP segment.`
* `Schedule our win-back campaign to send tomorrow at 9 AM local time.`
**Limitation:** Campaign authoring is not supported. Use the Braze dashboard for creating and editing campaigns; use Gradial for reads, previews, sends, and scheduling.
List Canvases, read Canvas details and analytics, trigger existing Canvases, and create, update, or delete Canvas trigger schedules.
Trigger sends and schedule mutations default to **dry run**. Live execution requires explicit confirmation.
**Example prompts:**
* `List our active Braze Canvases.`
* `Summarize Canvas performance for our onboarding journey.`
* `Prepare a dry run to trigger our win-back Canvas for a test audience.`
**Limitation:** Canvas flow authoring (step design, branching, persistent journey editing) still happens in the Braze dashboard.
List, read, create, and update email templates and content blocks.
The content tool supports dry-run previews for create and update actions. Content block names must contain only letters, numbers, dashes, and underscores.
**Example prompts:**
* `List our Braze email templates updated this month.`
* `Create a content block for our spring loyalty sale.`
* `Update our welcome email template with a shorter subject line.`
**Limitation:** Template and content-block create endpoints do not support idempotency keys, so a retried create action can produce duplicates.
List items in a Braze catalog and read specific catalog items. This is read-only and intended for retail personalization workflows where the agent needs to inspect catalog data before generating or validating message content.
**Example prompts:**
* `List items in the loyalty_rewards catalog.`
* `Show me the details for a specific catalog item.`
**Limitation:** Catalog creation, update, and deletion are not available through the agent toolset.
Read subscription status for a subscription group and read a user's subscription status across groups. Useful for consent validation, channel governance checks, and verifying subscription state before activation.
**Limitation:** Subscription-state mutation is not exposed through the chat toolset.
## What Still Happens in Braze
The following operations are intentionally out of scope for the current Gradial Braze integration and must be performed in the Braze dashboard:
| Not supported in Gradial | Workaround |
| :------------------------------------ | :--------------------------------------------------------------------------- |
| Saved segment create, update, archive | Build the criteria in Gradial, then save the segment in the Braze dashboard |
| Full campaign authoring | Author in Braze, then use Gradial for reads, previews, sends, and scheduling |
| Canvas step and branch authoring | Design in Braze, then use Gradial for reads and trigger operations |
| Catalog mutation | Manage catalog structure and items in the Braze dashboard |
| User deletion | Not available through agent tools |
| Subscription mutation | Manage in the Braze dashboard |
## Need Help?
Contact your Gradial representative for additional support with your Braze integration.
# Bynder
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/bynder
Connect Gradial to Bynder for digital asset management — search, curate, tag, and upload assets from a single flow.
Connect Bynder once and Gradial can work across assets, collections, metaproperties, tags, automations, and uploads without leaving your workflow.
***
## What You Can Do
List and keyword search assets. Filter by Bynder property queries (e.g. `property_Status: Approved`). Run text-based similarity search to find lookalike assets across the portal.
Read asset stats and versions. Update name, description, tags, and metaproperty values. Add or remove metaproperty options. Fetch download locations and request dynamic transformations.
List, create, read, update, and share collections by email. Add or remove assets from a collection. Manage collection media.
Prepare multi-chunk uploads, push base64-encoded chunks with SHA-256 verification, and finalize uploads to land new assets in Bynder.
List, create, read, update, and delete metaproperties. Manage options on a metaproperty. Bulk add or remove tags on assets.
List configured Bynder automations so downstream syndication workflows stay in sync.
***
## Prerequisites
* Admin access to your Bynder portal to create tokens or OAuth apps
* A Gradial organization **Administrator** role to complete setup
***
## How to Connect
Sign in to your **Bynder portal** as an account admin and open **Settings → Apps & Integrations** (or **Permanent Tokens**, depending on your portal version).
Choose the auth method that fits your security requirements:
**Permanent Token (simplest)**
1. Create a dedicated permanent token for Gradial.
2. Scope it to the operations you want available: asset read/write, collections, metaproperties, tags, automations, uploads.
3. Copy the token value.
**OAuth2 Client Credentials (recommended for production)**
1. Create a dedicated OAuth2 app for Gradial.
2. Grant it the asset, collection, metaproperty, tag, automation, and upload scopes.
3. Copy the **Client ID** and **Client Secret**.
Also copy your **Bynder Base URL** — your portal origin, for example `https://acme.bynder.com`.
Always create a dedicated token or OAuth app for Gradial rather than reusing a shared credential. Grant only the scopes needed for your workflows.
1. In Gradial, go to **Settings → Integrations**.
2. Find **Bynder** and click **+ Add**.
3. Fill in the connection details:
| Field | Value |
| ------------------------------ | ------------------------------------------------------------------------------------------ |
| **Integration Name** | A display name (e.g., `My Bynder Portal`) |
| **Bynder Base URL** | Your portal origin — HTTPS required, no path or query (e.g., `https://example.bynder.com`) |
| **Authentication Method** | Permanent Token or OAuth2 Client Credentials |
| **Token / Client ID + Secret** | From step 2 |
4. Click **Save**. Gradial validates the connection to confirm it can reach your portal before any agent work runs.
1. Go to **Settings → Environments** and select the Gradial Environment where Bynder should be available.
2. Add the Bynder integration to that Environment.
3. Repeat for any additional Environments.
***
## How It Fits Into Broader Workflows
| Use case | How to use it |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Campaign asset sourcing** | Use Bynder as the source of truth for approved creative when generating, editing, or QAing content elsewhere in Gradial |
| **Collection curation** | Curate audience- or campaign-specific collections without context-switching to the Bynder portal |
| **Metadata governance** | Bulk-apply Status, Channel, Campaign, or other metaproperty options across assets discovered by search |
| **Tag management** | Tag and re-tag assets so downstream Bynder automations, search, and syndication keep working as campaigns evolve |
| **Asset ingestion** | Upload newly generated creative back into Bynder so assets stay under DAM governance from day one |
**Example workflow — Assemble a campaign in Bynder from Gradial:**
1. Search Bynder for `keyword: "spring campaign"` and filter by `property_Status: Approved` to find existing approved candidates.
2. Open one asset to review stats, versions, and current metaproperty values.
3. Apply campaign-specific tags and metaproperty options in bulk.
4. Curate the assets into a new collection and share it with stakeholders.
5. Upload any newly generated creative into Bynder, then tag and add it to the same collection.
***
## Support
Contact your Gradial onboarding lead or email [support@gradial.com](mailto:support@gradial.com) for help with setup.
# Contentful
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/contentful
Connect Gradial to Contentful for live, end-to-end content authoring, optimization, and publishing workflows.
Connect Contentful once and Gradial can read live content directly — using it in authoring, optimization, and web task flows without switching systems.
***
## What You Can Do
Browse content models, locales, entries, assets, tags, and snapshots. Read live entries end-to-end, including linked content, so Gradial works with real content rather than static exports.
Create and update entries. Publish, unpublish, archive, and restore entries. Run bulk publishing workflows with validation.
Upload and manage assets directly through the integration alongside content work.
Preview content before publishing when preview URLs are configured — including content-type-specific preview patterns for precise previewing across different entry types.
***
## Prerequisites
Before connecting Contentful to Gradial, make sure you have:
* Access to the **Contentful web app** with permission to create a **Personal Access Token** for the Content Management API
* If your organization enforces token authorization or SSO, the ability to authorize the token for the correct organization
* The **Space ID** and **environment** name you want Gradial to use by default
* A Gradial organization **Administrator** role to complete setup
The Content Management API token is tied to the user who creates it. Use a token owned by a shared service identity if possible, and set an expiration policy your team can maintain — if the owner loses access, the integration will stop working.
***
## How to Connect
1. Sign in to the **Contentful web app**.
2. Go to **Settings → API keys** and open the **Content management tokens** tab.
3. Click **Generate personal token**, give it a descriptive name (e.g., `Gradial Integration`), and copy the token immediately — it is only shown once.
4. If your organization enforces token authorization, complete the authorization step for the correct organization. Some organizations also require an SSO step at this point.
In the Contentful web app, use the space selector in the top navigation to choose the space you want Gradial to use by default, then note the environment name (commonly `master`). Gradial uses these defaults in all downstream workflows unless overridden.
1. In Gradial, go to **Settings → Integrations**.
2. Find **Contentful** and click **+ Add**.
3. Fill in the connection details:
| Field | Value |
| ------------------------------------- | ------------------------------------------------------------------------ |
| **Integration Name** | A display name (e.g., `My Contentful Connection`) |
| **Content Management Token** | The token generated in Step 1 |
| **Default Space** | The Space ID for the space Gradial should use by default |
| **Default Environment** | The environment name (e.g., `master`) |
| **Default Preview URL** *(optional)* | The base preview URL configured in Contentful's content preview settings |
| **Preview URL patterns** *(optional)* | Per-content-type preview URL patterns (see below) |
4. Click **Save**. Gradial validates the connection and uses the default space and environment in all downstream workflows.
If your team uses content-type-specific preview URLs, you can configure them so Gradial previews entries against the correct URL for each content type.
To find your existing preview patterns:
1. In Contentful, go to `https://app.contentful.com/spaces//settings/content_preview`
2. Click into a content type to see its configured preview URL.
3. In Gradial, enter the **content type ID** (which corresponds to the Content Model name in Contentful) and paste the preview URL exactly as it appears in Contentful.
Repeat for each content type that has its own preview URL.
1. Go to **Settings → Environments** and select the Gradial Environment where Contentful should be available.
2. Add the Contentful integration to that Environment.
3. Repeat for any additional Environments.
***
## How It Fits Into Broader Workflows
| Use case | How to use it |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Live content in task flows** | Gradial reads the live Contentful entry instead of a static export or copied text, so reviews and updates are always working against the real content |
| **Insight to execution** | Read the live entry, generate the recommended update, preview it, and publish — all from the same working flow |
| **CX Optimization** | Pair content analysis with CX Optimizer to identify which pages, messages, or content structures should be improved next |
| **PM-led publishing** | Give PMs a clear path from content review to content activation without a separate handoff for every change |
**Example flow:**
1. Pull the live Contentful content for a page, article, or campaign asset.
2. Review performance signals and content quality together.
3. Ask Gradial to recommend or draft the next update.
4. Preview the change in context.
5. Publish the updated content and continue optimizing.
***
## Troubleshooting
**Token rejected at save**
Confirm the token was copied in full with no trailing spaces, and that it was authorized for the correct Contentful organization if your org uses token authorization.
**Space or environment not found**
Verify the Space ID and environment name are correct. The Space ID is the alphanumeric string in the Contentful web app URL, not the space display name.
**Previews not loading**
Confirm the Default Preview URL matches what is configured in **Contentful → Settings → Content Preview**, and that per-content-type patterns use the exact content type ID from the Content Model.
**Integration not available in a Workspace**
Assign the integration to the correct Gradial Environment under **Settings → Environments**.
***
## Support
Contact your Gradial onboarding lead or email [support@gradial.com](mailto:support@gradial.com) for help with setup.
# Contentstack
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/contentstack
Connect Gradial to Contentstack to author, migrate, publish, and preview entries and assets across content types, branches, and environments.
Connect a Contentstack stack once and Gradial can read, search, create, update, publish, and preview entries and assets across content types, branches, and environments from a single flow.
Contentstack's Content Management API enforces an aggressively low rate limit. Treat the integration as quota-constrained and bias toward narrow, targeted operations. See [Operational Notes](#operational-notes) below.
***
## What You Can Do
List content types, describe a single content type and its field shapes, list entries by content type with publish-detail metadata.
Read a single entry with linked-entry resolution. Re-inspect stored workspace snapshots without re-querying Contentstack.
Create entries (JSON RTE, master locale, custom asset fields, taxonomy). Update entries across locales. Preserve formatting and field-level rules so edits don't collapse rich content.
Upload assets and reference the returned asset UIDs in entry payloads.
Publish and unpublish entries on explicit request. The skill defaults to draft — entries are not published automatically.
Capture a source URL, assemble a source brief, discover the target content model, upload assets, create linked entries, and QA via the configured preview URL — end to end in one workflow.
***
## Prerequisites
* Admin access to your Contentstack stack to generate a Management Token
* Your stack's regional CMA host and Stack API Key
* A Gradial organization **Administrator** role to complete setup
***
## How to Connect
1. Sign in to **Contentstack** and open the target stack.
2. Go to **Settings → Stack** and copy the **Stack API Key**.
3. Go to **Settings → Tokens → Management Tokens** and create a token dedicated to Gradial.
4. Scope the token to the operations you want available:
* Read and write on entries, assets, content types, global fields, and taxonomies
* Publish/unpublish if the agent should be able to push live
* Branch- and environment-scoped if you want to limit Gradial's blast radius
5. **Do not** grant audit log, roles, stack admin, or token admin scopes — Gradial deliberately excludes those endpoints.
6. Copy the **Management Token**.
7. Confirm which **regional CMA host** your stack is on:
| Region | Host |
| ----------------------- | ------------------------------- |
| North America (default) | `api.contentstack.io` |
| Europe | `eu-api.contentstack.com` |
| Australia | `au-api.contentstack.com` |
| Azure NA | `azure-na-api.contentstack.com` |
| Azure EU | `azure-eu-api.contentstack.com` |
| GCP NA | `gcp-na-api.contentstack.com` |
| GCP EU | `gcp-eu-api.contentstack.com` |
Use a dedicated Management Token rather than reusing a developer's personal token. Gradial stores credentials encrypted and the agent cannot access them.
1. In Gradial, go to **Settings → Integrations**.
2. Find **Contentstack** and click **+ Add**.
3. Fill in the connection details:
| Field | Value |
| ---------------------- | --------------------------------------------- |
| **Integration Name** | A display name (e.g., `Dell Marketing Stack`) |
| **Management API URL** | Your regional CMA host |
| **Stack API Key** | From step 2 |
| **Management Token** | From step 2 |
4. Click **Connect** to validate. Gradial probes the CMA and discovers the stack's branches and environments.
5. Fill in the stack-specific config:
| Field | Value |
| ------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **Branch** | Default branch for CMA calls (typically `main`) |
| **Environment** | Default publishing environment (e.g., `production`) |
| **Page Content Type IDs** | Comma-separated UIDs for page-like content types (e.g., `page, article, landing_page`) |
| **Preview Base URL** *(optional)* | Host serving rendered preview pages |
| **Preview URL Patterns** *(optional)* | Per-content-type URL templates — supports `{entry.uid}`, `{entry.locale}`, `{entry.}` |
6. Click **Save**. Gradial validates the regional host, credentials, and any preview URL patterns at save time.
1. Go to **Settings → Environments** and select the Gradial Environment where Contentstack should be available.
2. Add the Contentstack integration to that Environment.
3. Repeat for any additional Environments.
***
## How It Fits Into Broader Workflows
| Use case | How to use it |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Content authoring** | Author Contentstack pages and components from the same Gradial thread that produced the brief, copy, or designs |
| **Live-page migrations** | Capture a public source URL, assemble a source brief, discover the target content model, upload assets, and assemble the page as linked entries preserving copy, hierarchy, and links 1:1 |
| **Rendered-page QA** | Use Gradial preview (via the configured preview URL pattern) to QA the actual rendered page, not just JSON |
| **Multi-region stacks** | Operate safely across NA, EU, AU, Azure, and GCP stacks by configuring the matching CMA host |
**Example workflow — Port a product page to Contentstack:**
1. Run `capture_webpage` against the source URL to capture cleaned markdown, content chunks, and images.
2. Discover the target model by listing content types and reading a nearby existing page as the shape reference.
3. Upload source images, capturing the returned asset UIDs.
4. Create referenced block entries first, then the root page entry, preserving section order and asset references.
5. Re-read the root page and verify against the source brief: sections present, copy 1:1, links mapped, images linked.
6. Open the Contentstack artifact and confirm the preview URL renders correctly before handing back to the requester.
***
## Operational Notes — Rate Limits
Contentstack's CMA enforces a notably low rate limit compared to other CMS APIs. Gradial does not currently implement client-side throttling or retry-with-backoff for Contentstack — a 429 from Contentstack surfaces directly as an error.
* **Bias toward narrow, targeted operations**: read a single entry by UID rather than listing entire content types when possible.
* **Bulk migrations are quota-fragile**: multi-locale writes, mass updates, or migration runs touching many linked blocks can saturate the quota in a single thread. Stage payloads carefully and expect to space work across multiple turns.
* **Asset uploads compound the cost**: each upload is its own request. Plan uploads alongside entry creation, not as a separate sweep.
* **Triage 429s manually**: if the agent reports a Contentstack 429, pause the workflow rather than retrying immediately.
* **Customer-side quota bumps help**: higher Contentstack plans come with higher CMA quotas. Confirm the plan tier supports expected request volume before kicking off bulk migrations.
***
## Security Boundary
Gradial deliberately blocks privileged Contentstack admin operations from the agent surface. The following are not callable through the integration:
* Audit log, Roles, Stacks, and Token admin endpoints
* `/management_tokens`, `/delivery_tokens`, `/roles`, `/stacks/share`, `/stacks/transfer_ownership`
***
## Support
Contact your Gradial onboarding lead or email [support@gradial.com](mailto:support@gradial.com) for help with setup.
# Custom MCP Agent Integration
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/custom-mcp
Extend Gradial using Model Context Protocol (MCP) — connect proprietary data sources, internal knowledge bases, and custom tools beyond the native catalog.
***
## What is MCP?
The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard for connecting AI agents to external data and tools. Developed by Anthropic and adopted across the industry, MCP is becoming the common language enterprises use to expose data to AI systems—regardless of which vendor's agents are consuming it.
Think of MCP as a universal adapter. Instead of building custom integrations for every AI platform, you build one MCP server and any compliant agent can use it. This matters for enterprises because:
* **Standardization** — Define once how your data is accessed, enforce it everywhere. Your CDP, product catalog, and internal knowledge base speak the same protocol whether Gradial, your internal tools, or other vendor agents are calling them.
* **Interoperability** — As more platforms adopt MCP, your agents can communicate with each other. A Gradial agent executing a content workflow can hand off to another vendor's agent for specialized tasks, passing context seamlessly.
* **Future-proofing** — Investing in MCP means your data infrastructure works with tomorrow's AI tools, not just today's. The protocol is designed to evolve with the ecosystem.
* **Control** — You decide exactly what data and capabilities to expose. MCP servers sit in your infrastructure, behind your security controls, serving only what you explicitly permit.
Gradial's MCP integration lets you connect any MCP-compliant server—whether you've built it yourself, deployed an open-source implementation, or are using a vendor's MCP endpoint—and immediately extend what Gradial agents can do.
***
## Why Connect an MCP Agent?
MCP integrations let you extend what Gradial agents can do without waiting for native integrations. Common use cases include:
* **First-party data access** — Connect your CDP, data warehouse, or customer database so agents can personalize content using real audience data
* **Internal tool access** — Expose internal APIs, proprietary calculators, or business logic to agents
* **Custom content sources** — Pull from internal knowledge bases, product catalogs, or pricing systems
* **Workflow automation** — Trigger actions in systems that don't have native Gradial integrations
***
## How the Connection Fits Together
Before starting setup, it helps to understand how the pieces connect:
1. Your organization hosts or selects an MCP server with the tools you want Grady to use.
2. An MCP integration is created once for your Gradial organization, then enabled for one or more Gradial Environments. Workspaces inherit access through their associated Environments.
3. A Gradial administrator creates the integration under **Settings → Integrations** and supplies the server URL, authentication settings, and a description of its capabilities.
4. Gradial validates the MCP session and tool list for shared-credential and SSO connections. For browser OAuth, Gradial validates OAuth discovery and client registration when the integration is created.
5. The administrator assigns the MCP integration to one or more Gradial Environments.
6. Grady uses the capabilities description and discovered tools to determine when the MCP integration is relevant.
7. If the server uses browser-based MCP OAuth, each Gradial user authorizes their own account before using the integration.
***
## Prerequisites
Before you begin, make sure you have:
* A running MCP server that supports remote HTTP connections
* The server's base URL and MCP endpoint path
* Authentication credentials or OAuth configuration for the server
* For Browser OAuth (MCP spec), the ability to allowlist Gradial's [callback URI](#gradials-oauth-callback-uri) on your authorization server if it does not accept dynamically registered redirect URIs
* An organization role with permission to manage Gradial settings and integrations
* The Gradial Environment or Environments that should have access to the integration
Your MCP server must:
* Be reachable from Gradial's infrastructure
* Accept MCP JSON-RPC requests over HTTP
* Support `initialize`, `notifications/initialized`, `tools/list`, and `tools/call`
* Advertise the MCP `tools` capability during initialization
* Return MCP responses as JSON or a server-sent event stream
If your MCP endpoint restricts inbound traffic by source IP, allowlist Gradial's outbound egress IP addresses on your firewall or reverse proxy. See [IP Allowlisting](/docs/integrations-administration-and-setup/ip-allowlist) for the current list.
Use HTTPS for production MCP endpoints. Give Gradial only the network access and server permissions required for the tools you intend to expose.
***
## Authentication Methods
Gradial supports the following authentication methods for external MCP servers:
| Method | Best for | Identity model | Required configuration |
| ----------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **API Key** | Servers protected by a shared static token | One credential shared by all users of the integration | API key, header name, and optional value prefix |
| **Browser OAuth (MCP spec)** | Per-user authorization | Each Gradial user connects their own account | MCP OAuth metadata, PKCE, Dynamic Client Registration, and Gradial's [callback URI](#gradials-oauth-callback-uri) on the server |
| **OAuth2 Client Credentials** | Most service-to-service integrations | One OAuth client shared by all users of the integration | Client ID, client secret, token URL, and optional scopes |
| **SSO Passthrough** | Internal MCP servers protected by the same identity provider as Gradial | Uses each user's existing SSO session | A configured Gradial [SSO provider](/docs/integrations-administration-and-setup/managing-access/sso) and the token type expected by the MCP server |
The authentication methods available in the setup dialog depend on your organization's Gradial configuration.
Use **OAuth2 Client Credentials** for most MCP integrations. It gives Gradial a dedicated service identity, avoids per-user authorization setup, and is easier to operate for shared Environment workflows. Use **Browser OAuth (MCP spec)** only when the MCP server must act on behalf of each individual Gradial user. This is called on-behalf-of (OBO) access: the external system checks the user's own permissions instead of using one shared service identity.
Use **SSO Passthrough** when users already authenticate to Gradial and the MCP server through the same identity provider, and the MCP server accepts that provider's access or ID token.
Use **API Key** when the MCP server expects a static token in a request header.
Shared API keys and client credentials give every user with access to the integration the same server permissions. Use a least-privileged service account and avoid personal credentials.
### Gradial's OAuth Callback URI
Browser OAuth (MCP spec) sends each user back to Gradial after they authorize the connection. Gradial's redirect URI is:
```text theme={null}
https://app.gradial.com/api/integrations/mcp-oauth/callback
```
Gradial submits this URI when it dynamically registers itself as an OAuth client, so most servers that fully support Dynamic Client Registration need no additional setup.
Register or allowlist the URI manually when your authorization server:
* Validates redirect URIs against a fixed allowlist, even for dynamically registered clients
* Restricts redirect URIs by hostname or domain
* Requires security review or change approval before accepting a new redirect target
Enter the URI exactly as shown. OAuth redirect URI matching is exact — a trailing slash, an added path segment, or `http` instead of `https` causes the authorization request to be rejected.
The callback URI applies only to **Browser OAuth (MCP spec)**. API Key, OAuth2 Client Credentials, and SSO Passthrough do not use a browser redirect, so no callback URI is needed.
***
## Connection Details
The following values are needed when creating an MCP connection:
| Field | Description | Example |
| ---------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| **Integration Name** | A clear name users can reference when asking Grady to use the integration | `Customer Data Platform` |
| **MCP Base URL** | The scheme and host for the MCP server, without the endpoint path | `https://cdp-api.example.com` |
| **MCP Endpoint Path** | The relative path to the MCP HTTP endpoint | `/mcp` |
| **Grady Capabilities** | A specific description of the data and actions available through the server | `Query customer segments, retrieve audience attributes, and look up product affinity scores.` |
Gradial combines the base URL and endpoint path when connecting — `https://cdp-api.example.com` plus `/mcp` results in:
```text theme={null}
https://cdp-api.example.com/mcp
```
If you paste a full MCP endpoint into **MCP Base URL**, Gradial extracts its path into **MCP Endpoint Path**. Review both fields before validating the connection.
The endpoint path must be relative to the base URL. Do not enter a second absolute URL in the endpoint path field.
### Write a Useful Capabilities Description
The **Grady Capabilities** field helps Grady decide when to use the MCP integration. Describe the tasks, data, and actions the server supports instead of describing only the underlying system.
Good:
```text theme={null}
Query customer segments, retrieve audience attributes, look up product
affinity scores, and fetch personalization rules by segment ID.
```
Too broad:
```text theme={null}
Access our customer platform.
```
The capabilities description helps with tool selection, but it is not an access-control policy. Enforce authorization and data restrictions on the MCP server.
For optimal performance, expose no more than 20 tools through a single MCP integration. Smaller, task-focused tool sets help Grady choose the right tool and reduce the amount of tool schema context sent to the model. If your MCP server supports more than 20 tools, create separate MCP integrations by workflow, data domain, or Environment instead of exposing every tool through one connection.
***
## How to Connect
1. Sign in to Gradial with permission to manage organization settings.
2. Go to **Settings → Integrations**.
3. Click **Connect Integration**.
4. Under **Web & developer tools**, select **MCP Server**.
The **Add MCP Integration** dialog opens.
1. Enter a descriptive **Integration Name**.
2. Enter the **MCP Base URL**.
3. Confirm or update the **MCP Endpoint Path**. The default is `/mcp`.
4. Describe the server's tools in **Grady Capabilities**.
Follow the instructions for your server's authentication method.
**API Key**
1. Select **API Key**.
2. Enter the API key.
3. Set **Header Name** to the header expected by the server. The default is `Authorization`.
4. Set **Prefix** to the value expected before the key. The default is `Bearer`.
5. Add any required non-authentication headers under **Additional Headers**.
6. Click **Validate Connection**.
Example request header:
```http theme={null}
Authorization: Bearer your-api-key
```
For a server that expects `X-API-Key` without a prefix, set **Header Name** to `X-API-Key` and leave **Prefix** empty.
**Browser OAuth (MCP spec)**
1. Select **Browser OAuth (MCP spec)**.
2. Add any required non-authentication headers under **Additional Headers**.
3. Click **Create Integration**.
During creation, Gradial probes the MCP endpoint for its OAuth challenge, discovers the server's protected-resource metadata, discovers the authorization server, confirms support for PKCE using `S256`, and dynamically registers Gradial as an OAuth client.
The MCP server and its authorization server must support:
* OAuth Protected Resource Metadata ([RFC 9728](https://www.rfc-editor.org/rfc/rfc9728))
* OAuth Authorization Server Metadata ([RFC 8414](https://www.rfc-editor.org/rfc/rfc8414)) or OpenID Connect discovery
* PKCE with the `S256` challenge method
* OAuth Dynamic Client Registration ([RFC 7591](https://www.rfc-editor.org/rfc/rfc7591))
* The authorization code and refresh token grants
Gradial registers the following redirect URI during client registration. If your authorization server allowlists redirect URIs, add it before creating the integration:
```text theme={null}
https://app.gradial.com/api/integrations/mcp-oauth/callback
```
See [Gradial's OAuth Callback URI](#gradials-oauth-callback-uri) for details.
Browser OAuth does not use **Validate Connection** before the integration is created. Gradial verifies OAuth discovery and client registration during creation. Each user completes authorization after the integration has been saved.
**OAuth2 Client Credentials**
1. Select **OAuth2 Client Credentials**.
2. Enter the **Client ID** and **Client Secret**.
3. Enter the authorization server's **Token URL**.
4. If required, enter the server's scopes in **Scope**, separated by spaces.
5. Add any required non-authentication headers under **Additional Headers**.
6. Click **Validate Connection**.
Gradial obtains and refreshes access tokens automatically using the shared OAuth client. The token endpoint must accept the client credentials through HTTP Basic authentication.
**SSO Passthrough**
Before using SSO Passthrough, configure the identity provider under **Organization → SSO**. See [Setting Up SSO](/docs/integrations-administration-and-setup/managing-access/sso).
1. Select **SSO Passthrough**.
2. Select the **SSO Provider** associated with the MCP server.
3. Select the **Token Source**:
* **Access token** — Recommended for most MCP servers
* **ID token** — Use only when the MCP server specifically requires identity claims
4. If required, enter one **Required Scope**, such as `mcp.read`. The required scope must be a single scope token without spaces. If configured, Gradial checks for it before calling the MCP server.
5. Add any required non-authentication headers under **Additional Headers**.
6. Click **Validate Connection**.
Gradial validates the connection using the current user's SSO session. Users with an active session from the selected SSO provider can use the MCP integration without a separate consent flow. Users without that SSO session must sign in through SSO before using it.
Use **Additional Headers** only for static, non-authentication values required by the MCP server, such as:
```http theme={null}
X-Client-Id: customer-tenant-123
```
Do not add authorization, API key, content negotiation, or MCP session headers here. Gradial manages those through the selected authentication method and MCP protocol.
Every additional header requires a unique name and a non-empty value.
For API Key, OAuth2 Client Credentials, and SSO Passthrough:
1. Click **Validate Connection**.
2. Confirm that Gradial reports a successful connection and the number of tools found.
3. Click **Create Integration**.
For Browser OAuth, click **Create Integration** after completing the server details. OAuth discovery and client registration occur during creation.
Connection validation initializes the MCP session and requests `tools/list`. It does not execute one of the server's business tools.
The integration exists at the organization level after it is created, but Grady can use it only in Environments to which it is assigned.
1. Return to the integrations list.
2. Find the new MCP integration.
3. Open its Environment selector. A new integration may show **No environment**.
4. Select each Environment that should have access to the MCP server.
All Workspaces associated with those Environments can use the integration.
Complete this step only when the integration uses **Browser OAuth (MCP spec)**.
Each user who needs the MCP integration must:
1. Go to **Settings → Integrations**.
2. Find the MCP integration.
3. Click **Connect**.
4. Sign in to the MCP server's authorization provider.
5. Review and approve the requested access.
6. Return to Gradial and confirm the integration shows **Connected**.
The same Gradial user who starts the OAuth flow must complete it. Authorization is stored per user and is not shared with other members of the Environment.
***
## What Gradial Validates
When you click **Validate Connection**, Gradial:
1. Builds the full MCP URL from the base URL and endpoint path.
2. Applies the selected authentication method and additional headers.
3. Sends an MCP `initialize` request.
4. Confirms that the server advertises the `tools` capability.
5. Sends `notifications/initialized`.
6. Sends `tools/list`.
7. Reports the number of tools returned by the server.
A successful validation confirms connectivity, authentication, MCP initialization, and tool discovery. It does not guarantee that every discovered tool will succeed for every input or user.
***
## Using Your MCP Agent
Once connected and assigned to an Environment, your MCP agent becomes available to Gradial agents automatically. The agent capabilities description helps Gradial decide when to use your MCP tools.
To explicitly invoke your MCP agent in a prompt or workflow:
```text theme={null}
Use the {Integration Name} agent to [describe the task].
```
Example:
```text theme={null}
Use the HubSpot MCP Agent to pull the top 5 customer segments
by engagement score for the Q4 campaign.
```
### Test the Integration in Grady
After assigning the integration to an Environment, open a Workspace associated with that Environment and ask Grady to perform a low-risk read operation. Reference the integration by name to make the first test explicit:
```text theme={null}
Use the Customer Data Platform agent to list the available customer
segments. Return only each segment's name and identifier.
```
Confirm that:
* Grady selects the expected MCP integration
* The server receives the request under the expected user or service identity
* The response contains only data the identity is authorized to access
* No unexpected write operation occurs
After the initial test, Grady can select the MCP integration automatically when its capabilities description matches a task.
***
## Example: First-Party Data MCP
A common pattern is connecting a first-party data MCP to personalize content at scale.
**Setup:**
* **Integration Name:** `Customer Data Platform`
* **MCP Base URL:** `https://cdp-api.yourcompany.com`
* **MCP Endpoint Path:** `/mcp`
* **Authentication:** `OAuth2 Client Credentials`
* **Grady Capabilities:** "Query customer segments, retrieve audience attributes, look up product affinity scores, and fetch personalization rules by segment ID."
* **Environment:** `Production Marketing`
**Use case:** When creating landing page variants, Gradial agents can query your CDP to understand which segments exist, what attributes define them, and which messaging resonates with each—then generate on-brand content tailored to each audience.
**Test prompt:**
```text theme={null}
Use the Customer Data Platform agent to return the top five customer
segments by engagement score for the Q4 campaign.
```
***
## Troubleshooting
| Issue | Likely cause | Resolution |
| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Validate Connection** is unavailable | A required field is empty, the URL is invalid, or an additional header is incomplete | Review the base URL, authentication fields, capabilities description, and every additional header row |
| Connection times out or reports an unknown host | Gradial cannot reach the MCP server | Verify DNS and HTTPS configuration, then update firewall rules or allowlists so Gradial can reach the endpoint |
| MCP initialization fails | The endpoint is not an MCP HTTP endpoint or does not support the initialization handshake | Confirm the base URL and endpoint path, then test `initialize` directly against the server |
| Server does not advertise tool capabilities | The `initialize` response does not include the MCP `tools` capability | Update the MCP server to advertise tool support |
| `tools/list` fails | Authentication is valid for the endpoint but cannot list tools, or the server returns an invalid MCP response | Review server permissions, logs, response content type, and JSON-RPC response |
| Browser OAuth discovery fails | Protected-resource metadata, authorization-server metadata, PKCE, or Dynamic Client Registration is missing or invalid | Validate the server's OAuth metadata and confirm that PKCE `S256` and client registration are supported |
| Authorization server reports an invalid or unregistered `redirect_uri` | The authorization server does not accept Gradial's dynamically registered redirect URI | Add `https://app.gradial.com/api/integrations/mcp-oauth/callback` to the authorization server's allowed redirect URIs, matching it exactly |
| Browser OAuth user sees **Not connected** | The current user has not completed authorization | Click **Connect** on the integration and complete the OAuth flow as the same Gradial user |
| SSO validation reports a missing scope | The user's current identity-provider grant does not contain the configured scope | Add the scope at the identity provider, then sign out and back in to refresh the user's grant |
| Integration is not available in a Workspace | The integration is not assigned to the Workspace's Environment | Return to **Settings → Integrations** and add the correct Environment to the integration |
| Existing credentials need to be changed | Connection secrets cannot be viewed or replaced from the integration metadata editor | Create a new integration with the updated credentials, validate it, assign its Environments, and then retire the old integration |
When troubleshooting, compare the MCP server logs with the validation attempt. The server should receive `initialize`, `notifications/initialized`, and `tools/list` in that order.
***
## Security Recommendations
* Expose only the MCP tools Gradial needs. Keep each MCP integration to 20 tools or fewer for best performance.
* Apply authorization to every tool on the MCP server; do not rely on the capabilities description for enforcement.
* Use separate credentials and endpoints for development, staging, and production where possible.
* Use least-privileged scopes for OAuth clients and API keys.
* Treat tool descriptions and tool results as untrusted input and avoid returning secrets.
* Review write-capable tools carefully before assigning the integration to production Environments.
* Monitor authentication failures, tool calls, rate limits, and server errors.
***
## Need Help?
Contact your Gradial representative or [Gradial Support](https://portal.usepylon.com/) for help with network allowlisting, organization-specific authentication options, or MCP connection troubleshooting.
# Adobe Customer Journey Analytics
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/customer-journey-analytics
Connect Gradial to Adobe Customer Journey Analytics to turn cross-channel performance data into campaign recommendations, content updates, and activation plans.
Cross-channel performance data lives in CJA, but turning that data into a decision — a new audience, a content change, a follow-up campaign — requires analysts to translate reports into briefs, then hand those briefs to a separate team to act on them. The gap between insight and execution is where momentum dies.
Connect Adobe Customer Journey Analytics (CJA) and Gradial can read your data views, Workspace projects, filters, and calculated metrics — then turn that analysis into a concrete next action: updated content, a new campaign brief, a page change, or an activation step in a connected system. The analyst and the marketer can work in the same thread, moving from report to recommendation to execution without a handoff.
***
## What You Can Do
List data views and explore their dimensions, metrics, and date ranges. Pull the schema context Gradial needs to interpret your cross-channel data correctly.
Read Analysis Workspace projects, panels, and visualizations. Use project context to generate summaries, highlight trends, and draft recommendations.
List and inspect filters (segments) and calculated metrics. Reference audience definitions and custom KPIs when drafting briefs or activation plans.
Turn funnel analysis, behavior data, and segment performance into campaign briefs, content updates, journey plans, or execution steps in a connected system.
***
## Prerequisites
* An active Adobe Experience Cloud organization with Customer Journey Analytics licensed and live
* Access to the **Adobe Developer Console** to create a project and generate server-to-server OAuth credentials
* Your **IMS Org ID** and the **data view IDs** Gradial should have access to
* A product profile with CJA API access granted in Adobe Admin Console
* A Gradial organization **Administrator** role to complete setup
***
## How to Connect
1. Go to [Adobe Developer Console](https://developer.adobe.com/console) and sign in with your Adobe ID.
2. Select your organization from the org switcher.
3. Click **Create new project** and give it a name (e.g., `Gradial – CJA Integration`).
1. Inside your new project, click **Add API**.
2. Filter by **Experience Cloud** and select **Customer Journey Analytics**.
3. Choose **OAuth Server-to-Server** as the authentication type and click **Next**.
4. Select or create a **Product Profile** that grants CJA API access. The profile must be configured in Adobe Admin Console under Customer Journey Analytics.
| Scope | Required | Purpose |
| ----------------------------------------- | -------- | -------------------------------------------------- |
| `adobeanalytics.read` | Yes | Read data views, dimensions, metrics, and projects |
| `adobeio.appregistry.read` | Yes | Required for OAuth token exchange |
| `read_organizations` | Yes | Resolve IMS org context |
| `additional_info.projectedProductContext` | Yes | Confirm CJA product entitlement |
5. Click **Save configured API**.
From the project's **OAuth Server-to-Server** credential page, copy:
* **Client ID**
* **Client Secret**
* **IMS Org ID**
* **Technical Account ID**
Keep the Client Secret secure. It grants API access to your CJA data views and should be treated as a sensitive credential. Regenerate it in Adobe Developer Console if it is ever exposed.
Gradial reads CJA data using data view IDs. To find them:
1. In CJA, go to **Data Management → Data Views**.
2. Open each data view you want Gradial to access.
3. Copy the **Data View ID** from the URL or the data view settings panel (format: `dv_xxxxxxxxxxxxxxxxxx`).
Provide these IDs during Gradial setup so Gradial knows which data views are in scope.
1. In Gradial, go to **Settings → Integrations**.
2. Find **Adobe Customer Journey Analytics** and click **+ Add**.
3. Fill in the connection details:
| Field | Value |
| ------------------------ | ------------------------------------------------- |
| **Integration Name** | A display name (e.g., `Acme – CJA Production`) |
| **IMS Org ID** | From step 3 |
| **Client ID** | From step 3 |
| **Client Secret** | From step 3 |
| **Technical Account ID** | From step 3 |
| **Data View IDs** | Comma-separated list of data view IDs from step 4 |
4. Click **Save**. Gradial validates the credentials and confirms access to the specified data views.
1. Go to **Settings → Environments** and select the Gradial Environment where CJA should be available.
2. Add the integration to that Environment.
3. Repeat for any additional Environments.
***
## How It Fits Into Broader Workflows
| Use case | How to use it |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Performance to brief** | Ask Gradial to summarize a Workspace project or data view trend, then draft a campaign brief based on what the data shows |
| **Funnel gap analysis** | Pull funnel metrics into a Gradial thread and ask it to identify drop-off points and recommend content or journey changes |
| **Segment-driven content** | Reference a CJA filter to have Gradial tailor copy, subject lines, or page content for a specific audience |
| **Cross-channel activation** | Use CJA insight to execute or draft a follow-up in AJO, SFMC, Marketo, AEM, or another connected system |
| **Reporting summaries** | Ask Gradial to translate a complex Workspace project into an executive summary or stakeholder brief |
**Example — Turn a funnel report into a campaign plan:**
1. Ask Gradial to list your CJA data views and pick the relevant one.
2. Have Gradial pull the funnel visualization from a Workspace project.
3. Ask Gradial to identify the biggest drop-off step and draft a re-engagement email.
4. Execute the draft in a connected system — AJO, SFMC, or Marketo — in the same thread.
**Example — Segment-specific content update:**
1. Ask Gradial to list the filters defined in a data view.
2. Select a high-value segment and ask Gradial to draft a tailored landing page headline and body copy.
3. Have Gradial push the update to AEM or your connected CMS.
***
## What's Not Covered Yet
* Writing back to CJA — the integration is read-only; Gradial cannot create or modify data views, projects, or filters through the API.
* Raw event-level data queries — Gradial reads aggregated project and dimension data, not individual event streams.
* Report Suite data from legacy Adobe Analytics — use the Adobe Analytics integration for that context.
* Real-time streaming data — CJA's API returns processed batch data, not live event streams.
***
## Troubleshooting
| Issue | Cause | Solution |
| ---------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized` | Invalid or expired credentials | Regenerate the Client Secret in Adobe Developer Console and update Gradial |
| `403 Forbidden` | Product profile lacks CJA API access | Confirm the profile has CJA API permission in Adobe Admin Console |
| `404 Not Found` on data view | Data view ID is incorrect or not shared | Verify the data view ID and confirm the technical account has been added to the data view's access list |
| No data views returned | IMS Org ID mismatch | Confirm the IMS Org ID matches the organization where CJA is provisioned |
| Token exchange fails | Missing required OAuth scopes | Re-add the API in Adobe Developer Console and confirm all required scopes are selected |
***
## Good to Know
* **Data view access is explicit**: The technical account created by the Adobe Developer project must be added to each CJA data view individually under **Data Views → Access**. If Gradial returns an empty data view list, this is the most common cause.
* **Workspace projects are read via the Projects API**: Only projects saved in Analysis Workspace are accessible. Auto-saved or unsaved drafts are not returned.
* **Calculated metrics are org-scoped**: Gradial can read calculated metrics defined at the org level. Data-view-scoped calculated metrics require the matching data view ID to be in scope.
* **Rate limits apply**: The CJA API enforces rate limits per org. For high-volume analysis threads, Gradial batches requests automatically.
***
## Support
Contact your Gradial onboarding lead or email [support@gradial.com](mailto:support@gradial.com) for help with setup.
# DaVinci Commerce
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/davinci-commerce
Build and maintain Jivox DCO campaign workbooks — audiences, treatments, asset variants and rotation weights — from a brief, and export them ready for the platform.
**DaVinci Commerce** is the vendor; **Jivox** is the product Gradial connects to. In **Settings → Integrations** the connection appears as **Jivox**. When asking Grady for a workbook you can call it *Jivox*, *DaVinci* or *Da Vinci* — all three refer to the same campaign workbook.
This is **DaVinci Commerce's Jivox** platform. It is unrelated to Movable Ink's DaVinci product, despite the shared name.
## Why connect it
Dynamic creative optimization is a matrix problem. A campaign has audiences down one axis and treatments across the other, and every cell needs a defined combination of copy, asset and rotation weight. A modest campaign is 40 cells. A real one is several hundred.
That matrix gets built in a spreadsheet, by hand, usually by one person who understands both the creative intent and the platform's expected column structure. It takes days, it is nearly impossible to review, and a single misaligned asset key means a treatment silently never serves. Then the brief changes — a market is added, a treatment is cut — and the whole grid has to be rebuilt without breaking the parts that were already approved.
Gradial builds the workbook from the brief, keeps it consistent as the brief changes, and validates it against your own column rules before it leaves.
***
## What Grady can do
| Capability | Detail |
| :---------------------------- | :---------------------------------------------------------------------------------------------------------- |
| Build a workbook from a brief | Turn a campaign brief, audience plan or treatment structure into a complete workbook artifact |
| Read and revise | Open an existing workbook, explain what's in it, and apply changes without rebuilding from scratch |
| Manage asset sources | Work with asset source definitions and the asset library behind the campaign |
| Validate structure | Check the workbook against your configured required columns and column mappings before export |
| Export | Produce the workbook as a native spreadsheet file, ready for the platform |
| Review in place | Open the workbook as an artifact in the task, so it can be read and commented on before anyone downloads it |
***
## Asset source profiles
The one piece of configuration that matters here. A **profile** tells Gradial what your workbooks are expected to look like — which columns must be present, and which column carries which meaning.
| Setting | What it does |
| :------------------------- | :-------------------------------------------------------------------------------------------------------- |
| **Profile name** | How you refer to this shape when asking for a workbook — for example *Retail EMEA* or *Always-on Display* |
| **Required columns** | Columns that must be present. Missing ones are reported before export |
| **Asset key column** | The column that identifies which asset a row refers to |
| **Asset group column** | The column that groups assets belonging to the same set |
| **Asset variant column** | The column that distinguishes variants within a group |
| **Rotation weight column** | The column carrying serve weighting |
| **Reporting column** | The column used for reporting identifiers |
| **First row is title** | Whether the first row is a header row |
| **Validation mode** | **Warn** reports problems and continues; **Block** refuses to export an invalid workbook |
You can define several profiles — most organizations have more than one workbook shape — and nominate one as the default.
Start a new connection in **Warn** mode. Run two or three real workbooks through it, see what gets flagged, and correct the profile against reality. Switch to **Block** once the flags have stopped, and the profile then acts as a genuine gate rather than a source of noise.
***
## Set up
Go to **Settings → Integrations**, find **Jivox** under Creative & DCO, and select **Connect**.
Add a profile using the settings above. If you have an existing workbook that represents your standard shape, use its column headers as the basis — that is the fastest route to a profile that matches what your team already produces.
Nominate the profile to use when a request doesn't name one. Profile names and IDs must be unique.
Ask Grady to build a workbook from a brief you have already delivered manually, then compare the two. Differences are usually a column-mapping detail, and correcting the profile once fixes every subsequent workbook.
***
## Using it
```
Build a DaVinci workbook from the attached campaign brief.
Audiences: the six segments in the brief's audience table.
Treatments: three per audience — awareness, consideration, retargeting.
Use the assets in the attached asset list, and weight retargeting at 50%.
```
```
Open the Q3 Retail workbook and add the two new DACH audiences.
Keep every existing row and weight unchanged — I only want the new rows added.
```
```
Read this workbook and tell me which cells have no asset assigned,
and which asset keys don't resolve to anything in the asset list.
```
Gradial builds, validates and exports the workbook. Loading it into the platform and launching the campaign remain your team's steps — Gradial does not activate campaigns or change live serving.
***
## Who this is for
| Role | What this unlocks |
| :--------------------------------- | :------------------------------------------------------------------------------------------------------------- |
| **Display / Programmatic Manager** | The matrix built from the brief rather than assembled by hand, and rebuilt cleanly when the brief moves |
| **Creative Ops** | Column structure validated before export, so a misaligned asset key is caught rather than discovered in flight |
| **Campaign Manager** | Audience and treatment structure that matches the plan you actually approved |
| **Regional Marketer** | Your markets added to an existing campaign without the whole grid being rebuilt |
| **Agency Partner** | A workbook in the shape the client's platform expects, first time |
***
## Availability
**Access:** Must be enabled for your organization. Contact your Gradial team to get access.
# Drupal
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/drupal
Connect Gradial to Drupal to read, search, create, update, and preview content without leaving your workflow.
Connect a Drupal site once and Gradial can read, search, create, update, delete, export, and preview content from a single flow — no context switch into the Drupal admin.
***
## What You Can Do
List and describe Drupal resource types — nodes, blocks, paragraphs, media, taxonomy — with field shapes and worked examples so the agent never guesses field names.
Find entities by title, path alias, UUID, or page-only filters. Read a full entity with relationship resolution, body field shapes, and stored snapshots.
Create new entities, update fields (including formatted text with value/format preservation), and delete entities. Multi-value, relationship, and reference fields stay JSON:API-shaped.
List and read media entities. Upload new media (images, documents) and reference them in content payloads.
Push a staged directory of payloads for relationship-heavy migrations where dependent entities must be created in order.
A dedicated content-migration workflow enforcing 1:1 source preservation, source-inventory files, asset upload before referencing, and rendered-page QA before completion.
***
## Prerequisites
* Admin access to your Drupal site to enable modules and create credentials
* Drupal's **JSON:API** module enabled (ships as core in Drupal 10/11)
* A Gradial organization **Administrator** role to complete setup
***
## How to Connect
Make sure **JSON:API** is enabled in Drupal (**Extend → JSON:API**). Drupal 10/11 ships it as a core module.
Then choose the auth method that fits your site:
**Basic (simplest)**
1. Enable Drupal core's **Basic Auth** module.
2. Create a dedicated editor/admin user for Gradial with JSON:API access permissions for the bundles you want to author.
3. Note the username and password.
**API Key Header**
1. If your site uses a custom auth module (e.g., `key_auth`, JWT, an SSO header, or a CDN-issued token), generate a token scoped to the Gradial editor account.
2. Note the token, header name, and prefix.
**Custom Headers**
Use this when the upstream needs more than one header or when you front Drupal with a proxy that injects its own auth.
Always create a dedicated Gradial user or token rather than reusing a real editor's credentials. Grant only the JSON:API permissions for the bundles you want available in Gradial.
1. In Gradial, go to **Settings → Integrations**.
2. Find **Drupal** and click **+ Add**.
3. Fill in the connection details:
| Field | Value |
| --------------------------------- | ---------------------------------------------------------------------------------------- |
| **Integration Name** | A display name (e.g., `United Rentals NL`) |
| **Drupal Base URL** | Your site's origin — the JSON:API root (e.g., `https://drupal-united-rentals.ddev.site`) |
| **Authentication Method** | Basic, API Key Header, or Custom Headers |
| **Preview Base URL** *(optional)* | If rendered pages are served from a different host than the JSON:API root |
4. Click **Connect** to validate. Gradial probes JSON:API, lists available resource types, and surfaces them so you can confirm which types should be treated as pages.
5. Click **Save**.
1. Go to **Settings → Environments** and select the Gradial Environment where Drupal should be available.
2. Add the Drupal integration to that Environment.
3. Repeat for any additional Environments.
***
## How It Fits Into Broader Workflows
| Use case | How to use it |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Content authoring** | Author Drupal pages and components from the same Gradial thread that produced the brief, copy, or designs |
| **Design-system migrations** | Remap source pages onto a customer's Drupal component model while preserving copy, imagery, hierarchy, links, and CTAs 1:1 |
| **Asset upload** | Upload source assets into Drupal media before referencing them in pages so the destination site stays self-contained |
| **Rendered-page QA** | Use Gradial preview to QA the actual rendered Drupal page (not just JSON), gating completion on rendered-page checks |
**Example workflow — Port a page to Drupal:**
1. Capture the source page (live HTML, screenshots, or export) into a source inventory listing sections, copy, CTAs, images, and downloads.
2. Discover the target model by listing and describing the target content types.
3. Upload source images, capturing the returned media UUIDs.
4. Stage the new entity payload and create the page.
5. Re-read the entity and inspect the snapshot and preview; iterate on field mappings until rendered-page QA passes.
6. Publish (or keep in draft) and hand the preview URL back to the requester.
***
## Support
Contact your Gradial onboarding lead or email [support@gradial.com](mailto:support@gradial.com) for help with setup.
# Figma
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/figma
Connect Figma to Gradial using OAuth 2.0, a plan access token, or a personal access token to generate production-ready CMS pages directly from your designs.
Gradial allows teams to generate production-ready CMS pages directly from Figma files or creative briefs. With just a few clicks, you can skip handoffs and reduce production time by over 75%.
***
## Overview
The Figma integration enables you to:
* Generate CMS pages directly from high-fidelity Figma designs
* Start from creative briefs or wireframes to scaffold CMS content
* Automatically detect and reuse assets from your DAM
* Preview live page output from imported designs
This integration eliminates redundant back-and-forth between designers, developers, and content authors by converting designs into live CMS structures.
***
## What You Can Do
| Capability | Description |
| ---------------------- | ------------------------------------------------------- |
| CMS page generation | Convert full-page Figma layouts into editable CMS pages |
| Creative brief parsing | Use wireframes or annotated frames to scaffold content |
| Asset reuse detection | Identify and reuse existing assets from your DAM |
| Preview support | Render real-time previews of pages based on Figma files |
***
## Authentication Methods
Gradial supports three ways to connect Figma:
| Method | Best For |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **OAuth 2.0 (recommended)** | Teams and organizations — provides scoped, revocable access tied to a dedicated service account |
| **Plan Access Token** | Figma Organization and Enterprise plans — a token owned by the plan rather than a person, created and rotated by Figma admins |
| **Personal Access Token** | Individual users or quick setup — simpler but tied to a personal account |
For most teams, **OAuth 2.0 is the recommended approach**. It provides more granular permission control, better security hygiene, and makes it easier to manage access centrally if team members change.
If your organization prefers token-based setup, **use a plan access token rather than a personal access token where your Figma plan supports it.** Plan access tokens are managed by plan administrators and are not tied to an individual user, so they don't break when someone leaves the organization. They also support longer expirations (up to 1 year, versus 90 days for personal access tokens) and can be scoped to specific files, folders, teams, or workspaces.
***
## How the Integration Fits Together
Before starting setup, it helps to understand how the pieces connect:
1. **Credentials are created in Figma first.** For OAuth 2.0 this is a Figma OAuth app; for token-based setup it is a plan access token or personal access token. Either way, this is what authorizes Gradial to connect to your Figma organization and defines the scopes — what Gradial is permitted to do.
2. **A service account is identified (OAuth 2.0).** When connecting in Gradial's settings, you specify a Figma account that all Gradial tasks will be executed on behalf of. With a plan access token, activity is attributed to the token instead, so no service account is needed. This is the account that will appear in Figma's audit logs for any activity Gradial performs.
3. **The integration is created once** at the organization level under Settings → Integrations.
4. **It is then assigned to one or more Environments** under Settings → Environments. This makes it available to all Workspaces within those Environments.
5. **Users interact with it through the agent** — there is no separate Figma panel. Once the integration is active in an Environment, users simply paste a Figma URL into the agent chat to begin working with a design.
***
## Setup Instructions: OAuth 2.0 (Recommended)
### Step 1: Create the Figma OAuth App
Your Figma admin creates the OAuth 2.0 app in Figma first. This is what authorizes Gradial to connect to your Figma organization and defines the permissions it has. Complete this step while logged in to Figma as an admin.
1. Go to [Figma Developer Settings](https://www.figma.com/developers/api#access-tokens) and navigate to **My apps → Create new app**.
2. Give the app a descriptive name (e.g., `Gradial Integration – [Your Company Name]`).
3. Under **Redirect URLs**, add the following URL exactly as shown:
```
https://app.gradial.com/api/integrations/figma/callback
```
4. Enable the required permissions. Gradial requests the following scopes:
**FILES & CONTENT**
* `file_content:read` — Read your design files, pages, and layers
* `file_metadata:read` — Access file names, thumbnails, and edit history
* `file_versions:read` — View saved versions of your files
**COMMENTS**
* `file_comments:read` — Read comments left on designs
* `file_comments:write` — Post and manage comments
**DEV RESOURCES**
* `file_dev_resources:read` — Read developer handoff annotations
* `file_dev_resources:write` — Add developer handoff annotations
**LIBRARIES**
* `library_assets:read` — Access published component assets
* `library_content:read` — Read shared component libraries
* `team_library_content:read` — Access team-wide design libraries
**ACCOUNT & PROJECTS**
* `current_user:read` — Identify the connected Figma account
* `projects:read` — List available projects and files
5. Under **Publish**, select **Private**.
6. Save the app. Figma will display a **Client ID** and **Client Secret** — copy both and store them securely immediately.
The client secret is shown only once at creation time. Store it in your secrets manager before closing this screen. If it is lost, you will need to regenerate it and reconnect the integration in Gradial.
***
### Step 2: Identify the Account Gradial Will Act On Behalf Of
When you connect Figma in Gradial's settings, you will specify a Figma account that all Gradial tasks will be executed under. This is the account Gradial uses when reading files, accessing dev resources, and performing any actions in Figma — and it is the account that will appear in Figma's audit logs for any activity Gradial performs.
**We strongly recommend using a dedicated service account rather than an individual's personal Figma account.** Here's why:
| Consideration | Service Account | Personal Account |
| ------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| **Audit & logging** | All Gradial activity is clearly attributable to a system account, keeping personal activity separate | Activity is mixed with the individual's own work, making audits harder to interpret |
| **Longevity** | Integration stays active regardless of team changes | If the person leaves or loses their seat, the integration breaks for all Environments |
| **Access control** | Permissions are managed centrally and intentionally | Permissions may change unexpectedly based on the individual's role |
**To set up the service account:**
1. Create a Figma account using a shared team email address — most teams reuse the same service account email they use for other integrations like their ticketing system (e.g., `integrations@yourcompany.com`). This avoids creating and managing multiple service identities.
2. Have your Figma admin assign this account a **Dev seat**. A Dev seat covers everything Gradial needs today, including access to Dev Mode, design files, and developer handoff resources.
3. Add the service account to the relevant Figma teams or projects so it has access to the files Gradial will need to read.
A **Dev seat** is sufficient for Gradial's current needs and is slightly cheaper than a Full seat, while sharing the same API rate limits. A **Full seat** is ideal if your organization plans to use additional Figma features beyond what Gradial requires. Your Figma admin should keep this in mind when planning seat allocations. See [Figma's pricing page](https://www.figma.com/pricing/) for a full breakdown of seat types.
***
### Step 3: Add the Integration in Gradial
With the OAuth app created and your service account ready, a Gradial administrator can now complete the connection.
1. In Gradial, go to **Settings → Integrations**.
2. Find **Figma** in the list of available integrations and click **+ Add**.
3. In the **Add Figma Integration** dialog, enter the **Client ID** and **Client Secret** from Step 1.
4. When prompted to specify the account Gradial will act on behalf of, sign in using the **service account credentials** set up in Step 2.
5. Once authorized, the integration will appear under **Existing Integrations**.
At this point the integration exists at the organization level but is not yet available to any Workspaces. Proceed to Step 4.
***
### Step 4: Assign the Integration to an Environment
A single Figma integration can be assigned to multiple Environments. Each Environment you assign it to will make the integration available to all Workspaces within that Environment.
1. In Gradial, go to **Settings → Environments**.
2. Select the Environment you want to enable Figma for.
3. Locate the Figma integration in the available integrations list and add it to the Environment.
4. Repeat for any other Environments that need access.
If a Workspace isn't seeing the Figma integration, check that it has been assigned to the correct Environment here — this is the most common cause.
***
### Step 5: Use Figma in the Agent
Once the integration is assigned to an Environment, users in any Workspace within that Environment can start working with Figma designs immediately. There is no separate import screen — just paste a Figma file URL directly into the agent chat.
You can provide either a URL to the full Figma file, or a URL scoped to a specific page or node within the file. Using a scoped URL is useful when you want Gradial to reference only a particular frame, component, or section of a design rather than the entire file.
* **Full file URL** — Gradial has access to all pages and frames within the file
* **Page or node URL** — Gradial focuses only on the specific page or element you've linked to, which is helpful for large files or when working with a specific component in isolation
You can get a node-specific URL directly from Figma by right-clicking any frame or component on the canvas and selecting **Copy link**.
**Example prompts:**
* *"Generate a CMS page from this Figma file: \[URL]"*
* *"Use this design as the basis for a new landing page: \[URL]"*
* *"Build out just the hero section from this frame: \[URL]"*
* *"What components are defined in this page? \[URL]"*
Gradial will retrieve the design and parse its frames, text, and images into structured CMS content.
***
## Setup Instructions: Plan Access Token
Figma plan access tokens are supported using exactly the same setup as personal access tokens — the only difference is which token you paste into Gradial. The overall flow — add the integration, then assign it to Environments — is unchanged.
Plan access tokens are available on Figma **Organization** and **Enterprise** plans, and only Figma organization administrators can create them. Creating one requires multi-factor authentication on the admin's Figma account.
### Step 1: Generate the Plan Access Token in Figma
Your Figma organization admin completes this step.
1. Go to [Figma's token developer hub](https://www.figma.com/developers/tokens).
2. In the upper-right corner of the table, click **Generate REST API token**.
3. On **Describe your token**, enter a name and description (e.g., `Gradial Integration`), select an expiration of up to 365 days, then click **Next**.
4. On **Choose scopes**, select the scopes Gradial needs — the same set listed in [Step 1 of the OAuth setup](#step-1-create-the-figma-oauth-app) — then click **Next**.
5. On **Choose resources**, select either **All resources** or **Only selected resources**. If you scope the token, make sure every file, folder, team, or workspace Gradial needs to read is included.
6. Click **Create**, then copy the token and store it securely immediately.
The token is shown only once at creation time. Store it in your secrets manager before closing the screen. If it is lost, generate a new token and re-enter it in Gradial.
### Step 2: Add the Token in Gradial
1. In Gradial, go to **Settings → Integrations**, find Figma, and click **+ Add**.
2. Enter the plan access token and click **Connect**.
3. Assign the integration to the relevant Environments under **Settings → Environments** as described in [Step 4](#step-4-assign-the-integration-to-an-environment) above.
Plan access tokens expire after the period the admin selected (maximum 1 year). Track the expiration date and generate a replacement before it lapses — when the token expires, the integration stops working for every Environment it is assigned to until a new token is entered.
Figma does not support comment-writing endpoints (`file_comments:write`) with plan access tokens. If your team relies on Gradial posting comments back into Figma, use OAuth 2.0 instead.
***
## Setup Instructions: Personal Access Token
If OAuth 2.0 is not required for your environment and your plan does not support plan access tokens, you can connect using a personal access token. The overall flow — add the integration, then assign it to Environments — is the same.
1. Go to [Figma Developer Settings](https://www.figma.com/developers/api#access-tokens) and generate a new personal access token under **Personal Access Tokens**.
2. In Gradial, go to **Settings → Integrations**, find Figma, and click **+ Add**.
3. Enter your personal access token and click **Connect**.
4. Assign the integration to the relevant Environments under **Settings → Environments** as described in Step 4 above.
Personal access tokens are tied to an individual Figma account and expire after a maximum of 90 days. If that person leaves the organization or their token expires, the integration will stop working for all Environments it is assigned to. For team environments, OAuth 2.0 with a service account is strongly preferred, with a plan access token as the next best option.
***
## Figma API Rate Limits
Figma enforces API rate limits that vary by **plan tier** and **seat type**. Because Gradial accesses the Figma API using the credentials you connect — a service account, a plan access token, or a personal access token — the limits below apply to all Gradial activity for that connection.
Rate limits are set by Figma and are outside Gradial's control. If your team runs high volumes of design-to-page workflows, ensure your service account is on a plan and seat type that supports the throughput you need.
| API Tier | Seat Type | Starter | Professional | Organization | Enterprise |
| ---------- | ------------ | ------------- | ------------- | ------------- | ------------- |
| **Tier 1** | View, Collab | Up to 6/month | Up to 6/month | Up to 6/month | Up to 6/month |
| **Tier 1** | Dev, Full | Up to 6/month | 10/min | 15/min | 20/min |
| **Tier 2** | View, Collab | Up to 5/min | Up to 5/min | Up to 5/min | Up to 5/min |
| **Tier 2** | Dev, Full | Up to 5/min | 25/min | 50/min | 100/min |
| **Tier 3** | View, Collab | Up to 10/min | Up to 10/min | Up to 10/min | Up to 10/min |
| **Tier 3** | Dev, Full | Up to 10/min | 50/min | 100/min | 150/min |
**Key takeaways:**
* **Seat type matters more than plan tier.** Dev and Full seats receive significantly higher per-minute limits than View or Collab seats at the same plan level. This is why [Step 2](#step-2-identify-the-account-gradial-will-act-on-behalf-of) recommends assigning the service account a **Dev seat**.
* **View/Collab seats are unsuitable for high-volume use.** At Professional, Organization, and Enterprise tiers, View/Collab seats are capped at 5–10 requests per minute regardless of tier — far lower than the Dev/Full equivalents.
* **Starter plans are limited across all seat types.** Consider upgrading to Professional or higher if you anticipate sustained Gradial usage.
If you hit rate limits, Gradial will surface an error indicating the Figma API is unavailable. Reducing the frequency of design imports or upgrading the service account's seat type will resolve this.
***
## Troubleshooting
**Figma file not accessible**
Ensure the service account has been granted access to the relevant Figma projects and files, and that the OAuth session or token is still active.
**Redirect URL mismatch error during OAuth**
Confirm that the redirect URL in your Figma app settings matches exactly:
`https://app.gradial.com/api/integrations/figma/callback`
Even a trailing slash difference can cause this error.
**Client secret was lost before saving**
Regenerate the client secret in your Figma app settings, then re-enter it in Gradial under **Settings → Integrations → Figma**.
**Integration not available in a Workspace**
The integration must be assigned to the Environment that the Workspace belongs to. Go to **Settings → Environments**, select the correct Environment, and confirm the Figma integration has been added.
**Integration stopped working after a team member left**
If the integration was set up using a personal account rather than a service account, it will need to be reconfigured. Follow the OAuth 2.0 setup steps above using a dedicated service account going forward, or switch to a plan access token, which is not tied to an individual user.
**Authentication errors after a period of working normally**
The access token may have expired — personal access tokens last a maximum of 90 days and plan access tokens a maximum of 1 year. Generate a replacement token in Figma and re-enter it in Gradial under **Settings → Integrations → Figma**.
**Figma file not accessible when using a plan access token**
If the token was created with **Only selected resources**, confirm the file's team, workspace, or folder is included in the token's resource allowlist. Otherwise, generate a new token with the correct resources selected.
***
## Support
Need help configuring or troubleshooting the integration? Contact your Gradial onboarding lead or email [support@gradial.com](mailto:support@gradial.com).
# Integrations Overview
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/get-started-with-integrations
Connect Gradial's AI agents to your CMS, DAM, marketing automation, analytics, design, and ticketing systems.
Gradial connects to the systems your team already uses — so content work stays in one flow without constant context-switching.
## CMS & DAM
Connect Gradial to AEM 6.5 or AEM Cloud for page authoring, content updates, and launches
Connect Gradial to Sitecore XM Cloud, XP, or Content Hub
Read, author, and publish entries in a live Contentful space
Author and migrate entries across content types, branches, and environments
Automate content authoring, updates, and publishing across your Sanity datasets
Read, create, update, and preview Drupal content via the JSON:API
Draft pages, posts, and media while preserving the Gutenberg block model
Search, curate, tag, and upload assets in your Bynder DAM
File the assets and artifacts Gradial creates into your Aprimo DAM as draft records
## Productivity & Collaboration
Search, read, tag, and file documents in the SharePoint libraries you explicitly allow
Search, read, and file documents in the Box folders shared with Gradial's service account
Find, read, and file documents in the Drive folders shared with Gradial's service account
Start and manage tracked Gradial tasks from Slack — mention Gradial in a channel, follow progress, and get results in the thread
## Marketing Automation
Build emails, organize campaigns, and orchestrate journeys in SFMC
Draft templates and schedule cross-channel sends across email, push, SMS, and in-app
Author campaigns, email templates, content blocks, and cross-channel offers
Manage email templates and CRM content operations
Connect to Braze for customer engagement and messaging
Connect to Adobe Target for AI-driven personalization
Turn a campaign brief into a branded HubSpot marketing email, review it, and publish with human approval
## Analytics
Connect for content performance insights
Connect for enterprise-grade content intelligence
Read organic search performance and turn query and position data into content changes
## Adobe Experience Platform
Create and retrieve audiences, inspect datasets, and activate segments across AJO, CJA, and connected systems
Inspect campaigns, journeys, messages, and templates — and execute supported operations
Turn cross-channel performance data into campaign recommendations and activation plans
## Design & Creative
Ingest design files and assets directly from Figma
Build and validate Jivox DCO campaign workbooks — audiences, treatments, asset variants and rotation weights
## Ticketing Systems
Streamline content workflows with Jira integration
Connect content tasks with Workfront projects
Integrate with Wrike for project management
Connect with Asana for project and task management
Automatically ingest board items and sync results back to your monday.com boards
Ingest work items by project, area path, type, state or WIQL, and sync results back
## Custom Integrations & APIs
Connect Gradial to your own tools via Model Context Protocol (MCP)
Contact your Gradial representative to explore additional integration possibilities for your specific use case.
# Google Drive
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/google-drive
Connect Google Drive so Grady can find, read and file documents — scoped to exactly the folders you share with it, and never able to delete anything.
## Why connect Google Drive
A large share of the context Gradial needs already lives in Drive. The campaign brief. The approved copy deck. The product spec. The spreadsheet listing 200 pages and what each one needs. Today that context reaches Grady by someone downloading a file and attaching it — which works, but means every request starts with a manual step, and the version attached is whatever was current when the person remembered to download it.
Connecting Drive lets Grady go and get the file itself, and put results back where the rest of the team will look for them.
***
## What Grady can do
| Capability | Detail |
| :--------------------- | :-------------------------------------------------------------------------- |
| Browse folders | Navigate the folder structure that has been shared with Gradial |
| Search content | Find files by name and content across the shared scope |
| Read file metadata | Names, types, sizes, modified dates, and folder location |
| Download into the task | Pull a document into the working context so Grady can read and work from it |
| Create folders | Organize output into new folders inside the shared scope |
| Upload files | File documents, reports and artifacts Gradial produced back into Drive |
**Nothing is ever deleted.** The Drive connection has no delete, move, or share operation. Grady can read, create and upload — it cannot remove or relocate your files, and it cannot change who else can see them.
***
## How access is scoped
This is the part worth understanding before you set it up, because it differs from how most integrations work.
Gradial connects using a **Google service account** — a distinct Google identity with its own email address. That identity starts with access to nothing. It can only reach a folder or file that someone has explicitly **shared with it**, exactly as you would share with a colleague.
That means:
* **You control scope through Drive's own sharing, not through a setting in Gradial.** Share the three folders Grady should see, and those three folders are the entire world it can reach.
* **Revoking access is instant and happens in Drive.** Un-share a folder and it becomes unreachable, with no change needed in Gradial.
* **There is no organization-wide access.** The service account is not a domain-wide delegate; it cannot enumerate or reach content nobody has shared with it.
***
## Prerequisites
* A Google Cloud project where you can create a service account
* Permission to create a service account key (JSON)
* A Google Drive user or administrator who can share folders with the service account address
***
## Set up the connection
In the Google Cloud console, create a service account dedicated to Gradial. Give it a name that makes its purpose obvious to whoever audits your Drive sharing later — `gradial-drive` rather than `svc-account-3`.
Enable the **Google Drive API** on the project.
Generate a key for the service account and download the JSON file. Handle it as a credential — it grants whatever the service account can reach.
Gradial connections carry exactly one scope. Pick the narrower one unless you need uploads.
| Scope | Grady can | Choose this when |
| :------------------- | :---------------------------------------------- | :------------------------------------------------------- |
| **Read-only** | Browse, search, read metadata, download | Drive is a source of briefs and reference documents |
| **Full (non-admin)** | The above, plus create folders and upload files | You also want Gradial to file its output back into Drive |
Even on the full scope, deletion and sharing changes remain unreachable — Gradial never constructs those requests.
Go to **Settings → Integrations**, find **Google Drive** under Productivity & collaboration, and select **Connect**. Provide a name, paste the service-account JSON, and choose the scope from the previous step. Save — Gradial validates the credential against Drive and reports the result immediately.
Copy the service account's email address (it appears in the JSON as `client_email`, and ends in `.iam.gserviceaccount.com`). In Google Drive, share each folder Grady should work with to that address.
Grant **Viewer** for read-only use, or **Editor** where you want Grady to be able to upload into that folder.
Ask Grady to list what it can see in Drive. It should return exactly the folders you shared — no more. If a folder you expected is missing, it hasn't been shared with the service account address.
A clean pattern: create one Drive folder called something like *Gradial* with subfolders for briefs in, deliverables out, and reference material. Share that one parent folder. Scope stays obvious, and anyone auditing later can see the whole arrangement in one place.
***
## Troubleshooting
| Symptom | Cause | Fix |
| :--------------------------- | :----------------------------------------------------------------------------------- | :------------------------------------------------------------------------ |
| Grady sees nothing in Drive | No folders shared with the service account yet | Share at least one folder with the `client_email` address from the JSON |
| A specific folder is missing | That folder isn't shared, or is shared with a person rather than the service account | Share it directly with the service account address |
| Uploads fail but reads work | The connection uses the read-only scope, or the folder is shared as Viewer | Reconnect with the full scope, and share the destination folder as Editor |
| Connection rejected on save | The JSON key is malformed, revoked, or the Drive API isn't enabled on the project | Regenerate the key and confirm the Drive API is enabled |
| Requests intermittently fail | Google is rate-limiting the project | Retry; if it persists, check quota on the Cloud project |
***
## Who this is for
| Role | What this unlocks |
| :------------------------- | :-------------------------------------------------------------------------------------------- |
| **Campaign Manager** | Pointing Grady at the brief in Drive instead of downloading and re-attaching it |
| **Content Ops** | Deliverables filed back where the team already looks for them |
| **Marketing Ops** | Change lists and trackers read straight from the spreadsheet of record |
| **Brand / Legal Reviewer** | Copy docs and QA reports arriving in a shared folder, in a format you already review in |
| **IT / Security** | Scope controlled through Drive's own sharing model, with no delete capability to reason about |
***
## Availability
**Access:** Must be enabled for your organization. Contact your Gradial team to get access.
# HubSpot
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/hubspot
Use Grady as one conversational interface for HubSpot email — turn a campaign brief into a branded marketing email, review it, and publish with approval.
## Overview
The HubSpot integration gives marketing teams one conversational interface for HubSpot email operations. Hand Grady an approved campaign brief and it can create a branded HubSpot marketing email, apply the edits you describe, and surface a rendered preview for review — while HubSpot continues to operate underneath as the connected system of record.
The HubSpot integration must be enabled for your organization by the Gradial team, and a HubSpot portal must be connected through OAuth. Contact your Gradial team for access and setup guidance.
### Why use Gradial with HubSpot
Building a campaign email normally means translating a brief across several applications by hand — copying headlines into a template, hunting down the right approved layout, swapping images, checking every link. The HubSpot integration collapses that into a single conversation:
* **The brief becomes the input** — describe or attach the approved brief instead of retyping it into an editor
* **Approved structure is preserved** — start from an existing branded email rather than rebuilding styling and sender configuration
* **Review happens in the thread** — open a rendered preview without leaving Gradial
* **Publishing stays deliberate** — sending is always a separate, human-approved action
***
## What Grady can do
### Turn a campaign brief into an email draft
Give Grady an approved campaign brief and it creates a new HubSpot marketing email from it — no manual translation of the brief across multiple tools.
### Reuse a branded template
Grady can clone an existing HubSpot email so the new draft inherits approved structure, styling, sender configuration, and branding.
Cloning does not copy recipient lists. If the new email needs an audience, prepare one explicitly — see [Audience support](#audience-support) below.
### Edit a designed email
Grady can update supported modules in a designed email and verify that each requested change was actually applied:
| Element | What Grady can change |
| ------------------ | ------------------------------------------------------------------- |
| **Rich text** | Body copy, headlines, and supported text content |
| **Buttons** | Button label and destination |
| **Images** | Replace the image itself |
| **Image links** | The destination an image points to |
| **Email settings** | Subject line, preview text, sender, subscription type, and audience |
### Produce a reviewable artifact
Grady publishes a rendered email preview directly in the thread so you can review the result without switching tools. When the preview can't fully represent the final email, Grady flags it clearly so you know to complete exact review in HubSpot.
### Audience support
When your workflow includes audience preparation, Grady can find an existing HubSpot contact list or create a new one and attach it to the email.
### Publishing
Publishing is a real send. It remains a separate action that requires explicit human approval and is validated against the final email content before it goes out.
Publishing sends the email. Grady will not publish without explicit human approval, and publishing depends on the connected portal's HubSpot permissions and portal eligibility.
***
## Example prompt
```
Using the attached "Gradial Frontier 2026: Post-Event" campaign brief, clone our
approved HubSpot marketing email and create a new draft for Audience 1: All attendees.
Preserve the existing header and branding. Rewrite the subject, preview text, body copy,
and CTA to match the brief, verify every edited module and link, and show me the
rendered artifact. Do not publish the email.
```
***
## Setup and permissions
Contact your Gradial team to enable the HubSpot integration for your organization. This gates HubSpot setup, OAuth, and Grady's HubSpot capabilities.
A Gradial organization admin connects the HubSpot portal to Gradial through OAuth.
What Grady can do is bounded by the OAuth permissions the connected portal grants:
* **Email drafting** requires HubSpot content access
* **Image replacement** requires files access
* **Audience preparation** requires CRM Lists access
* **Publishing** additionally requires an eligible HubSpot portal and the appropriate HubSpot permission
Once connected, authorized workspace users can run the Grady email workflow. All HubSpot operations remain limited by the connected portal's granted permissions.
***
## Current limitations
* **Designed-email editing is module-scoped.** Only supported text, button, image, and image-link modules can be edited.
* **The Gradial artifact is a simplified review surface.** Incomplete previews require exact final review in HubSpot.
* **Cloning does not copy recipient lists.**
* **No test sends.** HubSpot does not expose a public marketing-email test-send API, so Grady cannot trigger one.
* **Publishing is a real send** and always requires explicit human approval.
### Not in this release
This release covers HubSpot email operations with optional audience support. Contacts, companies, deals, pipelines, associations, engagement summaries, forms, campaign import, owners, and standalone file-management workflows are out of scope.
***
## Related
* [CRM & Email →](/docs/campaign-management/crm-email) — how Gradial manages email templates and content at scale across every connected platform
* [Cross-Channel Campaigns →](/docs/campaign-management/cross-channel-campaigns) — coordinating campaign work across channels
* [Integrations Overview →](/docs/integrations-administration-and-setup/integrations/get-started-with-integrations)
# Marketo
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/marketo
How to set up and configure Gradial with Adobe Marketo Engage — a CRM platform — using OAuth 2.0 Client Credentials authentication.
## Overview
Gradial integrates with Marketo Engage to enable content synchronization, personalization token management, and email asset operations at scale. You can build and update email templates, manage programs, smart campaigns and smart lists, maintain landing pages and forms, and keep reusable content items — including Snippets and Tokens — current within your Marketo instance.
## Authentication Method
Marketo uses OAuth 2.0 Client Credentials for API authentication. This server-to-server authentication method is ideal for automated integrations as it doesn't require user interaction after initial setup.
### OAuth 2.0 Client Credentials
**Required for all Marketo integrations.** This authentication method uses a Client ID and Client Secret to obtain access tokens directly from Marketo's identity service. Tokens are automatically refreshed by Gradial as needed.
## Prerequisites
Before starting the integration, ensure you have:
* Admin access to your Marketo instance
* Permission to create API-only users and custom services
* Your Marketo Base URL (typically `https://[instance-id].mktoweb.com`)
## Integration Steps
### Step 1: Create an API-Only User in Marketo
**What this step does:** Creates a dedicated user account that Gradial will use to authenticate with Marketo's REST API.
1. Log in to your Marketo instance
2. Navigate to **Admin** → **Users & Roles**
3. Click the **Roles** tab
4. Click **New Role** and create a role with the following permissions:
* **Access API** (required)
* **Read-Write Assets** (for landing pages and emails)
* **Read-Only Lead Database** (if personalization features are needed)
5. Click the **Users** tab
6. Click **Invite New User**
7. Fill in the user details:
* **Email:** Use a service account email (e.g., `gradial-api@yourcompany.com`)
* **First Name:** `Gradial`
* **Last Name:** `Integration`
8. On the permissions step, check **API Only**
9. Assign the role you created in step 4
10. Click **Send** to create the user
> **Note:** API-Only users do not consume a Marketo user license and cannot log in to the Marketo UI.
### Step 2: Create a Custom Service (LaunchPoint)
**What this step does:** Creates the OAuth client application that generates the Client ID and Client Secret needed for authentication.
1. Navigate to **Admin** → **Integration** → **LaunchPoint**
2. Click **New** → **New Service**
3. Configure the service with the following values:
* **Display Name:** `Gradial`
* **Service:** Select **Custom**
* **Description:** `Gradial CMS Integration`
* **API Only User:** Select the user created in Step 1
4. Click **Create**
### Step 3: Retrieve OAuth Credentials
**What this step does:** Obtains the Client ID and Client Secret that Gradial needs to authenticate.
1. In the LaunchPoint services list, find the **Gradial** service you just created
2. Click **View Details**
3. Note the following values:
* **Client ID**
* **Client Secret**
> **Important:** Keep the Client Secret secure. This credential provides access to your Marketo instance and should be treated as a sensitive security credential. If compromised, you can regenerate the secret from the LaunchPoint service details.
### Step 4: Find Your Marketo Base URL and Identity URL
**What this step does:** Retrieves the endpoint URLs needed for API authentication.
1. Navigate to **Admin** → **Integration** → **Web Services**
2. Under the **REST API** section, note:
* **Endpoint URL:** This is your Marketo Base URL (e.g., `https://123-ABC-456.mktoweb.com`)
* **Identity URL:** This is used for token generation (e.g., `https://123-ABC-456.mktorest.com/identity`)
> **Note:** The Identity URL is used as the Token URL Override if your Marketo instance uses a non-standard configuration.
### Step 5: Configure the Integration in Gradial
**What this step does:** Connects Gradial to your Marketo instance using the credentials obtained in previous steps.
Create campaigns from a prepared payload, search existing campaigns, fetch campaign metadata, change status (launch, pause, stop), and send test campaigns to a list of test addresses.
List, fetch, create, and update email templates. Read a template with referenced content blocks resolved into a single merged composition so reviewers see the final output rather than raw placeholders.
List blocks by search text, content type, or status. Fetch, create, and update HTML or text blocks. Name validation is enforced upfront so the API never rejects a create.
Build a normalized preview artifact for offers, inbox cards, or campaign shells that reference content managed elsewhere — capturing placement, audience, lifecycle, custom fields, and a template-shaped preview.
***
## Prerequisites
* Admin access to your MoEngage dashboard to generate API tokens
* Your MoEngage **Data Center / API Base URL** and **Workspace ID** from **Settings → APIs → API Settings**
* A Gradial organization **Administrator** role to complete setup
***
## How to Connect
1. Sign in to your **MoEngage dashboard** as a workspace admin.
2. Open **Settings → APIs → API Settings** and copy your **Data Center / API Base URL** (e.g., `https://api-101.moengage.com`). MoEngage assigns this per region — always copy it from the dashboard rather than guessing.
3. Copy the **Workspace ID** (also shown as the workspace `app_id`) from the same page.
4. Create a dedicated API token for Gradial. MoEngage scopes tokens by API family — generate the one that matches your intended workflows:
| Token Type | Enables |
| --------------- | ------------------------------------------------------------------- |
| **Campaign** | Campaign create/search/meta/status/test and content block authoring |
| **Data** | Read-only audience and analytics lookups |
| **Inform** | Transactional and inform APIs |
| **Personalize** | Personalization and content-reference APIs |
5. MoEngage returns a workspace and API secret pair. Base64-encode `workspace:api-secret` — this is the token value you'll paste into Gradial.
Always create a dedicated MoEngage API token for Gradial rather than reusing a broad shared key. Scope it to the API family you need and add additional tokens later if a workflow requires a different scope. Gradial stores credentials encrypted and never exposes them to the agent.
1. In Gradial, go to **Settings → Integrations**.
2. Find **MoEngage** and click **+ Add**.
3. Fill in the connection details:
| Field | Value |
| ------------------------- | ------------------------------------------------------------------------- |
| **Integration Name** | A display name (e.g., `My MoEngage Workspace`) |
| **MoEngage API Base URL** | Your data-center origin (e.g., `https://api-101.moengage.com`) |
| **Workspace ID** | The workspace `app_id` |
| **API Token Type** | `campaign`, `data`, `inform`, or `personalize` |
| **API Token** | Your Base64-encoded `workspace:api-secret` token, with the `Basic` prefix |
4. Click **Save**. Gradial validates the workspace, base URL, and credential scope during setup.
1. Go to **Settings → Environments** and select the Gradial Environment where MoEngage should be available.
2. Add the MoEngage integration to that Environment.
3. Repeat for any additional Environments.
***
## How It Fits Into Broader Workflows
| Use case | How to use it |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **End-to-end email authoring** | Author email templates and content blocks from the same Gradial thread that produced the brief, copy, or designs |
| **Campaign execution** | Prepare a payload, run a test send, change status, and verify with a follow-up search — all from chat |
| **Content-reference offers** | Stage inbox messages, in-app cards, or offers whose creative lives in a DAM or CMS — the offer artifact captures placement, audience, and lifecycle before any MoEngage write happens |
| **Cross-integration campaigns** | Combine MoEngage with Bynder for approved creative, your CMS for landing pages, and Gradial's asset search to assemble a campaign end-to-end in one workflow |
**Example workflow:**
1. Start with a campaign brief — for example, "send a welcome email to new sign-ups."
2. List existing content blocks to find reusable hero copy or footers; create or update blocks as needed.
3. Draft the email template with resolved HTML and any content block references, then read it back to confirm the merged composition.
4. Build a content-reference offer artifact capturing audience, placement, and lifecycle so reviewers can preview the card before any send.
5. Send a test campaign to the QA distribution list and iterate until the rendered output is right.
6. Create the live campaign and change status to launch it once approvers sign off.
7. Re-run campaign search to confirm the campaign is active and surface the artifact in the thread for stakeholders.
***
## Support
Contact your Gradial onboarding lead or email [support@gradial.com](mailto:support@gradial.com) for help with setup.
# Salesforce Marketing Cloud
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/salesforce-marketing-cloud
Connect Gradial to Salesforce Marketing Cloud to build emails, organize campaigns, and orchestrate journeys from a single flow.
Connect Marketing Cloud once and Gradial can build emails, organize campaigns, and orchestrate journeys — with reviewers able to click straight from a Gradial artifact back into the Marketing Cloud UI whenever they want to finish in their familiar tool.
***
## What You Can Do
Browse Content Builder folders. Draft new emails from chat — HTML, text-only, or from a template. Update subject lines, preheaders, and body content. Preview the rendered email inline before sending.
Create campaigns with names, codes, and color tags. List, view, and delete campaigns. Attach or remove email assets from a campaign. Open any campaign straight in the Marketing Cloud UI.
View existing journeys. Draft new journeys from built-in templates: single email, drip, decision split, and random split. Update activity wiring, copy, wait durations, and decision criteria. Publish journeys when ready.
Read existing templates so Gradial can reference them when drafting new emails. Template authoring stays in the SFMC UI for now.
***
## Prerequisites
* Admin access to your Salesforce Marketing Cloud account
* Permission to create **Installed Packages** in Marketing Cloud
* Your Marketing Cloud subdomain (found in your account URL)
* A Gradial organization **Administrator** role to complete setup
***
## How to Connect
1. Log in to Salesforce Marketing Cloud.
2. Navigate to **Setup → Platform Tools → Apps → Installed Packages**.
3. Click **New**, enter a name (e.g., `Gradial`) and description, then click **Save**.
1. In the newly created package, click **Add Component → API Integration**.
2. Choose **Server-to-Server** and click **Next**.
3. Grant the scopes the team needs:
| Category | Permission | Required |
| ------------------------ | -------------------------- | -------- |
| **Email** | Read, Write, Send, Publish | Yes |
| **Documents and Images** | Read, Write | Yes |
| **Campaign** | Read, Write | Yes |
| **Journeys** | Read, Write, Execute | Yes |
| **Event Definitions** | Read | Yes |
| **Data Extensions** | Read | Optional |
| **Tracking Events** | Read | Optional |
4. Click **Save**.
From the Installed Package details page, copy:
* **Client ID**
* **Client Secret**
* **Authentication Base URI** (e.g., `https://mcXXXXXX.auth.marketingcloudapis.com`)
* **Account ID (MID)** — the business unit's Member ID
Keep the Client Secret secure. If you navigate away, it will be hidden. You can regenerate it, but doing so will invalidate any existing integrations using the old secret.
1. In Gradial, go to **Settings → Integrations**.
2. Find **Salesforce Marketing Cloud** and click **+ Add**.
3. Fill in the connection details:
| Field | Value |
| ---------------------- | ----------------------------------------------------------------------------------- |
| **Integration Name** | A display name (e.g., `Acme Marketing Cloud — Production BU`) |
| **SFMC Auth Base URL** | Your Authentication Base URI (e.g., `https://mcXXXXXX.auth.marketingcloudapis.com`) |
| **Client ID** | From step 3 |
| **Client Secret** | From step 3 |
| **Account ID (MID)** | The business unit's Member ID |
4. Click **Save**. Gradial validates the credentials before the integration goes live.
5. *(Optional)* Choose a default Content Builder folder for new email assets.
1. Go to **Settings → Environments** and select the Gradial Environment where SFMC should be available.
2. Add the integration to that Environment.
3. Repeat for any additional Environments.
***
## How It Fits Into Broader Workflows
| Use case | How to use it |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Email to campaign in one thread** | Draft the email and attach it to a campaign in the same Gradial thread that produced the brief or copy |
| **Journey authoring** | Plan welcome, drip, and A/B journeys end-to-end from chat — entry source, emails, wait durations, branches, publish |
| **Inline QA** | Use Gradial's inline email preview to QA the rendered email; click into Marketing Cloud from a campaign or journey artifact when reviewers want the SFMC canvas |
| **Cross-integration workflows** | Combine SFMC with DAM, asset search, image generation, and content gen so a single thread can produce the creative, place it in Content Builder, and drop it into a journey |
**Example — Build and attach an email to a campaign:**
1. Ask Gradial to find (or create) the right Content Builder folder.
2. Have Gradial draft a new email — subject line, preheader, and body copy.
3. Ask Gradial to create a campaign with a name and code.
4. Attach the new email to the campaign in the same turn.
5. Open the campaign artifact and click into Marketing Cloud when the team is ready to launch.
**Example — Draft a welcome journey:**
1. Ask Gradial to list the available entry sources.
2. Pick one of the bundled templates — single email, drip, decision split, or random split.
3. Tell Gradial which email to send, how long to wait, and how to branch.
4. Publish the journey when it's ready.
***
## What's Not Covered Yet
* Stopping, pausing, or republishing a journey — only the initial publish is supported from Gradial.
* Authoring new entry-source event definitions — Gradial can see them, not create them.
* Activity types beyond Email, Wait, Decision Split, and Random Split (SMS, Push, Update Contact, etc.).
* Automation Studio workflows.
* Template authoring.
***
## Multi-Business Unit Configuration
**Parent-Level Access** — Create one Installed Package at the Parent Business Unit level with access to all child Business Units. Use the Parent MID when configuring Gradial.
**Business Unit-Specific Access** — Create separate Installed Packages for each Business Unit that requires isolation. Configure multiple integrations in Gradial, one per Business Unit.
***
## Troubleshooting
| Issue | Cause | Solution |
| ------------------------------- | ------------------------------------ | ------------------------------------------- |
| `invalid_client` error | Incorrect Client ID or Secret | Verify credentials in the Installed Package |
| `unauthorized` error | Package lacks required permissions | Add missing scopes to the API component |
| `invalid_request` error | Incorrect subdomain or Auth URI | Check the Authentication Base URI |
| `insufficient_privileges` error | MID doesn't match package assignment | Verify the MID and Business Unit access |
***
## Good to Know
* **Inline previews are safe to share**: Gradial renders email previews through a server-side proxy that strips unsafe HTML.
* **Campaign updates are narrow**: Marketing Cloud's campaign API only allows a small set of updates. To rename or recolor a campaign, delete and recreate it through Gradial, or edit it in the Marketing Cloud UI.
* **Publishing a journey is asynchronous**: once Gradial publishes, Marketing Cloud takes a moment to transition the journey through its internal states.
***
## Support
Contact your Gradial onboarding lead or email [support@gradial.com](mailto:support@gradial.com) for help with setup.
# Sanity
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/sanity
Connect Gradial to Sanity to automate content authoring, updates, and publishing workflows across your Sanity datasets.
Sanity is a headless CMS built around a real-time, structured content platform. Content is stored as portable, schema-driven documents in Sanity's cloud-hosted Content Lake and managed through Sanity Studio — a fully customizable editing environment your team can adapt to any content model. Because Sanity exposes all content through a flexible API, it works equally well as the content backbone for websites, apps, and multi-channel publishing pipelines.
Connect Sanity once and Gradial can read and write live content directly — enabling authoring, optimization, and publishing workflows without switching systems.
***
## What You Can Do
Read documents, schemas, and assets across your Sanity datasets so Gradial always works with real content rather than static exports.
Create and update documents. Publish and unpublish content. Run bulk update workflows with validation.
Upload and manage images and file assets alongside content work.
Preview content before publishing when a preview URL is configured for your Sanity Studio.
***
## Prerequisites
Before connecting Sanity to Gradial, make sure you have:
* Access to the **Sanity management console** ([sanity.io/manage](https://sanity.io/manage)) with permission to create API tokens
* Your Sanity **Project ID** (visible in the project overview)
* The **dataset name** Gradial should use (commonly `production`)
* A Gradial organization **Administrator** role to complete setup
***
## How to Connect
1. Sign in to [sanity.io/manage](https://sanity.io/manage) and open your project.
2. Go to **API → Tokens** and click **+ Add API token**.
3. Give the token a descriptive name (e.g., `Gradial Integration`).
4. Set the **Permissions** to **Editor** — this grants read and write access to all datasets, with limited access to project settings.
5. Click **Save** and copy the token immediately — it is only shown once.
The API token is shown only once at creation time. If you lose it, you will need to delete it and generate a new one.
Your **Project ID** appears on the project overview page in [sanity.io/manage](https://sanity.io/manage). The default dataset is typically named `production` — confirm the dataset name under **Datasets** in the same project.
1. In Gradial, go to **Settings → Integrations**.
2. Find **Sanity** and click **+ Add**.
3. Fill in the connection details:
| Field | Value |
| -------------------- | ------------------------------------------------ |
| **Integration Name** | A display name (e.g., `My Sanity Connection`) |
| **Project ID** | The Project ID from your Sanity project overview |
| **Dataset** | The dataset name (e.g., `production`) |
| **API Token** | The Editor token generated in Step 1 |
4. Click **Save**. Gradial validates the connection and uses the specified dataset in all downstream workflows.
1. Go to **Settings → Environments** and select the Gradial Environment where Sanity should be available.
2. Add the Sanity integration to that Environment.
3. Repeat for any additional Environments.
***
## Troubleshooting
**Token rejected at save**
Confirm the token was copied in full with no trailing spaces, and that it was created with **Editor** permissions.
**Dataset not found**
Verify the dataset name matches exactly what appears under **Datasets** in your Sanity project. Dataset names are case-sensitive.
**Integration not available in a Workspace**
Assign the integration to the correct Gradial Environment under **Settings → Environments**.
***
## Support
Contact your Gradial onboarding lead or email [support@gradial.com](mailto:support@gradial.com) for help with setup.
# SharePoint
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/sharepoint
Connect your SharePoint document libraries so Grady can find, read, tag, and file documents — inside the folders you explicitly allow, and never with the ability to delete.
## Overview
The SharePoint integration lets Grady work directly in your Microsoft SharePoint Online document libraries. It can inventory sites and libraries, browse folders, read file metadata and managed-metadata tags, search across document content, pull files into a working session, and file new documents back into the folders you choose — with tags applied.
Access is deliberately narrow. You pick the exact folders Grady may touch and whether each is read-only or read-and-write. Until you pick at least one, Grady can access nothing.
**Access:** Must be enabled for your organization. Contact your Gradial team to get access.
### Why use Gradial with SharePoint
Most marketing teams keep briefs, brand guidelines, case studies, decks, and approved assets in SharePoint — then spend real time hunting through it and hand-carrying files into other systems. With SharePoint connected:
* **Grady finds things by meaning, not folder memory** — full-text search across document content, not just file names
* **Documents become inputs** — Grady can read a Word doc, compare two PDFs, or check hero-image dimensions without you downloading anything
* **SharePoint becomes a destination** — generated documents get filed into the right folder with the right tags
* **It bridges to your other connected systems** — pull assets out of SharePoint and into your CMS, or attach documents to Workfront tasks, in one conversation
***
## What Grady can do
| Capability | What it means |
| ----------------------- | --------------------------------------------------------------------------------------------------------- |
| **Inventory** | List reachable sites and their document libraries |
| **Browse** | Page through a folder's files and subfolders |
| **Read metadata** | File size, image dimensions, and list-item column values including managed-metadata tags and descriptions |
| **Search** | Full-text search over document content and file names, within an allowed folder |
| **Download** | Pull a file into the working session to read, parse, compare, or migrate |
| **Upload** | File a document into a library folder, optionally setting its columns and tags |
| **Create folders** | Add a folder inside a library |
| **Update fields** | Set tags, descriptions, and other column values on an existing item |
| **Show its own access** | Report exactly which folders it can read and write, and test that they're reachable |
### What Grady can never do
Deletion, moving, copying, sharing, and publishing are not restricted by policy — those operations do not exist in the integration at all. There is no way to phrase a request that removes, relocates, or externally shares a SharePoint file through Grady.
Microsoft's consent screen lists broader permissions, **including delete**. That's a limitation of how Microsoft describes permission bundles — Gradial requests write access because applying tags and columns requires it. The integration itself has no delete operation.
***
## How access works
Two independent boundaries apply, and both must allow an action:
Grady acts as the person who connected the integration. It can never see or do more in SharePoint than that person can. Your existing SharePoint permissions remain the outer limit.
Within that, you narrow further — Grady is confined to an explicit list of folders, each marked read-only or read-and-write.
Because Grady acts as the connecting user, connect SharePoint using an account whose access covers the folders you intend to allow — and one that will persist. If that person leaves the organization, loses their SharePoint access, or has their session revoked, the integration stops working for everyone and an admin must reconnect it.
The allow-list fails closed. A newly connected SharePoint integration with no folders configured grants Grady **no access at all**. Requests for anything outside the list are refused, searches only ever return in-scope results, and folder counts reflect only in-scope items — so Grady never reports or reasons about content you haven't shared with it.
***
## Before you start
You'll need:
* **A Gradial organization admin** — connecting an integration requires the Manage settings permission in Gradial
* **A Microsoft work or school account** with access to the SharePoint sites you want to connect
* **Microsoft administrator involvement, in most cases** — see below
* **The folder URLs** you want Grady to use, ready to paste
### Do you need a Microsoft admin?
**Usually yes, in practice.** The Microsoft Graph permissions Gradial requests are not, by Microsoft's own definition, admin-consent-required — a regular user is technically able to approve them for themselves. However, most enterprise Microsoft 365 tenants disable user consent entirely as a matter of policy. In those tenants the approval must come from a Microsoft administrator, who can either:
* Grant tenant-wide admin consent to the Gradial application, or
* Perform the connection themselves
Plan for a Microsoft admin to be involved. If you're not sure how your tenant is configured, the fastest path is to have a Microsoft 365 administrator complete the connect flow — it takes a few minutes and removes the guesswork.
***
## Connect SharePoint
In Gradial, go to **Settings → Integrations**, find **SharePoint**, and start the connect flow.
The **Add SharePoint** dialog explains what happens next. Read the notice — it covers the two things people most often ask about: that a Microsoft administrator may need to approve access, and that Microsoft's approval screen lists broader permissions than Gradial actually uses.
Select **Connect with Microsoft**. You'll be taken to Microsoft to sign in and approve access. If your tenant requires administrator approval, the flow will say so — hand it to a Microsoft admin at that point.
Once approved, you're returned to Gradial with the connection established but **no folders yet allowed**. Grady still can't access anything.
Gradial opens the folder picker immediately after connecting. You can also reopen it later from the SharePoint integration row.
Each row in the **Choose SharePoint folders** dialog is one allowed folder. The fastest way to add a folder is to paste its URL:
1. Open the folder in SharePoint in your browser
2. Copy the URL from the address bar
3. Paste it into **Paste a SharePoint folder URL** and select **Add**
Gradial resolves the URL into the correct **Site**, **Document library**, and **Folder** — you don't need to know SharePoint's internal naming. For example, a pasted URL might resolve to site `sites/Gradial`, library `Documents`, folder `Grady Dev`.
Prefer to type the values yourself? Use **Add Manually** and fill the three fields directly. Leave **Folder** blank to allow the whole library, and leave **Site** blank for your tenant's main site.
Each folder has its own **Access** setting:
* **Read only** — Grady can browse, read metadata, search, and download. Uploads, folder creation, and tag changes are refused.
* **Read & write** — Grady can additionally file documents into the folder, create subfolders, and set tags and column values.
Grant read-and-write only where Grady genuinely needs to file work back. A read-only folder is a hard boundary, not a preference.
Select **Test Read Access** to check that each folder is actually reachable with the connected account's permissions. A folder that comes back unreachable is usually a typo in a manually entered path, or a folder the connecting user can't actually see.
Select **Save** to apply the list. Changes take effect immediately.
Go to **Settings → Environments**, select the Environment you want SharePoint available in, and add the SharePoint integration to it. This makes it available to all Workspaces in that Environment. Repeat for any other Environments that need it.
If a Workspace isn't seeing SharePoint, check this first — an unassigned integration is the most common cause.
### Adding or changing folders later
Reopen the folder picker from the SharePoint integration row at any time. Add folders as new work comes in, change an access level, or remove a folder with the delete icon on its row. Removing a folder immediately revokes Grady's access to it.
***
## Limits
* **Uploads and downloads are capped at 250 MB per file.**
* **Uploads never overwrite.** If a file of the same name already exists, the upload is saved under a slightly different name rather than replacing the existing document.
* **Tags may lag an upload.** Grady can file a document and set its tags in one step. If the file lands but the tag update fails, Grady tells you the document is uploaded but **not** tagged, and can set the tags in a follow-up step. Treat that warning as real — don't assume tagging succeeded.
* **Search is scoped to one allowed folder at a time**, not the whole tenant.
* **Tags are read one item at a time.** Managed-metadata values come back reliably when Grady inspects a single item, not from bulk folder listings.
***
## Troubleshooting
| What you see | What it means |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Grady says a path isn't available** | The folder is outside the allow-list. Add it in the folder picker, or point Grady at a folder that is on the list. Grady won't retry — the answer won't change. |
| **Grady refuses to upload or tag** | The destination is a **Read only** folder. Change it to **Read & write** if that's intended. |
| **A folder tests as unreachable** | Either the path is wrong, or the connecting user can't see that folder in SharePoint. Confirm the path by pasting the folder URL instead of typing it. |
| **The connection needs reconnecting** | Delegated Microsoft access can be invalidated by a password change, a Conditional Access policy requiring re-authentication, or an admin revoking consent. An admin reconnects from **Settings → Integrations**. |
| **A Workspace can't use SharePoint** | The integration isn't assigned to that Workspace's Environment. |
***
## Example prompts
```
Search our SharePoint case studies folder for manufacturing customers and
summarize the three most recent ones.
```
```
Read the messaging section of Brand/Guidelines/brand.docx in SharePoint and
tell me whether the attached draft follows it.
```
```
Take every image in the Brand Assets/2026 folder in SharePoint, carry each
image's description across as alt text, and upload them to your CMS.
```
```
Write the Atlas launch case study as a Word document and file it in our
SharePoint case-studies folder, tagged for the Atlas campaign.
```
***
## Related
* [Box →](/docs/integrations-administration-and-setup/integrations/box) — the same document workflows, with Box's collaborator-based access model
* [Office Docs →](/docs/campaign-management/office-docs) — how Gradial creates and works with Word, Excel, and PowerPoint files
* [Digital Asset Management →](/docs/asset-management/digital-asset-management)
* [Integrations Overview →](/docs/integrations-administration-and-setup/integrations/get-started-with-integrations)
# Searching in Content Hub
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/sitecore-content-hub
Write effective prompts for Gradial's Content Hub agent — covering keyword searches, taxonomy filtering, and multi-step discovery workflows.
Gradial's Content Hub agent can find assets, content, campaigns, taxonomy items, and any other entity type in your Content Hub instance. This guide covers how to phrase your requests effectively — from simple everyday searches to advanced multi-step discovery workflows.
***
## Simple Searches
### Keyword Searches
The simplest way to find something is to describe it in plain language. The agent searches across titles, descriptions, filenames, and other text fields.
> "Find assets about airplanes"
> "Search for content related to product launches"
> "Show me assets with 'sustainability' in the description"
Be specific about the **type of entity** you want. The agent can search assets, content, campaigns, and more — naming the type helps it look in the right place.
| Vague | Clear |
| ----------------------------- | -------------------------------------------------------- |
| "Find campaign stuff" | "Find **assets** related to the summer campaign" |
| "Show me spring content" | "Find **content items** about our spring campaign" |
| "What do we have for social?" | "Search for social media **assets** for the Q2 campaign" |
When your search term could mean different things, offer alternatives:
> "Find assets about airplanes — also try aircraft, aviation, and jets"
The agent uses all of these terms to cast a wider net, which is especially helpful for jargon, abbreviations, and regional spelling differences.
### Taxonomy Searches
Taxonomies are the classification systems in your Content Hub instance — brands, asset types, tags, categories, and more. You can browse and search them directly.
**Listing what's available:**
> "What brands are set up in Content Hub?"
> "Show me all available asset types"
> "List the taxonomy categories in our instance"
**Finding a specific taxonomy item:**
> "Find the brand entry for \[your brand]"
> "Look up the 'Corporate Video' asset type"
This is useful when you want to confirm what classifications exist before filtering your asset searches.
### Filtering by Category
The agent treats **keywords** (what something is about) differently from **categories** (how something is classified). This distinction is critical for accurate results.
An asset might be tagged with a brand but never mention the brand name in its title or description. A keyword-only search would miss it entirely. When you reference a brand, tag, or category explicitly as a classification, the agent filters by the structured relationship instead of just searching text.
Searches text fields — title, description, filename
> "Find assets with 'airplane' in the title or description"
Filters by taxonomy relationships
> "Find assets tagged with the \[Brand Name] brand"
Combining both gives you the most precise results:
> "Find airplane assets from the \[Brand Name] brand"
The agent recognizes common classification language naturally:
* **Brands**: "from the \[Brand Name] brand", "branded as \[Brand Name]"
* **Asset types**: "video assets", "images", "documents"
* **Lifecycle status**: "approved assets", "assets in draft", "final content"
* **Tags**: "tagged with sustainability", "items tagged Q2 launch"
* **Campaigns**: "assets linked to the Spring 2025 campaign"
### Controlling Results
**Limiting how many results you get:**
> "Show me the first 5 airplane assets from the \[Brand Name] brand"
> "Find all approved assets tagged with the summer campaign (up to 50)"
By default you'll get around 20 results. Ask for more or fewer as needed.
**Filtering by lifecycle status:**
> "Find approved airplane images from the \[Brand Name] brand"
> "Show me assets in final status for the Q2 campaign"
### Quick Reference
| To find... | Prompt pattern |
| ------------------------- | ------------------------------------------------------------------ |
| Assets by keyword | "Find assets about \[keyword]" |
| Assets by brand | "Find assets from the \[brand name] brand" |
| Assets by keyword + brand | "Find \[keyword] assets from the \[brand name] brand" |
| Approved assets only | "Find approved \[keyword] assets" |
| Content items | "Find content about \[topic]" |
| Taxonomy items | "Show me all \[taxonomy type]" or "Look up \[name] in \[taxonomy]" |
| With synonyms | "Find \[keyword] assets — also try \[variant1], \[variant2]" |
| Limited results | "Show me the first \[N] results for \[query]" |
***
## Advanced Discovery Workflows
For more complex tasks, the agent chains multiple searches together — discovering what exists in your instance, resolving references, and then executing against those results.
### The Discovery-Then-Act Pattern
The most powerful prompts follow a two-stage pattern: first discover what's available, then act on it. The agent handles this automatically, but understanding it helps you write prompts that guide the agent efficiently.
**Example:** "Find all airplane assets from the \[Brand Name] brand and add them to the Spring 2025 campaign"
Behind the scenes, the agent will:
1. Look up "\[Brand Name]" in the brand taxonomy to find its exact ID
2. Search for assets matching "airplane" filtered to that brand
3. Look up "Spring 2025" in the campaign definitions to find its ID
4. Link the discovered assets to the campaign
Knowing this pattern helps you understand why **naming things explicitly** matters — each named reference triggers a lookup step that ensures the agent operates on the right entity.
### Multi-Step Discovery Prompts
When exploring unfamiliar territory, ask discovery questions first:
> "What types of entities are available in our Content Hub?"
> "List all campaign-related definitions in our instance"
> "What brands do we have set up?"
> "Show me the properties and relationships available on assets"
> "Now find all video assets from the \[Brand Name] brand that are in approved status"
You can collapse these into a single prompt if you're confident about the structure:
> "Find all approved video assets from the \[Brand Name] brand — if that brand doesn't exist, show me what brands are available"
This gives the agent a fallback path and avoids dead ends.
### Combining Filters Across Multiple Dimensions
The agent can layer several filters in a single search. The more dimensions you specify, the more precise your results:
> "Find approved video assets from the \[Brand Name] brand tagged with 'product launch' that are linked to the Q2 2025 campaign"
This single prompt combines entity type, brand, tag, campaign, and lifecycle status filters simultaneously.
### Working with Results Iteratively
After a search, you can ask the agent to act on the results or refine them:
> "Find airplane assets from the \[Brand Name] brand, then tag them all with the 'Aviation' category"
> "Search for draft content items from last quarter and show me their current tags"
The agent remembers search results within the conversation, so you can refine iteratively:
```
"Find airplane assets from the [Brand Name] brand"
→ agent returns results
"Now narrow that to only approved images"
→ agent refines
"Add all of those to the Spring campaign"
```
### Handling Instance Variability
Every Content Hub instance is configured differently. Definition names, taxonomy structures, and property names vary between organizations. The agent discovers your instance's actual schema rather than assuming standard names.
If you ask for something that doesn't exist, the agent will tell you what's available instead. Prompts that acknowledge this uncertainty work well:
> "Find the campaign definition in our instance — it might be called something like 'Campaign' or 'PCM.Campaign' — and then create a new one for Q3"
> "Look up what taxonomy is used for brands in our Content Hub, then find all assets tagged with \[your brand]"
***
## How the Agent Works
The agent has three distinct search capabilities:
**Entity Search** is the general-purpose workhorse. It searches for entities of any type (assets, content, campaigns, etc.) using full-text search across all indexed fields, with support for taxonomy relationships, property values, and lifecycle filters.
**Taxonomy Search** is specialized for finding items within a single taxonomy definition (brands, asset types, tags, etc.). It resolves human-friendly names to numeric IDs used as filters in entity searches.
**Definition Listing** enumerates all entity types available in the instance. This is the entry point for discovery workflows — the agent uses it to find the actual definition name for entity types in your specific instance.
The agent translates your natural language into the right combination of search parameters automatically:
* **Search strategy**: Starts with a focused, filtered query. If too few results come back, it progressively broadens — trying without the keyword, expanding with synonym variants, or running an unfiltered pass. Results from multiple passes are deduplicated and merged.
* **Keyword processing**: Your terms are searched as both the full phrase and individual words. "Product launch video" will match items containing the full phrase as well as items containing just "product", "launch", or "video".
* **Filter translation**: When you mention a brand, tag, or category by name, the agent first resolves it to a numeric ID via a taxonomy search, then applies it as a structured relationship filter. This runs server-side for efficiency.
All Content Hub search results remain fully visible to the agent throughout the conversation — results from earlier turns are not compressed or summarized. This means:
* You can search, review results, and act on them in separate messages
* The agent can cross-reference results from multiple searches
* In very long conversations with many large searches, results accumulate in context — starting a fresh conversation can help if you notice degraded performance
The agent automatically chains taxonomy lookups, multi-pass search strategies, and filtering to produce the most relevant results from your natural language prompt. The more clearly you distinguish keywords from categories and name the entity type you want, the more efficiently it navigates this pipeline.
# Sitecore Content Hub
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/sitecore-content-hub-integration
Connect Gradial's AI agents to Sitecore Content Hub to automate asset management, content creation, and campaign workflows via REST APIs.
Gradial connects with Content Hub via its published REST APIs to enable AI marketing workflows such as uploading new assets, creating Content Items, and managing Campaigns within Content Hub.
To enable this integration, Gradial requires a dedicated Content Hub user account with API access. You can either create a new user account or configure an existing one.
### Create a new Content Hub integration
Open the Content Hub Admin Console, typically located at:
`https://{your-hostname}/{your-locale}/admin`
From the **Users** page, select **New User** to add an account with access to the necessary modules.
Enable the user account to interact with the Content Hub APIs by making it an **API User**:
* In the **Users** dashboard, click the **key shield** icon on the right-hand side.
* In the modal that appears, select **New Token**.
You do not need to copy this token — once the account is designated as an API User, Gradial Agents will be able to generate new tokens automatically.
Ensure that the user account has a configured password and the correct permissions:
* Click the **information** icon on the right-hand side of the Users dashboard.
* Under the **User Groups** tab, verify the account's permissions for creating, reading, updating, and deleting entities. Typically, the **Superusers** Group and Policy encompass these permissions.
* In the **Details** tab, assign a valid email address to the account. This step is required to configure a password.
In Gradial:
1. Sign in and navigate to **Settings → Integrations**.
2. Enter the **hostname** of your Content Hub environment along with the **Username** and **Password** of the configured Content Hub user account.
3. Click **Validate Connection** to confirm permissions and ensure Gradial can authenticate.
4. Once verified, select **Create Connection** to complete the integration.
You can now connect your Content Hub integration to environments and projects within Gradial.
# Sitecore
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/sitecore-integration
Connect Gradial to the Sitecore product family — integration guides for Sitecore XM Cloud, Sitecore XP on-premises, and Sitecore Content Hub.
Gradial integrates deeply with the Sitecore product family — XM Cloud, XP, and Content Hub — to put AI agents directly inside your content supply chain. Rather than copying content out of Sitecore to work on it elsewhere, Gradial agents operate on your actual Sitecore items: reading live page content, applying changes through the authoring APIs, triggering publishing workflows, and pulling media from your library — all without a human touching the CMS.
This means your team describes what they want in plain language ("update the hero copy on the Q3 campaign page to match this brief") and Gradial handles the navigation, field editing, and publishing steps end-to-end. The same model applies to Content Hub: agents can discover assets by taxonomy, create or update content items, and link assets to campaigns without manual DAM work.
The integration also fits naturally into ticketing workflows. When a Jira or Workfront ticket triggers a Gradial task, the agent uses the connected Sitecore environment to execute the change and can post results or previews back to the ticket automatically.
Select the Sitecore product you want to connect below.
Connect Gradial to Sitecore XM Cloud using a guided setup wizard with live credential validation and site selection
Connect Gradial to Sitecore XP (on-premises) using the Service Gateway module and OIDC client credentials
Connect Gradial to Sitecore Content Hub using a dedicated API user account
# Sitecore XM Cloud
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/sitecore-xm-cloud
Connect Gradial's AI agents to Sitecore XM Cloud to automate content creation, updates, and publishing workflows via GraphQL and REST APIs.
Gradial AI agents connect with XM Cloud via Sitecore's published GraphQL and REST APIs. The integration is configured through a guided onboarding wizard in Gradial under **Settings → Integrations**.
## Prerequisites
Before starting the wizard, create **automation credentials** in the Sitecore Deploy app. These are the OAuth client credentials Gradial uses to authenticate against your environment.
Go to [deploy.sitecorecloud.io](https://deploy.sitecorecloud.io), then select **Credentials** in the left nav and open the **Environment** tab.
Click **Create credentials → Automation**.
Choose your project and environment. The environment should be the **Authoring** environment.
Click **Create** and save the credentials.
Copy the **Client Secret** now — it cannot be viewed again after this screen is closed.
### Where to find environment details
You'll need several values from your environment during onboarding. Find them in the Deploy app under **Projects → your project → Authoring Environments → Details**.
## Create a new Sitecore XM Cloud integration
Provide the base connection information:
* **Integration Name** — A human-readable label for this environment, e.g. "Staging" or "Production"
* **Description** *(optional)* — A short note to help your team identify this connection
* **Sitecore XM Cloud Hostname** — The **Environment host name** from the environment details page in the Deploy app
* **Edge API Key** — From the environment details page, open the **Preview GraphQL IDE**, click **Generate Preview API token**, and copy the API key
Enter the automation credentials you created in the Deploy app:
* **Client ID** — The automation credential Client ID
* **Client Secret** — The automation credential Client Secret
* **Audience** — The token audience (use the default)
* **Token URL** — The token URL (use the default)
Configure the first site you want Gradial to work with:
* **Available Sites** — A dropdown of all sites detected on the environment; select the one to use
* **Editing Host URL** — The [Editing Host](https://doc.sitecore.com/xmc/en/developers/xm-cloud/configure-an-external-editing-host.html) URL. Auto-populates from the site configuration
* **Live Domain** — Used for live-page URL resolution (e.g. `https://yoursite.com/about` → `/sitecore/content/yoursitecollection/yoursite/Home/about`)
* **Default Asset Path** — The default Media Library path where Gradial uploads assets. Auto-populates from the site configuration
### Multi-site support
The Gradial integration for Sitecore supports multi-site tenants. The onboarding wizard configures the **first** site of the integration. After the integration has been created, you can add more sites by editing the integration, opening the **Sites** tab, and clicking **Add Site**.
# Sitecore XP
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/sitecore-xp
Connect Gradial's AI agents to Sitecore XP to automate content creation, updates, and publishing on your on-premises or managed environment.
Gradial connects to Sitecore XP by running a lightweight **Service Gateway** module inside your CM's IIS process. The gateway exposes a secured REST API at `/_api/gradial/*` that Gradial agents call to read items, apply edits, and trigger publishing — all without VPN tunnels, additional servers, or schema changes to your Sitecore databases.
Authentication uses short-lived JWT bearer tokens issued by your existing OIDC provider (Sitecore Identity Server or a third-party IdP like Azure AD, Okta, or Keycloak). Gradial exchanges a client secret for a token on every request, so no long-lived credentials are stored on the CM server.
This page covers the on-premises / managed **Sitecore XP** integration. For Sitecore XM Cloud or Content Hub, see the [Sitecore overview](/docs/integrations-administration-and-setup/integrations/sitecore-integration).
## What you'll need
* A **Sitecore XP 10.0–10.4** CM instance reachable over HTTPS
* **Administrator access** to the CM to install files and create a service user
* Access to your **OIDC provider** (Sitecore Identity Server or equivalent) to register a client
* A **Gradial account** with permission to create integrations under Settings → Integrations
The setup takes around 30 minutes for a straightforward deployment. Allow extra time if your environment uses split-horizon networking or a non-standard identity provider.
## Steps in this guide
| Section | What you'll do |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| [1. Install the Service Gateway](#1-install-the-service-gateway-module) | Choose an install method (Sitecore package, WDP, or drop-in zip), then configure identity via the setup page |
| [2. Register the OIDC client](#2-register-gradial-as-an-oidc-client) | Create an API resource, scope, and client-credentials client in your IdP |
| [3. Service user permissions](#3-service-user-permissions) | Create a Sitecore user and grant item-level rights on the content tree |
| [4. Configuration reference](#4-module-configuration-reference) | Full reference for every gateway setting |
| [5. Create the integration in Gradial](#5-create-the-integration-in-gradial) | Enter the connection details and credentials in Gradial to go live |
When you are done, Gradial talks to your CM over HTTPS at `/_api/gradial/*`, authenticated by short-lived JWT bearer tokens issued by your OIDC provider via the client-credentials grant.
***
## 1. Install the Service Gateway module
The gateway ships as two DLLs and a config patch. It runs in-process inside the Sitecore CM IIS app domain — no separate service, no database changes, no schema updates.
**Supported versions:** Sitecore XP 10.0, 10.1, 10.2, 10.3, 10.4 (CM role).
Gradial provides the gateway in three formats. Pick the one that matches how you deploy Sitecore — all three land the same files in the CM webroot, after which you complete the shared [post-install steps](#after-installing-all-methods).
Best for a one-off manual install by a Sitecore administrator on a running CM.
**Artifact:** `Gradial.Gateway.Module--sc10.zip`
In the Sitecore Desktop, go to **Sitecore → Development Tools → Installation Wizard** (or **Control Panel → Administration → Install a package**).
Choose **Upload package**, select `Gradial.Gateway.Module--sc10.zip`, and upload it, then click **Next**.
Step through the wizard and click **Install**. The package writes the module binaries (`bin\Gradial.SitecoreXP.Gateway.*.dll`, `bin\Swashbuckle.Core.dll`) and the config patch (`App_Config\Include\Gradial\`) into the webroot. On an upgrade, accept the file-overwrite prompts.
If the wizard offers to restart the Sitecore client or application, allow it so the new assemblies load.
Best for automated CI/CD into Azure App Service or any Web Deploy–based pipeline. You download the package from your Gradial release and add it as a step in **your own** pipeline — Gradial does not deploy into your environment for you.
**Artifact:** `Gradial.Gateway.Module--sc10.scwdp.zip`
Download `Gradial.Gateway.Module--sc10.scwdp.zip` from your Gradial gateway release and store it alongside your other Sitecore deploy artifacts.
Add a Web Deploy step that syncs the package to your CM web app. In **Azure DevOps**, use the **Azure App Service deploy** task with the `.scwdp.zip` as the package. Or call `msdeploy` directly:
```bash theme={null}
msdeploy -verb:sync \
-source:package="Gradial.Gateway.Module--sc10.scwdp.zip" \
-dest:auto,computerName="https:///msdeploy.axd?site=",username="",password="",authtype="Basic"
```
Run the pipeline. Web Deploy lands the module binaries and config patch in the CM webroot and replaces any previous version cleanly on redeploy.
The WDP is built with the Sitecore Azure Toolkit and mirrors the same webroot layout as the other formats. It contains only the module binaries and configuration — no content items and no database changes.
Best when you deploy by copying files directly into the webroot (e.g. a scripted release).
**Artifact:** `Gradial.SitecoreXP.Gateway--sc10.zip`
Stop the Sitecore CM application pool before copying files.
Unzip `Gradial.SitecoreXP.Gateway--sc10.zip` into the Sitecore CM webroot (e.g. `C:\inetpub\wwwroot\\`). The archive mirrors the webroot layout:
* `bin\Gradial.SitecoreXP.Gateway.Core.dll`
* `bin\Gradial.SitecoreXP.Gateway.Sitecore10.dll`
* `bin\Swashbuckle.Core.dll`
* `App_Config\Include\Gradial\Gradial.CmGateway.config`
### After installing (all methods)
Once the files are in the webroot, finish the setup the same way regardless of install method:
This loads the gateway assemblies. `GET https:///_api/gradial/health` should now return `200 OK`. (Authenticated endpoints return `503` until you configure identity in the next step.)
If you get `404`, the gateway did not initialize — check the Sitecore log for `[Gradial.Gateway]` entries during app pool startup.
Browse to **`/sitecore/admin/Gradial.Setup.aspx`** on the CM (Sitecore administrator login required) and enter your OIDC values — **Authority**, **Expected audience**, **Allowed client IDs**, and **Required scopes** (from [Section 2](#2-register-gradial-as-an-oidc-client)); set the optional **Metadata address** / discovery options only for split-horizon setups. Click **Validate** to confirm the values are well-formed and that your identity provider's discovery document is reachable from the CM, then **Save**.
**Containerized CM (Docker / Kubernetes / any topology where the CM is recreated from an image):** the webroot — including `App_Config` — is an ephemeral container layer, so the file this page writes **does not survive a container recreate**. When it vanishes, gateway authentication breaks with `503 Identity provider unavailable`. On containers, treat this page as a **validation and smoke-test tool** (the Validate button's live discovery probe is still the fastest way to confirm the CM can reach your identity provider): make the durable configuration an `install-settings.json` on a persistent volume, or `GRADIAL_IDENTITY_*` environment variables in your compose file/manifest — both are re-applied automatically on every CM start.
Precedence note: when `install-settings.json` or `GRADIAL_IDENTITY_*` variables are present, they are authoritative on every CM start for the settings they supply — values saved through this page for those same settings are overwritten at the next app-pool recycle.
On a classic VM/IIS install the webroot is durable and this page is a perfectly good permanent configuration method.
Prefer configuration-as-code? You can supply the same identity values without the page: hand-edit the config patch (see [Section 4](#4-module-configuration-reference)), set `GRADIAL_IDENTITY_*` environment variables, or drop an `install-settings.json` in the Sitecore data folder — the last two are applied automatically on CM start. Non-identity settings such as `Gradial.Security.AllowedDatabases` are always edited in the config patch.
Create the Sitecore user referenced by `Gradial.Sitecore.ServiceUser` (default `sitecore\gradial-service`) and grant the item-level rights in [Section 3](#3-service-user-permissions).
Confirm `GET https:///_api/gradial/health` returns `200`, then run the [OIDC smoke test](#end-to-end-smoke-test) to confirm a real token is accepted.
### Uninstall
* **Sitecore package / drop-in zip:** stop the app pool, remove `bin\Gradial.SitecoreXP.Gateway.*.dll`, `bin\Swashbuckle.Core.dll`, and the entire `App_Config\Include\Gradial\` folder, then restart the app pool.
* **WDP:** remove the module step from your pipeline and redeploy, or delete the same files from the web app. The `Gradial.CmGateway.Customer.config` written by the setup page is not part of any package, so remove it by hand if you want the identity configuration gone too.
***
## 2. Register Gradial as an OIDC client
The gateway is an **OAuth 2.0 resource server** — it validates JWTs but never issues them. Token issuance is the job of your OIDC provider. You need to register three things there:
| Concept | Purpose |
| --------------------------- | ---------------------------------------------------------------------------------------------- |
| **API resource (audience)** | Identifies the gateway as a protected resource. The token's `aud` claim must match. |
| **API scope** | Permission name the caller must request to get a usable token. |
| **Client** | Gradial's identity. Has a `client_id` + `client_secret` and is authorized for the scope above. |
Gradial requests tokens with the **client credentials grant** and sends them on the `Authorization: Bearer ` header of every request.
### How the values map across the three sides
```
OIDC Provider Gateway config (Gradial.CmGateway.config)
───────────── ──────────────────────────────────────────
API resource "gradial.gateway" ───► Gradial.Identity.ExpectedAudience
API scope "gradial.cm.gateway" ───► Gradial.Identity.RequiredScopes
Client id "gradial" ───► Gradial.Identity.AllowedClientIds
Issuer URL https://id.example ───► Gradial.Identity.Authority
Discovery base URL ───► Gradial.Identity.MetadataAddress
(gateway appends /.well-known/openid-configuration;
leave empty to reuse Authority)
```
All four values must agree on both sides, or the gateway rejects tokens with `401`.
### Reference: Sitecore Identity Server
Sitecore Identity Server is based on IdentityServer4 and accepts XML patch files mounted into its container. A complete Gradial registration:
```xml theme={null}
gradial.gateway
Gradial CM Gateway
gradial.cm.gateway
gradial.cm.gateway
Gradial CM Gateway Access
gradial
Gradial Gateway Client
0
3600
true
false
client_credentials
$(env:GRADIAL_CLIENT_SECRET)
gradial.cm.gateway
```
Place this in the Identity container's config directory (typically `Config/production/` or via a mounted volume) and restart the container.
If you use a different OIDC provider (Azure AD, Okta, Auth0, Keycloak, etc.), the concepts are identical — register an API resource, an API scope, and a client-credentials client, then map the four values into the gateway's config.
### Split-horizon networks (internal vs. public issuer)
`MetadataAddress` exists for the case where **the ID server has a different internal origin than the JWT's public issuer URL**. In simple deployments where the CM can reach the same URL clients use, leave `MetadataAddress` empty and the gateway will derive everything from `Authority`.
This split is common in containerized deployments. For example:
* The Sitecore Identity container is reachable from the CM container at `http://id` (an internal Docker DNS name, plain HTTP).
* The same Identity service is reachable from the public internet at `https://id.example.com` (TLS, public DNS).
* Tokens issued to Gradial carry `iss: https://id.example.com` because that's the issuer the public clients trust.
In this case:
| Setting | Value | Why |
| ---------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Gradial.Identity.Authority` | `https://id.example.com` | Must match the JWT's `iss` claim. The gateway compares this string to the token's issuer during validation. |
| `Gradial.Identity.MetadataAddress` | `http://id` | Base URL the gateway uses to fetch the discovery document and signing keys. Use the internal hostname the CM container can actually reach. The gateway appends `/.well-known/openid-configuration` automatically — do **not** include that suffix here. |
| `Gradial.Identity.DiscoveryRequireHttps` | `false` | Required when `MetadataAddress` is plain HTTP. Leave `true` when both URLs are HTTPS. |
Sitecore patch form for `MetadataAddress`:
```xml theme={null}
http://id
```
Never set `Authority` to the internal URL. The gateway validates the token's `iss` claim against `Authority`, and the issuer baked into the token is the public URL — using the internal URL there will fail every token with a `401`.
### Generating the client secret
Use **32 bytes (256 bits) of cryptographic randomness**, base64-encoded.
PowerShell:
```powershell theme={null}
[Convert]::ToBase64String([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(32))
```
OpenSSL:
```bash theme={null}
openssl rand -base64 32
```
Do not use GUIDs, `Get-Random`, or human-friendly password generators — they have insufficient entropy.
Store the plaintext secret in a secret manager. Inject it into the Identity container as an environment variable (the sample above reads `$(env:GRADIAL_CLIENT_SECRET)`). Provide the same plaintext value to Gradial when you create the integration.
### Rotating the secret
1. Generate a new secret.
2. Add it as `` alongside the existing one — IdentityServer4 accepts any configured secret, so old and new both work during rollover.
3. Update the integration in Gradial to use the new secret.
4. Once traffic has migrated, remove the old `` and restart the Identity container.
### End-to-end smoke test
```powershell theme={null}
$body = @{
client_id = "gradial"
client_secret = $env:GRADIAL_CLIENT_SECRET
grant_type = "client_credentials"
scope = "gradial.cm.gateway"
}
$token = (Invoke-RestMethod `
-Uri "https:///connect/token" `
-Method Post `
-Body $body).access_token
Invoke-RestMethod `
-Uri "https:///_api/gradial/whoami" `
-Headers @{ Authorization = "Bearer $token" }
```
A successful `/whoami` response returns the client identity extracted from the token.
***
## 3. Service user permissions
The gateway executes every Sitecore operation as the configured service user (`Gradial.Sitecore.ServiceUser`, default `sitecore\gradial-service`). The OIDC client identity authorizes Gradial to call the gateway; the Sitecore user is what actually reads and writes content in Sitecore. Sitecore's audit trail records this user, not the JWT caller — the gateway logs the JWT caller separately, with a correlation ID joining the two streams.
### Recommended rights
Grant the minimum item-level rights for the content roots the integration will operate against. Replace `[TENANT]` and `[SITE]` with your actual values; repeat for every tenant/site you want to expose.
| Path | Rights | Notes |
| ------------------------------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/sitecore/content/[TENANT]/[SITE]` | Read, Write, Create, Delete, Rename | Content tree the integration will manage. |
| `/sitecore/media library/Project/[TENANT]/[SITE]` | Read, Write, Create, Delete, Rename | Media items associated with the same site. |
| `/sitecore/templates` | Read | Required so the gateway can resolve field definitions when reading or creating items. **Do not grant Write** — content operations should never mutate templates. |
Apply rights with inheritance ("Descendants") so child items inherit them. Use the Sitecore Security Editor (**Desktop → Security Tools → Security Editor**), or assign the user to a role that carries these rights.
### Path-level access control
Path-level access control is enforced by:
1. The Sitecore ACLs above on the service user — anything outside the granted scope returns `403` from the underlying SDK.
2. The consuming application's allowed-paths configuration (set in Gradial).
Database-level access is enforced separately by the `Gradial.Security.AllowedDatabases` setting. Requests targeting a database outside the allowlist are rejected before any Sitecore call is made. The setting **fails closed** — an empty allowlist denies all requests.
***
## 4. Module configuration reference
All settings live in `App_Config\Include\Gradial\Gradial.CmGateway.config`. Most defaults are correct out of the box; only the identity values are required.
### Module
| Setting | Default | Description |
| ----------------- | ------- | ------------------------------------------------------------------------------------------------- |
| `Gradial.Enabled` | `true` | Master switch. When `false`, the initializer skips route registration and the gateway is dormant. |
### Identity (OIDC / JWT validation)
| Setting | Default | Description |
| ---------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Gradial.Identity.Authority` | *(empty — required)* | OIDC issuer URL. The token's `iss` claim must match. |
| `Gradial.Identity.ExpectedAudience` | *(empty — required)* | Value the token's `aud` claim must equal. |
| `Gradial.Identity.ValidateAudience` | `true` | Disable only for diagnostics. Keep `true` in production. |
| `Gradial.Identity.AllowedClientIds` | `gradial` | Pipe-separated list of client IDs allowed to call the gateway (e.g. `gradial\|tool-b`). The token's `client_id` claim must appear here. |
| `Gradial.Identity.RequiredScopes` | `gradial.cm.gateway` | Pipe-separated list of scopes the token must contain. |
| `Gradial.Identity.ClockSkewMinutes` | `2` | Allowance for clock drift between the OIDC issuer and CM server. |
| `Gradial.Identity.ClientIdClaimType` | `client_id` | Claim name used to read the client ID from the token. Override only if your provider emits a non-standard claim. |
| `Gradial.Identity.MetadataAddress` | *(empty)* | Base URL for OIDC discovery and JWKS fetches. The gateway appends `/.well-known/openid-configuration` itself, so the value is just an origin (e.g. `http://id`) — not a full discovery URL. Leave empty to reuse `Authority`. Set this only when the CM cannot reach `Authority` directly; see [Split-horizon networks](#split-horizon-networks-internal-vs-public-issuer). |
| `Gradial.Identity.DiscoveryRequireHttps` | `true` | Enforces HTTPS for the discovery endpoint. Only set `false` for local development against a non-TLS Identity host. |
### Sitecore execution context
| Setting | Default | Description |
| ---------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `Gradial.Sitecore.ServiceUser` | `sitecore\gradial-service` | The Sitecore user every gateway operation runs as. Must exist before the app pool starts. See [Section 3](#3-service-user-permissions). |
| `Gradial.Sitecore.DefaultDatabase` | `master` | Database used when a request omits `?db=`. |
### Security
| Setting | Default | Description |
| ----------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `Gradial.Security.AllowedDatabases` | `master` | Pipe-separated allowlist of databases the gateway may touch (e.g. `master\|web`). **Fails closed** — empty value denies all requests. |
| `Gradial.Security.DefaultFields` | *(empty)* | Pipe-separated list of fields always returned in item responses. Empty means "all fields except those denied". |
| `Gradial.Security.DeniedFields` | `__Security\|__Owner\|__Workflow state\|__Lock\|__Created by\|__Updated by` | Pipe-separated list of fields stripped from every response. |
### Feature settings
| Setting | Default | Description |
| ---------------------------------- | ------- | -------------------------------------------------------------------------------------- |
| `Gradial.Features.Preview.Enabled` | `true` | Enables the page preview rendering endpoints. Set `false` to disable preview entirely. |
### Preview rendering (HTTP loopback)
The preview endpoint renders a page by issuing an HTTP request back to the CM. These settings control that loopback.
| Setting | Default | Description |
| ----------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| `Gradial.Preview.CmBaseUrl` | `http://localhost` | Base URL preview requests target. If empty, preview derives the base URL from the incoming gateway request's scheme + host. |
| `Gradial.Preview.IgnoreCertificateErrors` | `false` | When `true`, the loopback HTTP client accepts self-signed and invalid TLS certs. **Only enable in non-production.** |
| `Gradial.Preview.RenderTimeoutSeconds` | `60` | Maximum time to wait for a loopback render before giving up. |
***
## 5. Create the integration in Gradial
With the gateway installed, the OIDC client registered, and the service user permissioned, you can now create the integration in Gradial.
### Connection
| Field | Value |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Integration name** | A name for this connection (e.g. `Acme Production CM`). |
| **Description** *(optional)* | Free-text notes — environment, owner, ticket reference, etc. |
| **Sitecore CM URL** | Base URL of the CM instance, e.g. `https://cm.example.com`. Do **not** include `/_api/gradial`; Gradial appends that automatically. |
| **Mark as production** | Tick if this is a production CM. Gradial uses this flag to apply additional confirmation steps and audit emphasis. |
### Credential
These are the values you produced in [Section 2](#2-register-gradial-as-an-oidc-client).
| Field | Value | Maps to |
| ----------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| **Client ID** | The client registered in your OIDC provider (e.g. `gradial`). | `` and `Gradial.Identity.AllowedClientIds`. |
| **Client Secret** | Plaintext secret you generated (32 bytes, base64). Store securely — Gradial will not display it again after save. | ``. |
| **Token URL** | Token endpoint of your OIDC provider, e.g. `https://id.example.com/connect/token`. | The `token_endpoint` published by the discovery document. |
| **Scope** | The scope the gateway requires. | `Gradial.Identity.RequiredScopes` (default `gradial.cm.gateway`). |
| **Audience** | The audience the gateway expects. | `Gradial.Identity.ExpectedAudience` (e.g. `gradial.gateway`). |
After saving, Gradial will fetch a token via the client-credentials grant and call `/_api/gradial/health` and `/_api/gradial/whoami` to verify the connection end-to-end.
***
## Failure modes
| HTTP status | Likely cause |
| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized` (every request) | `Authority` mismatch, signing key not loadable, or `ExpectedAudience` doesn't match the token's `aud` claim. |
| `403 Forbidden` with `insufficient_scope` | Token doesn't include a scope listed in `RequiredScopes`. |
| `403 Forbidden` with `client not allowed` | Client ID isn't in `AllowedClientIds`. |
| `403 Forbidden` on item operations | Service user lacks the required rights on the requested path. Review [Section 3](#3-service-user-permissions). |
| `503 Service Unavailable` on authenticated endpoints | `Authority` is empty or the gateway can't reach the discovery document at `MetadataAddress`. |
| `404 Not Found` on `/_api/gradial/*` | Gateway didn't initialize. Check the Sitecore log for `[Gradial.Gateway]` errors during app pool startup. |
All gateway log entries are tagged `[Gradial.Gateway]` and include a correlation ID. When opening a support case, include the correlation ID from the failed request's `X-Correlation-Id` response header.
# Slack
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/slack
Bring Gradial into Slack — start tracked agent work with an @-mention, follow live progress in the thread, and get the finished response without switching.
## Overview
The Slack integration brings Gradial into the place where work is already being discussed. Mention Gradial in a Slack channel to hand a request into a tracked Gradial task, follow progress directly in the Slack thread, and receive the completed response in the same thread — without switching tools.
The Slack integration must be explicitly enabled for your organization. An admin must configure the integration, and the Gradial app must be added to the Slack channels where teams want to use it. Contact your Gradial team for access and setup guidance.
### Why use Gradial with Slack?
Most content requests start as a conversation — a channel message, a thread, a quick ask. Normally someone has to carry that request out of Slack, recreate it as a task, and report back when it's done. The Slack integration removes that loop:
* **Requests become tracked work instantly** — a mention in a channel creates a real Gradial task, so nothing gets lost in the scroll
* **Context carries over automatically** — the request and its Slack thread context travel into Gradial with the task
* **The requester stays informed without leaving Slack** — progress, controls, and the final result all live in the original thread
***
## How It Works
### Start work with a mention
Mention Gradial in a channel where the app has been added and describe what you need. Gradial creates a tracked task from your request, carrying the message and surrounding thread context into the task so Grady starts with the full picture.
### Follow live progress in the thread
While Gradial works, a rich working message in the Slack thread shows the task's current progress. You can watch the request move through the workflow without opening Gradial.
### Control the task from Slack
The working message includes in-thread controls:
* **Open in Gradial** — jump to the full task view at any time
* **Cancel** — stop the active run directly from Slack; cancellation halts the workflow at its next safe checkpoint
### Receive a clean final response
When the work finishes, the live progress panel is replaced with a durable response card in the same thread — a clear record of what was done that stays in the channel for anyone who finds the thread later.
### Continue the conversation
Follow-up messages in the Slack thread stay connected to the same Gradial task, so iteration keeps its context instead of spawning disconnected requests.
***
## Task Status in Slack
Gradial reports clear outcome states in the thread so teams always know what happened and what to do next:
| Outcome | What you see |
| ---------------------- | ------------------------------------------------------------------ |
| **Completed** | The progress panel is replaced with a final response card |
| **Cancelled** | The thread shows the run was cancelled and where it stopped |
| **Timed out** | The thread shows the run did not finish in time, with next steps |
| **Duplicate request** | Gradial flags that the request matches one already in flight |
| **Processing failure** | The failure is surfaced in the thread rather than silently dropped |
***
## Configuration
1. Contact your Gradial team to enable the Slack integration for your organization.
2. An org admin completes the Slack integration setup for your workspace.
3. Add the Gradial app to each Slack channel where teams should be able to start work.
Once the app is in a channel, anyone in that channel can mention Gradial to start a task.
***
## Related
* [Notifications →](/docs/platform/notifications) — in-app and email task notifications
* [Mentions →](/docs/platform/mentions) — referencing people and platform entities inside Gradial
# WordPress
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/wordpress
Connect Gradial to WordPress to draft pages, posts, media, and templates while preserving the Gutenberg block model.
Connect a WordPress site once and Gradial can draft and update pages, posts, custom content types, templates, and media from a single flow — and edits respect the Gutenberg block model so a page Gradial touches still opens cleanly in the WordPress editor afterwards.
***
## What You Can Do
Browse, draft, and update pages and posts in either draft or published state. Edit Gutenberg blocks safely — block markers are preserved so the WordPress editor still treats the page as a real block document.
Discover the site's custom post types and use them exactly like pages and posts. Create, read, update, and list entries for any custom post type exposed via the REST API.
Upload images and documents. Update media metadata (title, alt text, caption, description). Set featured images and insert image blocks with correct media references.
List and edit block templates and template parts (headers, footers, sidebars). Inspect and update widgets.
***
## Prerequisites
* Admin or Editor access to your WordPress site
* WordPress REST API (`/wp-json/wp/v2`) accessible — required for self-hosted and WordPress VIP sites
* A Gradial organization **Administrator** role to complete setup
WordPress.com hosted sites that don't expose the standard REST API are not supported. This integration targets self-hosted and VIP-style sites where the REST API is reachable.
***
## How to Connect
Choose the auth method that matches how your site is set up:
**Application Password (recommended)**
1. Sign in to WordPress as the editor/admin account Gradial should use.
2. Open **Users → Profile → Application Passwords**.
3. Create a new application password named "Gradial" and copy the generated value.
4. In Gradial, choose **Basic** auth and use the username + application password.
**Bearer Token / JWT**
If the site uses a JWT or token-issuing plugin, generate a token scoped to the Gradial editor account. In Gradial, choose **API Key Header**, paste the token, and set the prefix to `Bearer`.
**Custom Headers**
Use this when the site is fronted by a proxy or CDN that needs extra headers, or when several headers must be sent together.
**OAuth2 Client Credentials**
For sites running an OAuth server plugin — supply the client ID, client secret, and token URL.
Always create a dedicated Gradial user or token rather than reusing a real editor's credentials. Grant only the WordPress capabilities the team needs — typically Editor level.
1. In Gradial, go to **Settings → Integrations**.
2. Find **WordPress** and click **+ Add**.
3. Fill in the connection details:
| Field | Value |
| --------------------------------------------- | ------------------------------------------------------------------------------- |
| **Integration Name** | A display name (e.g., `Acme Marketing Site`) |
| **WordPress Site URL** | Your site's public origin (e.g., `https://wordpress.example.com`) |
| **Authentication Method** | Application Password, Bearer Token, Custom Headers, or OAuth2 |
| **REST API Base Path** *(optional)* | Defaults to `/wp-json/wp/v2` — only change if the site uses a non-standard path |
| **Preview Base URL** *(optional)* | The host serving rendered or preview pages, if different from the API origin |
| **Default Author / Post Status** *(optional)* | Used when an authoring workflow does not specify them |
4. Click **Save**. Gradial validates that the site responds before the integration goes live.
1. Go to **Settings → Environments** and select the Gradial Environment where WordPress should be available.
2. Add the WordPress integration to that Environment.
3. Repeat for any additional Environments.
***
## How It Fits Into Broader Workflows
| Use case | How to use it |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Campaign landing pages** | Draft the next campaign landing page in the same Gradial thread that produced the brief, copy, and creative |
| **Image and media management** | Upload generated or sourced imagery into the WordPress media library and drop it straight into the right page or post |
| **Page updates** | Update an existing page's hero copy, swap an image, or insert a new section without breaking the block document |
| **Content migration** | Capture source pages, upload assets into WordPress, then assemble new pages using block-aware HTML preserving copy, structure, and links |
**Example — Draft a new campaign landing page:**
1. Ask Gradial to draft a new draft page with a title, slug, and body copy from the brief.
2. Have Gradial upload the hero image into the WordPress media library.
3. Ask Gradial to set the uploaded image as the page's featured image and insert it as the hero block.
4. Verify the draft by asking Gradial to look it up by slug.
5. Open the page in the WordPress editor when reviewers are ready to publish.
***
## Good to Know
* **Drafts need explicit lookups**: WordPress REST list endpoints exclude drafts by default. Gradial knows to request `status: draft` and `context: edit` when verifying freshly created draft content.
* **Gutenberg block preservation**: every Gradial edit keeps surrounding `` block markers intact — the difference between a clean page in the WordPress editor and a page that opens as one giant classic block.
* **Media uploads are size-capped**: the integration accepts up to 25MB per upload. Larger assets need to go through the WordPress admin directly.
* **Production sites must use HTTPS**: media source URLs Gradial pulls from are validated against HTTPS and blocked from private/internal hosts in production.
***
## Support
Contact your Gradial onboarding lead or email [support@gradial.com](mailto:support@gradial.com) for help with setup.
# User Groups
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/managing-access/groups
Organize members into role-based and custom groups that can be @-mentioned, assigned as approvers, and assigned to workspaces to grant access — manage teams as a unit, not person by person.
User Groups let you address a team as a single unit. Mention an entire squad on a ticket, assign a whole team as an approver, or give the same people access to several workspaces at once — instead of handling five people one at a time and hoping you didn't miss anyone.
***
## Group Types
### Default role groups
Gradial automatically maintains a group for each role at both the organization and workspace level:
| Scope | Default groups |
| ---------------- | ----------------------------------------------------------- |
| **Organization** | Owners, Admins, Brand Managers, Designers, Members, Viewers |
| **Workspace** | Owners, Admins, Members, Viewers |
Membership in these groups is computed from role assignments and workspace access, and stays in sync automatically — when someone's role changes, their default group membership follows. Default role groups are read-only: use them to see or select the people in a role, not to grant a role. Their membership can't be edited directly.
### Custom groups
Org owners and admins can build reusable groups of organization members that mirror how your team actually works — squads, regional teams, agency partners, launch teams.
Custom groups are the best choice when **the same people need access to several workspaces**. Assign a group to one or more standard workspaces, or leave it unassigned until you need it.
***
## Granting Workspace Access with Groups
Assigning a custom group to a workspace gives its eligible members **Workspace Member** access. A group assignment does not grant Workspace Admin, Owner, or Viewer access, and it does not change anyone's organization role.
Group-based access is *effective* Member access — it doesn't create a direct workspace-membership record for each person. Access takes effect **immediately** when a group is assigned, so review the group's membership before assigning it.
### When a group changes
| Change | Effect |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Adding a person to a group** | Grants the group's workspace access immediately, for as long as they remain an organization member |
| **Removing a person, or detaching a group from a workspace** | Removes only that group-based path. Direct access, public workspace visibility, or Organization Owner/Admin access can still apply |
| **Deleting a custom group** | Removes the group and its workspace assignments. Does **not** remove anyone from the organization |
| **Removing someone from the organization** | Removes them from custom groups and from group-granted workspace access. Re-adding them to the organization does not restore their former group memberships |
Removing someone's direct workspace membership is not a permanent block. If they're still in a custom group assigned to that workspace — or are added to one later — they keep or regain Member access. See [How Access Paths Combine](/docs/integrations-administration-and-setup/managing-access/roles#how-access-paths-combine).
***
## Managing Groups
Groups are managed from **Organization Settings → People → Groups**.
The Groups tab provides:
* Tabs and filters by scope, type, and member
* Inline member editing for custom groups
* Create and edit dialogs for building new groups
**To create a custom group:**
1. Go to **Organization Settings → People → Groups**
2. Click to create a new group
3. Give the group a name and, optionally, a description
4. Add at least one current organization member
5. Optionally assign the group to one or more workspaces
6. Save
Group lifecycle and membership changes are audit-logged.
***
## Group Mentions
Groups appear in the **@** mention picker anywhere mentions work. Mentioning a group notifies every member of the group who has access to the ticket, in one action — the author is excluded from their own mention's notifications.
> *"@Web Squad — can you review the updated hero copy on the summer campaign pages before Friday?"*
Because default role groups stay in sync with roles, mentions like **@Admins** or **@Designers** always reach the current set of people in that role — the mention never goes stale as the team changes.
See [Mentions](/docs/platform/mentions) for how the mention picker works.
***
## Group Approvers
Workspace-scoped groups can be assigned as a ticket's **approver**. Any member of the group can complete the approval, so reviews never wait on one person's availability.
Group approvers are supported everywhere individual approvers are: ticket creation, editing, bulk operations, filters, and Excel upload.
Removing a legacy workspace-scoped group from its workspace can set affected Task approvers to **No approver**. Restoring the group's scope does not restore those approver assignments automatically, so reassign approvers after the change.
***
## Permissions
| Action | Who can do it |
| -------------------------------------- | ------------------------------------------ |
| View groups | All organization members |
| Create, edit, and delete custom groups | Org owners and admins |
| Edit group membership | Org owners and admins (custom groups only) |
| Assign a custom group to a workspace | Org owners and admins |
Only people who can manage organization settings — normally Organization Owners and Admins — can create, edit, delete, or assign custom groups.
***
## Limitations
* **Default role groups are read-only** — membership is synced from roles and can't be edited directly.
* **Group assignments grant Member access only** — use a direct workspace role for Admin or Viewer access.
* **Same-organization only** — a custom group can contain only members of its own organization, and can be assigned only to active standard workspaces in that organization. Admin workspaces can't have group assignments.
* **Only workspace-scoped groups can be approvers** — org-scoped groups can be mentioned but not assigned as ticket approvers.
***
## Related
* [Roles & Permissions →](/docs/integrations-administration-and-setup/managing-access/roles) — the role model that powers default groups
* [Adding Team Members →](/docs/integrations-administration-and-setup/managing-access/manage-team-members) — inviting users and configuring access
* [Mentions →](/docs/platform/mentions) — the @ picker where groups appear
***
## Availability
**Access:** Must be enabled for your organization. Contact your Gradial team to get access.
# Manage Team Members
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/managing-access/manage-team-members
Invite users and manage access to Gradial's AI agent platform. Control roles and workspace permissions for your content team.
> **Note:** For details on what each role can do, see [Roles & Permissions](https://docs.gradial.com/docs/integrations-administration-and-setup/managing-access/roles).
***
## Inviting Users to Your Organization
Before someone can access Gradial, they must be invited to your organization.
### Steps
1. Navigate to [app.gradial.com](http://app.gradial.com)
2. Click **Settings** in the bottom-left corner of the navigation panel
3. Select **People** under the Organization section
4. Click the **Invite** button in the top-right corner
5. Enter the team member's **email address**
6. Select an **organization role** (Admin, Member, or Viewer)
7. Optionally assign **additional access** (Brand Manager, Designer) — these add permissions on top of the primary role
8. Click **Send Invitation**
### What Happens Next (For the Invited User)
The onboarding experience depends on your organization's authentication method:
**Username/Password Authentication**
* The invited user receives an email notification
* They must click the link and reset their password to activate their account
* After setting their password, they can log in at [app.gradial.com](http://app.gradial.com)
**Single Sign-On (SSO)**
* No password reset is required
* The user can log in immediately using your organization's SSO provider
* The invitation email serves as a notification only
***
## Granting Workspace Access
After a user joins your organization, you control which workspaces they can access.
**Important:** Organization Owners and Organization Admins automatically have access to all standard workspaces. You only need to manually add Members and Viewers.
### Public vs. Private Workspaces
* **Public workspaces** — All organization members and viewers have automatic access (members as Workspace Members, viewers as Workspace Viewers)
* **Private workspaces** — Access requires direct membership, an assigned [custom group](/docs/integrations-administration-and-setup/managing-access/groups), or a [SCIM group mapping](/docs/integrations-administration-and-setup/managing-access/scim)
> **Tip:** When the same people need access to several workspaces, create a [custom group](/docs/integrations-administration-and-setup/managing-access/groups#granting-workspace-access-with-groups) and assign it to each workspace instead of adding people one at a time.
### Adding a User to a Workspace
1. From the left navigation, select the workspace
2. Click **Settings** in the top-right corner
3. Select **Access Control**
4. Click **Add Members**
5. Search for the user by name or email
6. Select a **workspace role**
7. Click **Add**
A confirmation message will appear: "Access settings updated successfully."
***
## Common Tasks
### Changing a User's Organization Role
1. Go to **Settings → People** (Members tab)
2. Find the user in the list
3. Use the **Role** dropdown to select a new **Primary role**, and optionally toggle **Additional access** (Brand Manager, Designer)
4. Changes apply immediately across the organization
> **Tip:** The **Roles** tab on the People page shows every role and its current members, searchable and filterable by scope.
### Changing a User's Workspace Role
1. Open the workspace and go to **Settings → Access Control**
2. Find the user in the member list
3. Use the **Role** dropdown to change their workspace role
4. Changes apply only within that workspace
### Removing a User from a Workspace
1. Open the workspace and go to **Settings → Access Control**
2. Find the user in the member list
3. Click the remove option next to their name
***
# Roles & Permissions
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/managing-access/roles
Understand how Gradial calculates access from a user's primary organization role, optional additional access, and workspace role.
A user's effective access in Gradial is calculated from three things:
1. **Primary organization role** — the user's platform-wide role: Owner, Admin, Member, or Viewer.
2. **Additional access** (optional) — add-on permissions layered on top of the primary role: Brand Manager and Designer.
3. **Workspace role** — what the user can do inside a specific workspace: Owner, Admin, Member, or Viewer.
Permissions **combine** across these layers — additional access and workspace roles add to a user's primary organization role; they never replace it.
> **Looking to add someone to your team?** See [Adding Team Members ](/docs/integrations-administration-and-setup/managing-access/manage-team-members) for step-by-step instructions on inviting users and configuring workspace access.
***
## Primary Organization Roles
Every user has exactly one primary organization role, set from **Settings → People → Members**.
To see every role and who currently holds it, open **Settings → People → Roles**. Each role row can be expanded to show its members, and the list can be searched and filtered by scope (organization or workspace). Brand Manager and Designer appear here at the organization scope, alongside the four primary roles.
| **Role** | **Access summary** |
| :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Organization Owner** | Organization administration, billing, organization deletion, and organization ownership transfer. Manages integrations and settings, members, rules, and design systems. Has full access to all standard workspaces. |
| **Organization Admin** | Manages organization settings, integrations, members, rules, and design systems, and has access to every standard workspace. Does **not** include organization deletion, billing, or organization ownership transfer (can transfer *workspace* ownership). |
| **Organization Member** | Access to public standard workspaces as a Workspace Member. Access to a private workspace requires an access grant. |
| **Organization Viewer** | Read access to public standard workspaces as a Workspace Viewer. Access to a private workspace requires an access grant. |
* **Organization Owners** hold billing, organization deletion, and organization ownership transfer rights — permissions no other role has.
* **Organization Admins** manage the organization day to day and can reach every standard workspace, but cannot delete the organization, manage billing, or transfer organization ownership.
* Changing a user's organization role changes their inherited access **immediately**.
***
## Additional Access
A user may have their primary role plus one or both of these add-ons, assigned under **Additional access** in the role picker on the People page. They are organization-level add-ons — they are **not** workspace roles, and they don't replace the primary role.
| **Additional access** | **Access summary** |
| :-------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Brand Manager** | Can manage organization rules. Can manage rules in a workspace only when the user is also a member of that workspace — directly or through an assigned custom group. Public workspace visibility alone is not enough. |
| **Designer** | Can manage design systems, personas, and audiences — including viewing, creating, editing, and deleting design systems. This access is organization-scoped — it is not limited to a single workspace. |
Design system creation, editing, and deletion is authorized at the **organization** level: Organization Owners, Organization Admins, and users with Designer additional access. Workspace membership alone — including Workspace Admin — does not grant design-system management.
***
## Workspace Roles
Within a workspace, a user has one of four roles.
| **Role** | **Workspace and Task access** |
| :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Workspace Owner** | Manages workspace settings, members, rules, archiving, and workspace ownership transfer. Has full Task permissions, including delete and lock, and full artifact permissions, including publish. |
| **Workspace Admin** | Manages workspace settings, members, rules, and workspace ownership transfer. Can create, edit, and delete Tasks. Can view and create artifacts, but cannot archive the workspace or edit, delete, or publish artifacts. |
| **Workspace Member** | Can view and edit the workspace and create, edit, and delete Tasks. Cannot manage workspace settings, members, or rules. |
| **Workspace Viewer** | Can view the workspace, its Tasks, and its artifacts. Cannot create or modify them. |
A direct workspace role can **add** rights beyond what a user's organization role provides, but it never removes organization-derived rights.
### Workspace ownership
* A standard workspace has exactly **one owner**. To change it, use the ownership-transfer flow rather than assigning the Owner role directly.
* Workspace Owners and Workspace Admins can transfer workspace ownership.
* The new owner must be a **direct workspace member** or an **Organization Owner or Admin**. Access through a custom group alone is not sufficient.
* After the transfer, the former owner becomes a **Workspace Admin**.
***
## Public and Private Workspace Access
### Public standard workspaces
Public standard workspaces are accessible to everyone in the organization:
* **Organization Members** receive effective **Workspace Member** access.
* **Organization Viewers** receive effective **Workspace Viewer** access.
If a user also has a higher direct workspace role, the higher role applies.
### Private standard workspaces
Access to a private standard workspace can come from any of these paths:
* **Direct membership** — the user is added to the workspace individually
* **Custom group** — the user belongs to a custom group assigned to the workspace, which grants **Workspace Member** access ([User Groups](/docs/integrations-administration-and-setup/managing-access/groups))
* **SCIM group mapping** — the user belongs to an identity provider group mapped to the workspace ([SCIM User Provisioning](/docs/integrations-administration-and-setup/managing-access/scim))
**Exception:** Organization Owners and Organization Admins can access every standard workspace — public or private — without direct membership, and receive admin-level access. Removing a workspace grant does not remove an Organization Owner's or Organization Admin's inherited access.
### Admin workspaces
Admin workspaces are never public and are visible only to the organization's current Owners and Admins. Direct members, custom group assignments, and workspace owner rows cannot grant access to them, and promoting or demoting someone's organization role changes their access immediately.
Admin workspaces cannot have direct members, custom group assignments, role changes, or ownership transfers, and cannot be converted to or from a standard workspace.
***
## How Access Paths Combine
**There is no deny role.** If any access path allows an action, the user can perform it. To fully remove someone's access, remove **every** path that grants it.
A user can reach a workspace through several paths at once: their primary organization role, additional access, a direct workspace role, a custom group assignment, public workspace visibility, and SCIM group mapping. Keep these in mind:
* **Removing direct membership is not a permanent block.** If the user remains in the organization and is later added to a custom group assigned to that workspace, they regain effective Workspace Member access.
* **Organization Owners and Admins can't be restricted inside a standard workspace.** Removing their workspace membership doesn't remove their automatic access — change their organization role instead.
* **The last Organization Owner is protected.** Transfer organization ownership before demoting or removing that person.
***
## Task Visibility and Explore Chat Privacy
Workspace access does not expose every conversation in a workspace:
* **Committed Tasks** follow workspace access — anyone who can access the workspace can see them according to their workspace role.
* **Explore chats are creator-private.** Another Workspace Member or Workspace Admin cannot view your Explore chat just because they can access the workspace.
* **Organization Owners and Organization Admins** can read another user's Explore chat for governance purposes, but that access is **view-only** — they cannot edit, delete, or add messages to it.
***
## Managing Users
For step-by-step instructions on inviting users, granting workspace access, and changing roles, see [Adding Team Members ](/docs/integrations-administration-and-setup/managing-access/manage-team-members).
***
## Recommended Administration Flow
1. **Start with least privilege** — choose the lowest organization role that supports the person's normal work.
2. **Pick the right access path** — use a direct workspace role for one-off access; use a custom group when the same people need access to several workspaces.
3. **When troubleshooting access, check every path** — primary role, additional access, direct workspace role, custom group assignment, public visibility, and SCIM group mapping.
4. **To restrict an Organization Owner or Admin, change their organization role**, not their workspace membership.
***
## Quick Notes
* A user's effective access is the **combination** of their primary organization role, any additional access, and their workspace role.
* **Organization Owners and Admins** don't need to be added at the workspace level — they can access every standard workspace automatically.
* **Brand Manager** and **Designer** are organization-level additional access, not workspace roles.
* Organization ownership can be transferred by an Organization Owner. Workspace ownership can be transferred by a Workspace Owner, Workspace Admin, or Organization Admin.
* **There is no deny role** — remove every granting path to fully remove access.
* **To invite new users** or modify access, see [Adding Team Members ](/docs/integrations-administration-and-setup/managing-access/manage-team-members).
# SCIM User Provisioning
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/managing-access/scim
Automatically provision, update, and deprovision Gradial users, organization roles, and workspace access from your identity provider using SCIM 2.0.
Gradial separates *login* from *provisioning*:
* **SSO (SAML/OIDC)** answers "can this person log in?"
* **SCIM 2.0** answers "should this person have Gradial access, what role should they have, and which workspaces should they see?"
SCIM is **one-way**: your identity provider (IdP) pushes user and group changes into Gradial. Gradial never writes changes back to the IdP.
| | SSO | SCIM |
| -------------- | ---------------------------- | --------------------------------------------------- |
| Primary job | Authentication / login | Provisioning / lifecycle / access sync |
| Direction | User browser ↔ IdP ↔ Gradial | IdP server → Gradial API |
| Typical signal | "This user authenticated" | "Create / update / deactivate this user or group" |
| Gradial effect | Establishes a session | Grants or revokes organization and workspace access |
| If missing | User cannot log in | User may not exist, or may retain stale access |
SSO alone does not silently create a Gradial account. A user must be provisioned (through SCIM, a manual invite where allowed, or another valid linking path) before they can log in. An unprovisioned SSO user sees a clear "account not provisioned" error rather than ending up with a silent orphan account.
***
## How to Enable SCIM
SCIM requires two gates:
1. The SCIM provisioning feature must be enabled for your organization.
2. An organization owner must turn on **SCIM Provisioning** in organization settings.
Gradial admins configure SCIM under **Settings → Developer → SCIM Provisioning**:
* Toggle SCIM provisioning on or off (organization owners only)
* Copy the SCIM base URL
* Create and revoke SCIM bearer tokens
* Add SCIM group → workspace mappings (after groups have been provisioned)
Managing SCIM tokens and mappings requires organization settings permission.
***
## SCIM Tokens
Gradial issues a dedicated bearer token for SCIM. Treat it like any other sensitive credential.
* **Prefix:** `gxs_`
* **Scope:** exactly one organization — a token cannot reach any other organization
* **Visibility:** shown once at creation, so copy it immediately
* **Expiration options:** 30, 60, 90, 180, 365 days, or no expiration
* **Usage:** sent in the `Authorization: Bearer ` header
SCIM tokens can only access SCIM endpoints — they cannot call the rest of the Gradial API. Regular Gradial API keys cannot access SCIM endpoints. The token's owner must have member-management permission in the organization; a token owned by a member or viewer is rejected.
### Token rotation
Create a new SCIM token in Gradial and copy it.
Update the secret token in your IdP, test the connection, and save.
Revoke the previous token in Gradial.
***
## Base URL and Discovery
Base URL: `https:///api/scim/v2`
Discovery endpoints are served without authentication, because IdP connector setup may probe them before sending a bearer token:
* `GET /ServiceProviderConfig`
* `GET /Schemas`
* `GET /ResourceTypes`
Discovery advertises bearer token authentication, PATCH support, equality-only filters, User and Group resource types, and Gradial's optional organization-role extension schema. Bulk operations, password changes, and sorting are not supported.
***
## Supported Endpoints
### Users
| Method | Endpoint | Supported |
| -------- | ------------- | ---------------------------- |
| `GET` | `/Users` | Yes (list, with filters) |
| `POST` | `/Users` | Yes |
| `GET` | `/Users/{id}` | Yes |
| `PATCH` | `/Users/{id}` | Yes |
| `PUT` | `/Users/{id}` | Not supported |
| `DELETE` | `/Users/{id}` | Yes (treated as deprovision) |
User lookup filters (equality only; compound or complex filters are not supported):
* `userName eq "..."`
* `externalId eq "..."`
* `id eq "..."`
### Groups
| Method | Endpoint | Supported |
| -------- | -------------- | ------------- |
| `GET` | `/Groups` | Yes |
| `POST` | `/Groups` | Yes |
| `GET` | `/Groups/{id}` | Yes |
| `PATCH` | `/Groups/{id}` | Yes |
| `PUT` | `/Groups/{id}` | Not supported |
| `DELETE` | `/Groups/{id}` | Yes |
Group lookup filters (equality only):
* `displayName eq "..."`
* `externalId eq "..."`
* `id eq "..."`
***
## User Provisioning Behavior
### Creating users (`POST /Users`)
* A new email creates a Gradial user, a SCIM link, and organization membership.
* If the email already belongs to a Gradial user in another organization, that existing global identity is linked into this organization. Access in other organizations is not changed.
* If a SCIM link for that user is inactive, the user is reactivated.
* If an active SCIM user already exists in the same organization, the request returns a uniqueness conflict.
* `userName` is expected to be an email. If `userName` is absent, Gradial can use `emails[].value`.
### Updating users (`PATCH /Users/{id}`)
Supported attributes:
* `active`
* `externalId`
* `userName`, `displayName`, `name.givenName`, `name.familyName`, `name.formatted`, `emails`
* Role attributes (see [Organization role sync](#organization-role-sync))
Behavior notes:
* String booleans such as `"True"` / `"False"` are accepted, since some IdPs send these.
* PATCH operation names are case-insensitive (`Add`, `Replace`, `Remove`).
* Unknown attributes are ignored, so IdP extension attributes do not fail the whole sync.
* Password updates are rejected, not silently accepted.
### Profile ownership
Gradial user profiles are global across organizations. For a user who already exists in Gradial, SCIM does not rewrite shared global profile fields (such as name or email), because one customer's IdP should not change how that user appears in every other organization. In practice this means **SCIM can set a user's name only on first provisioning**.
SCIM manages organization-scoped state only: the SCIM external ID, active/deprovisioned state, organization membership, and supported roles.
### Deprovisioning users
Deprovisioning can be triggered by `PATCH active=false` (the common Entra path) or by `DELETE /Users/{id}`. Both have the same effect:
* The user's organization membership is removed.
* The user's SCIM group memberships are removed.
* The user's non-owner workspace memberships (in that organization) are removed.
* The user's sessions scoped to that organization are cleared.
* The user identity and SCIM link are **preserved** for audit, so the user can later be reprovisioned with the same Gradial identity.
Owners cannot be deprovisioned by SCIM. Removing an owner returns a conflict — the owner must be downgraded or transferred manually first.
***
## Organization Role Sync
SCIM can set the organization role of SCIM-managed users to `admin`, `member`, or `viewer`. `owner` is not SCIM-manageable: assigning it is rejected with a conflict, and owners always remain Gradial-managed.
Roles are read from two places:
1. The standard SCIM `roles` array, especially `roles[primary eq "True"].value`
2. Gradial's extension schema: `urn:gradial:params:scim:schemas:extension:organization-role:2.0:User` with `organizationRole`
Standard `roles` wins when present and parseable. Unknown role values are ignored.
Whether the IdP or Gradial controls a SCIM-managed member's primary organization role depends on the **Sync roles from Identity Provider** setting:
* **Enabled** — the primary organization role can only be changed in the identity provider. The People page shows these rows with disabled role controls.
* **Disabled** — Gradial manages the role and ignores the role value sent by the provider.
Additional access (Brand Manager, Designer) is managed in Gradial either way, separately from a SCIM-controlled primary role.
***
## Workspace Access Through Group Mappings
SCIM does not let the IdP directly create arbitrary Gradial groups or workspaces. Instead, access flows through admin-managed mappings:
1. The IdP provisions SCIM group identities and memberships.
2. A Gradial admin maps a provisioned IdP group to a Gradial workspace (and a workspace role) under **Settings → Developer → SCIM Group Mappings**.
3. Gradial reconciles workspace membership from the mapping and the latest group membership facts.
Mapping fields:
* **IdP Group** — a previously provisioned SCIM group
* **Workspace** — an existing workspace, or "create or reuse a workspace from this IdP group"
* **Workspace role** — `viewer`, `member`, or `admin`
### Workspace role rules
* `owner` is not a SCIM-managed workspace role. Workspace owner rows are always Gradial-managed and are never inserted over, updated, downgraded, or deleted by SCIM.
* Non-owner workspace membership and roles are IdP-managed for mapped workspaces.
* One IdP group maps to one workspace; multiple IdP groups can map to the same workspace.
* If a user is in multiple mapped groups for the same workspace, the highest role wins: `admin > member > viewer`.
* If a user is removed from an admin group but remains in a member/viewer group for the same workspace, Gradial downgrades rather than revokes.
* If a user is absent from every mapped group for that workspace, Gradial removes their non-owner workspace membership.
### Mapping lifecycle
* Creating a mapping immediately reconciles existing SCIM group membership.
* Deleting a mapping reconciles the affected workspace and can remove access for users whose only path was that mapping. The workspace itself is not deleted.
* Re-adding a mapping can reuse a workspace previously associated with that IdP group.
* The mapping UI shows an impact preview before saving (grants, revokes, and role changes).
For SCIM-mapped workspaces, manual changes to non-owner workspace members are blocked by the backend, not just disabled in the UI.
***
## Manual Invites in SCIM-Managed Organizations
When SCIM provisioning is enabled for an organization:
* Local email/password signup and manual invites cannot create or grant initial non-owner access in that organization.
* Owners are still managed in Gradial.
* The People page indicates which members are IdP-provisioned versus locally provisioned, so admins can verify that all non-owner access is coming through SCIM.
***
## Microsoft Entra ID Setup
Gradial's SCIM implementation is currently validated for Microsoft Entra ID only (see [Current limitations](#current-limitations)). The steps below are the Entra-specific setup.
An organization owner turns on SCIM Provisioning under **Settings → Developer**. Create a SCIM token and copy it immediately.
In **Microsoft Entra admin center → Enterprise applications → Gradial → Provisioning → Admin credentials**:
* Provisioning Mode: **Automatic**
* Tenant URL: `https:///api/scim/v2`
* Secret Token: your `gxs_...` token
Click **Test Connection**, then save.
In **Mappings → Provision Microsoft Entra ID Users**, verify the effective mappings. The key one is `externalId`, which must be mapped to a stable unique Entra identifier (commonly `objectId`). `userName` should be the user's email and should match the email used for SSO.
| Entra source | SCIM target | Notes |
| ----------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `userPrincipalName` or `mail` | `userName` | Must be an email and should match the SSO email. Use `mail` if UPN is not the login email. |
| `objectId` | `externalId` | The most important mapping. Use a stable unique Entra identifier; `objectId` is recommended over `mailNickname`. |
| `givenName` | `name.givenName` | First name. Include this so provisioned users show their name in Gradial. |
| `surname` | `name.familyName` | Last name. Include this together with `givenName`. |
| `mail` | `emails[type eq "work"].value` | Optional fallback if `userName` is absent. |
Do not map passwords — Gradial rejects password updates. Name mappings only take effect on **first provisioning**.
In **Mappings**, enable **Provision Microsoft Entra ID Groups**. This is required for Gradial workspace access: without it, Gradial receives users but no groups, and the Gradial group-mapping picker will be empty.
Recommended group mappings:
| Entra source | SCIM target |
| ------------- | ------------- |
| `displayName` | `displayName` |
| `objectId` | `externalId` |
| `members` | `members` |
If you want Entra to control Gradial organization roles, the final SCIM value must be one of `admin`, `member`, or `viewer`.
**Simplest option:** define Entra app-role values exactly as `admin`, `member`, and `viewer`, then map:
* Mapping type: **Expression**
* Expression: `SingleAppRoleAssignment([appRoleAssignments])`
* Target attribute: `roles[primary eq "True"].value`
* Apply this mapping: **Always**
**If your Entra app-role names differ**, use an expression that translates them to Gradial's vocabulary, for example:
```text theme={null}
Switch(SingleAppRoleAssignment([appRoleAssignments]), "", "YourReadOnly", "viewer", "YourAuthor", "member", "YourAdmin", "admin")
```
Entra `Switch` comparisons are case-sensitive. Assign only one app role per user for this mapping — `SingleAppRoleAssignment` is a single-role helper.
In **Users and groups**, assign the users and groups that should have Gradial access.
Set **Provisioning Status** to **On**. Use **Provision on demand** to test a single user and a single group before letting the full cycle run.
After Entra provisions groups, a Gradial admin maps each Entra group to a Gradial workspace under **Settings → Developer → SCIM Group Mappings**, choosing a workspace role of `viewer`, `member`, or `admin`.
***
## Troubleshooting
The group picker only shows IdP groups that Gradial has actually received. If it is empty:
1. Confirm SCIM provisioning is enabled in Gradial.
2. Confirm the SCIM token and base URL in Entra match the intended Gradial organization.
3. Confirm the IdP group is assigned to the Entra enterprise application.
4. Confirm Entra provisioning has **Provision Microsoft Entra ID Groups** enabled. This is a common root cause: Entra provisions users but never sends group calls.
5. Use **Provision on demand** for the group, or restart provisioning.
6. Wait for the next Entra polling cycle if not forcing a sync.
7. Confirm the group is not already mapped — already-mapped groups are removed from the available-groups picker.
This is expected. Provision the user through SCIM first (assign them to the Entra enterprise app and run provisioning), then have them log in again.
Gradial requires an email claim to complete SSO. Azure AD only emits the `email` claim when the user's `mail` attribute is populated — it does not synthesize one from the user principal name (UPN), and adding `email` to the app registration's optional claims does not fix this on its own. Accounts without `mail` (commonly service, shared, or non-mailbox accounts) therefore see this error, while users with a normal mailbox sign in normally — which is why it often affects only a subset of users.
**Fix:** have your Entra admin populate the `mail` attribute on the affected accounts.
**Prevention:** before enabling Gradial SSO, have your Entra admin verify that every user who will sign in has a populated `mail` attribute. Catching mailless accounts during rollout planning is much cleaner than after a user hits the error page.
A deprovisioned user's identity is preserved on purpose for audit and reprovisioning. Their access (organization membership and workspace access) is removed, and they cannot log in. If they reappear with access, confirm the IdP has not reactivated or re-assigned them.
Entra can quarantine an app and slow its sync cadence if error rates are high. Check the Entra provisioning logs for failing requests, verify the SCIM token is valid and not expired, and verify the Gradial organization still has SCIM enabled. Use **Provision on demand** to isolate a failing user or group.
***
## Current Limitations
* **Microsoft Entra ID is the only IdP currently validated** end-to-end for customer rollout. The implementation follows the SCIM 2.0 standard and is designed to be largely IdP-agnostic (case-insensitive PATCH operations, string booleans, tolerated unknown extension attributes); support for additional IdPs (Okta, Ping, etc.) is on the roadmap and will be documented here when validated.
* **SCIM cannot assign or remove owners**, at either the organization or workspace level.
* **One IdP group maps to one workspace** — multiple groups can map to one workspace.
* **SCIM can set a user's name only on first provisioning**, because Gradial profiles are global across organizations. If users were synced before a name mapping was added, their names must be corrected manually in Gradial.
***
## Related
* [Single Sign-On (SSO) →](/docs/integrations-administration-and-setup/managing-access/sso) — configuring authentication for your identity provider
* [Roles & Permissions →](/docs/integrations-administration-and-setup/managing-access/roles) — the role model SCIM syncs into
* [Adding Team Members →](/docs/integrations-administration-and-setup/managing-access/manage-team-members) — manual invites and the People page
# Single Sign-On (SSO)
Source: https://docs.gradial.com/docs/integrations-administration-and-setup/managing-access/sso
Configure SSO for Gradial using Microsoft Entra ID, Okta OIDC, or any custom OpenID Connect provider. SAML 2.0 is available as a custom integration.
Gradial supports three self-serve methods for setting up Single Sign-On (SSO) in your organization:
* **Microsoft Entra ID (Azure AD)** — recommended for Microsoft-based organizations
* **Okta OIDC** — streamlined integration for Okta customers
* **Custom OIDC** — for any OAuth2/OpenID Connect–compliant provider (e.g., Google, Ping, Auth0)
If your identity provider is SAML-only, or your security policy requires SAML, see [SAML 2.0](#saml-2-0) below — it is configured with your Gradial team rather than self-serve.
SSO handles *authentication* — whether a user can log in. To automatically create, update, and deactivate Gradial accounts (and sync organization roles and workspace access) from your identity provider, see [SCIM User Provisioning](/docs/integrations-administration-and-setup/managing-access/scim).
***
## Option 1: Microsoft Entra ID Admin Setup (Recommended)
### Overview
If your organization uses Microsoft Entra ID (formerly Azure Active Directory), this is the fastest and most secure setup method. Gradial is a verified publisher in the Microsoft Azure Marketplace, so your IT team can trust the flow and consent screen.
Microsoft Entra ID: [https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/plan-an-application-integration](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/plan-an-application-integration)
### Steps to Enable SSO
1. **Log in to Gradial**\
Go to: `https://app.gradial.com`
2. **Select Microsoft Login**\
Click **Sign in with Microsoft**
3. **Authenticate as an Admin**\
Use a Microsoft Entra ID admin account. The first login will prompt a Microsoft consent screen.
4. **Grant Permissions**\
Review the requested permissions and click **Accept** to authorize Gradial.
5. **SSO Activated**\
Gradial links to your Microsoft tenant. All users from your domain (e.g., `@company.com`) can now log in with Microsoft.
***
## Option 2: Okta OIDC Setup
### Overview
If your organization uses Okta as its identity provider, you can configure SSO with Gradial using OpenID Connect. Gradial provides a prebuilt Okta option to simplify setup.
Okta Documentation:[https://help.okta.com/en-us/content/topics/apps/apps\_apps.htm](https://help.okta.com/en-us/content/topics/apps/apps_apps.htm)
> **Note**: Some organizations require Gradial to be explicitly added as an authorized Okta application. If you encounter issues, check with your Okta administrator.
### Steps to Enable SSO
1. In Gradial, go to **Settings → Integrations → Single Sign-On**
2. Select **Okta**
3. Copy the **Callback URL** from Gradial into your Okta app configuration
4. Enter your **Okta Domain** (e.g., `dev-123456.okta.com`)
5. Enter your **Organization Domain** (e.g., `gradial.com`)
6. Paste your **Client ID** and **Client Secret** from Okta
7. Save and test login
**Steps in OKTA**
***
## Option 3: Custom OIDC Setup
### Overview
Use this method if your organization uses a non-Microsoft, non-Okta identity provider that supports OpenID Connect (e.g., Google, Ping, Auth0).
### Steps to Enable SSO
1. In Gradial, go to **Settings → Integrations → Single Sign-On**
2. Select **Custom OIDC**
3. Enter your **Domain** (e.g., `gradial.com`)
4. Provide:
* **Issuer URL** (e.g., `https://accounts.google.com`)
* **Discovery URL** (e.g., `https://accounts.google.com/.well-known/openid-configuration`)
* **Client ID** and **Client Secret** from your IdP
* *(Optional)* **Scopes** (default: `openid, email, profile`)
5. Save and test login
***
## SAML 2.0
The three options above are OpenID Connect. Gradial can also authenticate against a **SAML 2.0** identity provider, configured as a custom integration with your Gradial team rather than from the Single Sign-On screen.
Use this route if your identity provider doesn't offer an OIDC application for Gradial, or if your security policy standardizes on SAML.
**Access:** SAML 2.0 is set up as a custom integration. Contact your Gradial team to scope it — they'll confirm your IdP, the assertion attributes Gradial needs to map users to accounts, and the timeline to stand the connection up.
***
## Getting Help
Options 1–3 can be completed as a **self-serve setup** in Gradial.
> **Important**: At least one admin account must be set up with a **username and password** (not SSO) to initially access the integrations screen and complete setup.
If you prefer assistance, reach out to your **Customer Solutions team**, who can walk through configuration and validation with you.
***
## Multiple SSO Configurations
Gradial supports multiple SSO configurations for a single organization—useful for organizations spanning multiple geographies with separate identity providers, or when a managed service provider is supporting your implementation. To add additional SSO connections, repeat the setup steps for each identity provider.
## Additional Notes
* Self-serve setup requires an IdP that supports **OpenID Connect** and **authorization code flow**; SAML 2.0 providers are handled as a custom integration
* Share secrets only through secure channels
* Keep at least one password-based admin account as a backup in case of SSO misconfiguration
***
## Related
* [SCIM User Provisioning →](/docs/integrations-administration-and-setup/managing-access/scim) — automatically provision users, roles, and workspace access from your IdP
* [Roles & Permissions →](/docs/integrations-administration-and-setup/managing-access/roles)
* [Adding Team Members →](/docs/integrations-administration-and-setup/managing-access/manage-team-members)
# Foundational Guidelines
Source: https://docs.gradial.com/docs/marketing-brain/foundational-guidelines
Migrate legacy Rules into a versioned, sheet-style guideline library managed alongside Skills — one governed home for brand, compliance, and QA guidance.
Foundational Guidelines move legacy customer Rules into the same management system as Skills, giving teams one governed place to manage the brand standards, compliance requirements, workflow rules, and QA guidance Grady depends on.
Functionally, Grady uses the same customer guidance during work tasks after migration — the difference is that the guidance now lives in a versioned, auditable, and easily editable library instead of the legacy Rules surface.
***
## Where Guidelines Live
Foundational Guidelines are managed under **Skills → Foundational Guidelines**. Guidelines are organized into typed folders with sidebar grouping, and rows can be moved across sections with drag-and-drop.
***
## Building the Guideline Library
### Import from a spreadsheet
Bring existing rules in bulk:
1. Open **Skills → Foundational Guidelines**
2. Import your rules from a CSV file
3. Review and edit the imported rows in the sheet-style editor
4. Set each guideline's enablement, scope, agents, and integrations before rolling it into Grady's rulebook
You can also export the library back to CSV at any point for offline review or bulk editing.
### Add guidelines manually
Individual guidelines can be added directly in the sheet-style editor — useful for new standards that never existed as legacy rules.
### Let Grady capture guidelines
With Learning Mode, Grady can create or update guidelines from real work, the same way it proposes Skills — so guidance that surfaces during tasks can be captured into the governed library instead of living only in someone's head.
***
## Governance Controls
Each guideline row carries the controls that determine how it applies:
| Control | What it does |
| ---------------- | ------------------------------------------------------------------- |
| **Enablement** | Only enabled guidelines are hydrated into Grady's customer rulebook |
| **Scope** | Organization-wide or workspace-specific |
| **Agents** | Which agents the guideline applies to |
| **Integrations** | Which connected systems the guideline is relevant for |
Guidelines keep full **version history**, and guideline management follows the existing Skills and admin permission model.
***
## Migrating from Legacy Rules
The migration is designed to be safe and reversible rather than a one-way cutover:
1. **Build the library first.** The guideline library is enabled while Grady continues using your legacy Rules — nothing changes in agent behavior yet.
2. **Import and validate.** Migrate your legacy rules (and any relevant captured guidance) into enabled guidelines, and review them in the sheet editor.
3. **Cut over.** Once the library is complete, the Gradial team switches Grady's customer rulebook to source from enabled guidelines. Legacy Rules surfaces are hidden from that point.
4. **Rollback is available.** If something isn't right, the cutover can be reversed while you adjust the library.
Migrate every legacy rule you still rely on into an enabled guideline **before** the rulebook cutover — after cutover, Grady's customer rulebook comes from enabled guidelines only.
***
## Related
* [Managing Skills →](/docs/marketing-brain/managing-skills) — the expertise layer Foundational Guidelines sit alongside
* [Managing Rules (Legacy) →](/docs/marketing-brain/managing-rules-legacy) — the legacy system guidelines replace
* [Learning System →](/docs/marketing-brain/learning-system) — how the Marketing Brain fits together
***
## Availability
**Access:** Must be enabled for your organization. Your Gradial team enables the guideline library so your team can build and validate it, then switches Grady over to guidelines as its source of standing guidance once you confirm it is ready. Contact your Gradial team to get access.
# Learning System
Source: https://docs.gradial.com/docs/marketing-brain/learning-system
How Gradial encodes your organization's knowledge as brand intelligence — so agents execute with consistent expertise on every task, across every platform.
Great marketing teams don't just follow instructions — they learn. The best ones build institutional knowledge over time: what your brand sounds like, how your workflows run, what actually converts. That expertise lives in your people.
Until now, it also left with them. Every time someone's out, switches teams, or moves on, that knowledge walks out the door too. The next person starts over. Quality becomes inconsistent. The organization never compounds.
**The Marketing Brain changes that.**
***
## What is the Marketing Brain?
The Marketing Brain is Gradial's system for encoding, storing, and applying your organization's institutional marketing knowledge — and making it available to every agent, on every run, automatically.
It's the difference between an AI that executes instructions and one that genuinely understands how your organization works. When Grady draws on your Marketing Brain, it's not just following rules — it's applying the same depth of expertise your best people bring to their work.
The Marketing Brain is built on two layers that work together — Rules as the foundation, Skills as the evolution built on top.
The standards every output must meet. Brand compliance, legal requirements, accessibility, SEO. Rules define the floor: the non-negotiables that run automatically on every task, every time. [Managing Rules (Legacy) →](/docs/marketing-brain/managing-rules-legacy)
The institutional knowledge that shapes how agents work. Proven processes, workflow patterns, brand know-how — encoded once and available to every agent. Skills are the evolution of Rules: they go beyond what to avoid and into how to excel. [Managing Skills →](/docs/marketing-brain/managing-skills)
***
## Why this matters
Most AI tools give you guardrails. They tell the agent what to avoid. That's valuable — but it's only half the picture.
What makes a marketing team genuinely excellent isn't just knowing what not to do. It's knowing *how* to do it well: the specific approach that works for your audience, the workflow that consistently produces quality output, the institutional judgment that comes from doing this work for years.
**Rules get you to consistent. Skills get you to excellent.**
Rules encode the guardrails — the floor that every output clears, automatically. Skills encode the expertise — the ceiling that keeps rising as your team's institutional knowledge compounds. Together, they give Grady a marketing brain that gets better with your organization, not just alongside it.
***
## How Skills work
Skills are reusable capabilities that encode your team's institutional knowledge and make it available to every agent on every run.
### Skill Builder
Create and edit skills in a rich, document-style editor. You can write skills yourself based on your team's knowledge, or let Grady surface them through **agentic skill development** — where the agent identifies patterns worth encoding from real work and proposes them for your review.
### Scope and versioning
Every skill is scoped so it applies to the right teams:
| Scope | What it covers |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Workspace** | Applies within the specific workspace where it was created — right for team-specific processes, regional workflows, or product-line expertise |
| **Organization** | Promoted org-wide by an admin when a skill should apply everywhere — right for universal brand voice, company-wide process standards, or cross-team expertise |
Full version history is maintained for every skill, so you always know what changed, when, and why. If a change doesn't work as expected, you can roll back.
### Agentic skill development
Grady can build and refine its own skills from the work it does. As agents complete tasks, they can identify patterns worth encoding as reusable skills and propose them for your review. This means your Marketing Brain doesn't just reflect what you've thought to write down — it grows from real work, capturing the judgment that's hard to articulate but easy to recognize.
***
## Brand intelligence, built in
Brand intelligence is the active, operational layer that turns brand knowledge into brand behavior — consistently, at scale, without relying on individuals to carry it in their heads.
Most organizations have brand knowledge scattered across style guides, editorial decks, compliance checklists, and the institutional memory of their best people. That knowledge is valuable. The problem is that it's passive: it only becomes intelligence when someone who knows it shows up to apply it.
Gradial's Marketing Brain is a different kind of brand intelligence system. It takes that scattered knowledge — the voice guidelines, the terminology standards, the workflow patterns, the compliance requirements — and makes it active. Every agent, on every task, draws on the same encoded expertise. It doesn't matter who submitted the task, what workspace it came from, or which agent is running it.
The result is brand intelligence that behaves like your best people, not your least experienced ones.
**What brand intelligence looks like in practice:**
* A content update applies your exact voice and terminology standards — not a generic interpretation of them
* A new page is structured the way your best pages are structured, not the way a general-purpose AI might structure one
* QA catches the specific issues that matter to your organization, not just industry defaults
* A skill developed from a successful campaign workflow is available the next time a similar campaign runs — without anyone having to remember or re-explain it
This is the difference between AI that follows instructions and AI that genuinely understands how your organization works.
### Brand intelligence that spans your whole stack
A brand intelligence system is only as good as the signals it learns from. Brand feedback happens everywhere your team works — in project management tools, review comments, editorial corrections, client conversations, campaign retrospectives. If an intelligence system can only see the signals from one platform's workflow, it learns the brand as that platform sees it, not as your whole organization practices it.
Gradial's Marketing Brain is built from signals across your full stack: JIRA tickets, Workfront briefs, editorial corrections made in your CMS, campaign performance from your analytics platform, QA outcomes across every connected integration. Skills can capture institutional knowledge from any source — not just the slice that flows through any one tool.
The brand intelligence that results reflects how your best people actually think and work — not a partial picture filtered through a single platform's approval queue.
***
## Orchestration across platforms, not within one
Most enterprise AI tools are experts at their own platform's data and blind to everything else. That's fine for specialized tasks. But a marketing execution platform needs to understand your full context — and route work, apply brand standards, and enforce quality across every system you use.
Gradial is built to orchestrate across your entire stack. The Marketing Brain doesn't just inform tasks that happen inside Gradial — it informs every execution that Gradial coordinates, whether that's a content update in your CMS, an asset operation in your DAM, an email in your marketing platform, or a page update triggered by a JIRA ticket.
This means:
* **Brand standards apply everywhere** — a rule or skill active in your Marketing Brain applies to every connected system, not just Gradial's own interface
* **Quality is consistent across channels** — the same QA standard enforced on your web content applies to your email, your campaigns, your regional variants
* **The brain grows from every integration** — agentic skill development learns from work done across all connected tools, so the intelligence reflects your full operation
* **No single-platform lock-in** — if you add a new CMS, swap your DAM, or expand to a new channel, the Marketing Brain moves with you
This is what separates brand intelligence that scales from brand intelligence that silos.
***
## Strategy and execution in one motion
Many AI execution tools require you to arrive with a fully formed strategy — a defined goal, a clear brief, a decided channel mix — and then hand it to the tool to execute. The execution is capable. The strategic layer is yours to figure out separately.
Gradial is different. The Marketing Brain connects your team's institutional knowledge to the execution layer, so the intelligence that shapes *what to do* is the same intelligence that drives *how to do it*. When Grady draws on your Skills and Rules, it's not just running a task — it's applying your organization's judgment about what good looks like, which approaches work for your audience, and how work like this has been done well before.
The result: teams spend less time translating strategy into instructions for tools, and more time directing outcomes. The brief and the execution live in the same motion — informed by the same brain.
***
## Governance that's built in, not bolted on
A marketing brain is only trustworthy if the humans directing it stay in control of what matters. Gradial's architecture puts human review at the decision layer by default — agents propose and execute, humans approve at the points that matter most to your team.
This isn't a limitation on automation. It's what makes automation trustworthy at scale. Teams configure how much oversight they want per task type: full review for brand-sensitive launches, spot-checks for routine updates, auto-approval for high-confidence recurring tasks. The governance model adapts to your team's actual risk tolerance — and as your confidence in agent outputs grows, you can extend autonomy progressively.
The Marketing Brain reinforces this: Skills and Rules that encode your standards mean agents are less likely to need correction in the first place. Good governance isn't about reviewing more — it's about needing to review less because the execution is reliably right.
***
## For teams transitioning from Rules
If your team has been using Rules, that work carries forward. The guardrails you've established remain active — nothing changes there.
Skills is the evolution of that foundation. Rules gave you guardrails. Skills give you expertise: structured, versioned, improvable capabilities that go far beyond what to avoid and into how to excel.
A good signal that guidance belongs in a Skill rather than a Rule: if you're writing a Rule that describes *how* to do something well rather than a standard every output must meet, it belongs in a Skill.
***
## Getting started
Skills must be activated for your organization. Contact your Gradial account team to get started.
Once activated, you can create your first skill in the **Skills** section of the left sidebar, or ask Grady to propose one based on a task you've been running regularly.
[Managing Skills →](/docs/marketing-brain/managing-skills)
***
## Who this is for
| Role | What Gradial handles |
| :-------------------------------- | :------------------------------------------------------------------------------ |
| **Content Ops / Enablement Lead** | Institutional knowledge captured where it gets used, not in a wiki nobody opens |
| **Brand Manager** | Brand standards applied on every task, not only when you're in the review |
| **Marketing Leadership** | Quality that doesn't depend on who happens to be staffed on the work |
| **Team Lead / Manager** | New starters producing to standard in weeks rather than quarters |
| **Subject Matter Expert** | Your expertise reused without you being the bottleneck for every request |
# Managing Rules (Legacy)
Source: https://docs.gradial.com/docs/marketing-brain/managing-rules-legacy
Reference documentation for Gradial's Rules system — the legacy guardrail layer. Existing rules remain active. New organizations use Skills.
**Rules is the legacy guardrail system.** New organizations start with Skills, which is the evolution of Rules and the recommended approach for encoding organizational knowledge going forward. If your organization was set up before Skills was available, your existing rules remain fully active — nothing changes unless you choose to transition.
Rules are organization-wide and workspace-level standards that every agent checks before completing a task. They define the non-negotiables: what every output must meet, automatically, every time.
***
## Rules Manager
Access Rules from **Rules & Skills** in the left sidebar, then select the **Rules** tab.
The Rules Manager shows all active rules across your organization, organized by:
* **Scope**: Organization-wide or workspace-specific
* **Type**: Brand, Compliance, Accessibility, SEO, Custom
* **Status**: Active or Inactive
* **Agent assignment**: Which agents the rule applies to
***
## Adding a rule
1. Click **New Rule** in the Rules Manager
2. Enter a rule name and description
3. Write the rule content — describe the standard every output must meet
4. Set the scope (Organization or Workspace)
5. Assign to relevant agents
6. Set status to **Active**
7. Save
Gradial provides starter templates for common rule types:
1. Click **New Rule → From Template**
2. Browse templates by category (Brand, Compliance, Accessibility, SEO)
3. Select a template
4. Customize for your organization
5. Activate
***
## Rule types
| Type | Use for |
| ----------------- | --------------------------------------------------------------------------------------- |
| **Brand** | Voice, tone, terminology, style standards — what must be true of every piece of content |
| **Compliance** | Legal, regulatory, and disclosure requirements |
| **Accessibility** | WCAG compliance standards and accessibility requirements |
| **SEO** | Metadata requirements, heading structure, keyword standards |
| **Custom** | Organization-specific standards that don't fit a standard category |
***
## Agent assignment
By default, rules apply to all agents. To restrict a rule to specific agents:
1. Open the rule in the Rules Manager
2. Go to **Agent Assignment**
3. Toggle off any agents that shouldn't apply this rule
4. Save
Use agent-specific assignment when a standard only applies to certain task types — for example, an email-specific compliance rule that shouldn't run on web content tasks.
***
## Transitioning from Rules to Skills
Rules and Skills serve different layers of the Marketing Brain:
* **Rules** define the floor — standards every output must clear
* **Skills** build the ceiling — expertise that makes outputs excellent
If you have rules that describe *how* to do something well (rather than a standard every output must meet), those are good candidates to migrate into Skills.
To identify candidates:
* Look for rules that are long and process-oriented
* Look for rules with conditional logic ("if the page is a product page, then...")
* Look for rules that describe approach, structure, or workflow
You don't need to delete rules to add skills. Rules and Skills work together — rules handle the non-negotiables, skills handle the expertise.
Contact your Gradial account team if you'd like guidance on transitioning your rules library to a Skills-first approach.
### Migrating rules in bulk
For organizations ready to move off legacy Rules entirely, [Foundational Guidelines](/docs/marketing-brain/foundational-guidelines) provide a structured migration path: import your existing rules from a spreadsheet into a versioned, sheet-style guideline library managed alongside Skills, validate it, and then cut Grady's rulebook over — with rollback available. Contact your Gradial team to plan a migration.
***
## Related
* [Managing Skills →](/docs/marketing-brain/managing-skills) — the recommended approach for new organizations
* [Foundational Guidelines →](/docs/marketing-brain/foundational-guidelines) — the migration path for legacy rules
* [Learning System →](/docs/marketing-brain/learning-system) — how Rules and Skills fit into the Marketing Brain
# Managing Skills
Source: https://docs.gradial.com/docs/marketing-brain/managing-skills
Create, manage, and evolve Skills in Gradial — encode your team's institutional knowledge so every agent executes with consistent expertise on every task.
Skills are the primary way to encode your organization's institutional knowledge and make it available to every agent, on every run. Where Rules define the standards every output must meet, Skills define how your team does its best work — the processes, patterns, and expertise that make the difference between consistent and excellent.
***
## Skill Builder
Create and manage skills in the **Skills** section of the left sidebar. The Skill Builder provides a rich, document-style editor for authoring skills directly.
### Creating a skill
1. Navigate to **Skills** in the left sidebar
2. Click **New Skill**
3. Give the skill a clear, descriptive name (e.g., "Campaign Landing Page Structure" or "Product Voice & Terminology")
4. Write the skill content — describe the process, pattern, or expertise you want the agent to apply
5. Set the scope (see below)
6. Save and activate
### Writing effective skills
Skills work best when they describe *how* to do something well, not just what to avoid. Good skills read like guidance from your most experienced team member:
* Describe the approach, not just the outcome
* Include examples of what "good" looks like
* Reference specific patterns, structures, or voice guidelines your team has developed
* If a workflow has steps that matter, spell them out
A good signal that guidance belongs in a Skill rather than a Rule: if you're writing something that describes *how* to do work well rather than a standard every output must meet, it belongs in a Skill.
***
## Scope and versioning
Every skill is scoped to control where it applies:
| Scope | What it covers | Who can create |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| **Workspace** | Applies within the specific workspace where it was created — right for team-specific processes, regional workflows, or product-line expertise | Any workspace member |
| **Organization** | Applies to all agents across the entire organization — right for universal brand voice, company-wide process standards, or cross-team expertise | Org admin or owner |
To promote a workspace skill to org-wide, an admin can change the scope from the skill's settings.
### Version history
Full version history is maintained for every skill. You can see what changed, when, and who made the change. If a change doesn't perform as expected, you can roll back to any previous version.
### Comparing versions
From a skill's version history, you can view a diff between versions to see exactly what changed. Comparisons cover:
* **Content changes** — edits to the skill's instructions and guidance
* **Metadata changes** — updates to enablement status, owner, and workspace scope
* **Child file changes** — files added, edited, or deleted under the skill appear in the parent skill's version comparison, so a single diff shows the full picture
Use comparisons to review a teammate's edit before relying on it, to confirm what a proposed change from Grady actually modifies, or to find exactly which change to roll back when output quality shifts.
***
## Agentic skill development
Grady can build and refine skills from the work it does. As agents complete tasks, they identify patterns worth encoding as reusable skills and propose them for your review.
This means your Marketing Brain grows from real work — not just what you've thought to write down. The agent captures the judgment that's hard to articulate but easy to recognize once you see it in a well-executed task.
To review proposed skills:
1. Go to **Skills** in the left sidebar
2. Look for skills with **Proposed** status
3. Review the proposed skill content
4. Edit if needed, then **Activate** — or dismiss if it doesn't apply
***
## Best practices
**Start specific, then generalize.** Begin with skills for the tasks you run most often. Once you see patterns across tasks, generalize those into broader organizational skills.
**Name skills for what they do.** "Hero section structure for product pages" is more useful than "Page skills." Agents match skills to tasks by name and description, so specificity improves targeting.
**Iterate based on output.** When agent outputs consistently miss the mark in a specific way, that's a signal your skill needs refinement. Use the version history to track what you changed and whether it helped.
**Skills and Rules work together.** Rules set the floor — the non-negotiables. Skills build on top of them. A skill that duplicates a rule adds noise. Use skills for the expertise layer, rules for the standards layer.
***
## Related
* [Learning System →](/docs/marketing-brain/learning-system) — how the Marketing Brain works
* [Managing Rules (Legacy) →](/docs/marketing-brain/managing-rules-legacy) — if your organization used Rules before Skills
***
## Availability
**Access:** Must be enabled for your organization. Contact your Gradial team to get access.
# Memory
Source: https://docs.gradial.com/docs/marketing-brain/memory
Grady carries knowledge from completed threads into later work — so your team doesn't restate the same decisions, context, and workarounds in every request.
Every thread your team completes produces knowledge: the decision you made about a component, the workaround for a stubborn template, the tone your legal team signed off on. Normally that knowledge stays locked inside the thread that produced it — and the next person to do similar work starts from scratch.
Memory changes that. Completed work in a workspace contributes to a structured memory bank that Grady can draw on in later threads, so teams don't have to re-explain the same context every time.
***
## What Memory does
When Memory is enabled, Grady receives relevant workspace knowledge as part of its context on a new request. In practice that means:
* You can point at past work — "the approach we used on the launch page QA" — instead of re-describing it.
* Decisions and workarounds established in earlier threads carry forward rather than being rediscovered.
* Grady's starting point on a new request reflects how your workspace actually works, not just the prompt in front of it.
Memory is **workspace-scoped**. Knowledge from one workspace does not leak into another.
***
## How Memory is built
Memory is not raw chat history. Gradial synthesizes each completed thread into a summary, then consolidates those per-thread summaries into a workspace-level memory bank. Grady reads from that consolidated bank rather than replaying old conversations.
Memory records can preserve the name of the person whose work produced the remembered context, so teams can see whose decision is being carried forward — not just what was decided.
Memory generation (synthesis) and memory recall are separate controls. A workspace can be building memory before recall is switched on, which means recall requires an existing, non-empty workspace memory before it has anything to draw from.
***
## Seeing where a memory came from
When Grady uses a memory from another thread, you'll see it in the **References** panel on the right side of the thread.
References shows a flat, deduplicated list of the source threads behind memory citations, and each entry is a clickable link back to the thread that generated the finding. That means you can always check the original source yourself rather than taking a recalled claim on faith.
### Permission-aware links
Source threads appear only when you're allowed to see them. If a memory traces back to a thread outside your visibility, the link isn't surfaced — Memory never becomes a side channel into work you don't have access to.
***
## Reliability
If memory hydration is unavailable when a turn starts, the turn continues without memory rather than failing the thread. You may get a result that lacks earlier context, but the work itself still runs.
***
## Current limitations
* Memory generation and recall are enabled separately.
* Recall requires existing workspace memory — a brand-new workspace has nothing to recall yet.
* There is no customer-facing memory editor in this release. You can't directly browse, edit, or delete individual memory records.
* No aggregate memory analytics ship in this release.
* Source-thread links appear only when a visible source thread can be resolved.
* Memory shapes how Grady approaches a request. It informs behavior — it does not guarantee a specific answer.
***
## Related
* [Learning System →](/docs/marketing-brain/learning-system) — how Gradial encodes and applies your organization's knowledge
* [Managing Skills →](/docs/marketing-brain/managing-skills) — deliberately encoding a process or pattern for every agent to use
* [Thread Outcome Feedback →](/docs/marketing-brain/thread-feedback) — telling Gradial which completed work landed well
***
## Availability
**Access:** Must be enabled for your organization. Memory generation and memory recall are controlled separately. Contact your Gradial team to get access.
# Thread Outcome Feedback
Source: https://docs.gradial.com/docs/marketing-brain/thread-feedback
Mark a completed thread as good or bad, add context, and give Gradial a first-hand signal about which agent behaviors worked — and which need to improve.
A thread can finish successfully and still miss the mark. The work completed, the steps ran, nothing errored — but the tone was wrong, the CTA requirements were ignored, or it simply isn't what you asked for.
Today that judgment usually lives outside the product, in Slack messages, calls, and personal notes. It never makes it back to the thread that produced the work, so there's no way to connect a good or bad outcome to the specific thread, version, and agent behavior behind it.
Thread Outcome Feedback closes that loop. Once a thread is complete, you can mark the outcome good or bad and add optional context. That turns "technically finished" into "actually approved" — and gives Gradial a concrete signal to learn from.
***
## Giving feedback
When a thread reaches a terminal state and has no active workflow running, a good/bad feedback control appears on the thread.
Feedback becomes available once the thread has finished. It does not appear while a workflow is still in flight.
Select the positive or negative rating depending on whether the work landed.
Describe what worked or what missed. Specifics are what make the signal actionable:
> *"This missed the CTA requirements and used the wrong tone for the audience."*
> *"This matched the brief and is a good pattern for future launch-page QA."*
Giving feedback is always optional — a completed thread never requires a rating before you can move on.
Anyone who can access the thread can see the feedback on it. Submitting feedback follows the same edit boundary as the thread or project itself.
***
## What happens with your feedback
Submitting feedback posts a follow-up turn to the agent behind the scenes, so the thread can respond to your judgment rather than simply recording it.
### Negative feedback opens a recovery loop
When you mark an outcome bad, the agent can re-engage with a concrete plan to address the issue — so a missed result becomes the start of a fix rather than a dead end. Your written context is what that plan is built from, which is why specifics matter more than a bare thumbs down.
Negative feedback also becomes a high-signal example for evaluation, prompt tuning, and workflow debugging.
### Positive feedback identifies reusable patterns
Marking an outcome good flags the agent behavior behind it as something that worked, and the agent can confirm back what it understood to be successful. Those patterns become candidates for reuse — saved as examples, or promoted into a Skill.
If a thread produced an approach you want your whole team to follow, feedback is the signal — but a [Skill](/docs/marketing-brain/managing-skills) is the durable artifact. Promotion is deliberate: marking a thread good does not save a Skill on its own.
***
## Feedback history on a thread
Feedback is recorded as append-only checkpoints in the thread timeline. Nothing is overwritten, so the full arc of an outcome stays visible — a thread can show negative feedback, the agent's recovery, and later positive feedback, in order.
Each checkpoint is tied to the thread, organization, user, and the specific **thread version** being judged. Feedback stays attached to the state of the work it actually assessed, even after the thread moves on.
***
## Availability
| | |
| ------------------ | ------------------------------------------------------------------------------------------------ |
| **Access** | Opt-in — enabled per organization or workspace on request |
| **Pricing** | Included in your standard subscription |
| **Platforms** | All. Feedback is a thread-level capability, so your CMS or marketing platform does not affect it |
| **Agent versions** | All versions |
| **Integrations** | None required |
Until the feature is turned on, threads behave exactly as they do today, with no feedback control.
***
## Current limitations
* **Binary rating only.** Good or bad — there is no multi-point scale or category breakdown.
* **Completed threads only.** Feedback appears only once a thread is finished with no workflow actively running.
* **No analytics dashboard in this release.** The release creates the feedback signal; aggregate reporting can follow.
* **Not automatic training.** Feedback creates labeled examples for evaluation and improvement. It does not retrain the agent.
* **Not automatic Skill saving.** A good thread becomes a candidate for a Skill or saved pattern, but promoting it stays a deliberate step.
***
## Related
* [Learning System →](/docs/marketing-brain/learning-system) — how Gradial encodes and applies your organization's knowledge
* [Memory →](/docs/marketing-brain/memory) — carrying knowledge from completed threads into later work
* [Managing Skills →](/docs/marketing-brain/managing-skills) — turning a successful pattern into a reusable capability
* [Evals →](/docs/evals/evals) — measuring agent output quality
***
## Availability
**Access:** Included in your standard subscription, but not on by default — it must be turned on for your organization or workspace. Contact your Gradial team to enable it.
# Mentions
Source: https://docs.gradial.com/docs/platform/mentions
Type @ anywhere in Gradial to reference teammates, workspaces, tasks, and integrations — giving Grady structured context and keeping collaboration in place.
Gradial's global mention system lets users type **@** in any rich text surface — chat, tasks, artifact comments, and skills — to insert a durable, clickable reference to a person or platform entity. Reviews happen in context, Grady receives mention context automatically, and handoffs that used to require a Slack loop can happen in a single prompt.
***
## What You Can Mention
The **@** picker searches across eight entity types:
| Entity | What it references |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **People** | Teammates in your Gradial organization |
| **Groups** | [User groups](/docs/integrations-administration-and-setup/managing-access/groups) — mention a whole squad or role group; every member with access to the thread is notified in one action |
| **Workspaces** | Project workspaces in Gradial |
| **Tasks** | Existing tasks — useful for reusing structure or passing context to Grady |
| **Integrations** | Connected systems like your CMS, Marketo, or Salesforce Marketing Cloud |
| **Environments** | Specific environment configurations within an integration |
| **Rules** | Org-level rules governing agent behavior |
| **Skills** | Reusable agent skill definitions |
***
## How It Works
### Typing a mention
Type **@** anywhere in a supported surface to open the picker. Start typing to filter by name — results are grouped by entity type. Use arrow keys to navigate, Enter or Tab to select, and Escape to dismiss.
When you open the picker with no query, your **recently used entities** appear first so you don't have to retype common references.
### How mentions look
Mentions render as **rich interactive pills** — styled badges with entity icons and links. They are not plain blue text. Deep-links for environments and integrations open inline.
### How mentions stay accurate
Mentions reference entities by their **internal ID**, not their display name. If someone renames a workspace or task, the mention label updates automatically at render time — the link stays intact.
### Grady context hydration
When you mention a task, workspace, or integration in a task request, Grady **automatically receives that entity's structured context** before it starts working. You don't need to paste URLs or re-explain what you're referring to.
***
## Use Cases
### Collaboration
Mentions make Gradial the place where review, approval, and handoffs happen in context — without forcing anyone to copy task links into Slack.
**Ask for review or approval**
> *"@Maya please review the updated hero copy on @Nordstrom Holiday Campaign Page before launch."*
The reviewer is pulled into the exact work item with the page and task context already attached.
**Debug with a teammate**
> *"@Alex, can you help debug why this task failed? It looks like the CMS update succeeded but the email asset did not refresh. It's using @CMS Sandbox integration."*
The person, task, and failure context are all connected in one place — no separate "send me the task link" loop.
**Pull the right people into a workflow**
> *"Bring @Maya, @Priya, and @Jordan into @Nordstrom Holiday Campaign Launch. Maya should review visuals, Priya should approve copy, and Jordan should give final launch approval."*
Cross-functional handoffs become explicit without a separate coordination thread.
***
### Execution Context
Mentions tell Grady what prior work, decisions, chats, or tasks should guide the next piece of work.
**Use a task as source-of-truth guidance**
> *"Use @Nordstrom Holiday Campaign Guidance for every follow-up task in this campaign. Make sure product images are not repeated, sale language stays consistent, and CTAs match the campaign pattern."*
Campaign-level consistency without repeating the same guidance in every prompt.
**Reference a task as a content pattern**
> *"Reference @Anniversary Sale Page Task and create a new page that follows the same structure for the Kids campaign."*
Grady reuses a proven structure instead of starting from scratch.
**Carry forward decisions from a chat**
> *"Before making changes, read @Q4 Launch Planning Chat and preserve the decisions about image rotation, headline tone, and CTA placement."*
Decisions made in prior conversations become reusable execution context.
***
### Governance
Mentions make brand, legal, compliance, and policy requirements explicit at the moment of work.
**Apply rules directly in the prompt**
> *"Rewrite this email using @FINRA Copy Rules and @No Guaranteed Returns Rule."*
The right constraints go in the prompt — reducing back-and-forth review cycles.
**Convert feedback into governed changes**
> *"Address @Priya's feedback on @Holiday Landing Page Review, but make sure all changes still follow @Premium Brand Voice Rules."*
Feedback loops stay grounded in the right rules, not just individual preferences.
***
### Systems
Mentions tell Grady which connected systems, integrations, or operating environments to inspect or act through.
**Use an environment as an operating bundle**
> *"Use @North America Campaign Ops and @Launch QA Skill to prepare this campaign for publishing."*
The environment tells Grady which connected systems are relevant for the work.
**Debug across a system bundle**
> *"Within @Campaign Ops Environment, check whether the lead routing issue is coming from the CMS form, @Marketo, or the ticket workflow."*
The environment provides the system map; individual integration mentions narrow the investigation.
**Prepare a campaign across connected tools**
> *"Use @Campaign Ops Environment to prepare @Nordstrom Holiday Campaign Page for launch. Confirm the CMS page is updated, the Marketo email references the right assets, and the ticket workflow is ready for approval."*
Multi-system work in one natural language instruction.
***
### Skills
Mentions let users tell Grady which playbook, capability, or workflow mode to apply.
**Use a skill as the playbook**
> *"Use @Page Editing Skill on the work from @Product Launch Task."*
Tell Grady exactly which workflow or capability should guide the task.
**Combine a skill with prior task context**
> *"Use @Page Editing Skill and reference @Anniversary Sale Page Task to build a new Kids campaign page with the same structure."*
The skill tells Grady how to operate; the task tells Grady what pattern to follow.
**Run a QA skill on demand**
> *"Run @Launch QA Skill on @Nordstrom Holiday Campaign Page and summarize anything that needs to be fixed before publishing."*
Repeatable review workflows become explicit, reusable one-line actions.
***
## Where Mentions Work
| Surface | Supported |
| -------------------- | --------------------------------------------- |
| Chat composer | Yes |
| Task / ticket editor | Yes |
| Artifact comments | Yes (including dark-mode styling) |
| Skills | Yes |
| Plain text fields | No — mention pills require a rich text editor |
***
## Configuration
### Enabling mentions
1. Contact your Gradial team to enable mentions for your organization.
2. The picker activates immediately across all supported surfaces — no per-surface configuration needed.
### Permissions
Available to all Gradial roles with organization access. No additional role restrictions apply.
***
## Limitations
* **Artifact mentions not yet supported** — the ability to @ an artifact directly in the picker ships in a future release.
* **External ticket mentions not yet supported** — Jira, Asana, Workfront, and Wrike mentions are later scope.
* **No mention dates in V1** — @today / @tomorrow style date mentions are designed but not yet shipped.
* **No backlinks or mention analytics** — a backlink graph and mention history are on the roadmap.
***
## Availability
**Access:** Must be enabled for your organization. Contact your Gradial team to get access.
# Notifications
Source: https://docs.gradial.com/docs/platform/notifications
Stay informed of task status changes through an in-app inbox, real-time banners, and email — with per-event channel control at the org and individual level.
Gradial Notifications keep task subscribers informed as work moves through your organization. When a task is kicked off, needs attention, or is ready for review, the right people are notified on the right channel — without anyone having to watch the app for updates.
***
## What Notifications Enable
A dedicated sidebar tab alongside Home and Chats. Mark notifications read or unread, archive them, and scroll through your full history. Sort and filter preferences are saved per user across sessions.
Task status changes surface as live in-app banners the moment they happen — no refresh needed. Banner delivery respects your per-event channel preference.
Branded task notification emails delivered for enabled events, with the task title, a summary, your workspace, and a deep link back to the task thread.
Choose Banner, Email, or None for each of the five task events. Set organization-wide defaults as an admin, and let individuals override their own preferences.
Assignees and approvers are subscribed automatically. Anyone can be added manually from the task header. Subscribers are who gets notified.
Created, Kicked off, Needs attention, Ready for review, and Unblocked — the moments that actually require a response.
***
## How It Works
When a task changes to a covered status, Gradial creates a notification for each subscriber. That notification drives both the in-app inbox entry and, if enabled for that event, the email delivery. Because both channels share the same source, email and in-app notifications stay consistent.
**In-app banners** appear immediately. **Email** is delivered by a background job that processes in near-real-time — expect a short delay between the status change and the email landing.
***
## Channel Types
| Channel | What it does |
| --------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Banner** | Shows an in-app toast and creates an item in the Notifications inbox |
| **Email** | Sends an email notification and also creates an item in the Notifications inbox |
| **None** | Silences notifications for that event — no banner, no email, no inbox item |
| **Org default** | Uses the organization's default setting for that event (the default for all users until they set a personal override) |
***
## Common Use Cases
**Approver pulled in at the right moment.** A task reaches *Ready for review*. The approver — automatically subscribed — gets an email and an in-app banner, and can act without hunting for the thread.
**Author unblocked.** A task that was waiting on a dependency becomes *Unblocked*. The assignee sees it surface in their inbox and picks the work back up immediately.
**Needs-attention escalation.** A running task hits a state that needs input. The subscriber is notified so the task doesn't sit stalled without anyone knowing.
**Org admin sets team policy.** An admin configures org-default channels per event — email on *Ready for review*, banner-only on *Created* — so the whole team starts with sensible defaults.
**Individual tunes their own noise.** A user switches *Created* and *Kicked off* to None for themselves while keeping *Ready for review* on email, overriding the org default just for their account.
***
## Configuration
### Admin setup
1. Contact your Gradial team to enable the `notifications` flag for your organization.
2. Navigate to **Settings → Notifications** as an org admin.
3. Set the organization-default channel for each event. These defaults apply to all users until they set a personal override.
### Personal preferences
Each user can override the org defaults for their own account from **Settings → Notifications**. Org defaults remain visible but are read-only for non-admins.
### Default behavior
Out of the box, banners are on and email is off for each event. Users inherit the org default until they set a personal override.
***
## Permissions
| Action | Required role |
| ----------------------------------- | ----------------------------------- |
| Set org-default channel preferences | Org admin |
| Set personal channel preferences | Any user (for their own account) |
| View org defaults | Any user (read-only for non-admins) |
***
## Limitations
* **Task notifications only** — not arbitrary app activity, comments, mentions, or non-task threads.
* **Two channels** — in-app banner/inbox and email. No SMS, mobile push, or webhook delivery. Task notifications are not delivered to Slack, but teams that start work from Slack get progress and completion updates in the Slack thread through the [Slack integration](/docs/integrations-administration-and-setup/integrations/slack).
* **Five fixed event types** — users choose channels per event but cannot define custom events or trigger conditions.
* **Email is not instant** — processed by a background job in near-real-time batches; the in-app banner is the immediate channel.
***
## Availability
**Access:** Must be enabled for your organization. Contact your Gradial team to get access.
# Accessibility Reports
Source: https://docs.gradial.com/docs/quality-assurance-and-accessibility/accessibility-report
Identify, prioritize, and resolve WCAG 2.2 AA accessibility violations across your digital content with Gradial's automated accessibility reports.
## Overview
Accessibility isn't just a compliance requirement—it's about ensuring your content reaches and serves all users, including those who rely on assistive technologies. Gradial makes accessibility actionable by:
* Automatically detecting accessibility violations in your content
* Distinguishing between issues you can fix directly in your CMS and those requiring design or development changes
* Providing clear remediation guidance for each issue
* Tracking accessibility status across pages and over time
## WCAG 2.2 AA Compliance
Gradial's accessibility checks are based on the [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/) Level AA standard. This is the globally recognized benchmark for digital accessibility and the standard referenced by most accessibility regulations and policies.
### The Four Principles
WCAG organizes requirements around four principles. Your content must be:
**Perceivable** Users must be able to perceive the content through at least one of their senses. This includes providing text alternatives for images, captions for video, and sufficient color contrast.
**Operable** Users must be able to navigate and interact with your content. This includes keyboard accessibility, clear link text, and avoiding content that could cause seizures.
**Understandable** Users must be able to understand both the content and how to use the interface. This includes readable text, predictable navigation, and helpful error messages.
**Robust** Content must be compatible with current and future tools, including assistive technologies. This includes valid HTML, proper ARIA usage, and semantic markup.
### What Gradial Checks
Accessibility reports validate against key WCAG 2.2 AA success criteria, including:
| Category | Checks Include |
| :------------------ | :---------------------------------------------------------------- |
| **Images** | Alt-text presence, decorative image handling, image-of-text usage |
| **Structure** | Heading hierarchy, landmark regions, list markup |
| **Links & Buttons** | Discernible text, descriptive labels, keyboard focus |
| **Forms** | Input labels, error identification, required field indication |
| **Color** | Contrast ratios, color-only information |
| **ARIA** | Valid attributes, permitted roles, proper usage patterns |
| **Media** | Captions, audio descriptions, autoplay controls |
## Using Accessibility Reports
Gradial supports two primary workflows: auditing existing content and validating new content before publication.
### Auditing Existing Pages
Use accessibility reports to audit pages already in production and identify remediation priorities.
**Running an Audit**
1. Enter the URL of the page you want to audit
2. Run the QA review to generate a report
3. Filter to the **Accessibility** tab to focus on accessibility results
**Prioritizing Remediation**
Not all accessibility issues require the same level of effort to fix. The report helps you prioritize by showing:
* **Severity** — How significantly the issue impacts users
* **Scope** — How many elements or pages are affected
* **Actionability** — Whether the issue can be fixed in your CMS or requires other teams
Start with high-severity issues that affect the most users, then work through lower-priority items systematically.
### Validating New Content
Integrate accessibility checks into your content workflow to catch issues before they go live.
**Pre-Publication Checks**
After authoring new content or making updates:
1. Run QA before submitting for review
2. Review the accessibility section of the report
3. Resolve any issues flagged
4. Re-run QA to confirm fixes
5. Proceed with publication
By checking accessibility before publication, you avoid introducing new issues into production and reduce the backlog of remediation work.
## Remediation Workflows
Accessibility issues fall into two categories: those you can fix directly in your CMS and those requiring coordination with design or development teams.
### Issues You Can Fix in Your CMS
Many common accessibility issues can be resolved by content authors directly within the CMS. Gradial can automatically suggest or apply fixes for these issues.
**Missing Alt-Text**
When an image component lacks alt-text, Gradial flags the issue and can:
* Prompt you to add descriptive alt-text
* Pull alt-text from DAM metadata if available
* Suggest marking the image as decorative if appropriate
*How to fix:* Edit the image component and add alt-text that describes the image's purpose or content. If the image is purely decorative, set the alt attribute to empty.
**Missing Form Labels**
Form inputs without associated labels are inaccessible to screen reader users.
*How to fix:* Ensure every form field has a visible label connected via the `for` attribute or wrapped around the input.
**Empty Links and Buttons**
Links or buttons without discernible text can't be understood by assistive technology users.
*How to fix:* Add visible text, or for icon-only buttons, add an aria-label that describes the action.
**Heading Hierarchy Issues**
Skipped heading levels (e.g., jumping from H1 to H3) create navigation problems for screen reader users.
*How to fix:* Restructure headings to follow a logical hierarchy without skipping levels.
### Issues Requiring Other Teams
Some accessibility issues stem from design decisions or code implementation that content authors cannot change directly. Gradial helps you identify and route these appropriately.
**Color Contrast**
When text doesn't have sufficient contrast against its background, it's difficult for users with low vision to read.
*Why authors can't fix it:* Contrast issues typically involve brand colors, component styles, or background images controlled by design systems or CSS.
*Remediation path:* Flag the issue to your design team with the specific contrast ratio and WCAG requirement. They can update the design system or provide alternative color options.
**Focus Indicators**
Interactive elements must have visible focus states for keyboard users.
*Why authors can't fix it:* Focus styles are defined in CSS and component code.
*Remediation path:* Report to your development team. Include which components lack visible focus and the relevant WCAG criteria (2.4.7 Focus Visible).
**Keyboard Traps**
Users must be able to navigate into and out of all components using only a keyboard.
*Why authors can't fix it:* Keyboard behavior is controlled by JavaScript and component implementation.
*Remediation path:* Document which component creates the trap and the steps to reproduce. Route to development for investigation.
**Complex Widget Accessibility**
Carousels, modals, accordions, and other interactive components require specific ARIA patterns and keyboard handling.
*Why authors can't fix it:* These behaviors are built into component code.
*Remediation path:* Note the component and specific issue (e.g., "carousel lacks pause button" or "modal doesn't trap focus"). Development can update the component to follow [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/).
### Routing Issues to the Right Team
When Gradial identifies an issue that requires design or development work:
1. **Document the issue** — Note the page URL, component, and specific failure
2. **Reference the WCAG criterion** — Include the success criterion number and level (e.g., "1.4.3 Contrast Minimum, Level AA")
3. **Explain the user impact** — Help the team understand who is affected and how
4. **Track in your issue system** — Create tickets in your project management tool so issues aren't lost
5. **Verify the fix** — Re-run the accessibility report after changes are deployed
## Understanding Results
### Status Definitions
| Status | Meaning |
| :------------- | :------------------------------------------------------------------ |
| **Passed** | The content meets the accessibility requirement |
| **Failed** | A violation was detected that must be corrected |
| **Incomplete** | Automated testing found something that requires manual verification |
### Incomplete Results
Some accessibility requirements can't be fully validated through automation. When you see "Incomplete," manual review is needed to determine pass or fail.
Common incomplete checks include:
* **Alt-text quality** — Automation can detect if alt-text exists, but only a human can verify it accurately describes the image
* **ARIA accuracy** — Automation can check if ARIA is valid, but only testing confirms it creates the intended experience
* **Reading order** — Automation can identify potential issues, but manual testing confirms logical flow
For incomplete results, test the specific element with assistive technology or keyboard navigation to make a final determination.
## Best Practices
### Building Accessibility into Your Workflow
**Check early and often.** Run accessibility reports during authoring, not just before publication. It's easier to fix issues when the content is fresh.
**Train authors on common issues.** When authors understand accessibility basics, they create better content from the start.
**Establish clear handoff processes.** Define how content-fixable issues are resolved vs. how design/dev issues are routed and tracked.
### Maintaining Accessible Content
**Audit regularly.** Even pages that passed initially can develop issues through updates. Schedule periodic audits of high-traffic pages.
**Monitor for regressions.** When components or templates change, re-check pages using those elements.
**Learn from patterns.** If the same issues appear repeatedly, address the root cause—update templates, improve author training, or refine component defaults.
## Additional Resources
* [WCAG 2.2 Specification](https://www.w3.org/TR/WCAG22/) — The complete technical standard
* [Understanding WCAG 2.2](https://www.w3.org/WAI/WCAG22/Understanding/) — Explanations and examples for each success criterion
* [ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/) — Patterns for building accessible interactive components
* [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) — Tool for testing color contrast ratios
***
## Who this is for
| Role | What Gradial handles |
| :---------------------- | :------------------------------------------------------------------------------------- |
| **Accessibility Lead** | WCAG 2.2 AA violations found across the estate, prioritized, with remediation guidance |
| **Web Producer** | A clear split between what you can fix in the CMS and what needs design or engineering |
| **Legal / Risk** | Conformance evidence on every page rather than an annual audit sample |
| **Content Author** | Alt text and heading structure checked as you go, not flagged months later |
| **Designer / Engineer** | Only the issues that genuinely need a design or code change routed to you |
# QA Reports
Source: https://docs.gradial.com/docs/quality-assurance-and-accessibility/qa-report
Understand what Gradial's QA reports surface, how to read them, and how to integrate quality checks into your content workflow.
## Why This Matters
Quality review is the step that gets skipped when the launch date is tomorrow. Not because anyone thinks it's optional — because it's manual, it's slow, and it's the last thing standing between a finished page and a deadline. So it gets sampled: check a few pages, assume the rest are fine, ship.
Then the disclaimer is missing on the one page a regulator looks at, or the brand name is styled three different ways across a campaign, or the alt text is empty on the hero of the highest-traffic page on the site.
QA reports run on every output rather than a sample, before anything reaches a human reviewer — so review becomes a decision, not an inspection.
***
QA reports evaluate content against the rules your organization has defined — surfacing failures, explaining why they occurred, and guiding resolution before content reaches reviewers or goes live.
Rules are configured in the [Rules Manager](/docs/marketing-brain/managing-skills). Once rules are active, QA runs automatically on every task output.
***
## Reading a QA Report
When a QA review runs, Gradial generates a report showing how content performed against each active rule.
### Report summary
At the top of every report:
| Field | What it shows |
| ---------------- | --------------------------------------- |
| **Rules failed** | Count of rules the content did not pass |
| **Rules passed** | Count of rules the content met |
| **Incomplete** | Checks that require manual verification |
### Result detail
Each rule result includes:
| Field | Description |
| --------------- | ----------------------------------------------------------------- |
| **Title** | The rule name |
| **Type** | Whether this is a brand/compliance Rule or an Accessibility check |
| **Status** | Passed, Failed, or Incomplete |
| **Explanation** | What was found and why it failed |
Click any result to expand the full explanation — including the exact content that triggered the failure and guidance on how to fix it.
### Status definitions
* **Passed** — Content meets the standard
* **Failed** — A violation was detected that must be corrected
* **Incomplete** — Automated testing found something that requires manual verification before a final determination can be made
***
## Issue types
QA reports surface issues across five categories:
| Category | What it catches |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Brand & editorial** | Voice and tone violations, unapproved terminology, messaging inconsistencies |
| **SEO** | Missing or duplicate meta descriptions, heading hierarchy problems, keyword usage |
| **Compliance** | Missing required disclosures, unapproved claims, regional regulatory language |
| **Accessibility** | Alt-text, heading structure, ARIA, color contrast — see [Accessibility Reports](/docs/quality-assurance-and-accessibility/accessibility-report) for full detail |
| **Functional** | Missing asset references, broken links, incomplete metadata |
Not all issues carry equal weight. Compliance and accessibility failures have regulatory implications; editorial issues may be lower priority. Use the severity and explanation fields to triage.
***
## QA in your content workflow
The authoring agent produces output guided by active rules. Planning-agent rules apply early, before authoring begins. Integration-agent rules apply during content creation.
After the authoring agent completes work, the QA agent evaluates the output against all active rules for that workspace and integration.
Failed and incomplete checks appear in the report with explanations. Content with failures is flagged before it reaches a human reviewer.
Fix the flagged issues and re-run QA to confirm. Content with a clean report moves to review with confidence.
With baseline quality validated automatically, reviewers can focus on strategic messaging, creative direction, and stakeholder alignment — not catching compliance issues.
***
## Scaling QA across teams
QA reports are most valuable when distributed teams — regional marketers, agency partners, extended business teams — are creating content without deep familiarity with every brand guideline.
**The report explains, not just flags.** Each failure includes the reasoning: what the rule requires, what was found, and how to fix it. Authors self-correct before submitting for review, which reduces back-and-forth.
**Pass rates improve over time.** As authors encounter and resolve the same rule types repeatedly, the failures decrease. Teams that track pass rates over time see measurable quality improvement without increased review overhead.
**Give the trend a home.** A per-output report answers "is this page ready"; it doesn't answer "how are we doing." Ask Grady for a [custom app](/docs/insights/custom-apps) to get a dashboard across QA results — pass rates by team or campaign, the rules that fail most often, and what's still waiting on a fix.
**Add rules as patterns emerge.** If the same issue keeps appearing and no rule currently catches it, add one. The rules library grows in response to real production patterns.
***
*To configure the rules that power QA reports, see [Rules & Skills](/docs/marketing-brain/managing-skills). For accessibility-specific results and WCAG remediation guidance, see [Accessibility Reports](/docs/quality-assurance-and-accessibility/accessibility-report).*
***
## Who this is for
| Role | What Gradial handles |
| :-------------------------------- | :-------------------------------------------------------------------------------------------- |
| **Web Producer / Content Author** | Issues caught and explained before review, not after a stakeholder finds them |
| **Brand Manager** | Every output checked against brand standards, not a sample |
| **Legal / Compliance Reviewer** | Required disclosures and regulated wording verified on every page, with a record of the check |
| **Accessibility Lead** | WCAG conformance measured across the estate rather than spot-checked |
| **Marketing Leadership** | A launch that doesn't depend on whether anyone had time to review it properly |
### How this maps to your function
In a regulated environment the cost of a missed disclosure isn't a correction — it's exposure. Sampling is the standard practice because full review doesn't scale manually, which means the assurance you have is statistical rather than actual. Checks that run on every output change what you're able to claim. See [Regulated Industries & Compliance Workflows](/docs/governance/regulatory-compliance).
Brand drift is rarely a decision. It's the accumulation of small inconsistencies introduced under deadline — the name styled two ways, the CTA that doesn't match the pattern, the tone that slipped. Consistent automated checks make the standard real at the point content is produced, rather than something audited quarterly and corrected retroactively.
# Localization & MSM Inheritance
Source: https://docs.gradial.com/docs/translation-and-localization/msm
How Gradial works with AEM Multi Site Manager — respecting MSM inheritance by default while giving administrators control to override when needed.
**AEM-specific.** Multi Site Manager is an AEM feature, so this page applies to AEM environments only. Other CMS platforms handle localized site structures differently — Gradial respects each platform's own inheritance model.
## How MSM Inheritance Works
AEM's Multi Site Manager allows you to create language copies and regional variations that inherit content from a source (blueprint). When the source is updated, those changes can roll out automatically to inherited pages—keeping localized sites in sync without manual updates.
Inheritance can be set at the page level or component level:
* **Page-level inheritance** — The entire page inherits from the blueprint
* **Component-level inheritance** — Individual components inherit while others are localized independently
This architecture is powerful for managing global sites, but it also means edits need to be made carefully. Changing an inherited component breaks that inheritance relationship, which may not be the intended outcome.
## How Gradial Respects Inheritance
By default, Gradial protects MSM inheritance to prevent unintended breaks in your localization architecture.
### MSM Inheritance Protection
When **MSM Inheritance Protection** is enabled (the default), Gradial blocks edits to pages or components with active inheritance. This ensures that:
* Inherited content isn't accidentally overwritten
* Your blueprint/live copy relationships stay intact
* Localization teams don't inadvertently break rollout configurations
If Gradial encounters a page with active inheritance, it will notify you rather than proceeding with edits that would break the inheritance chain.
## Common Issue: "Why Can't I Edit This Page?"
Sometimes users report that Gradial is "blocking" them from editing a page. In most cases, Gradial isn't blocking the edit—MSM inheritance is.
### What's Happening
When you see a message about inheritance preventing an edit, it means:
1. The page (or component) you're trying to edit is a live copy
2. It's currently inheriting content from a blueprint page
3. Gradial is protecting that relationship so it doesn't get broken accidentally
### What This Means
If Gradial were to edit this page, it would cancel the inheritance. That means future updates to the blueprint would no longer roll out to this page automatically. For most localization setups, that's not what you want.
### What to Do
**If you need to edit the blueprint instead:** The content you want to change may need to be updated on the source blueprint page, not the live copy. Changes to the blueprint will then roll out to all live copies.
**If this page genuinely needs local customization:** Contact your administrator to either disable MSM Inheritance Protection or manually cancel inheritance for this specific page in AEM. This is the right choice when a regional market needs content that differs from the blueprint permanently.
**If you're not sure:** Ask your localization or site architecture team whether this page should be inheriting or independent. They can help determine the right approach.
## Overriding Inheritance
Sometimes you need to break inheritance intentionally—for example, when a regional market requires substantially different content that shouldn't be overwritten by blueprint updates.
### Administrator Override
Administrators can disable MSM Inheritance Protection at the integration level:
1. Navigate to your workspace settings
2. Open **Integrations** and select your AEM configuration
3. In the **General** tab, locate **MSM Inheritance Protection**
4. Uncheck "Block edits to pages with active MSM inheritance"
5. Click **Save Changes**
With protection disabled, Gradial can edit inherited pages directly. This will cancel inheritance for any components that are modified.
### When to Override
Consider overriding inheritance when:
* A regional page needs permanent local customization
* The content strategy for a specific market diverges from the blueprint
* You're doing a one-time localization that shouldn't sync with future blueprint changes
# Translation
Source: https://docs.gradial.com/docs/translation-and-localization/translation
Translate marketing content directly inside your CMS with Gradial's AI agents. No exports or file handoffs required.
## Why Translate with Gradial
### Work Where Your Authors Already Work
Traditional translation workflows pull content out of your CMS, run it through separate systems, and require manual re-integration. This creates delays, version control issues, and context loss.
With Gradial, translation happens inside your CMS. Authors and localization teams work in the same environment they use for everything else. No exports, no file handoffs, no waiting for round-trips.
### Get 80% of Your Content Done Without Leaving Your Workflow
Most translation needs don't require specialized linguists or complex review cycles. Product descriptions, landing pages, blog posts, metadata—this content can be translated directly by the agent while your team stays focused on higher-value work.
Reserve your external translation resources and human review for the 20% that truly needs it: regulated content, legal documents, and high-stakes campaigns. Let Gradial handle the rest.
### Agent-Based Translation Benefits
Because Gradial uses an agent-based approach, translation isn't just mechanical word conversion:
* **Rules are applied automatically** — Your brand glossaries, terminology standards, and style guidelines are enforced during translation, not checked afterward
* **Context is preserved** — The agent understands the page structure, component types, and content relationships in your CMS
* **Iteration is instant** — Need to adjust the translation? Update your task and run it again, just like any other content change
## How to Translate Content
### Creating a Translation Task
1. Create a new task in your workspace
2. Reference the source page URL you want to translate
3. Specify the target language in your request (e.g., "Translate this page to Spanish" or "Create the French version of this page")
4. Run the task
Gradial translates the content and applies any relevant rules, including brand glossaries you've configured.
## Supported Languages
The platform supports content translation through AI model providers. The following languages are well-supported across all configured providers and will generally produce high-quality translations.
Arabic, Chinese (Simplified & Traditional), Czech, Danish, Dutch, Finnish, French, German, Greek, Hebrew, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese (Brazil & Portugal), Romanian, Spanish, Swedish, Thai, Turkish, Ukrainian, Vietnamese
### Notes on Quality
Translation quality is generally highest for languages with the most training data. English, Spanish, French, German, Japanese, Chinese, and Portuguese have the most training data.
### Regional Variants
For languages with regional differences, specify the variant in your request:
* "Translate to Canadian French" (not France French)
* "Translate to Swiss German" (not Germany German)
* "Translate to Mexican Spanish" (not Spain Spanish)
* "Translate to Brazilian Portuguese" (not Portugal Portuguese)
Gradial adapts vocabulary, spelling, and expressions for the specified region.
## Translation Modes
### Direct Translation (Default)
By default, Gradial performs direct translation—converting your content to the target language while preserving the original meaning, tone, and structure. This is appropriate for most content where you want the translated version to match the source.
### Content Strategy Rewrite
If you need content adapted for a different market rather than directly translated, specify this in your task:
"Translate this page to German, but adapt the messaging for the German market rather than translating directly."
Use content strategy rewrite when cultural references, market positioning, or competitive context differs significantly between regions.
## Brand Glossaries
Glossaries ensure consistent terminology across all translations. Common glossary entries include product names, feature names, branded terms, and industry-specific vocabulary.
### Adding a Glossary
Glossaries are managed as rules in the Rules Manager:
1. Navigate to **Rules**
2. Click **Create Rule Manually**
3. Add your terminology with source terms and approved translations
4. Assign the rule to the translation workflow
Example glossary rule content:
| Source Term | Translation | Notes |
| :-------------- | :------------- | :-------------- |
| Dashboard | Dashboard | Keep in English |
| Quick Start | Schnellstart | German |
| Customer Portal | Portail client | French |
Once configured, Gradial automatically applies your glossary to all translations.
## Bulk Metadata Translation
Metadata fields like page titles, meta descriptions, and image alt-text are often overlooked in traditional translation workflows—they're buried in CMS fields and easy to miss when content is exported for translation.
With Gradial, you can translate these fields in bulk without leaving your CMS:
1. Create a task specifying the pages or section to translate
2. Indicate you want to translate metadata/SEO fields
3. Specify the target language
This ensures your localized pages are fully optimized for search without manual field-by-field work or separate metadata translation projects.
## Human Review for Sensitive Content
Gradial handles the bulk of translation work, but we recommend adding human review for:
* **Regulated content** — Financial, healthcare, legal, or pharmaceutical materials
* **Legal documents** — Terms of service, privacy policies, contracts
* **Safety-critical content** — Warnings, medical instructions, emergency procedures
For these content types, use Gradial to generate the initial translation, then route to qualified human reviewers before publication.
## Best Practices
**Set up glossaries before scaling.** Consistent terminology is easier to establish upfront than to fix across existing translations.
**Start with quality source content.** Clear, well-written source content produces better translations.
**Specify regional variants explicitly.** Don't assume "French" means the right variant for your market—be specific.
**Use bulk operations for metadata.** Translate SEO fields in batches rather than page-by-page.
***
## Who this is for
| Role | What Gradial handles |
| :-------------------------------- | :---------------------------------------------------------------------------------------------------- |
| **Localization Manager** | Translation happening in place, without an export, a vendor round-trip and a re-import |
| **Regional / In-Market Marketer** | Your market's pages current at the same time as the master, not weeks behind |
| **Content Ops** | No file handoffs to track, and no version drift between source and translation |
| **Brand Manager** | Voice and terminology holding across languages, because the same standards apply to every locale |
| **Web Producer** | Inheritance and regional overrides respected, so a translation doesn't break the market's own changes |
### How this maps to your function
The real cost of the export-translate-reimport cycle isn't the translation — it's the latency. By the time a market's pages are current, the master has moved on, so regional teams are permanently working from a version that's already stale, and campaign timing across markets never quite lines up. Translating in place removes the round trip, which is what lets markets launch together.
File-based workflows lose context: the translator sees a string, not the component it renders in or the page it lives on. That's where most localization QA findings come from. Working inside the CMS keeps the content and its context together, and the same brand and accessibility checks that run on the source run on every locale.
# Video Translation
Source: https://docs.gradial.com/docs/translation-and-localization/video-translation
Localize talking-head video into another language — translated audio in the speaker's own voice, synchronized mouth movement, and localized on-screen text.
Localizing a video normally means moving one source file between four different tools: a dubbing service for the audio, a lip-sync tool for the picture, a design tool for the on-screen text, and an editor to reassemble it all. Every handoff is a place for timing to drift and branding to break.
Gradial can now run that whole chain inside a single task. Ask Grady to localize a talking-head video and it coordinates the voice, visual synchronization, on-screen text, and final assembly steps, then returns one playable video file.
Grady can also generate a new video from a written creative prompt.
***
## What Grady can do
### Generate a video from a prompt
Describe the video you want in a written creative prompt and Grady can create it.
### Dub while preserving the speaker's voice
Existing speech can be translated into another language while retaining the original speaker's voice, delivery, and overall timing — so the localized version still sounds like the person who recorded it.
### Synchronize visible speech
Where a speaker is on camera, Grady can adjust their mouth movement to match the translated audio, or audio you supply yourself.
### Localize static on-screen text
Full-screen title cards, presentation slides, and clean static text panels can be translated while preserving their layout and branding.
On-screen text localization covers **static** text — title cards, slides, and clean text panels. Text that moves, animates, or sits over busy footage is not in scope.
### Assemble and deliver one file
Translated audio, synchronized footage, and localized static text are combined into a single, broadly compatible video file. Completed videos are published directly in the task as downloadable artifacts, ready to play or hand off.
***
## How delivery is verified
Video work runs long and depends on external processing, so Gradial checks the result before handing it back:
| Check | What it confirms |
| ---------------------- | -------------------------------------------- |
| **Readable picture** | The video decodes and renders |
| **Supported encoding** | The output uses a broadly compatible format |
| **Expected duration** | The finished video runs the length it should |
| **Non-silent audio** | The audio track actually contains sound |
Grady tracks long-running provider jobs through to completion, and safely reuses a matching submission when a task is retried — so a retry doesn't silently kick off duplicate work.
***
## Related
* [Translation →](/docs/translation-and-localization/translation) — translating page content in your CMS
* [Multi-Site Manager →](/docs/translation-and-localization/msm) — managing localized site structures
* [Digital Asset Management →](/docs/asset-management/digital-asset-management) — managing the assets your campaigns use
***
## Availability
**Access:** Must be enabled for your organization. Contact your Gradial team to get access.
# Roll a Change Across the Whole Site
Source: https://docs.gradial.com/docs/updating-existing-experiences-i-e-content-updates/complex-content-updates
Site-wide and multi-page operations — find-and-replace, bulk property updates, SEO and analytics audits, and coordinated campaign launches across large content sets.
Legal changes a required disclaimer. Marketing retires a product name. The brand becomes one word instead of two. The change itself is trivial; finding every place it appears is the project — across every locale, every section, every depth of the site, including the pages nobody has opened in two years.
The usual answer is a spreadsheet, a week of someone's time, and a web producer running the same CMS operation four hundred times. The usual outcome is that eleven pages get missed and surface in an audit six months later.
These are operations that span many pages, need pattern-matching across a site, or need systematic auditing before anything is changed.
These updates affect multiple pages or site-wide properties. Always confirm scope and review a representative sample before promoting changes to production.
***
### What this covers
| Update Type | Examples |
| :---------------------------- | :------------------------------------------------------------------------------------------------------ |
| Find-and-replace | Rebranding copy across a site section, updating legal disclaimers, year changes |
| Bulk page property updates | Updating metadata, analytics tags, or page properties across sets of pages |
| Site audits | Identifying broken links, missing metadata, accessibility issues, or outdated content at scale |
| Coordinated campaign launches | Synchronized updates across many pages with staging and sequenced publishing |
| Analytics & tracking updates | Adding or modifying data layer properties, UTM structures, or tag configurations across pages |
| Template-wide changes | Applying a consistent structural change across all pages using a given template |
| CMS maintenance | Folder creation, path lookups, tag creation and updates — structural work that's tedious to do manually |
***
## Update Type: Find-and-Replace
### Purpose
Make consistent text changes across multiple components or pages in bulk — without opening each page manually.
### Common Scenarios
* **Rebranding**: Company name, product names, or taglines changing across a site section
* **Legal & compliance**: Updating disclaimer text, terms language, or copyright notices globally
* **Date & year updates**: © 2024 → © 2025 across all pages
* **Terminology standardization**: Replacing deprecated product names or category labels
### How It Works
1. **Define the search term** — exact text string or pattern to locate
2. **Define the replacement text** — what it should become
3. **Set the scope** — specific section, page template, or site-wide
4. Gradial **identifies all instances** and generates a change list for review
5. **Review the change list** — inspect matches in context before committing
6. **Apply selectively or in bulk** — approve all or exclude specific instances
### Considerations
* Review matches carefully — the same term may need different handling in different contexts (e.g., a product name in copy vs. in a URL)
* Gradial preserves surrounding formatting and linked content when replacing text
* For large scopes, review a representative sample before approving the full set
***
## Update Type: Bulk Page Property Updates
### Purpose
Update metadata, page properties, or configuration fields across a large set of pages without touching each one individually.
### Common Scenarios
* Setting or standardizing SEO title and description fields across a section
* Updating Open Graph or social sharing properties for a product line
* Adding or changing `noindex` / `canonical` configurations
* Updating page-level analytics tags (e.g., content category, business unit, page type)
* Assigning or reassigning template references after a design system update
### How It Works
1. **Define the target page set** — by URL pattern, template type, section path, or uploaded list
2. **Specify the property to update** and the new value (or the transformation logic — e.g., append a suffix, replace a value)
3. Gradial **generates a preview of all changes** across the page set
4. **Review and confirm scope**
5. **Apply** — Gradial updates each page's properties through your CMS, staged for review before publish
### Tips
* Provide a CSV or spreadsheet with page paths and target values for precise, row-by-row control
* For analytics properties, confirm the data layer field names with your analytics team before running
***
## Update Type: Site Audits
### Purpose
Systematically scan a section or the full site to identify content issues — broken links, missing metadata, accessibility problems, outdated content — and generate a prioritized issue list or apply fixes in bulk.
### Common Scenarios
* **Pre-launch QA**: Validate all pages in a new section before go-live
* **SEO hygiene**: Identify pages missing title tags, descriptions, or canonical URLs
* **Accessibility**: Flag pages with missing alt text, improper heading structure, or low-contrast components
* **Broken link detection**: Surface links pointing to 404s or deprecated URLs across a site section
* **Stale content**: Identify pages with outdated dates, deprecated product references, or missed rebranding instances
### How It Works
1. **Define the audit scope** — section path, template, or a list of URLs
2. **Specify what to check** — link validity, SEO fields, accessibility attributes, content patterns
3. Gradial **scans each page** and returns a structured report with issues, severity, and page location
4. **Review the report** — prioritize by issue type or page importance
5. **Optionally apply fixes in bulk** — for issues with a clear resolution (e.g., fill missing alt text, correct a broken URL), Gradial can apply fixes across the flagged pages
***
## Update Type: Analytics & Tracking Updates
### Purpose
Add, update, or standardize data layer properties, analytics tags, or tracking configurations across pages — ensuring consistent, accurate reporting without manual CMS edits.
### Common Scenarios
* Rolling out a new data layer schema across a site section
* Adding UTM-aware tracking parameters to CTAs at scale
* Updating page-type or content-category classifications for reporting
* Correcting inconsistent tag implementations discovered in an audit
* Migrating from one analytics platform's tag structure to another
### How It Works
1. **Define the target pages** — by section, template, or uploaded list
2. **Provide the tag specification** — field names, values, and any conditional logic (e.g., product pages vs. blog pages get different values)
3. Gradial **updates the relevant page properties or component fields** across the set
4. **Review a sample** to confirm correct implementation
5. **Apply and stage** for QA before publish
### Tips
* Coordinate with your analytics or data team to confirm field names and expected values before running
* Use a spreadsheet input for complex tag mappings where each page or page type has unique values
***
## Update Type: Coordinated Campaign Launches
### Purpose
Execute synchronized content updates across many pages — ensuring consistent messaging, accurate links, and aligned publishing across a campaign's full scope.
### Common Scenarios
* Launching a product refresh where headline, imagery, and CTAs need updating across 30+ product pages
* Running a seasonal campaign that touches landing pages, navigation elements, and promotional banners simultaneously
* Coordinating a global messaging change across regional sites with per-region variations
### How It Works
1. **Define the campaign scope** — all pages, components, and assets involved
2. **Provide the update brief** — new copy, imagery, links, or structured input (spreadsheet, copy doc)
3. Gradial **stages all changes** across the full page set, ready for review before any page goes live
4. **Review and approve** — inspect the full change set or approve by section
5. **Coordinate publishing** — publish pages in sequence or simultaneously based on your go-live plan
For campaigns with per-page or per-region variation, provide a spreadsheet where each row maps a page to its specific content. Gradial processes the full list consistently.
***
## Update Type: CMS Maintenance Tasks
### Purpose
Handle the structural and administrative work inside your CMS that's too tedious to do manually at scale — folder setup, path resolution, and tag management. These tasks are typically owned by CMS admins or power users, but even individual contributors run into them constantly when setting up new campaigns, onboarding new sites, or keeping taxonomy up to date.
### Folder Creation
Large-scale content operations often require standing up new folder structures in the CMS before authoring can begin — for a new campaign, a new regional site, a new product line, or a content migration. Doing this manually means navigating the CMS tree page by page.
**Common scenarios:**
* Creating a full folder hierarchy for a new campaign or launch (e.g., `/content/brand/en/campaigns/2025/q3-launch/` with all subfolders and correct permissions)
* Setting up new locale or regional folder structures when expanding to new markets
* Preparing a migration destination before content is moved or created in bulk
**How it works:** Provide the target path, the folder structure you need (can be a simple description or a tree outline), and any metadata or permission requirements. Gradial creates the folder hierarchy in your CMS, ready for content authoring.
***
### Path Reference Lookups
Content authors frequently need to reference exact CMS paths — for linking, for configuring components, for setting page parents — and tracking these down manually means navigating deep content trees or asking a CMS admin.
**Common scenarios:**
* Looking up the correct content path for a page, asset, or fragment to use in a component configuration
* Finding the DAM path for a specific image or asset before referencing it in a template
* Resolving where a reusable component or fragment lives before wiring it to a new page
* Auditing which pages reference a specific path (e.g., before moving or deleting a resource)
**How it works:** Describe what you're looking for — a page name, fragment title, asset description, or pattern — and Gradial queries your CMS to return the correct path. For audits, Gradial can return a list of all pages referencing a given path.
***
### Tag Creation and Updates
Tags in enterprise CMS platforms (AEM tags, Sitecore taxonomy, Contentful tags) are foundational to content organization, filtering, personalization, and reporting. Keeping them consistent across a large site is slow work when done through the CMS UI.
**Common scenarios:**
* Creating a new tag namespace or taxonomy tree for a product launch or content type
* Applying or updating tags across a set of pages or assets in bulk (e.g., tagging all pages in a campaign section with a new content-type tag)
* Renaming or reorganizing tags when taxonomy changes — and updating all content that references the old tag
* Auditing tag usage: which pages use a given tag, which pages are missing required tags
**How it works:**
* **Create tags**: Specify the tag namespace, hierarchy, and any required metadata. Gradial creates the tag structure in your CMS.
* **Apply tags to content**: Define the target pages or assets and the tags to apply. Gradial updates each item's tag fields in bulk.
* **Update or migrate tags**: Specify the old tag and new tag. Gradial finds all content referencing the old tag and updates references to the new one.
* **Audit tags**: Define the scope and Gradial returns a report of tag usage, missing tags, or inconsistencies across the content set.
Tag changes that affect how content is personalized or filtered can have broad downstream effects. Always confirm the full impact with your CMS admin before applying tag migrations at scale.
***
## General Workflow for Complex Updates
Identify the full set of pages, properties, or content items involved. Be explicit — use URL lists, section paths, or template identifiers.
Attach a brief, copy doc, or spreadsheet with the target values. The more structured your input, the more accurately Gradial can apply changes at scale.
Before applying anything, review Gradial's full change list. For large sets, inspect a representative sample across page types.
Run the operation. All changes are staged in your CMS's review layer (AEM Launch, workflow state, draft environment) — nothing hits production automatically.
Spot-check across the staged set. Approve and promote using your standard CMS publishing workflow.
***
## When to Use Complex Updates
* Rebranding or terminology changes affecting more than a handful of pages
* SEO, accessibility, or analytics audits that need to scale beyond manual spot-checks
* Campaign launches touching 10+ pages that need consistent staging before go-live
* Setting up folder structures, resolving path references, or managing tags before or during a content project
* Any operation where running the same CMS action manually across many pages would take hours or days
# Content Updates
Source: https://docs.gradial.com/docs/updating-existing-experiences-i-e-content-updates/content-updates
Update existing pages and experiences across every connected CMS — from a one-line copy change to a phrase swapped on every page of the site.
Enterprise content teams are stuck in a cycle that doesn't scale. Every page update — a headline change, a link fix, a campaign refresh — means opening a ticket, waiting on a developer or web producer, manually entering content field by field in AEM or Sitecore, running QA, and submitting for approval. For a 50-page campaign launch, this can take weeks. When messaging or branding changes globally, coordinating updates across hundreds of pages is practically a project in itself.
And the requests never arrive in a convenient shape. A stakeholder sends a marked-up screenshot. Legal sends a Word doc with fourteen tracked changes. Someone asks whether the old product name still appears anywhere on the site, and nobody actually knows.
Gradial works directly inside your CMS — reading, updating, and staging content from your instructions — so content teams can execute at the speed the business demands without burning out web producers or opening engineering tickets for routine changes.
***
## Who this is for
Tired of repetitive field-by-field entry. Need to push updates faster without waiting on dev queues.
Managing high volumes of page QA, publishing workflows, and manual CMS work daily. The most time-constrained people in the content supply chain.
Measured on campaign launch speed and on-time delivery. Blocked by the gap between brief approval and live page.
***
## What Is a Content Update?
A content update is any task where Gradial reads, modifies, and stages content in a connected system based on your instructions. This includes:
* Editing copy, headlines, or body text
* Swapping or updating images and media
* Modifying links, CTAs, or metadata
* Updating reusable content blocks (fragments, experience fragments)
* Replacing or reordering components on a page
* Bulk changes applied across many pages at once
* Site-wide audits, find-and-replace, and analytics property updates
You can start an update directly in Gradial, by asking Grady, or from your existing ticketing system (Jira, Workfront, Wrike, Asana, monday.com, Azure DevOps).
By default, Gradial does not write directly to production — changes are staged for review first. Organizations that want Gradial to publish can enable it, and publishing then requires explicit human approval on every action. See [Roles & Permissions](/docs/integrations-administration-and-setup/managing-access/roles).
***
## Start with what you need to change
You don't need to classify your request before making it — describe the change and Gradial works out the steps. These pages are here for when you want to know how a particular kind of change is handled.
| What you need | Start here |
| :------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------- |
| Fix a headline, a link, an image or a CTA on one page | [Change Copy, Links or Images on a Page](/docs/updating-existing-experiences-i-e-content-updates/small-content-updates) |
| Apply a stakeholder's marked-up screenshot | [Change Copy, Links or Images on a Page](/docs/updating-existing-experiences-i-e-content-updates/small-content-updates) |
| Swap a component or restructure a section | [Rework Sections and Reusable Content](/docs/updating-existing-experiences-i-e-content-updates/medium-content-updates-in-gradial) |
| Change a reusable block that appears on many pages | [Rework Sections and Reusable Content](/docs/updating-existing-experiences-i-e-content-updates/medium-content-updates-in-gradial) |
| Work through a Word doc, deck or spreadsheet of changes | [Rework Sections and Reusable Content](/docs/updating-existing-experiences-i-e-content-updates/medium-content-updates-in-gradial) |
| Swap a brand name, legal phrase or disclaimer everywhere it appears | [Roll a Change Across the Whole Site](/docs/updating-existing-experiences-i-e-content-updates/complex-content-updates) |
| Update metadata, analytics tags or page properties in bulk | [Roll a Change Across the Whole Site](/docs/updating-existing-experiences-i-e-content-updates/complex-content-updates) |
| Find out where something appears before changing it | [Site Search & Find-and-Replace](/docs/updating-existing-experiences-i-e-content-updates/site-search) |
| Launch a campaign's worth of coordinated changes at once | [Roll a Change Across the Whole Site](/docs/updating-existing-experiences-i-e-content-updates/complex-content-updates) |
***
## Where this works
Content updates are native in every connected CMS: **Adobe AEM** (6.5 and Cloud Service), **SitecoreAI CMS** (XM Cloud), **Sitecore XP**, **Contentful**, **Contentstack**, **Sanity**, **Drupal**, **WordPress**, and **Gradial ACI**.
The mechanics differ by platform — what a "reusable block" is called, how staging and publishing work, what a component's fields look like — and Gradial uses each platform's own model. Some capabilities on these pages are AEM-specific and are marked where that's the case. See [Integrations](/docs/integrations-administration-and-setup/integrations/get-started-with-integrations) for the current list of connected platforms.
***
*For creating net-new pages, see [New Page Workflow](/docs/creating-new-experiences/new-page). For platform connection setup, see [Integrations](/docs/integrations-administration-and-setup/integrations/get-started-with-integrations).*
# Rework Sections and Reusable Content
Source: https://docs.gradial.com/docs/updating-existing-experiences-i-e-content-updates/medium-content-updates-in-gradial
Swap components, restructure sections, update reusable content blocks, and drive changes from a source document — with the impact known before anything changes.
Some changes don't stay where you put them. Swap a component and the section around it has to still work. Edit a reusable content block and it changes on every page that references it — including pages you weren't thinking about and teams you didn't tell. Hand over a marked-up Word doc with fourteen changes in it and someone has to translate each one into a CMS operation.
This is where content work stops being typing and starts being judgment about scope. Gradial does the typing and shows you the scope first: which pages reference the block you're about to change, what the section looks like after the swap, and what the source document actually asked for.
### What this covers
| Change | Examples |
| :---------------------- | :------------------------------------------------------------------ |
| Component swaps | Replacing one component type with another |
| Batched changes | Multiple discrete updates in a single request or ticket |
| Find-and-replace | Text changes across components or a handful of pages |
| Reusable content | Creating or updating content fragments and structured content items |
| Shared page sections | Updating experience fragments and other multi-page blocks |
| Versioning | Creating a new version of an existing page before you change it |
| Document-driven updates | Updating pages from Word docs, decks, PDFs or spreadsheets |
***
## General Workflow
These updates follow an extended version of the standard workflow:
1. **Start a content update task** in Gradial
2. **Define the scope** (single component, multiple components, or fragment)
3. **Provide source material or instructions**
4. **Generate revised content**
5. **Review and refine** across all affected areas
6. **Run QA and validation checks**
7. **Apply updates** in the CMS
***
## Update Type: Component Swaps
### Purpose
Replace an existing component with a different component type while preserving content intent and page structure.
### Common Scenarios
* Swapping a basic text component for a text-with-image component
* Replacing a static banner with an interactive carousel
* Upgrading a legacy component to a newer version
* Changing a CTA style (e.g., button to card)
### How It Works
1. **Select the target page and component** to be replaced
2. **Specify the new component type** to use
3. **Provide mapping guidance** for how existing content should transfer
4. Gradial **generates the new component** with migrated content
5. **Review the swap** to ensure content and layout integrity
6. **Apply the change** via Launch or direct authoring
### Considerations
* Field mappings between old and new components may require manual guidance
* Some content may not have a direct equivalent in the new component
* Visual review is recommended to catch layout shifts
***
## Update Type: Multiple Discrete Changes (Batched Updates)
### Purpose
Execute several unrelated updates across a page or site within a single ticket, improving efficiency for routine maintenance.
### Common Scenarios
* Quarterly compliance updates affecting multiple sections
* Campaign refreshes touching headlines, CTAs, and images
* Post-launch fixes addressing several small issues at once
### How It Works
1. **Create a single task** with multiple update instructions
2. **List each change clearly**, specifying:
* Target page and component for each
* The specific update required
3. Gradial **processes each change independently**
4. **Review all changes** in a consolidated view
5. **Apply updates** together or selectively
### Best Practices
* Number or bullet each discrete change for clarity
* Group changes by page when possible
* Indicate priority if some changes are more urgent
***
## Update Type: Find-and-Replace Edits
### Purpose
Make consistent text changes across multiple components or pages in bulk.
### Common Scenarios
* Rebranding (company name, product names, taglines)
* Legal or compliance updates (disclaimer text, terms)
* Date or year updates (© 2024 → © 2025)
* Terminology standardization
### How It Works
1. **Define the search term** (exact text or pattern)
2. **Define the replacement text**
3. **Set the scope** (single page, section, or site-wide)
4. Gradial **identifies all instances** and generates replacements
5. **Review the change list** before applying
6. **Apply changes** in bulk or selectively
### Considerations
* Review matches carefully—context matters
* Some instances may require different handling
* Preserve formatting and links in replaced text
***
## Update Type: Structured Content Items
### Purpose
Create or update reusable, structured content blocks — Content Fragments in AEM, datasource items in Sitecore, entries in Contentful, and the equivalent in each other connected CMS. See [Working with Fragments](/docs/creating-new-experiences/working-with-fragments) for how these map across platforms.
### Create a Content Fragment
1. **Specify the fragment model** to use
2. **Provide the content** for each field in the model
3. Gradial **generates the fragment** according to the schema
4. **Review field mappings** and content accuracy
5. **Create the fragment** in your CMS
### Update a Content Fragment
1. **Select the existing fragment** to modify
2. **Provide update instructions** for specific fields
3. Gradial **generates revised content** for the targeted fields
4. **Review changes** against the original
5. **Apply the update** to the fragment
### Key Benefits
* Fragment updates propagate everywhere the fragment is used
* Structured content ensures consistency
* Changes are versioned and auditable
***
## Update Type: Layout-Based Blocks
### Purpose
Update reusable page sections that bundle layout and components together — Experience Fragments in AEM, Partial Designs in Sitecore, Content Blocks in SFMC, and the equivalent in each other connected CMS. See [Working with Fragments](/docs/creating-new-experiences/working-with-fragments) for how these map across platforms.
### Common Scenarios
* Updating shared headers or footers
* Modifying promotional banners used across pages
* Refreshing navigation elements
### How It Works
1. **Select the experience fragment** to update
2. **Identify the component(s)** within the fragment to modify
3. **Provide update instructions**
4. Gradial **generates the revised fragment content**
5. **Review the changes** in context
6. **Apply the update** to the experience fragment
### Considerations
* Changes affect all pages using the fragment
* Coordinate with stakeholders before updating shared elements
* Test across multiple page contexts
***
## Update Type: Create a Version of a Page
### Purpose
Generate a new version of an existing page—useful for A/B testing, seasonal variations, or campaign-specific messaging.
### Common Scenarios
* Creating a holiday version of a landing page
* Building an A/B test variant
* Developing a region-specific version
* Archiving current state before major updates
### How It Works
1. **Select the source page** to version
2. **Specify what should change** in the new version
3. Gradial **generates the new page version** with modifications
4. **Review the new version** against the original
5. **Save as a new page** or Launch branch
### Best Practices
* Use clear naming conventions for versions
* Document the purpose of each version
* Set expiration or review dates for temporary versions
***
## Update Type: Document-Driven Updates
### Purpose
Update page content using an external source document—Word doc, PowerPoint, or PDF—as the input.
### Update Page from Copy Doc (Word)
**Best for:** Text-heavy updates with structured content
1. **Upload the Word document** containing approved copy
2. **Map document sections** to page components
3. Gradial **extracts and applies content** to the appropriate fields
4. **Review the mapping** and generated content
5. **Apply updates** to the page
### Update Page from PowerPoint
**Best for:** Campaign or creative briefs with visual layout context
1. **Upload the PowerPoint file**
2. **Indicate which slides** correspond to which page sections
3. Gradial **interprets slide content** and maps to components
4. **Review extracted content** and adjust as needed
5. **Apply updates** to the page
### Update Page from PDF
**Best for:** Approved final documents, legal content, or archived materials
1. **Upload the PDF**
2. **Identify the relevant sections** for extraction
3. Gradial **extracts text and structure** from the PDF
4. **Review and refine** the extracted content
5. **Apply updates** to the page
### Tips for Document-Driven Updates
* Use clean, well-structured source documents
* Annotate or highlight sections that map to specific components
* Provide supplementary instructions for ambiguous areas
* PDFs with complex layouts may require additional guidance
***
## Ticketing Integration for Medium Updates
Medium updates work well with ticketing integrations, though they may require:
* **Richer ticket descriptions** with detailed instructions
* **Attached source documents** (for document-driven updates)
* **Defined scope** (pages, components, or fragments affected)
* **Stakeholder review steps** before final application
The same fast-lane benefits apply—reduced handoffs, consistent tracking, and governed execution—with appropriate review gates for the added complexity.
***
## Key Takeaways
* Medium updates involve **more scope or complexity** than simple copy changes
* **Multiple components, fragments, or pages** may be affected
* **Source documents** can drive updates directly
* **Human review remains essential** given the broader impact
* **Versioning and governance** are preserved throughout
***
## When to use this
* Component modernization or upgrades
* Batch maintenance across multiple page areas
* Rebranding or terminology standardization
* Fragment management (content and experience)
* Campaign versioning and A/B testing
* Processing approved documents into web content
# Site Search & Find-and-Replace
Source: https://docs.gradial.com/docs/updating-existing-experiences-i-e-content-updates/site-search
Index your sites and run site-wide content operations — swap brand names, legal phrases, or regulated wording across every page without manual editing.
## Why This Matters
"Do we still say that anywhere?" is one of the hardest questions to answer about a large site, and one of the most consequential. A retired product name, a claim legal no longer approves, an old brand treatment, a regulated phrase that changed — each one is somewhere in the estate, and CMS search generally can't tell you where.
So teams guess. They check the pages they remember, fix those, and hope. Months later the phrase surfaces on a page nobody had opened since 2023.
Site Search indexes your sites so Gradial can answer "what's in it?" exhaustively — and turn that answer into bulk action.
***
Site Search indexes your connected sites so Gradial can answer "what's in it?" exhaustively — and turn that answer into bulk action. Once indexed, you can run find-and-replace operations across every locale, every section, and every depth of your sites.
Site Search needs your sites indexed before the steps on this page will return results. Your Gradial team configures and runs the initial index.
***
## What You Can Do
### Site-Wide Find & Replace
Ask Grady to swap a brand name, product name, legal phrase, or regulated wording across your entire site in plain English:
> "Replace every mention of \[old brand name] with \[new brand name] across all pages."
> "Update the legal disclaimer on every page that references \[product line]."
Gradial searches indexed page snapshots, fans out one task per matched page, edits each on a safe staged copy, and reports results independently — so no single page blocks the others.
### Visual Workflow Mapping
A live graph shows every fan-out task in flight, every page completed, and anything stuck upstream. You can track progress across the full site-wide operation as it runs.
### Human-in-the-Loop Approvals
Workflows pause at QA checkpoints. Nothing ships until brand and compliance sign off. Each page's staged copy is available for review before promotion to live.
***
## How It Works
Your Gradial team sets up and runs indexing jobs over your connected sites. Site Search results are only available after indexing is complete.
In Gradial Chat, describe what you want replaced — the term, phrase, or content type, and any scope constraints such as specific sections, locales, or page types.
Gradial surfaces matched pages with paths and titles before taking any action. Confirm the scope looks right before proceeding.
Gradial fans out one task per matched page, edits each on a safe staged copy, and surfaces results for review. Promote to live when you're ready.
***
## Getting Started
1. **Connect your sites.** Add your CMS environment from the integrations page if you haven't already — see [Integrations](/docs/integrations-administration-and-setup/integrations/get-started-with-integrations).
2. **Contact your Gradial team** to schedule indexing for your connected sites.
3. **Run your first operation.** Once indexing is complete, describe the change you want in Gradial Chat.
***
*Also need to find and act on assets across your DAM? See [Asset Search](/docs/asset-management/asset-search) for brand-matched Asset Packs and visual duplicate detection.*
***
## Who this is for
| Role | What Gradial handles |
| :------------------------------ | :----------------------------------------------------------------------------------------------------------- |
| **Legal / Compliance Reviewer** | A definitive answer to "does this wording still appear anywhere", with the change applied everywhere it does |
| **Brand Manager** | Retired names, old treatments and off-standard phrasing found across the whole estate |
| **Content Ops** | One operation instead of a spreadsheet and a fortnight |
| **Web Producer** | Not opening four hundred pages to change the same six words |
| **Localization Manager** | Coverage confirmed across every locale, not just the ones anyone remembered |
***
## Availability
**Access:** Must be enabled for your organization, and your sites must be indexed before you can search them. Contact your Gradial team to get access.
# Change Copy, Links or Images on a Page
Source: https://docs.gradial.com/docs/updating-existing-experiences-i-e-content-updates/small-content-updates
Edit the text, links, images and styling on a single page — without opening the CMS or waiting on a web producer.
The most common request in any content team: a headline needs to change, a link points somewhere retired, an image is out of date, a CTA needs different words. Individually each one takes a web producer a few minutes. Collectively they are the queue that never empties — and the reason the people who could be planning next quarter's campaign are instead working through a backlog of one-line edits.
These are the changes to hand to Gradial first. Describe the change, point at the page, and review the result.
### What this covers
| Change | Examples |
| :-------------------- | :---------------------------------------------------- |
| Copy | Headlines, paragraph text, CTA button text, eyebrows |
| Links | Changing link destinations or link text |
| Images | Swapping an image from an upload or a DAM path |
| Styling | Modifying styles defined within the component |
| Annotated screenshots | Marking up a screenshot to direct the change visually |
| Page metadata | Titles, descriptions and page-level properties |
***
## Fast Lane: Ticketing Integrations
### The Business User Advantage
Small content updates are ideal candidates for **ticketing system integrations**, giving business users a streamlined path to request and execute simple changes without leaving their system of record.
### How It Works
1. **Create a ticket** in your existing system (e.g., Jira, ServiceNow, Workfront)
2. **Assign the ticket directly to Gradial** using the integration
3. Gradial **automatically interprets the request** and generates the update
4. The change flows through **standard review and approval workflows**
5. Once approved, the update is **applied to the CMS**
### Why This Matters
| Benefit | Description |
| :---------------------- | :-------------------------------------------------------------------- |
| **Reduced handoffs** | No need to context-switch between systems or re-enter request details |
| **Faster turnaround** | Simple updates bypass lengthy creative queues |
| **Consistent tracking** | All requests remain visible in your system of record |
| **Governed execution** | Updates still pass through QA, review, and approval before publishing |
### Best Fit for Ticketing Workflows
* Routine copy corrections (typos, outdated dates, legal disclaimers)
* Link updates and fixes
* High-volume, repetitive changes across multiple pages
* Time-sensitive updates that can't wait for a full content cycle
### Integration Requirements
Work with your Gradial administrator to configure:
* Ticket assignment rules (which ticket types route to Gradial)
* Field mappings (how ticket details translate to update instructions)
* Approval workflows (who reviews before CMS application)
***
## General Workflow
All small content updates follow the same core workflow:
1. **Start a content update task** in Gradial
2. **Select the page and component** to modify
3. **Provide update instructions**
4. **Generate revised content**
5. **Review and refine** the proposed changes
6. **Run QA and validation checks**
7. **Apply the update** in the CMS
***
## Update Type: Copy Changes
### Purpose
Modify on-page text content—such as headlines, body copy, or CTA text—while preserving governance, review, and CMS versioning.
### Step-by-Step Walkthrough
#### 1. Start a Content Update Task
* Create a new task in Gradial
* Select **Update Existing Content** as the task type
**Outcome:** Gradial understands this is an edit, not new content creation.
#### 2. Select the Page and Component
* Identify the target page where the update is needed
* Select the specific component (headline, paragraph, CTA, etc.)
**Outcome:** Gradial scopes the change precisely, avoiding unintended edits elsewhere on the page.
#### 3. Provide Update Instructions
Provide guidance for the update, such as:
* Revised copy
* Directional feedback (tone, clarity, compliance-driven changes)
* References to approved language or source material
**Outcome:** Gradial has clear instructions for how the content should change.
#### 4. Generate the Revised Content
Gradial proposes an updated version based on your instructions while maintaining alignment with:
* Existing page structure
* Component field constraints
* Brand and content rules
**Outcome:** A draft update is generated without manual CMS editing.
#### 5. Review and Refinement
* Review the proposed update directly in Gradial
* Make adjustments before anything is applied to the CMS
**Outcome:** Human review ensures the update is accurate, intentional, and approved.
#### 6. QA and Validation
Gradial runs automated checks, which may include:
* Required field validation
* Accessibility considerations (e.g., heading structure)
* Content formatting and length constraints
**Outcome:** Errors or issues are caught early, reducing rework.
#### 7. Apply the Update in the CMS
Once approved, apply the change:
* **Via a Launch:** Creates a safe, isolated branch of the page
* **Via direct authoring:** Depending on workspace rules
**Outcome:** The updated content is ready for final review and publication.
***
## Update Type: Screenshot-Guided Edits
### Purpose
Use an annotated screenshot to visually communicate what needs to change, reducing ambiguity in update instructions.
### How It Works
1. **Capture a screenshot** of the page or component
2. **Annotate the image** to highlight the specific area and describe the change
3. **Upload the screenshot** when creating your update task
4. Gradial interprets the visual context alongside any written instructions
### Best Practices
* Circle or highlight the exact element to change
* Add text callouts describing the desired update
* Include both the screenshot and written instructions for clarity
***
## Update Type: Hyperlink Updates
### Purpose
Change link destinations or link text without editing the CMS directly.
### Common Scenarios
* Updating a URL that has changed
* Fixing broken links
* Changing link text for clarity or compliance
* Redirecting CTAs to new landing pages
### Instructions to Provide
* The current link text and/or URL
* The new link text and/or URL
* Any context (e.g., "This link should now point to the 2024 annual report")
***
## Update Type: Styling Adjustments
### Purpose
Modify component-level styling options that are exposed in your CMS's authoring interface.
### Scope
This applies only to styles defined within the CMS component configuration, such as:
* Color variants
* Layout options
* Size or spacing presets
* Theme selections
### Note
Styling changes outside of component-defined options require development work and are not covered by this workflow.
***
## Key Takeaways
* Updates are **scoped to a specific component**, not the entire page
* **Manual CMS editing is avoided**
* **Human-in-the-loop governance** is preserved throughout
* **Versioning, review, and rollback** capabilities remain unchanged
***
## When to use this
* Frequent copy tweaks (headlines, CTAs, descriptions)
* Compliance- or legal-driven wording changes
* High-volume updates across similar pages
* Situations where speed matters but control is required
* Link maintenance and updates
* Minor styling adjustments within component options
# Scheduled Tasks
Source: https://docs.gradial.com/docs/workflow-management/scheduled-tasks
Run any Gradial task on a recurring schedule — set it once and Grady executes autonomously at every interval, with full lifecycle control and run history.
Scheduled Tasks let you put any existing Gradial task on a recurring cadence. Set the schedule once and Grady runs the task autonomously at each interval — no manual triggering required. Monitor every run from the Scheduled Tasks dashboard and stay in control with pause, resume, and run-now controls.
***
## What Scheduled Tasks Enable
Schedule any existing task with a cron expression and timezone. Grady clones and runs it autonomously on each fire.
An org-level view of all active schedules with status badges (Active, Paused, Failed), next run time, last modified, and created by.
Every scheduled run links back to the parent schedule. A "Scheduled" badge on cloned task threads makes the origin clear at a glance.
After 5 consecutive failed runs, the schedule pauses automatically to prevent runaway execution. The failed state is visible in the dashboard.
Pause, resume, edit the task template or cadence, trigger an immediate run, and delete schedules with the option to keep or remove run history.
"Delete Schedule" keeps completed run threads for reference. "Delete Schedule and Runs" also removes the associated cloned task threads.
***
## How It Works
Navigate to **Scheduled Tasks** in the left sidebar. This page lists all schedules your organization has set up, with their current status and next run time.
Select an existing task to use as the template. Set the cadence (daily, weekly, monthly, or a custom cron expression) and choose the timezone. Use **Run Now** to trigger an immediate run before the recurring schedule starts.
At each scheduled interval, Grady clones the template task and runs it end-to-end. The cloned thread appears in your task history with a "Scheduled" badge linking back to the parent schedule.
The Scheduled Tasks page shows real-time status for every schedule. Open the run history drawer on any schedule to see each past run, its outcome (Success / Failed), and a link to the cloned task thread.
Pause a schedule when you need to hold runs, resume it when ready, or edit the template and cadence at any time. If a schedule auto-pauses after 5 consecutive failures, investigate from the run history and resume once resolved.
***
## What makes a good scheduled task
Any existing task can be scheduled, but the cadence pays off most for work that is **recurring, predictable, and worth doing on a fixed rhythm** — where the value is in it happening reliably without someone remembering to trigger it. Good candidates tend to be:
* **Time-based by nature** — weekly refreshes, monthly audits, nightly batch jobs.
* **Repeatable with the same instructions** — the prompt doesn't need to change run to run.
* **Better caught early** — monitoring and compliance checks where a regular cadence surfaces drift before it becomes a problem.
Because each run starts from a task template, the prompt you schedule looks like any other Gradial prompt. See the [Prompt Library](/docs/gradial-prompt-library/customer-use-cases) for ready-to-use prompts that work well on a recurring schedule.
## Common Use Cases
**Weekly content refreshes.** Schedule a social media or blog refresh task to run every Monday morning. Grady executes autonomously and the team reviews results in the run history.
**Monthly audits.** Set a brand audit or compliance check to fire on the first of each month — no one needs to remember to kick it off.
**Nightly localization.** Run overnight localization tasks across markets while the team is offline. Scheduled runs execute and surface results in thread history for review the next morning.
***
## Permissions
| Action | Required permission |
| ------------------------------ | --------------------- |
| Create, edit, resume, run now | `Org.MANAGE_SETTINGS` |
| View schedules and run history | `Org.VIEW` |
***
## Limitations
* **One schedule per task template** in this release — multiple cadences on the same template are not yet supported.
* **No attachment replacement on edit** — if a scheduled task template includes file attachments, editing the template message does not replace the attached files.
* **Human-in-the-loop tools stay active** in scheduled runs. A run that calls a HITL tool will stall its workflow.
* **No live next-fire-time preview** when editing the cron expression — the updated next-run estimate does not recalculate in real time after a cadence change.
***
## Getting Started
1. **Contact your Gradial team** to enable Scheduled Tasks for your organization.
2. **Navigate to Scheduled Tasks** in the left sidebar.
3. **Create a new schedule** — select an existing task template, set the cadence and timezone, and save.
4. **Monitor runs** from the Scheduled Tasks dashboard and run history drawer.
***
## Availability
**Access:** Must be enabled for your organization. Contact your Gradial team to get access.
# Workflow Management
Source: https://docs.gradial.com/docs/workflow-management/workflow-management
Orchestrate complex, multi-step campaigns end-to-end — coordinating humans and AI, executing across platforms, with governance built in at every step.
Enterprise marketing teams can now orchestrate full campaign execution end-to-end — humans and AI coordinated, multi-platform, with governance built into every step.
***
## The Problem It Solves
Enterprise campaign launches are a coordination problem. A single campaign touches dozens of steps across teams, platforms, and approval processes. Today it's managed with spreadsheets, Slack threads, and sequential handoffs. When one step blocks, everything behind it stalls. QA, brand, and compliance gates are manual and inconsistent — bolted on after the work is done rather than built into the process.
The result: slow launches, governance gaps, and over-reliance on the team members who know how everything connects.
***
## How It Works
Upload a brief or strategy doc, and Grady decomposes it into an executable workflow: every task defined, every dependency mapped, every role assigned — to an AI agent or a teammate. Agents execute directly in your marketing platforms. The workflow pauses at every approval gate. Nothing ships without human sign-off. Your ticketing systems stay in sync throughout.
***
## Key Capabilities
Upload strategy docs, briefs, and process diagrams. Workflows parses and decomposes them into actionable subtasks with dependencies mapped automatically.
Assign execution and approval to a Gradial agent or a named teammate. The platform recommends assignments based on workflow context and org rules.
Agents execute directly in SFMC, Marketo, Braze, and your connected CMS — building emails, drafting pages, and staging content without leaving the workflow.
A live graph shows every task, dependency, and blocker so teams always know where the campaign stands.
QA, brand, and accessibility checkpoints are built into the workflow structure. Nothing ships until approvers sign off.
Create and update tickets in connected ticketing systems automatically. The workflow can wait on external status changes before continuing.
***
## Who It's For
Gradial Workflows is built for enterprise marketing teams running large, multi-step campaigns who need to coordinate execution across platforms, teams, and approval processes at scale.
**Best fit for:** Marketing Operations, Campaign Directors, and Digital Experience leaders accountable for campaign velocity and governance compliance.
***
## Platform Scope
Agents execute across all connected platforms within a single workflow — including SFMC, Marketo, Braze, AEM, Sitecore, Contentful, and connected DAMs.
***
## Availability
Gradial Workflows is available now for all enterprise accounts and is opt-in. Contact your Gradial representative to enable it for your organization.
# Gradial Workflows
Source: https://docs.gradial.com/docs/workflow-management/workflows
Orchestrate enterprise marketing work end-to-end — coordinate humans and AI across large teams, run dozens of subtasks under one plan, and ship campaigns.
## Why This Matters
The hardest part of enterprise marketing work isn't any individual task — it's the dependencies between them. The email can't be built until the copy is signed off. Legal won't review until the disclaimer is final. The regional variants can't start until the master page is approved. Three teams are each waiting on a different one of those, and the status of all of it lives in someone's head or a spreadsheet that was accurate on Monday.
So the coordination becomes a full-time job, and the work moves at the speed of the next status meeting.
Gradial Workflows let you orchestrate and execute that work end-to-end — humans and AI in the same plan, with dependencies enforced rather than remembered.
***
Gradial Workflows let you orchestrate and execute enterprise marketing work from start to finish. Upload a strategy doc or brief, and Gradial breaks it into subtasks, assigns work to agents and teammates, tracks dependencies, and ships through the tools your team already uses — Jira, your CMS, marketing automation platforms, and more.
***
## What Workflows Enable
Upload strategy docs, briefs, and process diagrams. Gradial parses them and decomposes the project into actionable subtasks with dependencies.
Assign any step to a Gradial agent or a named teammate. The platform recommends assignments based on workflow context and org rules.
Workflows produce copy docs, Excel trackers, formatted briefs, and staged pages — not just plans and recommendations.
Create and update Jira tickets automatically. Workflows can wait on external status changes before continuing downstream work.
Built-in checkpoints pause the workflow for review. Nothing ships until brand and compliance sign off.
A live graph shows every task, dependency, and blocker — what's in progress, what's awaiting approval, and what's stuck upstream.
***
## How It Works
Attach a campaign brief, process diagram, or strategy document to a new workflow. Gradial reads it and proposes a structured task breakdown with subtasks, roles, and dependencies.
Review the proposed task structure before execution begins. Reassign steps, adjust dependencies, or add approval gates as needed.
Agents execute assigned steps autonomously — drafting content in your CMS, building emails in marketing automation platforms, staging landing pages, and generating documents. Human steps route to the assigned teammate with context and artifacts attached.
The workflow pauses at QA checkpoints and notifies approvers. Review the artifact, approve or request changes, and the workflow continues.
When all gates are cleared, Gradial promotes content to live through your connected CMS and marketing systems.
***
## Common Use Cases
**Campaign launches.** Break a full campaign brief into CMS pages, emails, social copy, and asset requests — each routed to the right agent or teammate, with dependencies enforced so nothing goes live out of sequence.
**Site-wide operations.** Run bulk content updates, rebrands, or localization across dozens or hundreds of pages under a single workflow plan. See [Site Search & Find-and-Replace](/docs/updating-existing-experiences-i-e-content-updates/site-search) for site-wide content operations.
**Multi-team approvals.** Route legal, brand, and accessibility review in the right order, with workflow state tracked in one place instead of email threads.
**Jira-driven execution.** Create and update Jira tickets as subtasks complete. Gradial waits on external ticket status changes before advancing downstream steps.
***
## Dual-Track Approvals
Workflows support two approval tracks running in parallel:
| Track | When to use |
| ------------------- | ----------------------------------------------------------------------------------------------- |
| **AI reviewers** | Speed — automated QA, brand rule checks, and accessibility validation before human review |
| **Human reviewers** | Judgment — brand, legal, compliance, or stakeholder sign-off where a human decision is required |
Both tracks can run simultaneously. The workflow advances only when both clear.
***
## Getting Started
1. **Contact your Gradial representative** to enable Workflows for your account.
2. **Create a new workflow** from the Workflows section of the sidebar.
3. **Upload your brief.** Attach a strategy doc, campaign brief, or process diagram.
4. **Review the task breakdown** Gradial proposes and adjust before starting execution.
***
*For how individual tasks enter and move through Gradial, see [Workflow Management](/docs/workflow-management/workflow-management). For ticketing system setup, see [Ticketing Integrations](/docs/integrations-administration-and-setup/how-gradial-works-with-ticketing-systems/setting-up-ticketing-integrations).*
***
## Who this is for
| Role | What Gradial handles |
| :---------------------------------- | :----------------------------------------------------------------------------------------- |
| **Campaign Manager / Program Lead** | The whole campaign in one plan, with dependencies enforced instead of tracked |
| **Content Ops** | Per-deliverable coordination, so your job is the plan rather than the chasing |
| **Marketing Ops** | Work routed to the right person or executed automatically, with state visible in one place |
| **Legal / Brand Reviewer** | Review arriving at the right moment with the artifact attached, not as an interruption |
| **Marketing Leadership** | An accurate answer to "where is everything" without a status meeting |
| **Agency Partner** | Your deliverables sequenced into the client's plan rather than handed over a wall |
### How this maps to your function
A campaign plan of 50–200 assets is really a dependency graph that nobody has drawn. The coordination cost of keeping it straight is the single largest hidden line item in campaign delivery, and it scales with the number of channels rather than the amount of content. Making the graph explicit — and letting Gradial execute the parts that don't need a person — is where the time comes back.
Approval gates usually slow work down because they're queues attached to people's inboxes. As workflow steps they're checkpoints instead: the work pauses in place, the reviewer gets the artifact and the context, and the moment it clears the downstream work starts. Automated brand and compliance checks can run in parallel with human review rather than before it.
The hard part of ops isn't any single process — it's that every campaign reinvents one. Once a plan works, save it as a template and run it again, so the process becomes an asset rather than institutional memory.
***
## Availability
**Access:** Must be enabled for your organization. Contact your Gradial team to get access.
# Release Notes
Source: https://docs.gradial.com/release-notes/overview
Latest features and updates for Gradial — AI agents for marketing content operations, CMS automation, and more.
## Redesigned Task Experience, Now Available to Everyone
The redesigned task experience is now available to all customers. It's built for campaigns, batch work, and multi-step projects, so you can follow a large piece of work without inspecting every item one at a time. Here's a quick tour.
### Start from Home
Home is your starting point. Chat with Grady, or choose **Create as Task** to turn your request into a task. Below that, jump back into recently visited workspaces and see your tasks under **My Tasks**. Switch between **All Tasks**, **Assigned**, and **Approvals** to find what needs you.
## Custom Apps Built on Your Gradial Data
Grady-built custom apps can now combine live data with interactive forms. Turn a prompt into a governed dashboard or operational report that refreshes against current data — from Gradial and from your connected systems — collects attributed input from your team, and hands that work back to Grady, without leaving the task.
Teams are using them for image QA dashboards over a connected DAM, custom intake forms for creative requests, reporting against a connected ticketing system, and single views of campaign progress spanning web, email, and social.
**Key capabilities:**
* **Live, governed data** — apps query tasks, artifacts, activity, and shared records, plus data from any system Gradial is integrated with, such as an external DAM or ticketing system. Queries are read-only, scoped to the viewer's permissions, and audited. Refreshing re-runs them against current data.
* **Rich generated interfaces** — Grady builds dashboards and reports with metric strips, responsive tables, charts, and proper loading and error states from a single prompt.
* **Forms and actions** — apps can collect structured input through forms and store submissions as attributed shared records, which Grady can then read and act on.
**Access:** Must be enabled for your organization. Contact your Gradial team to get access. See [Custom Apps](/docs/insights/custom-apps).
***
## Redesigned Task Experience
Tasks now support campaigns, batch work, and larger multi-step projects without the interface becoming crowded — and without project managers having to inspect work one item at a time. Each task is organized into three focused areas — Task, Subtasks, and Artifacts — alongside new project-management views that make dependencies, progress, and milestones easier to read and update.
**Key capabilities:**
* **Focused task home** — the request, its inputs, primary artifact previews, and associated subtasks in one place, with outputs opening directly in a full-screen preview.
* **Four ways to manage subtasks** — switch between a workflow canvas, a table with interactive dependency and blocker controls, a Kanban board with drag-and-drop status updates, and a calendar of due dates and milestones.
* **Faster artifact review** — preview the two most recent outputs from the task home, or open the full artifact grid with inline thumbnails and instant expansion, without waiting for a page reload.
* **Flexible Grady panel** — work with Grady in a resizable side panel, close it to focus on the task, expand it into a full-screen chat, or move it to either side of the screen.
* **Cleaner activity display** — the activity and to-do list is expandable and handles long histories without stretching or text-wrapping problems.
**Access:** Must be enabled for your organization. Contact your Gradial team to get access. See [Inside a Task](/docs/getting-started/navigating-the-platform#inside-a-task).
***
## Ask Grady About Your Gradial Data
Grady can now answer questions about your own work in Gradial. Until now it could do the work but couldn't see its own record of it — anything spanning more than one task ("what's waiting on my team?", "who changed this page?") meant opening tasks one at a time.
Now you just ask, and Grady answers right in the conversation, drawing on your tasks, artifacts, comments, activity history, and connected systems.
**Key capabilities:**
* **Ask about your work in plain language** — what's waiting for approval, who's assigned, what's been sitting longest.
* **Trace what happened** — which task changed a page, who ran it, and whether anything failed.
* **Act on what it finds** — Grady doesn't just report; it can continue the work, for example locating an environment that already has your CMS configured and switching to it.
* **Read-only by design** — answering a question never changes your data.
* **Permission-aware** — answers only ever include what everyone in that task can already see.
**Access:** Must be enabled for your organization. Contact your Gradial team to get access. See [Ask Grady About Your Own Gradial Data](/docs/getting-started/ask-grady#ask-grady-about-your-own-gradial-data).
***
## GEO Insights in Grady
Grady can now work with your GEO monitoring data directly inside a task. Previously everything you could learn about how your brand shows up in AI answers lived in the GEO dashboard — a fixed set of views in a fixed shape. Now you can ask for the cut you actually want, in the format you actually need.
**Key capabilities:**
* **Ask about your GEO data in plain language** — across whichever brand and time window you care about.
* **Get the output you need** — a quick comparison table in the chat, a chart, or a boardroom-ready PowerPoint built from the same numbers.
* **Adjust monitoring from the conversation** — create or change a monitored brand without going into GEO settings.
* **Governed changes, protected data** — configuration changes go through an approval step and are recorded, and editing configuration remains an admin capability. Collected runs, responses, mentions, and citations can never be modified.
* **Turn an insight into work** — ask what to act on next, and Grady ranks your open recommendations and hands you the top one as a task card you can launch in one click.
**Access:** Must be enabled for your organization, and requires GEO monitoring already configured with collected data. Contact your Gradial team to get access. See [Working with GEO Data in Grady](/docs/insights/geo-monitoring#working-with-geo-data-in-grady).
***
## Box: Organize, Clean Up, and File Content
The Box integration now goes beyond finding and reading files. Grady can help your team structure Box content, file work back into it, and remove content that's no longer needed — with deletions always gated behind human approval.
**Key capabilities:**
* **Organize Box content** — ask Grady to create folders and help structure your files.
* **Find and use existing assets** — search Box, download relevant files, and use them in your Gradial work.
* **Send artifacts to Box** — upload Gradial artifacts directly into the appropriate folder.
* **Clean up outdated content** — ask Grady to remove files you no longer need. Every deletion requires explicit human approval before it proceeds.
**Access:** Requires a connected Box integration, which must be enabled for your organization. Grady's reach stays limited to the folders a Box admin has collaborated the service account on. See [Box](/docs/integrations-administration-and-setup/integrations/box).
## Video Translation
Gradial can now generate videos from a written prompt and localize existing talking-head videos into another language. Ask Grady to translate the spoken audio, preserve the original speaker's voice and timing, synchronize visible mouth movement, translate eligible static text in the picture, and deliver the result as one playable video file.
Grady coordinates the separate voice, visual synchronization, on-screen text, and final assembly steps within the same task. Teams no longer need to move a source video manually between separate dubbing, lip-sync, design, and editing tools or reassemble the provider outputs themselves.
**Key capabilities:**
* **Prompt-based video generation** — Grady can create a new video from a written creative prompt.
* **Voice-preserving dubbing** — existing speech can be translated while retaining the original speaker's voice, delivery, and overall timing.
* **Visual speech synchronization** — Grady can adjust a visible speaker's mouth movement to match translated or user-supplied audio.
* **Static on-screen text localization** — full-screen title cards, presentation slides, and clean static text panels can be translated while preserving their layout and branding.
* **Complete video assembly** — translated audio, synchronized footage, and localized static text are combined into one broadly compatible video file.
* **Reliable long-running processing** — Grady tracks provider jobs through completion and safely reuses matching submissions when a task is retried.
* **Validated delivery** — final videos are checked for readable picture, supported encoding, expected duration, and non-silent audio before they are delivered.
* **Downloadable task artifacts** — completed videos are published directly in the task for playback or download.
**Access:** Must be enabled for your organization. Contact your Gradial team to confirm availability. See [Video Translation](/docs/translation-and-localization/video-translation).
***
## Memory
Gradial can now carry useful workspace knowledge from completed threads into later work. Your team's previous daily work contributes automatically to a structured memory bank that Grady can draw on as reference, so teams don't have to restate the same decisions and approaches in every new thread — and can point back to earlier work, decisions, or workarounds to speed up new runs.
When Grady uses a memory from another thread, the References panel on the right shows a clickable link back to the thread that generated the finding, so you can always check the source yourself.
**Key capabilities:**
* **Continuity across threads** — Grady can use relevant knowledge from earlier work in later requests within the workspace.
* **Structured workspace memory** — per-thread summaries are consolidated into a workspace-level memory rather than relying on raw chat history alone.
* **Human attribution** — memory records can preserve the name of the person whose work produced the remembered context.
* **Source-thread provenance** — the References panel shows a flat, deduplicated list of visible source-thread names behind memory citations.
* **Permission-aware links** — source threads are surfaced only when the current user is allowed to see them.
* **Resilient recall** — if memory hydration is unavailable, the turn continues without memory instead of failing the thread.
**Access:** Must be enabled for your organization. Memory generation and recall are controlled separately. Contact your Gradial team to confirm availability and setup. See [Memory](/docs/marketing-brain/memory).
***
## Thread Outcome Feedback
Gradial now lets you give lightweight feedback on completed work directly within a thread, creating a clear, first-hand signal about which agent behaviors worked well and which need improvement. Positive feedback helps teams identify reusable patterns; negative feedback provides concrete examples for future evaluations, product improvements, and better agent behavior.
**Key capabilities:**
* **Post-thread outcome feedback** — mark a completed thread as good or bad and add optional context about what worked or what missed the mark.
* **Customer-labeled outcomes** — feedback is tied to the thread itself, making it easier to distinguish technically completed work from customer-approved work.
* **Learning-system signal** — positive feedback helps identify successful patterns that may be reused or saved; negative feedback creates examples for evaluation and improvement.
* **Traceable feedback history** — feedback is append-only and records the thread version it judged, so teams can review outcome quality alongside the work that produced it.
* **Agent recovery loop** — when feedback is negative, the agent can re-engage with a concrete plan to address the issue rather than leaving the thread as a dead end.
**Access:** Opt-in — not enabled by default. Must be turned on for your organization or workspace, and is included in your standard subscription. Contact your Gradial team to get access. See [Thread Outcome Feedback](/docs/marketing-brain/thread-feedback).
***
## HubSpot Integration
Gradial now gives marketing teams a single conversational interface for HubSpot email operations. Turn a campaign brief into a branded marketing email, review the result, and coordinate the work through Grady while HubSpot continues to operate underneath as the connected system of record.
**Key capabilities:**
* **Campaign brief to email draft** — give Grady an approved brief and create a new HubSpot marketing email without manually translating the brief across multiple applications.
* **Branded template reuse** — clone an existing HubSpot email to preserve approved structure, styling, sender configuration, and branding.
* **Designed-email editing** — update supported text, buttons, images, and image links while verifying that the requested changes were applied correctly.
* **Reviewable email artifacts** — open a rendered email preview directly from the Grady thread, with clear warnings when exact final review in HubSpot is needed.
* **Optional audience support** — find or create a HubSpot contact list and attach it to the email when the workflow includes audience preparation.
* **Controlled publishing** — publishing remains a separate action that requires explicit human approval and validation against the final email content.
**Access:** Requires a connected HubSpot portal. Publishing also depends on the connected portal's HubSpot permissions and always requires human approval. See [HubSpot](/docs/integrations-administration-and-setup/integrations/hubspot).
***
## Marketo Authoring
Grady can now build and edit Marketo assets directly, so campaign teams can go from a request to a working landing page or form without hand-building it in Marketo Design Studio. Landing pages, forms, landing page templates, and email templates are all supported for both creation and editing.
**Key capabilities:**
* **Landing page creation and editing** — create new Marketo landing pages and update existing ones from a conversational request.
* **Form creation and editing** — build new forms and adjust existing ones without leaving Gradial.
* **Template authoring** — create and edit both landing page templates and email templates to keep new assets on an approved structure.
* **Guarded deletes** — deleting any Marketo resource Grady can work with requires explicit human approval first.
**Access:** Requires a connected Marketo instance. See [Marketo](/docs/integrations-administration-and-setup/integrations/marketo).
***
## User Groups Enhancements
Manage access at scale with reusable user groups. Build a group of people once — even before the workspace exists — assign it to one or many workspaces, and administer each workspace's access through dedicated Members, Roles, and Groups views, all without changing anyone's organization-level role.
**Key capabilities:**
* **Reusable groups** — create a group of people once and reuse it across every workspace that needs it; new groups start unassigned and can be scoped later without redoing membership.
* **Assign to workspaces** — add an existing group to a workspace to grant its members access, with a confirmation step, and remove group access when it's no longer needed.
* **Members, Roles, and Groups views** — manage workspace access from clearly separated tabs, each with its own search, filters, and export.
* **Access without side effects** — granting workspace access through a group never changes a person's organization-level role.
* **Ownership transfer** — workspace admins can hand off ownership to an eligible member with the Make Owner action.
**Access:** Available by default to organization admins and workspace owners/admins. See [User Groups](/docs/integrations-administration-and-setup/managing-access/groups).
***
## Home Page Recommendations
The Gradial home page now surfaces a short list of relevant next actions directly below the composer. Recommendations are drawn from your recent work, how your organization is actually using Gradial, your onboarding state, and Gradial-curated highlights — and every suggestion respects your permissions and visible data.
**Key capabilities:**
* **Up to three focused suggestions** — concise, full-width action rows appear under the home composer, with Quick Start left unchanged below them.
* **One-click follow-through** — suggestions either populate the composer with a ready-to-run prompt or route directly to the relevant page.
* **Follow-ups on recent work** — threads and tasks that need attention or are ready for review can resurface as recommended next steps.
* **Adoption-aware feature suggestions** — when an organization uses a capability but an individual user has not, that feature can be surfaced to that user, including onboarding and setup prerequisites.
* **Gradial-curated highlights** — Gradial can promote timed recommendations, such as new releases, with priority and expiration so they appear while relevant and then retire on their own.
* **Permission- and readiness-safe** — recommendations are filtered by permissions, feature availability, required integrations, and setup prerequisites, so users never see actions they cannot take.
* **Stable daily rotation** — the list stays consistent throughout the day and refreshes over time, so suggestions stay fresh without shifting mid-session.
* **Dismissible and respectful** — dismissing a suggestion removes it permanently for that user and cycles in the next best candidate; clicking a suggestion does not hide it.
**Access:** Must be enabled for your organization. Contact your Gradial team to get access. See [Navigating the Platform](/docs/getting-started/navigating-the-platform#recommended-next-actions).
## Slack Integration
Bring Gradial into Slack so teams can start and manage agent work where conversations already happen. Mention Gradial in a channel to hand a request into a tracked Gradial task, follow progress in the Slack thread, and receive the completed response without switching tools.
**Key capabilities:**
* **Slack to Gradial handoff** — mention Gradial in a channel to start a tracked task, with the request and Slack thread context carried into Gradial.
* **Live progress in Slack** — follow a rich working message with current task progress while Gradial completes the request.
* **In-thread controls** — open the task in Gradial or cancel the active run directly from Slack; cancellation stops the workflow at its next safe checkpoint.
* **Clear final responses** — when the work finishes, the live progress panel is replaced with a clean, durable response card in the same Slack thread.
* **Connected follow-up work** — continue the conversation in the Slack thread while keeping the work tied to the same Gradial task.
* **Reliable status updates** — cancellations, timeouts, duplicate requests, and processing failures are shown with clear outcome states so teams know what happened and what to do next.
**Access:** Must be explicitly enabled for your organization. An admin must configure the Slack integration, and the Gradial app must be added to the Slack channels where teams want to use it. Contact your Gradial team to get access. See [Slack](/docs/integrations-administration-and-setup/integrations/slack).
***
## User Groups
Organize your team into groups and work with them as a unit. Mention an entire squad on a ticket or assign a whole team as an approver — no more tagging five people one at a time and hoping you didn't miss anyone.
**Key capabilities:**
* **Default groups out of the box** — Owners, Admins, Brand Managers, Designers, Members, and Viewers groups are created automatically at the organization and workspace level, and stay in sync as roles change.
* **Custom groups** — build your own groups (squads, regional teams, agency partners) at the organization level or scoped to a single workspace, managed from Organization Settings → People → Groups.
* **Group mentions** — @-mention a group anywhere mentions work; every member with access to the ticket is notified in one action.
* **Group approvers** — assign a workspace group as a ticket's approver; any member of the group can complete the approval, so reviews never wait on one person's availability.
**Access:** Must be explicitly enabled for your organization. Contact your Gradial team to get access. See [User Groups](/docs/integrations-administration-and-setup/managing-access/groups).
***
## GEO Brand Sentiment
GEO Monitoring now helps you understand not just whether AI systems mention or cite your brand, but how they describe it. The Brand Sentiment dashboard section summarizes favorability, recurring perception themes, and supporting quotes so teams can see how their brand is being presented relative to the narratives customers encounter in AI-generated answers.
**Key capabilities:**
* **Favorability breakdown** — see favorable, neutral, and unfavorable share for monitored brand mentions.
* **Perception summary** — get a concise narrative of how AI systems are currently describing the brand.
* **Recurring themes** — review the topics and themes that repeatedly show up across monitored responses.
* **Evidence drilldown** — open supporting quotes and examples behind each theme.
* **Trend view** — monitor net favorability over time when the trend view is enabled.
**Access:** Must be explicitly enabled for your organization. Contact your Gradial team to get access. See [GEO Monitoring](/docs/insights/geo-monitoring#brand-sentiment).
***
## Brand-Level Tracking for GEO
Track how a specific brand shows up in AI answers — not just your top-level company. GEO Monitoring can now follow a product, sub-brand, or business unit as its own entity, so brands that sit under a larger parent company get accurate mention and citation numbers instead of a misleading 0%.
**Key capabilities:**
* **Track any brand at its own level** — monitor a specific product, sub-brand, or business unit independently of your parent company.
* **Accurate numbers for product brands** — a brand tracked separately from its parent now shows its real performance instead of reading 0%.
* **Brand hierarchies** — group brands under a parent company and view each brand on its own or rolled up together.
* **Include child brands on demand** — toggle a parent's dashboard to blend in its child brands, then switch back to see the parent alone.
* **Honest citation reporting** — a brand with no domain configured shows "—" for citations instead of a false 0%.
**Access:** Must be explicitly enabled for your organization. Contact your Gradial team to get access. See [GEO Monitoring](/docs/insights/geo-monitoring#brand-level-tracking-and-hierarchies).
***
## Also in This Release
**Faster AEM asset sync with journaling.** Gradial can now keep its asset index in sync with AEM using Adobe's I/O Events Journaling API — asset changes show up in Gradial search within minutes instead of waiting for the next full re-scan. Add your Adobe journaling credentials in the AEM onboarding wizard or integration settings to enable it; see [AEM Advanced Configurations](/docs/integrations-administration-and-setup/integrations/aem/advanced-configurations#asset-sync-journaling).
## Skills
Great marketing teams don't just follow instructions, they learn. The best ones build up institutional knowledge over time: what your brand sounds like, how your workflows run, what actually converts. That expertise lives in your people — and it gets lost every time someone's out, switches teams, or leaves. Skills fixes that, giving Grady a "marketing brain" so your team can get measurably better over time.
**Skills**
Grady now draws on a library of reusable capabilities — proven processes and workflows, brand and compliance rules — and pulls in the right ones automatically for each task. Think of it as your marketing brain, encoded: the institutional knowledge your best team members carry in their heads, made available to every agent, every run, every time.
For teams who've been using Rules: Skills is the evolution of that foundation. Rules gave you guardrails. Skills give you expertise: structured, versioned, improvable capabilities that go far beyond what to avoid and into how to excel.
**Skill Builder**
Create and edit skills in a rich, document-style editor, or let Grady build and refine its own skills from real work (agentic skill development). Skills are scoped to your workspace by default and promotable org-wide, with full version history so you always know what changed and why.
**Access:** Skills must be activated for your organization. Contact your Gradial account team to get started. See [Rules & Skills](/docs/marketing-brain/managing-skills).
***
## Scheduled Tasks
Set a cadence once — daily, weekly, monthly, or any custom interval — and Grady automatically creates and executes a new run at each interval, without anyone needing to trigger it manually.
**Key capabilities:**
* **Recurring schedules on any task** — schedule any existing task, including ones with file attachments; Grady includes the attachments on every run.
* **Enhanced scheduling** — choose from a curated timezone list, preview upcoming fire dates in a calendar, see when a run-limited schedule will naturally end, and confirm Run Now counts toward the run limit.
* **Scheduled Tasks page** — view all your schedules in the same familiar layout as your main tasks, with status (Active, Paused, Failed, Stopped, Ended), next run time, and inline expandable run history. Each org can have up to 50 active schedules at a time.
* **Auto-pause on errors.** If a schedule fails 5 times in a row, it pauses automatically to prevent runaway activity.
* **Stop or delete a schedule.** Stop permanently ends future runs while keeping history intact; Delete removes the schedule and all its runs at once.
* **Bulk Stop.** Stop multiple schedules at once — already-stopped schedules are skipped automatically.
* **Run history.** Every run links back to its parent schedule so you always know where it came from.
**Access:** Scheduled Tasks must be explicitly enabled for your organization. Contact your Gradial team to get access. See [Scheduled Tasks](/docs/workflow-management/scheduled-tasks).
***
## Notifications
Gradial now keeps the right people informed when task statuses change — through an in-app inbox, real-time banners, or email, based on each person's preferences.
**Key capabilities:**
* **Task notification inbox.** A dedicated sidebar tab collects all your task notifications in one place. Mark read/unread, archive, and filter to find what matters.
* **Real-time banners.** Status changes surface instantly in the app — no refresh needed.
* **Email notifications.** Get notified when a task is ready for review, needs attention, or gets unblocked, with a direct link back to the task.
* **Per-event channel control.** Choose email, banner, or nothing for each of the five task events. Org admins set team-wide defaults; individuals can tune their own preferences.
* **Subscriber model.** Assignees and approvers are auto-subscribed; additional subscribers can be added from the task header.
**Access:** Notifications must be explicitly enabled for your organization. Contact your Gradial team to get access. See [Notifications](/docs/platform/notifications).
***
## Quick Starts
Org admins can now tailor the Gradial home screen for their teams. With Quick Starts, admins set up one-click prompts that surface the most common pathways into the app, so marketers land on a home screen built around the work they actually do — instead of staring at a blank prompt wondering where to begin.
Each Quick Start is a ready-to-run prompt that drops the user straight into a high-value workflow. For example: **Run a GEO analysis**, **Run a brand audit**, or **Help me launch a campaign**.
**Key capabilities:**
* **Admin-customized home screen** — org admins curate the set of Quick Starts their users see, aligning Gradial's entry points with the team's priorities and approved workflows.
* **Common pathways, one click away** — surface the workflows marketers reach for most (GEO analysis, brand audits, campaign launches, and more) as prompts users can launch instantly.
* **Faster activation and onboarding** — new and occasional users get guided into proven workflows from the moment they open Gradial, reducing the blank-prompt learning curve.
**Access:** Quick Starts are configured by org admins. Contact your Gradial team if you'd like help setting up Quick Starts for your organization.
***
## Also in This Release
**Create SFMC campaigns and journeys from Gradial.** Marketers can now build Salesforce Marketing Cloud campaigns, multi-email sequences, and Journey Builder automations directly from a Gradial prompt — collapsing what normally takes hours of manual work in SFMC into a single conversation.
**Rules page improvements.** All rules are now in one unified table — no more switching between org and workspace tabs. Use the Scope filter to narrow the view, and hover over any rule title to preview its content without opening it.
## GEO Monitoring Dashboard
Gradial now runs your GEO queries on a schedule and tracks your brand and competitor visibility across the AI answer engines Gradial monitors, including ChatGPT, Claude, and Perplexity. Take action on recommendations immediately without leaving Gradial by creating and executing tasks to improve visibility. Over time, you'll see movement or regressions in an easy-to-use dashboard view.
**Key capabilities:**
* **Trends, not snapshots.** Brand and competitor mention and citation rates show over a rolling time series. Overlay a persona filter to segment any trend chart with one click.
* **Cross-model coverage on one axis.** Major providers are monitored on the same cadence and charted together.
* **Citation rankings and competitor breakdown.** Domain-level aggregates show who else is being cited in the same answer sets, ranked by frequency.
* **Recommendations that name pages.** Gradial analyzes target pages and generates recommendations against your brand URLs. One click turns a recommendation into a task you can execute inside Gradial.
* **Full run history.** Every scheduled run is preserved with underlying data, so any point on the trend line is auditable.
To get started, work with your Account Director to enable the feature, then bulk-upload the queries you want monitored and add a representative list of pages for page-health scans. The dashboard populates as scheduled runs accumulate — the earlier you turn it on, the richer the trend view becomes. See [GEO Monitoring](/docs/insights/geo-monitoring) for setup steps.
***
## Artifact Tabs
The right panel of your workspace now has tabs so your artifacts, sources, and subtasks are organized and reachable in one place. Each artifact can be opened into its own dedicated tab so you can keep better track of your outputs.
**What are subtasks?** When you give Grady a complex task, it sometimes breaks it into smaller parallel steps and handles them independently — those are subtasks.
**Here's more about what is included:**
* **Home tab.** A permanent landing panel showing artifacts, sources, and subtasks in collapsible cards whenever you open a thread. See every subtask Grady created and its status, or open a new table or workflow view for more complex tasks.
* **Dedicated artifact tabs.** Open any artifact into its own named tab and keep it open while you continue chatting or reviewing other outputs. No more hunting back through the conversation.
* **Batch and context tabs.** Dedicated views for monitoring batch progress and reviewing batch objectives without leaving the thread.
* **Searchable tab picker.** Add new views via the + button; the tab bar stays uncluttered by default.
* **Your layout is saved.** Tab layout, ordering, and pane width are saved per thread and restored every time you return.
Artifact Tabs will be active on Friday, May 29.
***
## Sites & Assets Search
Asset Search is the indexing and retrieval foundation that lets Grady act on your enterprise sites and DAMs at scale. Once your AEM sites and asset libraries are indexed, Grady can answer "what's in it?" exhaustively — and turn that answer into bulk action.
**Site Search — Site-Wide Find & Replace**
Swap a brand name, product name, legal phrase, or regulated wording across your entire site. Grady searches indexed page snapshots, fans out one task per matched page, edits each on a safe launch copy, and reports results independently.
**Asset Search — Brand-Matched Asset Packs**
Drop in a campaign brief, pick your audiences, and Grady fills the full audience × treatment × channel matrix with imagery pulled from your indexed DAM. Different audiences get different visuals, every cell stays on brand.
**Asset Search — Visual Duplicate Detection**
Grady groups every visual duplicate and near-duplicate in your DAM into a single cluster — including re-exports, re-crops, and color edits a file-hash check would miss. Pick a canonical version and replace stale variants across every site that references them.
[Site Search docs](/docs/updating-existing-experiences-i-e-content-updates/site-search) · [Asset Search docs](/docs/asset-management/asset-search)
***
## Audience Manager
Define and manage the audience segments Gradial uses across all workflows. Audiences power persona simulation in CX Optimizer, drive content targeting in content update tasks, and determine which visuals are assigned to which cells in Asset Pack matrices. See [Audience Manager](/docs/campaign-management/audience-manager).
***
## Make & Edit Office Documents
Gradial can now create and edit Microsoft Office documents as part of your content workflows. Use Grady to build campaign briefs, pull copy from live pages into Word documents, produce QA analyses, and assemble Excel trackers — all from Gradial Chat or as part of a larger workflow. See [Make & Edit Office Documents](/docs/campaign-management/office-docs).
***
## Gradial Workflows
Gradial Workflows orchestrate and execute enterprise marketing work end-to-end. Upload a strategy doc or brief, and Gradial breaks it into subtasks, assigns work to agents and teammates, tracks dependencies, and ships through the systems your team already uses.
**Key capabilities:**
* Intelligent task breakdown from briefs and process documents
* Dynamic role assignment to agents or named teammates
* Dual-track approvals — AI reviewers for speed, human reviewers for judgment
* Real artifacts: copy docs, Excel trackers, formatted briefs, staged pages
* Jira ticket creation and status-based workflow gating
* Visual workflow graph showing every task, dependency, and blocker
***
## AEM Guides Integration
Gradial's AI agents now integrate with Adobe Experience Manager Guides for structured DITA-based content authoring and publishing. Automate content creation, updates, translation tasks, and QA across your DITA content libraries. See [AEM Guides](/docs/integrations-administration-and-setup/integrations/aem/aem-guides).
## Audiences for CX Optimizer
Audiences add a targeting layer on top of personas for CX Optimizer. Instead of selecting personas one by one for every run, teams can now save named groups — such as `Enterprise Buying Committee`, `Healthcare Prospects`, or `Trial-to-Paid Evaluators` — and reference them directly from chat when launching a CX Optimizer flow.
**Key capabilities:**
* **Named audience groups** — Combine existing personas into a saved audience at the org level or scoped to a specific workspace.
* **Segment filtering** — Layer segment or tag filters on top of an audience to narrow the run without rebuilding the saved group.
* **Chat integration** — Reference an audience by name in chat; the Journey Agent resolves it to the matching personas before the run starts.
* **Persona sampling** — Audiences with 5 or fewer personas run in full; larger audiences are sampled to up to 5 personas per run.
Creating and editing audiences is limited to Admin and Design roles.
**Access:** Audiences must be explicitly enabled for your organization. Contact your Gradial team to get access.
See the [Audiences documentation](/docs/insights/audiences) for full details and use cases.
## Workspace Categories
Categories make it easy to organize and navigate a large number of workspaces. Admins define a reusable label catalog at the org level — such as `Brand: ACME`, `Region: EMEA`, or `Q2 Launch` — and anyone on the team can filter, sort, and search the Workspaces page using those labels.
**Key capabilities:**
* **Org-scoped catalog** — Categories are defined once and reused across every workspace; no per-workspace catalog to maintain.
* **Inline creation** — Workspace Owners and Admins can create new categories directly from the Categories cell on their workspace row.
* **Filter and sort** — Filter the Workspaces page by one or more categories and sort the table by the Categories column.
* **Composable filters** — Combine category filters with the existing search box and `Pinned` / `Public` / `Private` status filters to narrow a long list quickly.
Managing the category catalog (rename, delete) is limited to org Owners and Admins.
See the [Workspace Categories documentation](/docs/governance/workspace-categories) for full details and use cases.
## CX Optimizer
CX Optimizer is now available as an opt-in feature. It uses agent-simulated personas to evaluate the customer experience as users journey through your website — surfacing content issues, UX bugs, and strategic gaps before they affect real customers.
**Key capabilities:**
* **Personas** — In Audience Manager, create individual simulated buyers and users representing your key customer segments. Personas are the foundation for all CX Optimizer analysis.
* **Audiences** — Group personas into saved, reusable sets — e.g. "Enterprise Buying Committee" or "Healthcare Prospects" — and call them directly from chat when launching a CX Optimizer run. Audiences can be shared across your organization or scoped to a specific workspace. Add segments or tags when you want to filter within audiences.
* **Scope** — Choose what CX Optimizer analyzes before a run — e.g. evaluating overall content quality, or checking for specific UX/UI bugs — and select up to 5 personas for each run.
* **CX research report** — Each run produces:
* An overall journey health score (0–10)
* **Actionable insights** — Recommendations can be converted into tasks and immediately executed using the **Create Task** button, organized into four categories:
* **Quick Wins** — Quick wins and content tweaks
* **Bug Fixes** — Broken functionality and UX issues
* **New Content** — Net-new pages, sections, or copy the site is missing
* **New Ideas** — Strategic, higher-effort improvements
* Per-persona breakdown including CX score, goal completion rate, sentiment, and session replay
* **Download Report** — Export the report to PDF for easy sharing
* **Validate changes** — Run CX Optimizer to validate the effect of site changes on the customer experience.
* **Preflight / Pre-Launch Mode** — Run a CX analysis on a single page before a full campaign goes live. Works with published and unpublished AEM pages via direct browser authentication, so you can catch issues before they reach customers.
Runs complete in 15–60 minutes depending on the depth and breadth of the request.
**Access:** CX Optimizer must be explicitly enabled per workspace. Contact your Gradial team to get access.
## GEO PDF Export
GEO reports can now be exported as a branded PDF directly from Gradial. Observations flow naturally across overflow pages with branded headers and footers, making reports easy to share outside the platform.
## Rules Workspace Mapping
A single rule can now be mapped to multiple workspaces at once. Define a rule once in the Rules Manager and apply it to as many workspaces as needed — no more re-creating the same rule across teams.
## Universal Thread Search
Search and jump to any thread from anywhere in the app. Use the thread search to quickly locate conversations across all your workspaces without navigating away from your current context.
## GEO Agent
Introducing GEO, a new way to understand how your brand appears in AI-generated answers across platforms such as ChatGPT, Perplexity, and Claude.
## Chats
### Configure multiple identity providers for a single organization
Gradial now supports multiple SSO configurations for a single organization—useful for organizations spanning multiple geographies with separate identity providers, or when a managed service provider is supporting your implementation.
To add additional SSO connections, repeat the setup steps for each identity provider in **Settings → Integrations → Single Sign-On**.
See our [SSO documentation](/docs/integrations-administration-and-setup/managing-access/sso) for setup instructions.
### Updated Ticket UI
We've redesigned the ticket interface to improve clarity when working with tasks.
**Properties Above Task Request**
Task properties (status, priority, approver, workspace, and actions) now appear prominently above the task request section. This layout gives you immediate context about the ticket's state without clicking. Long ticket requests will also appear inline without the need to scroll through a container.
# Customer Support Portal
Source: https://docs.gradial.com/support-portal
How to submit and track support requests through the Gradial Customer Support Portal.
All support requests can be submitted and tracked through the **Gradial Customer Support Portal**. This process ensures your requests are logged, prioritized, and resolved as efficiently as possible.
## Portal Access & Roles
Access to the portal is tied to your company email domain. There are two levels of access:
Anyone with a recognized company email domain can log in and submit tickets. Users can view and track their own submissions.
Users designated as **Admins** within the portal can view **all tickets** submitted by anyone at your organization — not just their own.
If you need Admin access, contact your Gradial account team and they can update your role in the portal.
## Submitting a Ticket
Navigate to [https://portal.usepylon.com/gradial](https://portal.usepylon.com/gradial).
Sign in with your company email address.
Enter the two-factor authentication (2FA) code sent to your email.
Click **Create Ticket** to start your request.
Fill out the form, attach any relevant files, and click **Submit**.
You'll receive a confirmation email with your **Ticket Number** and can track progress anytime in Pylon.
## Why Use the Portal?
Issues are immediately logged and routed to the right team.
See all your open and closed tickets in one place.
Stay in sync with the Gradial team throughout resolution.
## Questions?
If you run into any issues accessing the portal, please reach out to your Gradial account team.