This chapter offers a quick setup of a local environment to see an external application consume content from AEM using AEM’s GraphQL APIs. Later chapters in the tutorial will build off of this setup.
The following tools should be installed locally:
This tutorial uses the AEM as a Cloud Service SDK to explore AEM’s GraphQL APIs. This section provides a quick guide to installing the AEM SDK and running it in Author mode. A more detailed guide for setting up a local development environment can be found here.
It is also possible to follow the tutorial with an AEM as a Cloud Service environment. Additional notes for using a Cloud environment are included throughout the tutorial.
Navigate to the Software Distribution Portal > AEM as a Cloud Service and download the latest version of the AEM SDK.
The GraphQL feature is enabled by default only on the AEM SDK from 2021-02-04 or newer.
Unzip the download and copy the Quickstart jar (
aem-sdk-quickstart-XXX.jar) to a dedicated folder, i.e
Re-name the jar file to
author name specifies that the Quickstart jar will start in Author mode. The
p4502 specifies that the Quickstart server will run on port 4502.
Open a new terminal window and navigate to the folder that contains the jar file. Run the following command to install and start the AEM instance:
$ cd ~/aem-sdk/author $ java -jar aem-author-p4502.jar
Provide an admin password as
admin. Any admin password is acceptable, however its recommend to use
admin for local development to reduce the need to re-configure.
After a few minutes the AEM instance will finish installing and a new browser window should open at http://localhost:4502.
Login with the username
admin and the password selected during AEM’s initial start-up (usually
Sample content from the WKND Reference site will be installed to accelerate the tutorial. The WKND is a fictitious life-style brand, often used in conjunction with AEM training.
The WKND Reference site includes configurations needed to expose a GraphQL endpoint. In a real-world implementation follow the documented steps to include the GraphQL endpoints in your customer project. A CORS has also been packaged as part of the WKND Site. A CORS configuration is needed to grant access to an external application, more information about CORS can be found below.
Download the latest compiled AEM Package for WKND Site: aem-guides-wknd.all-x.x.x.zip.
Make sure to download the standard version compatible with AEM as a Cloud Service and not the
From the AEM Start menu navigate to Tools > Deployment > Packages.
Click Upload Package and choose the WKND package downloaded in the prior step. Click Install to install the package.
From the AEM Start menu navigate to Assets > Files.
Click through the folders to navigate to WKND Site > English > Adventures.
This is a folder of all the assets that comprise the various Adventures promoted by the WKND brand. This includes traditional media types like images and video, as well as media specific to AEM like Content Fragments.
Click into the Downhill Skiing Wyoming folder and click the Downhill Skiing Wyoming Content Fragment card:
The Content Fragment Editor UI will open for the Downhill Skiing Wyoming adventure.
Observe that various fields like Title, Description, and Activity define the fragment.
Content Fragments are one of the ways content can be managed in AEM. Content Fragment are reusable, presentation-agnostic content composed of structured data elements such as text, rich text, dates or references to other Content Fragments. Content Fragments will be explored in greater detail later in the tutorial.
Click Cancel to close the fragment. Feel free to navigate into some of the other folders and explore the other Adventure content.
If using a Cloud Service environment see the documentation for how to deploy a code base like the WKND Reference site to a Cloud Service environment.
One of the goals of this tutorial is to show how to consume AEM content from an external application using the GraphQL APIs. This tutorial uses an example React App that has been partially completed to accelerate the tutorial. The same lessons and concepts apply to apps built with iOS, Android or any other platform. The React app is intentionally simple, to avoid unnecessary complexity; it is not meant to be a reference implementation.
Open a new terminal window and clone tutorial starter branch using Git:
$ git clone --branch tutorial/react email@example.com:adobe/aem-guides-wknd-graphql.git
In the IDE of your choice open the file
aem-guides-wknd-graphql/react-app/.env.development. Verify that the
REACT_APP_AUTHORIZATION line is un-commented and that the file looks like the following:
REACT_APP_HOST_URI=http://localhost:4502 REACT_APP_GRAPHQL_ENDPOINT=/content/graphql/global/endpoint.json # Use Authorization when connecting to an AEM Author environment REACT_APP_AUTHORIZATION=admin:admin
React_APP_HOST_URI matches your local AEM instance. In this chapter we will connect the React App directly to the AEM Author environment. Author environments by default require authentication, so our app will connect as the
admin user. This is a common practice during development, since it allows us to quickly make changes on the AEM environment and see them immediately reflected in the app.
In a production scenario the App will connect to an AEM Publish environment. This is covered in more detail in the Production deployment chapter.
Navigate into the
aem-guides-wknd-graphql/react-app folder. Install and start the app:
$ cd aem-guides-wknd-graphql/react-app $ npm install $ npm start
A new browser window should automatically launch the app at http://localhost:3000.
A list of the current Adventure content from AEM should be displayed.
Click one of the adventure images to view the adventure detail. A request is made to AEM to return the detail for an adventure.
Use the browser’s developer tools to inspect the Network requests. View the XHR requests and observe multiple POST requests to
/content/graphql/global/endpoint.json, the GraphQL endpoint configured for AEM.
You can also view the parameters and JSON response by inspecting the network request. It may be helpful to install a browser extension like GraphQL Network Inspector for Chrome to get a better understanding of the query and response.
Now that the React app is running, make an update to the content in AEM and see the change reflected in the app.
Navigate to AEM http://localhost:4502.
Navigate to Assets > Files > WKND Site > English > Adventures > Bali Surf Camp.
Click into the Bali Surf Camp content fragment to open the Content Fragment Editor.
Modify the Title and the Description of the adventure
Click Save to save the changes.
Navigate back to the React app at http://localhost:3000 and refresh to see your changes:
GraphiQL is a development tool and needed only on lower-level environments like a development or local instance. The GraphiQL IDE allows you to quickly test and refine the queries and data returned. GraphiQL also provides easy access to the documentation, making it easy to learn and understand what methods are available.
Navigate to the Software Distribution Portal > AEM as a Cloud Service.
Search for “GraphiQL” (be sure to include the i in GraphiQL.
Download the latest GraphiQL Content Package v.x.x.x
The zip file is an AEM package that can be installed directly.
From the AEM Start menu navigate to Tools > Deployment > Packages.
Click Upload Package and choose the package downloaded in the prior step. Click Install to install the package.
Navigate to the GraphiQL IDE at http://localhost:4502/content/graphiql.html and begin exploring the GraphQL APIs.
The GraphiQL tool and GraphQL API is explored in more detail later in the tutorial.
Congratulations, you now have an external application consuming AEM content with GraphQL. Feel free to inspect the code in the React app and continue to experiment with modifying existing Content Fragments.
In the next chapter, Defining Content Fragment Models, learn how to model content and build a schema with Content Fragment Models. You will review existing models and create a new model. You will also learn about the different data types that can be used to define a schema as part of the model.
AEM, being secure by default, blocks cross-origin requests, preventing unauthorized applications from connecting to and surfacing its content.
To allow this tutorial’s React app to interact with AEM’s GraphQL API endpoints, a cross-origin resource sharing configuration has been defined in the WKND Site reference project.
To view the configuration deployed:
Navigate to AEM SDK’s Web Console at http://localhost:4502/system/console.
The Web Console is only available on the SDK. In an AEM as a Cloud Service environment this information can be viewed via the Developer Console.
In the top menu click OSGI > Configuration to bring up all of the OSGi Configurations.
Scroll down the page Adobe Granite Cross-Origin Resource Sharing.
Click on the configuration for
The following fields have been updated:
POSTis required for GraphQL however the other methods can be useful when interacting with AEM in headless manner.
This configuration and the GraphQL endpoints are a part of the AEM WKND project. You can view all the OSGi configurations here.