diff --git a/.github/workflows/ai-deploy-request.yml b/.github/workflows/ai-deploy-request.yml new file mode 100644 index 000000000..4ae188a70 --- /dev/null +++ b/.github/workflows/ai-deploy-request.yml @@ -0,0 +1,45 @@ +--- +########################### +########################### +## Deployment AI generation testing ## +########################### +########################### + +name: Hackathon Deployment Request + +###################################################### +# Start the job on a "deployment" to hackathon-test or other branch # +###################################################### + +on: + workflow_dispatch: + inputs: + target_branch: + description: "Target branch to send PR to (e.g., main, stage, etc)" + type: string + required: false + default: "hackathon-test" + +############### +# Set the Job # +############### + +jobs: + ai-metadata-update: + name: AI Metadata Update on Deployment + uses: AdobeDocs/adp-devsite-workflow/.github/workflows/ai-deploy-metadata.yml@app-builder-test + with: + FILE_NAME: "all_pages_content.txt" + secrets: + AZURE_OPENAI_ENDPOINT: ${{ secrets.AZURE_OPENAI_ENDPOINT }} + AZURE_OPENAI_API_KEY: ${{ secrets.AZURE_OPENAI_API_KEY }} + + lint: + name: Lint + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Lint + run: npx --yes github:AdobeDocs/adp-devsite-utils#add-lint-check runLint -v diff --git a/.github/workflows/ai-pr-request.yml b/.github/workflows/ai-pr-request.yml new file mode 100644 index 000000000..e738dea27 --- /dev/null +++ b/.github/workflows/ai-pr-request.yml @@ -0,0 +1,40 @@ +--- +########################### +########################### +## Pull request testing ## +########################### +########################### +name: Hackathon Pull Request + +# Documentation: +# - Workflow: https://help.github.com/en/articles/workflow-syntax-for-github-actions +# - SuperLinter: https://github.com/github/super-linter +# - Markdown linter: https://github.com/DavidAnson/markdownlint +# - Link validation: https://github.com/remarkjs/remark-validate-links + +###################################################### +# Start the job on a pull request to the hackathon-test branch # +###################################################### +on: + pull_request: + branches: [hackathon-test] + paths: + - 'src/pages/**' + +############### +# Set the Job # +############### +jobs: + call_reusable_workflow: + name: Generate AI Metadata + # Skip if PR title starts with "[AI PR] Metadata Update" or branch name starts with "ai-metadata" + if: >- + !startsWith(github.event.pull_request.title, '[AI PR] Metadata Update') || + !startsWith(github.event.pull_request.head.ref, 'ai-metadata') + uses: AdobeDocs/adp-devsite-workflow/.github/workflows/ai-pr-request-metadata.yml@app-builder-test + with: + PR_ID: ${{ github.event.pull_request.number }} + FILE_NAME: "pr_content.txt" + secrets: + AZURE_OPENAI_ENDPOINT: ${{ secrets.AZURE_OPENAI_ENDPOINT }} + AZURE_OPENAI_API_KEY: ${{ secrets.AZURE_OPENAI_API_KEY }} diff --git a/src/pages/hackathon-files/distribution.md b/src/pages/hackathon-files/distribution.md new file mode 100644 index 000000000..4e0949a0f --- /dev/null +++ b/src/pages/hackathon-files/distribution.md @@ -0,0 +1,306 @@ +--- +keywords: + - Distribution + - Local Distribution + - App Builder + - Public + - Private +title: Distribution +description: The Developer Console and aio CLI provide features for developers to distribute their App Builder applications. This documentation focuses on the distribution step of this lifecycle. +--- + +# Distribution Overview + +Developers may distribute App Builder applications privately or publicly. + +## Private + +Privately distributed apps are available only to users in the Developer's organization. They are submitted through the [Developer Console](https://developer.adobe.com/developer-console/), reviewed by an Administrator of the organization, and accessed through the [App Builder Catalog](https://experience.adobe.com/#/@adobeio/custom-apps). + +See [Publishing Your First App Builder Application](../../get_started/app_builder_get_started/publish-app.md) for a thorough discussion of this topic and a hands-on sample project. + +> Note: Only Adobe Experience Cloud Shell extensions may appear in the App Builder Catalog. + +## Public + +Publicly distributed apps are available for installation by anyone on [Adobe Exchange](https://exchange.adobe.com/apps/browse/ec). + +### Overview + +Publicly distributed applications are available for any Adobe organization to install and distribute for access through [Adobe Exchange](https://exchange.adobe.com/). These apps are submitted through [Adobe Developer Distribution](https://developer.adobe.com/developer-distribution/) and reviewed by Adobe. This section reviews configuration options and the steps required to prepare your app for public distribution. + +### Customer configuration + +Developers of publicly distributable apps can define configuration options for customers to set during installation. + +#### Defining customer configuration options + +Customer configuration can be defined through the `configSchema` property. + +**app.config.yaml** + +```yaml +application: + +extensions: + +configSchema: # This is a top-level property and is global to the app and all extensions + title: 'the title' + description: 'the description' + properties: + - title: 'Slack Webhook' + type: 'string' + description: 'Please provide the webhook used by this application. Configure in slack.com' + envKey: 'SLACK_WEBHOOK' +``` + +#### Usage + +The `envKey` property of a customer configuration option maps to the environment variable name in the app. + +##### Runtime action + +To use customer configuration in a Runtime action, map the `envKey` value for the desired variable to the inputs of the Runtime action, then access values via `params.` in the action code. + +**app.config.yaml** + +```yaml +configSchema: + title: 'the title' + description: 'the description' + properties: + - title: 'enable caching' + type: 'boolean' + envKey: 'IS_CACHING_ENABLED' <--- Environment variable name +application: + actions: actions + web: web-src + runtimeManifest: + packages: + dx-excshell-1: + license: Apache-2.0 + actions: + generic: + function: actions/generic/index.js + web: 'yes' + runtime: nodejs:16 + inputs: + LOG_LEVEL: debug + IS_CACHING_ENABLED: $IS_CACHING_ENABLED <--- Mapped environment variable + annotations: + require-adobe-auth: true + final: true + code-download: true +``` + +**Action code** + +```js +async function main (params) { + if (params.IS_CACHING_ENABLED) { + enableCache() + } +} + +exports.main = main +``` + +##### Web application + +To use customer configuration in a web application, access values directly through `process.env.`. + +**app.config.yaml** + +```yaml +configSchema: + title: 'Configurable Web App' + description: 'Web application that can be configured.' + properties: + - title: 'Frontend background color' + type: string + description: 'Please provide the background color for your frontend' + enum: + - blue-400 + - celery-400 + - indigo-400 + envKey: FRONTEND_BACKGROUND_COLOR <--- Environment variable name +application: + web: web-src +``` + +**Component.js** + +```js + +``` + +#### Customer configuration types + +##### Text field + +```yaml +configSchema: + title: 'Configure your application' + description: 'Set configurable variables for this Slack application' + properties: + - title: 'Slack Webhook' + type: 'string' + description: 'Please provide the webhook used by this application. Configure in slack.com' + envKey: 'SLACK_WEBHOOK' + default: 'https://slack.com/webhook' +``` + +##### Checkbox + +```yaml +configSchema: + title: 'Configure your application' + description: 'Customize this application to meet your needs.' + properties: + - title: 'Enable caching' + description: 'Determines whether or not the app caches.' + type: 'boolean' + envKey: 'IS_CACHING_ENABLED' +``` + +##### Dropdown + +```yaml +configSchema: + title: 'Configurable Web App' + description: 'Web application that can be configured.' + properties: + - title: 'Frontend background color' + type: string + description: 'Please provide the background color for your frontend' + enum: + - blue-400 + - celery-400 + - indigo-400 + envKey: FRONTEND_BACKGROUND_COLOR +``` + +##### Secret + +```yaml +configSchema: + title: 'the title' + description: 'the description' + properties: + - title: 'aws secret key' + type: 'string' + secret: true + envKey: 'AWS_SECRET' +``` + +> Note: This secret screenshot is pending a bug fix. + +##### Multiple configuration options + +```yaml +configSchema: + title: 'Configurable Web App' + description: 'Web application that can be configured.' + properties: + - title: 'Frontend background color' + type: string + description: 'Please provide the background color for your frontend' + enum: + - blue-400 + - celery-400 + - indigo-400 + envKey: FRONTEND_BACKGROUND_COLOR + - title: 'Enable caching' + description: 'Determines whether or not the app caches.' + type: 'boolean' + envKey: 'IS_CACHING_ENABLED' + - title: 'Slack Webhook' + type: 'string' + description: 'Please provide the webhook used by this application. Configure in slack.com' + envKey: 'SLACK_WEBHOOK' + default: 'https://slack.com/webhook' +``` + +### Required products + +Developers of publicly distributable App Builder apps can define Adobe products that are required for their apps to work properly. The [Discover](https://developer.adobe.com/developer-distribution/experience-cloud/docs/guides/discoverandmanage/#discover) and [Acquire](https://developer.adobe.com/developer-distribution/experience-cloud/docs/guides/discoverandmanage/#acquire) sections of the distribution documentation show how these options are surfaced to customers. + +#### Defining required products + +Required products can be defined using the `productDependencies` property. + +**app.config.yaml** + +```yaml +application: + +extensions: + +configSchema: + +productDependencies: + - code: AEP + minVersion: 0.0.0 + maxVersion: 1.0.0 +``` + +##### Valid products + +- **AEM** - Experience Manager +- **AAM** - Audience Manager +- **ANLYTC** - Analytics +- **CMPGN** - Campaign +- **TRGT** - Target +- **AEP** - Experience Platform Services +- **COMMC** - Commerce Cloud +- **MRKTO** - Marketo Engage +- **WRKFRNT** - Workfront +- **AAC** - Advertising Cloud +- **RTCDP** - Real-time Customer Data Platform +- **AJO** - Journey Optimizer +- **CJA** - Customer Journey Analytics +- **GPM** - GenStudio for Performance Marketing + +Product version information can be found on [Adobe Experience League](https://experienceleague.adobe.com/en/docs). + +### Packaging for developer distribution + +Once an app is configured for public distribution, it can be packaged and uploaded to [Adobe Developer Distribution](https://developer.adobe.com/developer-distribution/). + +The `aio app pack` command verifies and bundles applications for upload. In the root of your app folder, run: + +```sh +aio app pack +``` + +When it completes, you will find the app package in your app folder as `dist/app.zip`. Continue to the [Adobe Developer Distribution](https://developer.adobe.com/developer-distribution/) documentation for details on how to upload it. + +#### Validation + +When a Developer uploads a package to Adobe Developer Distribution, these validations are performed: + +1. `app.config.yaml` is checked for format validity, returning configuration errors to fix if necessary +2. `package.json` version format must be `X.Y.Z`, where X, Y, and Z are non-negative integers +3. files to be packaged - all files in your app folder will be packaged except: + - files specified in `.gitignore` + - files specified in `.npmignore` + - any `dist` folders + - any dot files (.env, .gitignore, etc) + - any OS junk files (.DS_Store, thumbs.db, etc) +4. event registrations, if any, for validity + +#### Hooks + +Two [hooks](architecture_overview/app-hooks.md) are available to customize the packaging step: + +1. `pre-pack` - runs before packaging +2. `post-pack` - runs after packaging + +Hook-handler functions will be passed two items: + +1. `appConfig` (object) contains the configuration of the current application +2. `artifactsFolder` (string) is the location of the folder that contains all the packaging artifacts to be bundled + +## Next step + +Return to the [Guides Index](../index.md). diff --git a/src/pages/hackathon-files/index.md b/src/pages/hackathon-files/index.md new file mode 100644 index 000000000..7f193f684 --- /dev/null +++ b/src/pages/hackathon-files/index.md @@ -0,0 +1,45 @@ +--- +keywords: + - App Builder + - Guides + - Documentation +title: App Builder Guides +description: Comprehensive guides for building and deploying applications with App Builder. +faqs: +- question: What topics are covered in the App Builder Guides? + answer: The guides cover architecture, development, configuration, deployment, security, and integration aspects of building applications with App Builder. +- question: Where can I find information about App Builder deployment? + answer: Deployment details are included under the Configuration and Deployment section of the App Builder Guides. +- question: Does the App Builder support integrations with other platforms? + answer: Yes, the guides include information about integrating App Builder with Adobe Experience Cloud and other services. +--- + +# App Builder Guides + +Welcome to the App Builder Guides section. Here you'll find comprehensive documentation about building and deploying applications with App Builder. + +## Architecture and Development + +* [Architecture Overview](architecture_overview/architecture-overview.md) +* [Application State](application-state.md) +* [Development](development.md) +* [Distribution](distribution.md) +* [Optimization](optimization.md) +* [Telemetry](telemetry.md) + +## Configuration and Deployment + +* [Configuration](configuration/configuration.md) +* [Deployment](deployment/deployment.md) +* [Application Logging](application_logging/logging.md) +* [Events](events/custom-events.md) +* [Extensions](extensions/extensions.md) +* [Security](security/index.md) + +## Integration + +* [Adobe Experience Cloud Integration](exc_app/aec-integration.md) + +## Next step + +Return to [Guides Index](../index.md). diff --git a/src/pages/hackathon-files/set-up.md b/src/pages/hackathon-files/set-up.md new file mode 100644 index 000000000..31dcfd455 --- /dev/null +++ b/src/pages/hackathon-files/set-up.md @@ -0,0 +1,76 @@ +--- +keywords: + - Acquire Access + - Credentials + - Local Environment + - Set up +title: Set Up Access, Environment, and Tools +description: App Builder is a complete framework that enables enterprise developers to build and deploy custom web applications that extend Adobe Experience Cloud solutions and run on Adobe infrastructure. +faqs: +- question: What access do I need to start using App Builder? + answer: You need membership in an Adobe Experience Cloud IMS organization with a Developer or System Admin role, and your organization must have a license for App Builder. +- question: How do I request access if I don’t have it? + answer: Customers should contact their account manager or company IT/Marketing admin, while partners should request access from their partner manager or via the Adobe Solution Partner Portal. +--- + +# Set Up Access, Environment, and Tools + +Here you'll learn what systems you need to access, how to access them, and how to configure your local environment. + +## Access and credentials + +**Adobe Experience Cloud Identity Management Service (IMS) organization** membership, with a Developer or System Admin role, is needed to access App Builder. + +* If your organization has a license for App Builder, use the IMS organization where App Builder is provisioned. Some companies have multiple IMS Organizations. Check with your company admin who manages Adobe software for details. + +- If you do not have access to your IMS organization: + + - Customers should request access from their account manager or their company IT/Marketing admin + + - Partners should request App Builder access from their partner manager, or Sandbox access though the [Adobe Solution Partner Portal](https://solutionpartners.adobe.com/home.html) + +**App Builder access** is only available with a purchased license. + +**[Adobe Developer Console](https://developer.adobe.com/developer-console/)** gives you access to APIs, SDKs, and developer tools. It also provides a way to set up your credentials. + +**[A GitHub account](https://github.com/)** is optional but highly recommended for setting up your CI/CD workflow. + +## Local environment setup + +### Required tools + +[**NodeJS**](https://nodejs.org/en/download/), version 18 or 20 (odd versions are not recommended), which will also install the npm package manager. We recommend [nvm](https://github.com/nvm-sh/nvm/blob/master/README.md) for NodeJS installation and version management. + +[**Adobe I/O Command Line Interface (CLI)**](https://github.com/adobe/aio-cli) + +- `npm install -g @adobe/aio-cli` +- If Adobe I/O CLI is already installed, please make sure you have the latest version: + - Check your CLI version using `aio -v` and compare it to`npm show @adobe/aio-cli version`. If your CLI is outdated, update it by running `npm install -g @adobe/aio-cli`. + - Even if your Adobe I/O CLI is up to date, run `aio update` to make sure all core plugins are updated. + - For seven days after release of a new version of Adobe I/O CLI, you'll see a message like this before the command output: + +```bash +› Warning: @adobe/aio-cli update available from 3.3.0 to 3.4.1. +› Run npm install -g @adobe/aio-cli to update. +``` + +#### Supported local environments + +We aim to provide similar quality of local development experience on Windows 10 and 11, and MacOS 10.14 and higher. +[Adobe I/O CLI](https://github.com/adobe/aio-cli) and its plugins are automatically tested against NodeJS versions 14 and 16 on both Windows and [Linux Xenial](http://releases.ubuntu.com/16.04/). + +#### Supported terminals for the CLI + +The [CLI](https://github.com/adobe/aio-cli) uses the popular [inquirer](https://www.npmjs.com/package/inquirer) package for all its interactive functions such as application generators. + +See [inquirer's Support section](https://www.npmjs.com/package/inquirer#support-os-terminals) and its [known issues](https://www.npmjs.com/package/inquirer#known-issues) for up-to-date details. + +### Optional tool + +If you intend to use local development (`aio app dev`) features provided by the [CLI](https://github.com/adobe/aio-cli), you will also need: + +- [Visual Studio Code](https://code.visualstudio.com/download), the supported integrated development environment (IDE) for editing, debugging, etc. You may use any other IDE as a code editor, but advanced usage like debugging is not yet supported. + +## Next step + +Now that you have your environment set up, you can start to [Create your First App Builder Application](first-app.md). diff --git a/src/pages/hackathon-files/todo-index.md b/src/pages/hackathon-files/todo-index.md new file mode 100644 index 000000000..7e8dce164 --- /dev/null +++ b/src/pages/hackathon-files/todo-index.md @@ -0,0 +1,20 @@ +--- +keywords: + - Adobe I/O + - Extensibility + - API Documentation + - Developer Tooling +title: Building an App Builder Todo App +description: How to build a Todo App with App Builder using aio-lib-state as storage library and React Spectrum components. +--- + +# Building an App Builder To-Do App with aio-lib-state and React Spectrum + +This Code Lab shows how to build a To-Do App with App Builder using [aio-lib-state](https://github.com/adobe/aio-lib-state) as a storage library and [React Spectrum](https://react-spectrum.adobe.com/) components. + +You'll learn: + +* How to use [aio-lib-state](https://github.com/adobe/aio-lib-state) as part of Runtime actions +* How to bind React Spectrum components to Runtime actions + +The project source code is available [here](https://github.com/adobedocs/adobeio-samples-todoapp/).