diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md index 831c9b5e35..818adbef2d 100644 --- a/docs/tutorials/README.md +++ b/docs/tutorials/README.md @@ -19,3 +19,4 @@ Github only: true | [**Working with the Nodes API Service**](working-with-nodes-api-service.md) | Intermediate | In this tutorial you will learn how to use the [`NodesApiService`](../core/services/nodes-api.service.md). | | [**Working with Nodes using the JS API**](working-with-nodes-js-api.md) | Intermediate | In this tutorial you will learn how to use the [`AlfrescoCoreRestApi`](https://github.com/Alfresco/alfresco-js-api/tree/master/src/alfresco-core-rest-api). | | [**Content metadata component**](content-metadata-component.md) | Advanced | In this tutorial you will learn how to work with the [`ContentMetadataComponent`](../content-services/components/content-metadata-card.component.md). | +| [**Building an ADF application on top of Activiti Cloud 7.0.0 GA Community Edition**](activiti-7-and-adf.md) | Intermediate | This tutorial shows how to configure an ADF app to connect to Activiti Cloud 7. | diff --git a/docs/tutorials/activiti-7-and-adf.md b/docs/tutorials/activiti-7-and-adf.md new file mode 100644 index 0000000000..9794a2cc02 --- /dev/null +++ b/docs/tutorials/activiti-7-and-adf.md @@ -0,0 +1,99 @@ +--- +Title: Activiti 7 and ADF +Level: Intermediate +--- + +# Building an ADF application on top of Activiti Cloud 7.0.0 GA Community Edition + +This tutorial shows how to configure an ADF app to connect to Activiti Cloud 7. + +[Activiti Cloud 7](https://www.activiti.org/) is the new generation cloud-native implementation +of Activiti BPM Engine. Starting with the +[ADF 3 major release](../release-notes/relnote300.md#activiti-7-support-experimental), +Alfresco began to support the Activiti 7 Engine within the ADF framework. We have nearly +finished implementing all the required features, and so in this tutorial we will explain how +to build an ADF application on top of Activiti Cloud 7.0.0 GA Community Edition. + +## Preparing Activiti 7 services + +As you can imagine, a prerequisite to create an ADF app like this is to have an instance of +Activiti 7 up and running. To learn how to install and setup your own +Activiti 7 instance, please follow the +[official documentation]([https://activiti.gitbook.io/activiti-7-developers-guide). + +Assuming that you already have your own instance of Activiti 7 up and running, a small tweak is required to make it work correctly with an ADF application. This is mainly a matter of how +the application is named, as described in detail below. + +### What ADF requires from Activiti 7 backend services + +By default, Activiti 7 starts a known list of services +(which are Kubernetes [pods](https://kubernetes.io/docs/concepts/workloads/pods/pod/)) +for each application. Specifically, these include the runtime bundle, connectors, audit, and +query among others. Our interest here is the runtime bundle service, which is directly used +by all ADF applications. + +The runtime bundle service pod (generated by the default installation) has the name +`rb-[appName]` (usually `rb-my-app`) to begin with. An ADF application requires the runtime +bundle service to be available with the name `[appName]-rb` (usually `my-app-rb`). + +### How to change the name of the runtime bundle service + +You can change the default name of the runtime bundle easily using the +[helm charts](https://github.com/Activiti/activiti-cloud-charts). If you used the +[quick-start guide](https://activiti.gitbook.io/activiti-7-developers-guide/getting-started/getting-started-activiti-cloud) (deploying the "Activiti Cloud Full Example") you can change the +[values.yaml](https://github.com/Activiti/activiti-cloud-charts/blob/master/activiti-cloud-full-example/values.yaml) +file as shown below: + +```yaml + application: + runtime-bundle: + enabled: true + service: + name: my-app-rb \\ <-- change it here! + ... +``` + +When this is done, clean up your deployment environment (delete the pods and everything needed +to create a fresh environment, ready to be deployed again) and deploy Activiti 7 again, using +the modified helm chart. + +When Activiti 7 is up and running again, you will be then ready to build your own Alfresco ADF application on top of it. + +## Building the ADF application + +You can create an ADF application easily using the [Yeoman generator](https://yeoman.io/). +See our [tutorial](creating-the-app-using-yeoman.md) for a full description of +how to do this. Make sure you select "Process Services with Activiti" as the type of project +to create. + +Once this is created, do not change the `proxy.conf.json` file, but continue with the configuration as described in the following paragraph. You are now very close to the goal of having your own ADF +application working against Activiti 7 Community Edition backend services. + +## Configuring the ADF application + +To configure your existing ADF application, you just need to edit the `app.config.json` file. + +First of all, be sure you set up the `bpmHost`, `identityHost` and `host` properties with the +correct URL of the Activiti 7 deployment. It should look something like the example below: + +```json + ... + "bpmHost": "", + "identityHost": "/auth/realms/alfresco", + "providers": "BPM", + "application": { + "name": "Alfresco ADF Application" + }, + "authType": "OAUTH", + "oauth2": { + "host": "/auth/realms/alfresco", + ... +``` + +Then, set the `alfresco-deployed-apps` property as shown below. + + "alfresco-deployed-apps": [{"name":"my-app"}] + +When you are done, save the `app.config.json` file and launch the application by executing +the `npm start` command. You should now be able to use your own ADF application +on top of Activiti 7 Community Edition backend services. diff --git a/docs/user-guide/summary.json b/docs/user-guide/summary.json index c9f0e69a7a..d7cdc7c546 100644 --- a/docs/user-guide/summary.json +++ b/docs/user-guide/summary.json @@ -19,7 +19,8 @@ { "title": "Working with a DataTable", "file": "working-with-data-table.md"}, { "title": "Working with the Nodes API Service", "file": "working-with-nodes-api-service.md"}, { "title": "Working with the Nodes using the JS API", "file": "working-with-nodes-js-api.md"}, - { "title": "Content metadata component", "file": "content-metadata-component.md"} + { "title": "Content metadata component", "file": "content-metadata-component.md"}, + { "title": "Activiti 7 and ADF", "file": "activiti-7-and-adf.md" } ] } ]