├── README.md ├── COPYRIGHT ├── manifest.json ├── LICENSE ├── CONTRIBUTING.md ├── CODE_OF_CONDUCT.md ├── submit.md ├── maintain.md └── implement.md /README.md: -------------------------------------------------------------------------------- 1 | # aem-connectors-temp 2 | -------------------------------------------------------------------------------- /COPYRIGHT: -------------------------------------------------------------------------------- 1 | © Copyright 2015-2018 Adobe. All rights reserved. 2 | 3 | Adobe holds the copyright for all the files found in this repository. 4 | 5 | See the LICENSE file for licensing information. 6 | -------------------------------------------------------------------------------- /manifest.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "AEM Connectors", 3 | "version": "1.0.0", 4 | "description": "AEM Connectors Implement, Submit, Maintain", 5 | "author": "Emily Walpole", 6 | "view_type": "mdbook", 7 | "meta_keywords": "Experience Cloud, Adobe Experience Manager", 8 | "meta_description": "Adobe Experience Manager Connectors Implementation, Submission, Maintenance", 9 | "publish_date": "06/11/2018", 10 | "show_edit_github_banner": false, 11 | "base_path": "", 12 | "pages": [ 13 | { 14 | "pages": [], 15 | "path": "implement.md", 16 | "title": "Implementing an AEM Connector", 17 | "description": "" 18 | }, 19 | { 20 | "pages": [], 21 | "path": "submit.md", 22 | "title": "Submitting an AEM Connector", 23 | "description": "" 24 | }, 25 | { 26 | "pages": [], 27 | "path": "maintain.md", 28 | "title": "Maintaining an AEM Connector", 29 | "description": "" 30 | } 31 | ] 32 | } 33 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | © Copyright 2018 Adobe. All rights reserved. 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing 2 | 3 | Thanks for choosing to contribute! 4 | 5 | The following are a set of guidelines to follow when contributing to this project. 6 | 7 | ## Code Of Conduct 8 | 9 | This project adheres to the Adobe [code of conduct](CODE_OF_CONDUCT.md). By participating, 10 | you are expected to uphold this code. Please report unacceptable behavior to 11 | [Grp-opensourceoffice@adobe.com](mailto:Grp-opensourceoffice@adobe.com). 12 | 13 | ## Have A Question? 14 | 15 | Start by filing an issue. The existing committers on this project work to reach 16 | consensus around project direction and issue solutions within issue threads 17 | (when appropriate). 18 | 19 | ## Contributor License Agreement 20 | 21 | All third-party contributions to this project must be accompanied by a signed contributor 22 | license agreement. This gives Adobe permission to redistribute your contributions 23 | as part of the project. [Sign our CLA](http://opensource.adobe.com/cla.html). You 24 | only need to submit an Adobe CLA one time, so if you have submitted one previously, 25 | you are good to go! 26 | 27 | ## Code Reviews 28 | 29 | All submissions should come in the form of pull requests and need to be reviewed 30 | by project committers. Read [GitHub's pull request documentation](https://help.github.com/articles/about-pull-requests/) 31 | for more information on sending pull requests. 32 | 33 | Lastly, please follow the [pull request template](PULL_REQUEST_TEMPLATE.md) when 34 | submitting a pull request! 35 | 36 | ## From Contributor To Committer 37 | 38 | We love contributions from our community! If you'd like to go a step beyond contributor 39 | and become a committer with full write access and a say in the project, you must 40 | be invited to the project. The existing committers employ an internal nomination 41 | process that must reach lazy consensus (silence is approval) before invitations 42 | are issued. If you feel you are qualified and want to get more deeply involved, 43 | feel free to reach out to existing committers to have a conversation about that. 44 | 45 | ## Security Issues 46 | 47 | Security issues shouldn't be reported on this issue tracker. Instead, [file an issue to our security experts](https://helpx.adobe.com/security/alertus.html) 48 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Adobe Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | In the interest of fostering an open and welcoming environment, we as 6 | contributors and maintainers pledge to making participation in our project and 7 | our community a harassment-free experience for everyone, regardless of age, body 8 | size, disability, ethnicity, gender identity and expression, level of experience, 9 | nationality, personal appearance, race, religion, or sexual identity and 10 | orientation. 11 | 12 | ## Our Standards 13 | 14 | Examples of behavior that contributes to creating a positive environment 15 | include: 16 | 17 | * Using welcoming and inclusive language 18 | * Being respectful of differing viewpoints and experiences 19 | * Gracefully accepting constructive criticism 20 | * Focusing on what is best for the community 21 | * Showing empathy towards other community members 22 | 23 | Examples of unacceptable behavior by participants include: 24 | 25 | * The use of sexualized language or imagery and unwelcome sexual attention or 26 | advances 27 | * Trolling, insulting/derogatory comments, and personal or political attacks 28 | * Public or private harassment 29 | * Publishing others' private information, such as a physical or electronic 30 | address, without explicit permission 31 | * Other conduct which could reasonably be considered inappropriate in a 32 | professional setting 33 | 34 | ## Our Responsibilities 35 | 36 | Project maintainers are responsible for clarifying the standards of acceptable 37 | behavior and are expected to take appropriate and fair corrective action in 38 | response to any instances of unacceptable behavior. 39 | 40 | Project maintainers have the right and responsibility to remove, edit, or 41 | reject comments, commits, code, wiki edits, issues, and other contributions 42 | that are not aligned to this Code of Conduct, or to ban temporarily or 43 | permanently any contributor for other behaviors that they deem inappropriate, 44 | threatening, offensive, or harmful. 45 | 46 | ## Scope 47 | 48 | This Code of Conduct applies both within project spaces and in public spaces 49 | when an individual is representing the project or its community. Examples of 50 | representing a project or community include using an official project e-mail 51 | address, posting via an official social media account, or acting as an appointed 52 | representative at an online or offline event. Representation of a project may be 53 | further defined and clarified by project maintainers. 54 | 55 | ## Enforcement 56 | 57 | Instances of abusive, harassing, or otherwise unacceptable behavior may be 58 | reported by contacting the project team at Grp-opensourceoffice@adobe.com. All 59 | complaints will be reviewed and investigated and will result in a response that 60 | is deemed necessary and appropriate to the circumstances. The project team is 61 | obligated to maintain confidentiality with regard to the reporter of an incident. 62 | Further details of specific enforcement policies may be posted separately. 63 | 64 | Project maintainers who do not follow or enforce the Code of Conduct in good 65 | faith may face temporary or permanent repercussions as determined by other 66 | members of the project's leadership. 67 | 68 | ## Attribution 69 | 70 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, 71 | available at [https://contributor-covenant.org/version/1/4][version] 72 | 73 | [homepage]: https://contributor-covenant.org 74 | [version]: https://contributor-covenant.org/version/1/4/ 75 | -------------------------------------------------------------------------------- /submit.md: -------------------------------------------------------------------------------- 1 | Submitting an AEM Connector 2 | =========================== 3 | 4 | Provided below is useful information for submitting [AEM Connectors](www.adobe.io/apis/experiencecloud/aem/aemconnectors.html) and should be read in conjunction with articles about [implementing](implement.md) and  [maintaining](maintain.md) connectors. 5 | 6 | AEM Connectors are listed on the [Adobe Exchange](https://marketing.adobe.com/resources/content/resources/en/exchange/marketplace.html), where they can be discovered by customers. We recommend distributing the package binary through AEM's Package Share, which implies some vetting of the package by an Adobe Exchange partner team representative. 7 | 8 | The steps below outline the process for submitting a connector, after it has been [implemented](implement.md): 9 | 10 | 1. Create a package: AEM connectors typically include an AEM package that is built and often installed using AEM Package Manager. Learn about using AEM Package Manager to [create a package](https://docs.adobe.com/docs/en/aem/6-3/administer/content/package-manager.html#Creating a New Package), including filling out the fields under [package settings](https://docs.adobe.com/docs/en/aem/6-3/administer/content/package-manager.html#Package Settings). 11 | 12 | 13 | 2. Optionally, upload the package to AEM Package Share: As described above, hosting the package through AEM's Package Share site is recommended. Learn about [accessing Package Share](https://docs.adobe.com/docs/en/aem/6-3/administer/content/package-manager.html#Package Share) and [uploading a package](https://docs.adobe.com/docs/en/aem/6-3/administer/content/package-manager.html#Uploading a package).  14 | 15 | 16 | 3. If uploaded to Package Share, an Adobe Admin will review the connector to ensure it functions correctly with activities that include: 17 | 4. installing the package 18 | * executing integration tests to validate proper execution, such as looking for regressions in core AEM code, broken UI, and reductions in overall performance. 19 | * validating that it does not introduce unwarranted warnings or errors into the logs. 20 | * ensuring that it does not interfere with upgrading the version of an AEM instance. 21 | * validating that certain design patterns are followed; for example, translation connectors should use the [AEM Translation Framework.](https://docs.adobe.com/docs/en/aem/6-3/administer/sites/translation/tc-tic.html) 22 | 5. Register for the [Adobe Exchange Program](https://partners.adobe.com/exchangeprogram/experiencecloud), which serves as the hub for vendors to manage their relationship with Adobe and their connectors. 23 | 24 | 25 | 6. Create a listing for the connector in Adobe Exchange by clicking the appropriate button on the Adobe Exchange Program's [main page](https://partners.adobe.com/exchangeprogram/experiencecloud). Fill out all required fields in the multi-page form and submit. Consider referencing documentation and videos to inform customers how the connector works.  26 | 27 | See this [App Listing Guide](https://partners.adobe.com/exchangeprogram/experiencecloud/build/ec-exchange.html) for best practices in filling out the form. 28 | 29 | If the package was uploaded to package share, make sure to indicate so by choosing "Experience Manager Package Share" for the "installation instructions" question. This will ensure that an Adobe administrator is aware of the connection between the listing and the binary submission in package share. 30 | 31 | 32 | 7. Once the listing is approved, the connector will be listed on Adobe Exchange and the package will be made available on Package Share, if uploaded there. The listing description will reference how the consumer can gain access to the connector, either in Package Share or a partner's own web infrastructure. 33 | 34 | Also read the [maintenance article](maintain.md) to understand a partner's commitments, once the initial connector has been approved and listed. 35 | -------------------------------------------------------------------------------- /maintain.md: -------------------------------------------------------------------------------- 1 | Maintaining an AEM Connector 2 | ============================ 3 | 4 | This article contains information about maintaining an [AEM Connector](www.adobe.io/apis/experiencecloud/aem/aemconnectors.html) and should be read in conjunction with articles about [implementing](implement.md) and [submitting](submit.md) connectors. 5 | 6 | Even after the initial submission, there may be reasons for a partner to update its AEM Connector, either due to a new release of AEM or independent of that – for example, to add features or to fix bugs. This article outlines the process for both scenarios and also describes a customer's typical process for validating connectors when upgrading AEM.  7 | 8 | Connector Updates due to AEM Releases 9 | ------------------------------------- 10 | 11 | AEM releases software via several [release vehicles](https://docs.adobe.com/docs/en/aem/6-3/deploy/maintenance-release-vehicle-definitions.html) and partners should pay particular attention to full releases and service packs to ensure that their connectors continue to function. If code changes are necessary, connectors should be updated so customers enjoy a seamless upgrade process. Since customers are in full control of when they upgrade, partners may choose to support multiple versions of their connector, based on their knowledge of which versions of AEM are most popular with their customers.  12 | 13 | ### Full releases 14 | 15 | A full release is a major AEM version upgrade once a year, historically in the April time frame. The current version is 6.3.  16 | 17 | Partners are expected to test their connector with each major version to ensure that it continues to function. If a new version of a connector is needed, the resubmission process will depend on whether the package binary is distributed through AEM Package Share. 18 | 19 | If hosted in Package Share  20 | 21 | * A partner can choose to replace the existing Package Share listing or create a new one. It's preferable to replace an existing listing, which implies backwards compatibility with  previous AEM versions, but here are some reasons for why this might not be possible: 22 | * the new AEM version has an API signature change 23 | * the new AEM version has an incompatible OSGI dependency 24 | * there are substantial code changes, either in AEM or the partner service (e.g. a new cloud API), making it difficult to support multiple versions of code in the same package 25 | * Indicate to the Adobe Exchange partner team whether the existing Package Share listing should be used by marking the same Name and Group ID in package metadata. This ensures that the package is uploaded to the same JCR location under /etc/packages so AEM Package Manager shows an option to update the package. 26 | * The package's description field should reference the supported AEM versions. 27 | * The AEM Tested With and AEM Built With fields should reflect the highest version supported for the package.  28 | * Email the Adobe Exchange partner team ([aemc-support@adobe.com](mailto:aemc-support@adobe.com)) when the updated package has been uploaded. When the Adobe Exchange partner team approves the listing, the associated Adobe Exchange listing will be updated with a reference to the latest package share link. 29 | 30 | If not hosted in Package Share 31 | 32 | * Email the Adobe Exchange partner team with the desired changes in the listing description, which should reference the newly supported AEM versions.  33 | 34 | ### Service packs 35 | 36 | A service pack is an update to a specific full release and potentially released every quarter.  Service Packs include important bug fixes and potentially product enhancements. 37 | 38 | Partners are expected to test their connector with each service pack to ensure that it continues to function. While it's less likely that a service pack will introduce major changes, if a new version of a connector is necessary, follow the same resubmission process as outlined under the "Full releases" section.  39 | 40 | ### Other release types 41 | 42 | While rare, a hot fix or cumulative fix pack can theoretically modify connector functionality. If a customer who has applied a patch notifies the partner that the connector has stopped functioning correctly, follow the same resubmission process as outlined under the "Full releases" section. 43 | 44 | Connector updates independent of AEM releases 45 | --------------------------------------------- 46 | 47 | A partner may decide to modify a connector for various reasons, including introducing new features or fixing bugs. The resubmission process is similar to what is outlined in the "Full releases" section under AEM Releases above, although the partner should also include more context about the changes in the new description.  48 | 49 | Customer AEM upgrade process and connector validation 50 | ----------------------------------------------------- 51 | 52 | Typically, a customer upgrading AEM will follow the process outlined below, validating that partner connectors continue to work. If a connector has issues, the customer will likely reach out to the partner. 53 | 54 | 1. Customers use AEM X.1 with connector Y.1 55 | 2. Adobe announces AEM X.2 56 | 3. Customers install X.2 on a test environment to see how it fits their business and see if the connector works 57 | 4. If the connector doesn’t work, they'll open a ticket directly with the partner 58 | 5. The partner updates their package and posts it as Y.2 and we certify the build on AEM X.2 59 | 6. Partner reaches out to the customer and lets them know that Y.2 build is available. 60 | 7. Customer installs the Y.2 build on top of Y.1 connector.  It is assumed that the packages are created in such a way that the Name and Group ID are consistent for the connector to be upgraded without having to uninstall an older version. 61 | 8. Customer tests the environment and upon success adds both AEM X.2 and connector Y.2 to their release plan. 62 | -------------------------------------------------------------------------------- /implement.md: -------------------------------------------------------------------------------- 1 | Implementing an AEM Connector 2 | ============================= 3 | 4 | Provided below are useful references for building [AEM Connectors](www.adobe.io/apis/experiencecloud/aem/aemconnectors.html) and should be read in conjunction with guidance on [submitting](submit.md) and [maintaining](maintain.md) connectors. 5 | 6 | Note that a Developer license for AEM can be obtained through the [Adobe Exchange Program](https://marketing.adobe.com/resources/content/resources/exchange-partner-program.html). 7 | 8 | Common Integration Patterns 9 | --------------------------- 10 | 11 | AEM is a cutting-edge web experience management solution and offers many potential areas of integrations. Common integration patterns include: 12 | 13 | * Pulling data from an external system into AEM. For example, exporting contact information from a CRM to make it available to a wider audience visiting an AEM-powered website. Implementations may leverage [Sling scheduler](https://helpx.adobe.com/experience-manager/using/aem-first-components1.html) or  [CQ poll config](http://blogs.adobe.com/experiencedelivers/experience-management/example-of-cq-poll-config/). See an [actual example](https://github.com/knennigtri/Import-Evernote-into-AEM) with working code. 14 | * Exporting data from AEM into an external system. For example, newsletter subscription settings submitted on an AEM-powered website to a CRM. 15 | * Retrieving assets from AEM. For example, an external Content Management System (CMS) referencing an asset stored in AEM Assets. Or as another example,  a PIM system linking to an image in AEM Assets. 16 | * Storing assets in AEM. For example, a Marketing Resource Management (MRM) system storing an approved asset in AEM Assets. 17 | * Configuring and rendering a custom UI component. For example, allow an author to drag and drop a video component and configure a specific video to play on the live site. Learn more about [AEM components](https://docs.adobe.com/docs/en/aem/6-3/develop/components/components-basics.html). 18 | * Acting on an asset with a partner service. For example, sending an asset to a video platform when a page is published. 19 | * Analyzing a site, page, or asset in the AEM admin console. For example, making SEO recommendations for an existing or unpublished page. 20 | * Page-level access to user data maintained by an external service. For example, leverage demographic information to personalize the site experience. Read about [ContextHub](https://docs.adobe.com/docs/en/aem/6-3/develop/personalization/contexthub.html), a framework for storing, manipulating, and presenting context data.  21 | * Translating site copy or asset metadata. See the [AEM Translation Framework Bootstrap Connector](https://github.com/Adobe-Marketing-Cloud/aem-translation-framework-bootstrap-connector) for sample code using the AEM Translation Framework, which is the preferred implementation of translation connectors. 22 | * Connecting with an eCommerce engine. Learn about the [AEM Commerce Framework](https://docs.adobe.com/docs/en/aem/6-3/administer/ecommerce.html#The Framework). 23 | 24 | Useful Documentation 25 | -------------------- 26 | 27 | AEM's [documentation](https://docs.adobe.com/content/docs/en/aem/6-3.html) provides valuable insights into developing in AEM. Below are some specific technical topics and references that you may find useful while implementing an AEM connector: 28 | 29 | * [How to Develop AEM Projects Using Eclipse](https://docs.adobe.com/docs/en/aem/6-3/develop/dev-tools/howto-projects-eclipse.html) 30 | * A list of [How-To articles](https://helpx.adobe.com/experience-manager/topics/how-to.html), many that include code and related walkthroughs 31 | * [Best Practices](https://docs.adobe.com/docs/en/aem/6-3/develop/best-practices.html) for various AEM topics 32 | * Adobe Consulting Services (ACS) [AEM Samples](http://adobe-consulting-services.github.io/acs-aem-samples/) for well-commented code to help educate AEM developers 33 | * Configuring a [Cloud Service Configuration](https://docs.adobe.com/docs/en/aem/6-3/develop/extending/cloud-service-configurations.html) dialog to make it easy for customers to setup the connector 34 | 35 | * The various documentation links in the Common Integration Patterns section of this article 36 | 37 | Community Resources  38 | -------------------- 39 | 40 | In addition to the static documentation above, Adobe and the AEM community offer resources to help bring a connector to market: 41 | 42 | * The Adobe Community's [AEM Forum](http://help-forums.adobe.com/content/adobeforums/en/experience-manager-forum/adobe-experience-manager.html) is an active site where your peers ask and respond to questions 43 | * Additional Adobe technical resources are available to certain partner levels. Learn more about the [Adobe Exchange Program](https://marketing.adobe.com/resources/content/resources/exchange-partner-program.html). 44 | * If your organization would like implementation help, consider Adobe's [Professional Services](http://www.adobe.com/marketing-cloud/service-support/professional-consulting-training.html) team or see the [Solution Partner Finder](https://solutionpartners.adobe.com/home/partnerFinder.html) for a list of Adobe's partners across the globe 45 | 46 | Technical Requirements 47 | ---------------------- 48 | 49 | Below is a list of best practices for AEM Connectors. While we highly recommend that all AEM connectors listed in the Adobe Marketing Cloud Exchange adhere to these requirements, they will be explicitly enforced for those connectors whose binaries are distributed via AEM Package Share. Connectors distributed via AEM Package Share are vetted by an Adobe Approver, giving customers greater confidence that the solution functions correctly. Learn more about [submitting a connector](submit.md). 50 | 51 | * Build with a supported JDK and test the connector in a supported environment, which can be referenced [here](https://docs.adobe.com/docs/en/aem/6-3/deploy/technical-requirements.html). 52 | * Due to security concerns, do not reference [the deprecated](http://sling.apache.org/documentation/the-sling-engine/service-authentication.html#deprecation-of-administrative-authentication) SlingRepository.loginAdministrative() and ResourceResolverFactory.getAdministrativeResourceResolver() methods. 53 | * Uninstalling a connector should not break AEM functionality. 54 | * Upgrading a connector should seamlessly replace the prior version. See the [connector maintenance article](maintain.md) to understand the common customer upgrade process.  55 | * Upgrading AEM should not break the connector. Of course, it is only possible to test this for connectors targeting older versions of AEM.    56 | * Works with main supported browsers, in particular IE11, Firefox, and Chrome. 57 | * Works on both Windows and Linux. Pay special attention to path case sensitivity, which differs on the two OSes. 58 | 59 | Design Considerations 60 | --------------------- 61 | 62 | When writing a connector, consider the following decisions: 63 | 64 | * Which versions of AEM should be supported? Partners may benefit from surveying their customers to determine what AEM versions to build for and maintain. Read more about requirements and best practices for [maintaining a connector](maintain.md) and providing a seamless upgrade path for customers upgrading to newer versions of AEM. 65 | * Support localization for connectors that will be used in different regions. Learn about [localizing components](https://docs.adobe.com/docs/en/aem/6-3/develop/components/i18n.html). 66 | * Check if the AEM instance uses a proxy before requesting remote URLs, retrieving the HttpClient using org.apache.http.osgi.services.HttpClientBuilderFactory.newBuilder().build(); 67 | --------------------------------------------------------------------------------