Extending the Alfresco Digital Workspace (ADW)

[angelborroy]

Alfresco provides two different UI applications based in Angular:

• Alfresco Content Application (ACA) is the application for Community users
• Alfresco Digital Workspace (ADW) is the application for Enterprise users

Both applications are built on top of the Alfresco Development Framework (ADF) that includes a set of Angular components consuming information from Alfresco Repository using the REST API.

We covered in previous articles the extension mechanism for ACA, this blog post is focused on creating extensions for the ADW application (that is only available for partners and Enterprise customers).

Obtaining ADW source code

ADW source code is available in Alfresco Nexus website. Since this is an Enterprise product, you need Alfresco credentials to access to this artifact. Contact with Alfresco Support to get yours.

Source code for ADW 2.8.0 is available in

https://nexus.alfresco.com/nexus/service/local/repositories/enterprise-releases/content/org/alfresco...

Running ADW

Before running ADW locally, deploy a local Alfresco Repository available in http://localhost:8080

Verify dependencies are available on your development environment.

$ node -v
v16.15.1
$ npm -v
8.11.0
$ git --version
git version 2.35.1

From the source code folder, once the ZIP has been uncompressed, create the environment file .env with the follow settings.

$ cat .env
ACA_BRANCH="2.10.0"
BASE_URL="http://localhost:8080"
APP_CONFIG_ECM_HOST="http://localhost:8080"
APP_CONFIG_PROVIDER="ECM"
APP_CONFIG_AUTH_TYPE="BASIC"
APP_CONFIG_PLUGIN_AOS=false
APP_CONFIG_PLUGIN_CONTENT_SERVICE=true
APP_CONFIG_PLUGIN_PROCESS_SERVICE=false
APP_CONFIG_PLUGIN_AI_SERVICE=false

Note that ADW 2.8.0 is using ACA 2.10.0, but you can verify required ACA version for your ADW version.

ADW   | ACA
2.0.0 | 2.2.0
2.1.0 | 2.3.0
2.2.0 | 2.4.0
2.3.0 | 2.5.0
2.4.0 | 2.6.0
2.5.0 | 2.7.0
2.6.0 | 2.8.0
2.8.0 | 2.10.0

This is a minimal configuration, but there are additional environment availables than can be used in this .env file.

# App config settings
APP_CONFIG_BPM_HOST="<url>"
APP_CONFIG_ECM_HOST="<url>"
APP_CONFIG_OAUTH2_HOST="<url>"
APP_CONFIG_IDENTITY_HOST="<url>"
APP_CONFIG_PROVIDER="ALL"
APP_CONFIG_AUTH_TYPE="OAUTH"
APP_CONFIG_OAUTH2_CLIENTID="alfresco"
APP_CONFIG_OAUTH2_IMPLICIT_FLOW=true
APP_CONFIG_OAUTH2_SILENT_LOGIN=true
APP_CONFIG_OAUTH2_REDIRECT_SILENT_IFRAME_URI="{protocol}//{hostname}{:port}/assets/silent-refresh.html"
APP_CONFIG_OAUTH2_REDIRECT_LOGIN=/
APP_CONFIG_OAUTH2_REDIRECT_LOGOUT=/
APP_CONFIG_APPS_DEPLOYED="[{"name": "simpleapp"}]"
APP_CONFIG_LANDING_PAGE="/personal-files"

# CONTENT RELATED
ACA_BRANCH="develop"
APP_CONFIG_PLUGIN_PROCESS_SERVICE=true
APP_CONFIG_PLUGIN_AI_SERVICE=true
APP_CONFIG_PLUGIN_AOS=true
APP_CONFIG_PLUGIN_CONTENT_SERVICE=true
APP_CONFIG_CUSTOM_MODELED_EXTENSION = "{}"

# CONTENT - MICROSOT PLUGIN RELATED
APP_CONFIG_PLUGIN_MICROSOFT_ONLINE=true
APP_CONFIG_MICROSOFT_ONLINE_OOI_URL="<url>"
APP_CONFIG_MICROSOFT_ONLINE_CLIENTID="<clientid>"
APP_CONFIG_MICROSOFT_ONLINE_AUTHORITY="<url>"
APP_CONFIG_MICROSOFT_ONLINE_REDIRECT="<url>"

# CONTENT - MICROSOT INTEGRATION TEST RELATED
MICROSOFT_USER_INITIALS="<user-initials>"
MICROSOFT_EMAIL="<email>"
MICROSOFT_USER2_INITIALS="<user-initials>"
MICROSOFT_EMAIL2="<email>"
MICROSOFT_PASSWORD="<password>"
MOO_LOGIN_URL="<url>"

Install dependencies using following command.

$ npm ci

Once every is installed, ADW application can be started as "content-ee" application.

$ npm start content-ee

Application will be available in default port http://localhost:4200

Extending ADW

ADW is using the NX framework as building system with first class monorepo support, so installing Nx CLI globally is recommended.

$ npm install -g nx

Create my-extension Angular library using following command.

$ nx g @nrwl/angular:lib my-extension
UPDATE angular.json
CREATE libs/my-extension/README.md
CREATE libs/my-extension/tsconfig.lib.json
CREATE libs/my-extension/tsconfig.spec.json
CREATE libs/my-extension/tslint.json
CREATE libs/my-extension/src/index.ts
CREATE libs/my-extension/src/lib/my-extension.module.ts
UPDATE nx.json
CREATE libs/extension/tsconfig.json
UPDATE tsconfig.base.json
CREATE libs/my-extension/jest.config.js
CREATE libs/my-extension/src/test-setup.ts
UPDATE jest.config.js
CREATE libs/my-extension/.eslintrc.json

Modify the module declaration available in libs/my-extension/src/lib/my-extension.module.ts to add ADF Extension mechanism.

// Add the following import to the page.
import { provideExtensionConfig } from '@alfresco/adf-extensions';

// Add providers as described below.
NgModule({
  imports: [CommonModule],
  providers: [
    provideExtensionConfig(['my-extension.json'])
  ]
})
export class MyExtensionModule {}

Create the extension declaration file libs/my-extension/assets/my-extension.json to describe the part of the ADW application to be extended.

{
  "$version": "1.0.0",
  "$id": "my.extension",
  "$name": "my adf extension",
  "$description": "my adf extension",
  "$license": "Apache-2.0",
  "actions": [],
  "features": {
    "create": [
      {
        "id": "my.extension.hello.world",
        "title": "BYE BYE WORLD! (Logout)",
        "order": 50,
        "actions": {
          "click": "LOGOUT"
        }
      }
    ]
  },
  "routes": [],
  "rules": []
}

In this case, we're adding a new option for the Create button.

Import the module in the ADW extensions file apps/content-ee/src/app/extensions.module.ts

// Add the following import to the page.
import { MyExtensionModule } from '@alfresco-dbp/my-extension';

@NgModule({
    imports: [
        ...,
        MyExtensionModule,
    ],
})
export class AppExtensionsModule {}

Add the extension assets into angular.json file for the content-ee section

{
  "input": "libs/my-extension/assets",
  "output": "/assets/plugins/",
  "glob": "my-extension.json"
}

Start again ADW to verify the changes have been applied to the application

$ npm start content-ee

Video recording

Additional details can be found in the video tutorial available below.