From 7f4407d629b53debe7a5b251b33eada0799bcdbe Mon Sep 17 00:00:00 2001 From: Monika Michalska Date: Wed, 9 Oct 2024 15:32:34 +0200 Subject: [PATCH 1/6] [DOCS-7721] Update Custom Amp Documentation in ACA 4.0 --- .../develop/extension-content-accelerator.md | 77 ++++++++++++++++--- 1 file changed, 67 insertions(+), 10 deletions(-) diff --git a/content-accelerator/latest/develop/extension-content-accelerator.md b/content-accelerator/latest/develop/extension-content-accelerator.md index 4213e692a6..3d826db002 100644 --- a/content-accelerator/latest/develop/extension-content-accelerator.md +++ b/content-accelerator/latest/develop/extension-content-accelerator.md @@ -2,20 +2,34 @@ title: Extension Content Accelerator (Custom Amp) --- -The Extension Content Accelerator is a generic content accelerator for adding custom configurations and code to an existing accelerator. +One of the common ways customers and implementation teams extend the out-of-the-box ACA functionality is by using what we refer to as a "Custom Amp". This is essentially a way to use the Alfresco SDK to generate an Alfresco Amp file that can be deployed to Alfresco Content Services for the following functionalities: -## How to add the Extension Content Accelerator onto existing Accelerators +* Deploy custom content models +* Create custom rest endpoints +* Add custom Alfresco behaviors +* Override existing OpenContent code +* Create custom document overlays/watermarks -There are a few requirements that your custom AMP must meet to work with the existing accelerators. +This Custom Amp framework can also be thought of as a generic content accelerator for adding custom configurations and code to an existing ACA accelerator. -1. The AMP configuration and code must reside under `alfresco/module/com.alfresco.aca.accelerator.extension` to be properly picked up +The Offering Management team has generated a sample SDK project (see https://github.com/Alfresco/om-content-accelerator-enterprise-viewer) for reference as a starting point for developing your own Custom Amp. The sample Amp has been developed in a way that it can be used for extension of Claims, Policy and Procedure or Human Resources Employee File Management accelerators. + +## How to develop a Custom Amp for the existing extensions + +There are a few requirements that your Custom Amp must meet to work with the existing accelerators. The sample Amp has been developed to meet these standard rules and they are listed here for reference: + +1. The Amp configuration and code must reside under `alfresco/module/com.alfresco.aca.accelerator.extension` to be properly picked up + * Refer to `src/main/config/alfresco/module` in sample SDK project for reference 2. Any overrides for ACA properties must reside in a file named `opencontent-extension-override-placeholders.properties` + * Refer to `src/main/config/alfresco/module/com.alfresco.accelerator.extension/opencontent-extension-override-placeholders.properties` in sample SDK project for reference 3. Any overrides or additions to the ACA bean configurations need to reside in a file named `opencontent-extension-override-config.xml`. **Note:** This file can reference other xml config files but ACA will only specifically look for this file. + * Refer to `src/main/config/alfresco/module/com.alfresco.accelerator.extension/opencontent-extension-override-config.xml` in sample SDK project for reference 4. Name the module context file for the extension `opencontent-extension-override-module-ctx.xml` + * Refer to `src/main/config/alfresco/module/com.alfresco.accelerator.extension/opencontent-extension-override-module-ctx.xml` in sample SDK project for reference -### How to add custom Alfresco models into the custom AMP +### How to add custom Alfresco models into the Custom Amp -To add custom alfresco models you will need to define a bean that has a parent of `dictionaryModelBootstrap` and depends-on `dictionaryBootstrap,com.tsgrp.openContent.dictionaryBootstrap` in the aca extension accelerators module context file. This bean will need to extend any models that other accelerators would need. For instance, this is what it might look like to add onto the claims or pnp accelerators: +To add custom alfresco models you will need to define a bean that has a parent of `dictionaryModelBootstrap` and depends-on `dictionaryBootstrap,com.tsgrp.openContent.dictionaryBootstrap` in the ACA extension accelerators module context file. This bean will need to extend any models that other accelerators would need. For instance, this is what it might look like to add onto the claims or pnp accelerators: ```xml @@ -35,17 +49,60 @@ When you add a new document type extension for use in Alfresco Content Accelerat If, however, the `tsg:renditioned` aspect is not desired, or the model already exists and cannot be updated, it is possible to turn on view time renditioning in the [Document Viewer]({% link content-accelerator/latest/configure/admin-guide.md %}#document-viewer) config in the Stage. +Steps to accomplish this in your Custom Amp: + +1. Create a bean to extend `dictionaryModelBootstrap` that points to the xml file for your custom model. (See `alfresco-sdk-aca-sample\sample-platform\src\main\config\alfresco\module\com.alfresco.accelerator.extension\opencontent-extension-override-module-ctx.xml` in sample SDK project for reference) +2. Create a custom model xml and put it in the correct location in the amp code. (See `alfresco-sdk-aca-sample\sample-platform\src\main\config\alfresco\extension\model\sampleModel.xml` in sample SDK project for reference) + +### How to create a custom REST API endpoint in a custom amp + +To create a custom REST API endpoint in your custom amp, create REST controller and extend `RESTService`. + +Complete the following steps to create the REST controller and extend `RESTService` in your Custom Amp: + +1. Define a bean to make this Rest API accessible from ACA in file `opencontent-extension-override-config.xml`. (see `alfresco-sdk-aca-sample/sample-platform/src/main/config/alfresco/module/com.alfresco.accelerator.extension/opencontent-extension-override-config.xml` in sample SDK project for reference) +2. Create a Java class with your new REST endpoint(s). (see `alfresco-sdk-aca-sample/sample-platform/src/main/java/com/tsgrp/opencontent/rest/RESTSample.java` in sample SDK project for reference) + +### How to add a custom Alfresco behavior in a Custom Amp + +To create a custom behavior in your Custom Amp, you will need to create a behaviour class and extend `HPIBehaviorBase`. Define a bean to register this behaviour in file `opencontent-extension-override-module-ctx.xml`. + +To accomplish this, complete the following steps: + +1. Define a bean for your behavior. (see `sampleDocumentCreateBehavior` bean in `alfresco-sdk-aca-sample/sample-platform/src/main/config/alfresco/module/com.alfresco.accelerator.extension/opencontent-extension-override-module-ctx.xml`in sample SDK project for reference) +2. Create a custom Alfresco behavior class to write your behavior logic. (see `alfresco-sdk-aca-sample/sample-platform/src/main/java/com/tsgrp/sample/behaviour/SampleDocumentCreateBehavior.java` in sample SDK project for reference) + +### How to override existing OpenContent code in a Custom Amp + +To override the existing OpenContent code, create a bean in `opencontent-extension-override-config.xml` with the same id as the bean that points to the OpenContent code that you want to override. In your new bean, refer to a new custom class you will implement in your Amp rather than the class the comes out of the box with OpenContent. Note that this will only work for overriding OpenContent classes that are referenced by a bean in OpenContent's spring configuration. + +Steps to accomplish this in your Custom Amp (example shows overriding the out-of-the-box Supscription action in ACA): + +1. Create your own custom implementation of the java code you wish to override and give it its own name (see `alfresco-sdk-aca-sample/sample-platform/src/main/java/com/tsgrp/opencontent/action/executer/SampleSubscriptionActionExecuter.java` in sample SDK project for reference) +2. Create a bean in `opencontent-extension-override-config.xml` with the same id as the bean that points to the OpenContent code that you want to override. Set the class on the bean to the new custom class you created in step 1. (see `alfresco-sdk-aca-sample/sample-platform/src/main/config/alfresco/module/com.tsgrp.opencontent/extension/opencontent-extension-override-config.xml` in sample SDK project for reference) + +### How create custom overlays in a Custom Amp + +To configure your own custom document overlays (watermarks), create a file named `oc-overlay-config.xml` and configure custom overlays as needed. Refer to [Configuring Overlays]({% link enterprise-viewer/latest/config/overlay.md %}) for more information. + +This file will override the `oc-overlay-config.xml` configurations that come out-of-the-box with OpenContent. If you wish to keep the exisitng configurations and add your own on top of what is provided, start by copying the `oc-overlay-config.xml` from OpenContent source code and then simply append your configurations to that file rather than starting from scratch. + +Steps to accomplish this in your Custom Amp: + +1. Place your custom `oc-overlay-config.xml` file at `platform/src/main/config/alfresco/module/com.alfresco.accelerator.extension/`. (see `alfresco-sdk-aca-sample/sample-platform/src/main/config/alfresco/module/com.alfresco.accelerator.extension/oc-overlay-config.xml` in sample SDK project for reference) +2. Create an `overlayConfigBean` bean that points to your overlay config file from step 1. Also create a bean for `openPdfEngine`. (see `alfresco-sdk-aca-sample\sample-platform\src\main\config\alfresco\module\com.tsgrp.opencontent\opencontent-override-overlay-spring-config.xml` in sample SDK project for reference) + ## How to deploy Alfresco custom content model in Alfresco Content Accelerator -Once you create a custom AMP, the next step is to deploy it to an Alfresco container and validate that the AMP is applied correctly. For more information see [Install Alfresco Module Package]({% link content-services/latest/install/zip/amp.md %}). +Once you create a Custom Amp, the next step is to deploy it to an Alfresco container and validate that the Amp is applied correctly. For more information see [Install Alfresco Module Package]({% link content-services/latest/install/zip/amp.md %}). -When the custom AMP is deployed successfully: +When the Custom Amp is deployed successfully: -* If a default AMP custom model was installed, a `sample_document` is deployed. The custom content type can be found in the **ACA Admin Console**. +* If a default Amp custom model was installed, a `sample_document` is deployed. The custom content type can be found in the **ACA Admin Console**. ![AMP custom model]({% link content-accelerator/images/ACA_amp-custom-model.png %}) * Select the document type and configure the properties as required. * Click **Save Config** at the bottom of the page to save and apply the changes. -* If a default AMP custom aspect was installed, a `sample_aspect` is deployed. It can be added to the **Non-Mandatory Aspect** section in the **ACA Admin Console**. +* If a default Amp custom aspect was installed, a `sample_aspect` is deployed. It can be added to the **Non-Mandatory Aspect** section in the **ACA Admin Console**. ![AMP custom aspect]({% link content-accelerator/images/ACA_amp-custom-aspect.png %}) * Select the aspect and configure the properties as required. * Click **Save Config** at the bottom of the page to save and apply the changes. From cd99bb41717aa80ccfc6d49c010b18b96048bec1 Mon Sep 17 00:00:00 2001 From: Monika Michalska Date: Tue, 15 Oct 2024 12:10:27 +0200 Subject: [PATCH 2/6] [DOCS-7721] Update after review --- .../develop/extension-content-accelerator.md | 76 +++++++++---------- 1 file changed, 38 insertions(+), 38 deletions(-) diff --git a/content-accelerator/latest/develop/extension-content-accelerator.md b/content-accelerator/latest/develop/extension-content-accelerator.md index 3d826db002..d2de194a93 100644 --- a/content-accelerator/latest/develop/extension-content-accelerator.md +++ b/content-accelerator/latest/develop/extension-content-accelerator.md @@ -1,33 +1,33 @@ --- -title: Extension Content Accelerator (Custom Amp) +title: Extension Content Accelerator (Custom AMP) --- -One of the common ways customers and implementation teams extend the out-of-the-box ACA functionality is by using what we refer to as a "Custom Amp". This is essentially a way to use the Alfresco SDK to generate an Alfresco Amp file that can be deployed to Alfresco Content Services for the following functionalities: +One of the common ways customers and implementation teams extend the out-of-the-box ACA functionality is by using what we refer to as a "Custom AMP". This is essentially a way to use the Alfresco SDK to generate an Alfresco AMP file that can be deployed to Alfresco Content Services for the following functionalities: * Deploy custom content models -* Create custom rest endpoints +* Create custom REST endpoints * Add custom Alfresco behaviors * Override existing OpenContent code * Create custom document overlays/watermarks -This Custom Amp framework can also be thought of as a generic content accelerator for adding custom configurations and code to an existing ACA accelerator. +This Custom AMP framework can also be thought of as a generic content accelerator for adding custom configurations and code to an existing ACA accelerator. -The Offering Management team has generated a sample SDK project (see https://github.com/Alfresco/om-content-accelerator-enterprise-viewer) for reference as a starting point for developing your own Custom Amp. The sample Amp has been developed in a way that it can be used for extension of Claims, Policy and Procedure or Human Resources Employee File Management accelerators. + A sample SDK project has been generated for reference, see `https://github.com/Alfresco/om-content-accelerator-enterprise-viewer`, as a starting point for developing your own Custom AMP. The sample AMP has been developed so that it can be used for the extension of Claims, Policy and Procedure, or Human Resources Employee File Management accelerators. -## How to develop a Custom Amp for the existing extensions +## How to develop a Custom AMP for the existing extensions -There are a few requirements that your Custom Amp must meet to work with the existing accelerators. The sample Amp has been developed to meet these standard rules and they are listed here for reference: +There are a few requirements that your Custom AMP must meet to work with the existing accelerators. The sample AMP has been developed to meet these standard rules and they are listed here for reference: -1. The Amp configuration and code must reside under `alfresco/module/com.alfresco.aca.accelerator.extension` to be properly picked up - * Refer to `src/main/config/alfresco/module` in sample SDK project for reference +1. The AMP configuration and code must reside under `alfresco/module/com.alfresco.aca.accelerator.extension` to be properly picked up + * Refer to `src/main/config/alfresco/module` in the sample SDK project for reference 2. Any overrides for ACA properties must reside in a file named `opencontent-extension-override-placeholders.properties` - * Refer to `src/main/config/alfresco/module/com.alfresco.accelerator.extension/opencontent-extension-override-placeholders.properties` in sample SDK project for reference + * Refer to `src/main/config/alfresco/module/com.alfresco.accelerator.extension/opencontent-extension-override-placeholders.properties` in the sample SDK project for reference 3. Any overrides or additions to the ACA bean configurations need to reside in a file named `opencontent-extension-override-config.xml`. **Note:** This file can reference other xml config files but ACA will only specifically look for this file. - * Refer to `src/main/config/alfresco/module/com.alfresco.accelerator.extension/opencontent-extension-override-config.xml` in sample SDK project for reference + * Refer to `src/main/config/alfresco/module/com.alfresco.accelerator.extension/opencontent-extension-override-config.xml` in the sample SDK project for reference 4. Name the module context file for the extension `opencontent-extension-override-module-ctx.xml` - * Refer to `src/main/config/alfresco/module/com.alfresco.accelerator.extension/opencontent-extension-override-module-ctx.xml` in sample SDK project for reference + * Refer to `src/main/config/alfresco/module/com.alfresco.accelerator.extension/opencontent-extension-override-module-ctx.xml` in the sample SDK project for reference -### How to add custom Alfresco models into the Custom Amp +### How to add custom Alfresco models into the Custom AMP To add custom alfresco models you will need to define a bean that has a parent of `dictionaryModelBootstrap` and depends-on `dictionaryBootstrap,com.tsgrp.openContent.dictionaryBootstrap` in the ACA extension accelerators module context file. This bean will need to extend any models that other accelerators would need. For instance, this is what it might look like to add onto the claims or pnp accelerators: @@ -49,60 +49,60 @@ When you add a new document type extension for use in Alfresco Content Accelerat If, however, the `tsg:renditioned` aspect is not desired, or the model already exists and cannot be updated, it is possible to turn on view time renditioning in the [Document Viewer]({% link content-accelerator/latest/configure/admin-guide.md %}#document-viewer) config in the Stage. -Steps to accomplish this in your Custom Amp: +Steps to accomplish this in your Custom AMP: -1. Create a bean to extend `dictionaryModelBootstrap` that points to the xml file for your custom model. (See `alfresco-sdk-aca-sample\sample-platform\src\main\config\alfresco\module\com.alfresco.accelerator.extension\opencontent-extension-override-module-ctx.xml` in sample SDK project for reference) -2. Create a custom model xml and put it in the correct location in the amp code. (See `alfresco-sdk-aca-sample\sample-platform\src\main\config\alfresco\extension\model\sampleModel.xml` in sample SDK project for reference) +1. Create a bean to extend `dictionaryModelBootstrap` that points to the xml file for your custom model. (See `alfresco-sdk-aca-sample\sample-platform\src\main\config\alfresco\module\com.alfresco.accelerator.extension\opencontent-extension-override-module-ctx.xml` in the sample SDK project for reference) +2. Create a custom model xml and put it in the correct location in the AMP code. (See `alfresco-sdk-aca-sample\sample-platform\src\main\config\alfresco\extension\model\sampleModel.xml` in the sample SDK project for reference) -### How to create a custom REST API endpoint in a custom amp +### How to create a custom REST API endpoint in a Custom AMP -To create a custom REST API endpoint in your custom amp, create REST controller and extend `RESTService`. +To create a custom REST API endpoint in your Custom AMP, create REST controller and extend `RESTService`. -Complete the following steps to create the REST controller and extend `RESTService` in your Custom Amp: +Complete the following steps to create the REST controller and extend `RESTService` in your Custom AMP: -1. Define a bean to make this Rest API accessible from ACA in file `opencontent-extension-override-config.xml`. (see `alfresco-sdk-aca-sample/sample-platform/src/main/config/alfresco/module/com.alfresco.accelerator.extension/opencontent-extension-override-config.xml` in sample SDK project for reference) -2. Create a Java class with your new REST endpoint(s). (see `alfresco-sdk-aca-sample/sample-platform/src/main/java/com/tsgrp/opencontent/rest/RESTSample.java` in sample SDK project for reference) +1. Define a bean to make this REST API accessible from ACA in file `opencontent-extension-override-config.xml`. (See `alfresco-sdk-aca-sample/sample-platform/src/main/config/alfresco/module/com.alfresco.accelerator.extension/opencontent-extension-override-config.xml` in the sample SDK project for reference) +2. Create a Java class with your new REST endpoint(s). (See `alfresco-sdk-aca-sample/sample-platform/src/main/java/com/tsgrp/opencontent/rest/RESTSample.java` in the sample SDK project for reference) -### How to add a custom Alfresco behavior in a Custom Amp +### How to add a custom Alfresco behavior in a Custom AMP -To create a custom behavior in your Custom Amp, you will need to create a behaviour class and extend `HPIBehaviorBase`. Define a bean to register this behaviour in file `opencontent-extension-override-module-ctx.xml`. +To create a custom behavior in your Custom AMP, you will need to create a behaviour class and extend `HPIBehaviorBase`. Define a bean to register this behaviour in file `opencontent-extension-override-module-ctx.xml`. To accomplish this, complete the following steps: -1. Define a bean for your behavior. (see `sampleDocumentCreateBehavior` bean in `alfresco-sdk-aca-sample/sample-platform/src/main/config/alfresco/module/com.alfresco.accelerator.extension/opencontent-extension-override-module-ctx.xml`in sample SDK project for reference) -2. Create a custom Alfresco behavior class to write your behavior logic. (see `alfresco-sdk-aca-sample/sample-platform/src/main/java/com/tsgrp/sample/behaviour/SampleDocumentCreateBehavior.java` in sample SDK project for reference) +1. Define a bean for your behavior. (See `sampleDocumentCreateBehavior` bean in `alfresco-sdk-aca-sample/sample-platform/src/main/config/alfresco/module/com.alfresco.accelerator.extension/opencontent-extension-override-module-ctx.xml`in the sample SDK project for reference) +2. Create a custom Alfresco behavior class to write your behavior logic. (See `alfresco-sdk-aca-sample/sample-platform/src/main/java/com/tsgrp/sample/behaviour/SampleDocumentCreateBehavior.java` in the sample SDK project for reference) -### How to override existing OpenContent code in a Custom Amp +### How to override existing OpenContent code in a Custom AMP -To override the existing OpenContent code, create a bean in `opencontent-extension-override-config.xml` with the same id as the bean that points to the OpenContent code that you want to override. In your new bean, refer to a new custom class you will implement in your Amp rather than the class the comes out of the box with OpenContent. Note that this will only work for overriding OpenContent classes that are referenced by a bean in OpenContent's spring configuration. +To override the existing OpenContent code, create a bean in `opencontent-extension-override-config.xml` with the same id as the bean that points to the OpenContent code that you want to override. In your new bean, refer to a new custom class you will implement in your AMP rather than the class the comes out of the box with OpenContent. Note that this will only work for overriding OpenContent classes that are referenced by a bean in OpenContent's spring configuration. -Steps to accomplish this in your Custom Amp (example shows overriding the out-of-the-box Supscription action in ACA): +Steps to accomplish this in your Custom AMP (example shows overriding the out-of-the-box Supscription action in ACA): -1. Create your own custom implementation of the java code you wish to override and give it its own name (see `alfresco-sdk-aca-sample/sample-platform/src/main/java/com/tsgrp/opencontent/action/executer/SampleSubscriptionActionExecuter.java` in sample SDK project for reference) -2. Create a bean in `opencontent-extension-override-config.xml` with the same id as the bean that points to the OpenContent code that you want to override. Set the class on the bean to the new custom class you created in step 1. (see `alfresco-sdk-aca-sample/sample-platform/src/main/config/alfresco/module/com.tsgrp.opencontent/extension/opencontent-extension-override-config.xml` in sample SDK project for reference) +1. Create your own custom implementation of the java code you wish to override and give it its own name (See `alfresco-sdk-aca-sample/sample-platform/src/main/java/com/tsgrp/opencontent/action/executer/SampleSubscriptionActionExecuter.java` in the sample SDK project for reference) +2. Create a bean in `opencontent-extension-override-config.xml` with the same id as the bean that points to the OpenContent code that you want to override. Set the class on the bean to the new custom class you created in step 1. (See `alfresco-sdk-aca-sample/sample-platform/src/main/config/alfresco/module/com.tsgrp.opencontent/extension/opencontent-extension-override-config.xml` in the sample SDK project for reference) -### How create custom overlays in a Custom Amp +### How create custom overlays in a Custom AMP To configure your own custom document overlays (watermarks), create a file named `oc-overlay-config.xml` and configure custom overlays as needed. Refer to [Configuring Overlays]({% link enterprise-viewer/latest/config/overlay.md %}) for more information. This file will override the `oc-overlay-config.xml` configurations that come out-of-the-box with OpenContent. If you wish to keep the exisitng configurations and add your own on top of what is provided, start by copying the `oc-overlay-config.xml` from OpenContent source code and then simply append your configurations to that file rather than starting from scratch. -Steps to accomplish this in your Custom Amp: +Steps to accomplish this in your Custom AMP: -1. Place your custom `oc-overlay-config.xml` file at `platform/src/main/config/alfresco/module/com.alfresco.accelerator.extension/`. (see `alfresco-sdk-aca-sample/sample-platform/src/main/config/alfresco/module/com.alfresco.accelerator.extension/oc-overlay-config.xml` in sample SDK project for reference) -2. Create an `overlayConfigBean` bean that points to your overlay config file from step 1. Also create a bean for `openPdfEngine`. (see `alfresco-sdk-aca-sample\sample-platform\src\main\config\alfresco\module\com.tsgrp.opencontent\opencontent-override-overlay-spring-config.xml` in sample SDK project for reference) +1. Place your custom `oc-overlay-config.xml` file at `platform/src/main/config/alfresco/module/com.alfresco.accelerator.extension/`. (See `alfresco-sdk-aca-sample/sample-platform/src/main/config/alfresco/module/com.alfresco.accelerator.extension/oc-overlay-config.xml` in the sample SDK project for reference) +2. Create an `overlayConfigBean` bean that points to your overlay config file from step 1. Also create a bean for `openPdfEngine`. (See `alfresco-sdk-aca-sample\sample-platform\src\main\config\alfresco\module\com.tsgrp.opencontent\opencontent-override-overlay-spring-config.xml` in the sample SDK project for reference) ## How to deploy Alfresco custom content model in Alfresco Content Accelerator -Once you create a Custom Amp, the next step is to deploy it to an Alfresco container and validate that the Amp is applied correctly. For more information see [Install Alfresco Module Package]({% link content-services/latest/install/zip/amp.md %}). +Once you create a Custom AMP, the next step is to deploy it to an Alfresco container and validate that the AMP is applied correctly. For more information see [Install Alfresco Module Package]({% link content-services/latest/install/zip/amp.md %}). -When the Custom Amp is deployed successfully: +When the Custom AMP is deployed successfully: -* If a default Amp custom model was installed, a `sample_document` is deployed. The custom content type can be found in the **ACA Admin Console**. +* If a default AMP custom model was installed, a `sample_document` is deployed. The custom content type can be found in the **ACA Admin Console**. ![AMP custom model]({% link content-accelerator/images/ACA_amp-custom-model.png %}) * Select the document type and configure the properties as required. * Click **Save Config** at the bottom of the page to save and apply the changes. -* If a default Amp custom aspect was installed, a `sample_aspect` is deployed. It can be added to the **Non-Mandatory Aspect** section in the **ACA Admin Console**. +* If a default AMP custom aspect was installed, a `sample_aspect` is deployed. It can be added to the **Non-Mandatory Aspect** section in the **ACA Admin Console**. ![AMP custom aspect]({% link content-accelerator/images/ACA_amp-custom-aspect.png %}) * Select the aspect and configure the properties as required. * Click **Save Config** at the bottom of the page to save and apply the changes. From aee60bd36986dd271e5cec4c813277b9e77482a9 Mon Sep 17 00:00:00 2001 From: Monika Michalska Date: Tue, 15 Oct 2024 15:50:42 +0200 Subject: [PATCH 3/6] [DOCS-7721] Add information about GitHub repository --- .../latest/develop/extension-content-accelerator.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content-accelerator/latest/develop/extension-content-accelerator.md b/content-accelerator/latest/develop/extension-content-accelerator.md index d2de194a93..d54c9f28d1 100644 --- a/content-accelerator/latest/develop/extension-content-accelerator.md +++ b/content-accelerator/latest/develop/extension-content-accelerator.md @@ -12,7 +12,7 @@ One of the common ways customers and implementation teams extend the out-of-the- This Custom AMP framework can also be thought of as a generic content accelerator for adding custom configurations and code to an existing ACA accelerator. - A sample SDK project has been generated for reference, see `https://github.com/Alfresco/om-content-accelerator-enterprise-viewer`, as a starting point for developing your own Custom AMP. The sample AMP has been developed so that it can be used for the extension of Claims, Policy and Procedure, or Human Resources Employee File Management accelerators. + A sample SDK project has been generated for reference, see `https://github.com/Alfresco/om-content-accelerator-enterprise-viewer`, as a starting point for developing your own Custom AMP. Note that this GitHub repository has restricted access. To access the repository you need to work with the Hyland Services engagement. The sample AMP has been developed so that it can be used for the extension of Claims, Policy and Procedure, or Human Resources Employee File Management accelerators. ## How to develop a Custom AMP for the existing extensions From 061849cd96097d3f631e45a345cc49dc21a7b2e5 Mon Sep 17 00:00:00 2001 From: Adelaide Nxumalo <27953420+anxumalo@users.noreply.github.com> Date: Tue, 15 Oct 2024 18:02:37 +0100 Subject: [PATCH 4/6] [DOCS-7721] UA review - minor fixes --- .../develop/extension-content-accelerator.md | 118 ++++++++++++------ 1 file changed, 79 insertions(+), 39 deletions(-) diff --git a/content-accelerator/latest/develop/extension-content-accelerator.md b/content-accelerator/latest/develop/extension-content-accelerator.md index d54c9f28d1..1f4cfff1d9 100644 --- a/content-accelerator/latest/develop/extension-content-accelerator.md +++ b/content-accelerator/latest/develop/extension-content-accelerator.md @@ -2,34 +2,43 @@ title: Extension Content Accelerator (Custom AMP) --- -One of the common ways customers and implementation teams extend the out-of-the-box ACA functionality is by using what we refer to as a "Custom AMP". This is essentially a way to use the Alfresco SDK to generate an Alfresco AMP file that can be deployed to Alfresco Content Services for the following functionalities: +One of the common ways customers and implementation teams extend the out-of-the-box ACA functionality is by using what we refer to as a "Custom AMP". This is essentially a way to use the Alfresco SDK to generate an Alfresco AMP file that can be deployed to Alfresco Content Services for the following functionalities: -* Deploy custom content models +* Deploy custom content models * Create custom REST endpoints -* Add custom Alfresco behaviors -* Override existing OpenContent code -* Create custom document overlays/watermarks +* Add custom Alfresco behaviors +* Override existing OpenContent code +* Create custom document overlays/watermarks This Custom AMP framework can also be thought of as a generic content accelerator for adding custom configurations and code to an existing ACA accelerator. - A sample SDK project has been generated for reference, see `https://github.com/Alfresco/om-content-accelerator-enterprise-viewer`, as a starting point for developing your own Custom AMP. Note that this GitHub repository has restricted access. To access the repository you need to work with the Hyland Services engagement. The sample AMP has been developed so that it can be used for the extension of Claims, Policy and Procedure, or Human Resources Employee File Management accelerators. +A sample SDK project has been generated for reference, see `https://github.com/Alfresco/om-content-accelerator-enterprise-viewer`, as a starting point for developing your own Custom AMP. Note that this GitHub repository has restricted access. To access the repository you need to work with the Hyland Services engagement. The sample AMP has been developed so that it can be used for the extension of Claims, Policy and Procedure (PnP), or Human Resources Employee File Management accelerators. ## How to develop a Custom AMP for the existing extensions There are a few requirements that your Custom AMP must meet to work with the existing accelerators. The sample AMP has been developed to meet these standard rules and they are listed here for reference: -1. The AMP configuration and code must reside under `alfresco/module/com.alfresco.aca.accelerator.extension` to be properly picked up - * Refer to `src/main/config/alfresco/module` in the sample SDK project for reference -2. Any overrides for ACA properties must reside in a file named `opencontent-extension-override-placeholders.properties` - * Refer to `src/main/config/alfresco/module/com.alfresco.accelerator.extension/opencontent-extension-override-placeholders.properties` in the sample SDK project for reference -3. Any overrides or additions to the ACA bean configurations need to reside in a file named `opencontent-extension-override-config.xml`. **Note:** This file can reference other xml config files but ACA will only specifically look for this file. - * Refer to `src/main/config/alfresco/module/com.alfresco.accelerator.extension/opencontent-extension-override-config.xml` in the sample SDK project for reference -4. Name the module context file for the extension `opencontent-extension-override-module-ctx.xml` - * Refer to `src/main/config/alfresco/module/com.alfresco.accelerator.extension/opencontent-extension-override-module-ctx.xml` in the sample SDK project for reference +1. The AMP configuration and code must reside under `alfresco/module/com.alfresco.aca.accelerator.extension` to be properly picked up. + + Refer to `src/main/config/alfresco/module` in the sample SDK project for reference. + +2. Any overrides for ACA properties must reside in a file named `opencontent-extension-override-placeholders.properties`. + + Refer to `src/main/config/alfresco/module/com.alfresco.accelerator.extension/opencontent-extension-override-placeholders.properties` in the sample SDK project for reference. + +3. Any overrides or additions to the ACA bean configurations need to reside in a file named `opencontent-extension-override-config.xml`. + + > **Note:** This file can reference other XML config files but ACA will only specifically look for this file. + + Refer to `src/main/config/alfresco/module/com.alfresco.accelerator.extension/opencontent-extension-override-config.xml` in the sample SDK project for reference. + +4. Name the module context file for the extension `opencontent-extension-override-module-ctx.xml`. + + Refer to `src/main/config/alfresco/module/com.alfresco.accelerator.extension/opencontent-extension-override-module-ctx.xml` in the sample SDK project for reference. ### How to add custom Alfresco models into the Custom AMP -To add custom alfresco models you will need to define a bean that has a parent of `dictionaryModelBootstrap` and depends-on `dictionaryBootstrap,com.tsgrp.openContent.dictionaryBootstrap` in the ACA extension accelerators module context file. This bean will need to extend any models that other accelerators would need. For instance, this is what it might look like to add onto the claims or pnp accelerators: +To add custom alfresco models you will need to define a bean that has a parent of `dictionaryModelBootstrap` and depends-on `dictionaryBootstrap,com.tsgrp.openContent.dictionaryBootstrap` in the ACA extension accelerators module context file. This bean will need to extend any models that other accelerators would need. For instance, this is what it might look like to add onto the Claims or PnP accelerators: ```xml @@ -40,6 +49,7 @@ To add custom alfresco models you will need to define a bean that has a parent o ``` + When you add a new document type extension for use in Alfresco Content Accelerator, we recommend including the `tsg:renditioned` mandatory aspect. This aspect provides streamlined handling of PDFs renditions for viewing and includes: * Immediate renditioning to PDF upon document upload or version @@ -51,46 +61,71 @@ If, however, the `tsg:renditioned` aspect is not desired, or the model already e Steps to accomplish this in your Custom AMP: -1. Create a bean to extend `dictionaryModelBootstrap` that points to the xml file for your custom model. (See `alfresco-sdk-aca-sample\sample-platform\src\main\config\alfresco\module\com.alfresco.accelerator.extension\opencontent-extension-override-module-ctx.xml` in the sample SDK project for reference) -2. Create a custom model xml and put it in the correct location in the AMP code. (See `alfresco-sdk-aca-sample\sample-platform\src\main\config\alfresco\extension\model\sampleModel.xml` in the sample SDK project for reference) +1. Create a bean to extend `dictionaryModelBootstrap` that points to the xml file for your custom model. + + See `alfresco-sdk-aca-sample/sample-platform/src/main/config/alfresco/module/com.alfresco.accelerator.extension/opencontent-extension-override-module-ctx.xml` in the sample SDK project for reference. + +2. Create a custom model xml and put it in the correct location in the AMP code. + + See `alfresco-sdk-aca-sample/sample-platform/src/main/config/alfresco/extension/model/sampleModel.xml` in the sample SDK project for reference. ### How to create a custom REST API endpoint in a Custom AMP -To create a custom REST API endpoint in your Custom AMP, create REST controller and extend `RESTService`. +To create a custom REST API endpoint in your Custom AMP, create REST controller and extend `RESTService`. Complete the following steps to create the REST controller and extend `RESTService` in your Custom AMP: -1. Define a bean to make this REST API accessible from ACA in file `opencontent-extension-override-config.xml`. (See `alfresco-sdk-aca-sample/sample-platform/src/main/config/alfresco/module/com.alfresco.accelerator.extension/opencontent-extension-override-config.xml` in the sample SDK project for reference) -2. Create a Java class with your new REST endpoint(s). (See `alfresco-sdk-aca-sample/sample-platform/src/main/java/com/tsgrp/opencontent/rest/RESTSample.java` in the sample SDK project for reference) +1. Define a bean to make this REST API accessible from ACA in file `opencontent-extension-override-config.xml`. + + See `alfresco-sdk-aca-sample/sample-platform/src/main/config/alfresco/module/com.alfresco.accelerator.extension/opencontent-extension-override-config.xml` in the sample SDK project for reference. + +2. Create a Java class with your new REST endpoint(s). + + See `alfresco-sdk-aca-sample/sample-platform/src/main/java/com/tsgrp/opencontent/rest/RESTSample.java` in the sample SDK project for reference. ### How to add a custom Alfresco behavior in a Custom AMP -To create a custom behavior in your Custom AMP, you will need to create a behaviour class and extend `HPIBehaviorBase`. Define a bean to register this behaviour in file `opencontent-extension-override-module-ctx.xml`. +To create a custom behavior in your Custom AMP, you will need to create a behavior class and extend `HPIBehaviorBase`. Define a bean to register this behavior in file `opencontent-extension-override-module-ctx.xml`. To accomplish this, complete the following steps: -1. Define a bean for your behavior. (See `sampleDocumentCreateBehavior` bean in `alfresco-sdk-aca-sample/sample-platform/src/main/config/alfresco/module/com.alfresco.accelerator.extension/opencontent-extension-override-module-ctx.xml`in the sample SDK project for reference) -2. Create a custom Alfresco behavior class to write your behavior logic. (See `alfresco-sdk-aca-sample/sample-platform/src/main/java/com/tsgrp/sample/behaviour/SampleDocumentCreateBehavior.java` in the sample SDK project for reference) +1. Define a bean for your behavior. + + See `sampleDocumentCreateBehavior` bean in `alfresco-sdk-aca-sample/sample-platform/src/main/config/alfresco/module/com.alfresco.accelerator.extension/opencontent-extension-override-module-ctx.xml`in the sample SDK project for reference. + +2. Create a custom Alfresco behavior class to write your behavior logic. + + See `alfresco-sdk-aca-sample/sample-platform/src/main/java/com/tsgrp/sample/behaviour/SampleDocumentCreateBehavior.java` in the sample SDK project for reference. ### How to override existing OpenContent code in a Custom AMP -To override the existing OpenContent code, create a bean in `opencontent-extension-override-config.xml` with the same id as the bean that points to the OpenContent code that you want to override. In your new bean, refer to a new custom class you will implement in your AMP rather than the class the comes out of the box with OpenContent. Note that this will only work for overriding OpenContent classes that are referenced by a bean in OpenContent's spring configuration. +To override the existing OpenContent code, create a bean in `opencontent-extension-override-config.xml` with the same id as the bean that points to the OpenContent code that you want to override. In your new bean, refer to a new custom class you will implement in your AMP rather than the class the comes out of the box with OpenContent. Note that this will only work for overriding OpenContent classes that are referenced by a bean in OpenContent's spring configuration. Steps to accomplish this in your Custom AMP (example shows overriding the out-of-the-box Supscription action in ACA): -1. Create your own custom implementation of the java code you wish to override and give it its own name (See `alfresco-sdk-aca-sample/sample-platform/src/main/java/com/tsgrp/opencontent/action/executer/SampleSubscriptionActionExecuter.java` in the sample SDK project for reference) -2. Create a bean in `opencontent-extension-override-config.xml` with the same id as the bean that points to the OpenContent code that you want to override. Set the class on the bean to the new custom class you created in step 1. (See `alfresco-sdk-aca-sample/sample-platform/src/main/config/alfresco/module/com.tsgrp.opencontent/extension/opencontent-extension-override-config.xml` in the sample SDK project for reference) +1. Create your own custom implementation of the java code you wish to override and give it its own name. + + See `alfresco-sdk-aca-sample/sample-platform/src/main/java/com/tsgrp/opencontent/action/executer/SampleSubscriptionActionExecuter.java` in the sample SDK project for reference. + +2. Create a bean in `opencontent-extension-override-config.xml` with the same id as the bean that points to the OpenContent code that you want to override. Set the class on the bean to the new custom class you created in step 1. + + See `alfresco-sdk-aca-sample/sample-platform/src/main/config/alfresco/module/com.tsgrp.opencontent/extension/opencontent-extension-override-config.xml` in the sample SDK project for reference. ### How create custom overlays in a Custom AMP -To configure your own custom document overlays (watermarks), create a file named `oc-overlay-config.xml` and configure custom overlays as needed. Refer to [Configuring Overlays]({% link enterprise-viewer/latest/config/overlay.md %}) for more information. +To configure your own custom document overlays (watermarks), create a file named `oc-overlay-config.xml` and configure custom overlays as needed. Refer to [Configuring Overlays]({% link enterprise-viewer/latest/config/overlay.md %}) for more information. -This file will override the `oc-overlay-config.xml` configurations that come out-of-the-box with OpenContent. If you wish to keep the exisitng configurations and add your own on top of what is provided, start by copying the `oc-overlay-config.xml` from OpenContent source code and then simply append your configurations to that file rather than starting from scratch. +This file will override the `oc-overlay-config.xml` configurations that come out-of-the-box with OpenContent. If you wish to keep the existing configurations and add your own on top of what is provided, start by copying the `oc-overlay-config.xml` from OpenContent source code and then simply append your configurations to that file rather than starting from scratch. Steps to accomplish this in your Custom AMP: -1. Place your custom `oc-overlay-config.xml` file at `platform/src/main/config/alfresco/module/com.alfresco.accelerator.extension/`. (See `alfresco-sdk-aca-sample/sample-platform/src/main/config/alfresco/module/com.alfresco.accelerator.extension/oc-overlay-config.xml` in the sample SDK project for reference) -2. Create an `overlayConfigBean` bean that points to your overlay config file from step 1. Also create a bean for `openPdfEngine`. (See `alfresco-sdk-aca-sample\sample-platform\src\main\config\alfresco\module\com.tsgrp.opencontent\opencontent-override-overlay-spring-config.xml` in the sample SDK project for reference) +1. Place your custom `oc-overlay-config.xml` file at `platform/src/main/config/alfresco/module/com.alfresco.accelerator.extension/`. + + See `alfresco-sdk-aca-sample/sample-platform/src/main/config/alfresco/module/com.alfresco.accelerator.extension/oc-overlay-config.xml` in the sample SDK project for reference. + +2. Create an `overlayConfigBean` bean that points to your overlay config file from step 1. Also create a bean for `openPdfEngine`. + + See `alfresco-sdk-aca-sample/sample-platform/src/main/config/alfresco/module/com.tsgrp.opencontent/opencontent-override-overlay-spring-config.xml` in the sample SDK project for reference. ## How to deploy Alfresco custom content model in Alfresco Content Accelerator @@ -98,13 +133,18 @@ Once you create a Custom AMP, the next step is to deploy it to an Alfresco conta When the Custom AMP is deployed successfully: -* If a default AMP custom model was installed, a `sample_document` is deployed. The custom content type can be found in the **ACA Admin Console**. -![AMP custom model]({% link content-accelerator/images/ACA_amp-custom-model.png %}) - * Select the document type and configure the properties as required. - * Click **Save Config** at the bottom of the page to save and apply the changes. -* If a default AMP custom aspect was installed, a `sample_aspect` is deployed. It can be added to the **Non-Mandatory Aspect** section in the **ACA Admin Console**. -![AMP custom aspect]({% link content-accelerator/images/ACA_amp-custom-aspect.png %}) - * Select the aspect and configure the properties as required. - * Click **Save Config** at the bottom of the page to save and apply the changes. +* If a default AMP custom model was installed, a `sample_document` is deployed. The custom content type can be found in the **ACA Admin Console**: + + ![AMP custom model]({% link content-accelerator/images/ACA_amp-custom-model.png %}) + + * Select the document type and configure the properties as required. + * Click **Save Config** at the bottom of the page to save and apply the changes. + +* If a default AMP custom aspect was installed, a `sample_aspect` is deployed. It can be added to the **Non-Mandatory Aspect** section in the **ACA Admin Console**: + + ![AMP custom aspect]({% link content-accelerator/images/ACA_amp-custom-aspect.png %}) + + * Select the aspect and configure the properties as required. + * Click **Save Config** at the bottom of the page to save and apply the changes. -The newly created Object Type and Non-Mandatory Aspect can be used to create new forms in ACA. For more information see [Admin Guide]({% link content-accelerator/latest/configure/admin-guide.md %}). \ No newline at end of file +The newly created Object Type and Non-Mandatory Aspect can be used to create new forms in ACA. For more information see [Admin Guide]({% link content-accelerator/latest/configure/admin-guide.md %}). From 8dfdfb3460997bf15192abdfce36fcbfc4169731 Mon Sep 17 00:00:00 2001 From: Adelaide Nxumalo <27953420+anxumalo@users.noreply.github.com> Date: Tue, 15 Oct 2024 18:14:55 +0100 Subject: [PATCH 5/6] [DOCS-7721] UA review - minor fixes --- .../latest/develop/extension-content-accelerator.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content-accelerator/latest/develop/extension-content-accelerator.md b/content-accelerator/latest/develop/extension-content-accelerator.md index 1f4cfff1d9..d54a5f9131 100644 --- a/content-accelerator/latest/develop/extension-content-accelerator.md +++ b/content-accelerator/latest/develop/extension-content-accelerator.md @@ -59,7 +59,7 @@ When you add a new document type extension for use in Alfresco Content Accelerat If, however, the `tsg:renditioned` aspect is not desired, or the model already exists and cannot be updated, it is possible to turn on view time renditioning in the [Document Viewer]({% link content-accelerator/latest/configure/admin-guide.md %}#document-viewer) config in the Stage. -Steps to accomplish this in your Custom AMP: +Complete the following steps to accomplish this in your Custom AMP: 1. Create a bean to extend `dictionaryModelBootstrap` that points to the xml file for your custom model. @@ -101,7 +101,7 @@ To accomplish this, complete the following steps: To override the existing OpenContent code, create a bean in `opencontent-extension-override-config.xml` with the same id as the bean that points to the OpenContent code that you want to override. In your new bean, refer to a new custom class you will implement in your AMP rather than the class the comes out of the box with OpenContent. Note that this will only work for overriding OpenContent classes that are referenced by a bean in OpenContent's spring configuration. -Steps to accomplish this in your Custom AMP (example shows overriding the out-of-the-box Supscription action in ACA): +Complete the following steps to accomplish this in your Custom AMP. The example shows overriding the out-of-the-box Subscription action in ACA: 1. Create your own custom implementation of the java code you wish to override and give it its own name. @@ -117,7 +117,7 @@ To configure your own custom document overlays (watermarks), create a file named This file will override the `oc-overlay-config.xml` configurations that come out-of-the-box with OpenContent. If you wish to keep the existing configurations and add your own on top of what is provided, start by copying the `oc-overlay-config.xml` from OpenContent source code and then simply append your configurations to that file rather than starting from scratch. -Steps to accomplish this in your Custom AMP: +Complete the following steps to accomplish this in your Custom AMP: 1. Place your custom `oc-overlay-config.xml` file at `platform/src/main/config/alfresco/module/com.alfresco.accelerator.extension/`. From a7d0fe032c9cb25ff1cb071572e37fa53736ae48 Mon Sep 17 00:00:00 2001 From: Monika Michalska <153922997+monikamichalska@users.noreply.github.com> Date: Wed, 16 Oct 2024 12:02:02 +0200 Subject: [PATCH 6/6] [DOCS-7721] Minor UA fix --- .../latest/develop/extension-content-accelerator.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content-accelerator/latest/develop/extension-content-accelerator.md b/content-accelerator/latest/develop/extension-content-accelerator.md index d54a5f9131..5510833cdc 100644 --- a/content-accelerator/latest/develop/extension-content-accelerator.md +++ b/content-accelerator/latest/develop/extension-content-accelerator.md @@ -111,7 +111,7 @@ Complete the following steps to accomplish this in your Custom AMP. The example See `alfresco-sdk-aca-sample/sample-platform/src/main/config/alfresco/module/com.tsgrp.opencontent/extension/opencontent-extension-override-config.xml` in the sample SDK project for reference. -### How create custom overlays in a Custom AMP +### How to create custom overlays in a Custom AMP To configure your own custom document overlays (watermarks), create a file named `oc-overlay-config.xml` and configure custom overlays as needed. Refer to [Configuring Overlays]({% link enterprise-viewer/latest/config/overlay.md %}) for more information.