- Introduction
- Source Code and Tools
- Installation and Configuration
- Install software needed for Alfresco Project Generator
- Install APS ReST API Java Client
- Install ACS ReST API Java Client
- Generating an Alfresco Extension Project
- Implementing an ACS Content Model
- Implementing a Review and Approve Contract Process in APS
- Implementing the APS Set Contract Type Service Task
- Implementing the ACS Rule/Policy to start the Review & Approve Process
- Testing the Solution with Alfresco Share and Activiti App
- Implementing a User Interface for the solution with ADF
- Prerequisites
- Verify Node.js version
- Verify that the same username and password exist in both APS and ACS
- Generate the UI Client Project
- Implementing a form to view Contract File Metadata
- Generating a new document details page and setting up routing
- Creating and exporting a cm:content metadata form from APS
- Implementing the Document Details page template
- Implementing the Document Details page component class
- Adding the Document Details content action to the Document List page
- Creating and exporting an acme:contract metadata form from APS
- Testing the Solution with the ADF Application
- Debugging
- Hot Reloading
Introduction
In this article we will have a look at how you can build a content and process solution on top of the Alfresco Content Services (ACS) 6.0 and Alfresco Process Services (APS) 1.9 components of the Alfresco Digital Business Platform (DBP). The user interface will be built with the Alfresco Application Development Framework (ADF) version 2.6.
We will work in a Docker container environment as the ACS 6.0 application is provided as a number of Docker images. APS is also available as a Docker image.
We will implement a content model so we can see how files can be classified according to a specific domain and we will implement a simple review and approve workflow that we can apply to the files. But most importantly we will have a look at how ACS and APS can be integrated to achieve a complete solution. More specifically, we will start APS processes from ACS and we will apply ACS metadata from APS:
.png)
To talk to APS from ACS we will use a Java Client that wraps the APS ReST API. Likewise, to talk to ACS from APS we will use a Java Client that wraps the ACS ReST API. Finally, we will develop a user interface with ADF that will be used to drive the workflow and view metadata etc.
Source Code and Tools
You can find the source code for this article here. The Alfresco Project generator can be found here. The ReST API Java clients can be found here (ACS) and here (APS).
Installation and Configuration
As you can imagine, we need to set up quite a few things before we can start to develop this solution. We need a development environment, runtime environment, Java Clients for ReST APIs, IDEs etc.
Install software needed for Alfresco Project Generator
We will be using a code generator to quickly generate the Alfresco extension projects that we need when building the customisations and it will also provide the runtime environment that is required for testing those extensions.
So, to get started with setting up the environment follow these instructions. If you are not that familiar with Docker have a quick read though here.
You should now have Java, Maven, Docker, Yeoman, and Alfresco Code Generator installed.
Install APS ReST API Java Client
Before you can build a Repository extension with support for APS remote calls you need to clone, compile, and package the APS ReST API Java client:
$ git clone https://github.com/gravitonian/aps-rest-api-java-client
$ cd aps-rest-api-java-client/
aps-rest-api-java-client mbergljung$ mvn clean install
Make sure you got the project available in your local Maven Repository:
$ ls -l ~/.m2/repository/org/activiti/aps-rest-api-java-client/1.0.0-SNAPSHOT/
total 7184
-rw-r--r-- 1 mbergljung staff 385 27 Sep 11:13 _remote.repositories
-rw-r--r-- 1 mbergljung staff 1726618 27 Sep 11:13 aps-rest-api-java-client-1.0.0-SNAPSHOT-javadoc.jar
-rw-r--r-- 1 mbergljung staff 390438 27 Sep 11:13 aps-rest-api-java-client-1.0.0-SNAPSHOT-sources.jar
-rw-r--r-- 1 mbergljung staff 48381 27 Sep 11:13 aps-rest-api-java-client-1.0.0-SNAPSHOT-tests.jar
-rw-r--r-- 1 mbergljung staff 1472825 27 Sep 11:13 aps-rest-api-java-client-1.0.0-SNAPSHOT.jar
-rw-r--r-- 1 mbergljung staff 829 27 Sep 10:56 aps-rest-api-java-client-1.0.0-SNAPSHOT.jar.lastUpdated
-rw-r--r-- 1 mbergljung staff 9463 26 Sep 11:35 aps-rest-api-java-client-1.0.0-SNAPSHOT.pom
-rw-r--r-- 1 mbergljung staff 829 27 Sep 10:56 aps-rest-api-java-client-1.0.0-SNAPSHOT.pom.lastUpdated
-rw-r--r-- 1 mbergljung staff 1335 27 Sep 11:13 maven-metadata-local.xml
-rw-r--r-- 1 mbergljung staff 613 29 Sep 08:47 resolver-status.properties
Install ACS ReST API Java Client
Before you can build an Activiti extension with support for ACS remote calls you need to clone, compile, and package the ACS ReST API Java client:
$ git clone https://github.com/gravitonian/acs-rest-api-java-client
$ cd acs-rest-api-java-client/
acs-rest-api-java-client mbergljung$ mvn clean install
Make sure you got the project available in your local Maven Repository:
$ ls -l ~/.m2/repository/org/alfresco/acs-rest-api-java-client/1.0.0-SNAPSHOT/
total 5504
-rw-r--r-- 1 mbergljung staff 385 20 Sep 10:30 _remote.repositories
-rw-r--r-- 1 mbergljung staff 1538414 20 Sep 10:30 acs-rest-api-java-client-1.0.0-SNAPSHOT-javadoc.jar
-rw-r--r-- 1 mbergljung staff 322135 20 Sep 10:30 acs-rest-api-java-client-1.0.0-SNAPSHOT-sources.jar
-rw-r--r-- 1 mbergljung staff 27851 20 Sep 10:30 acs-rest-api-java-client-1.0.0-SNAPSHOT-tests.jar
-rw-r--r-- 1 mbergljung staff 897809 20 Sep 10:30 acs-rest-api-java-client-1.0.0-SNAPSHOT.jar
-rw-r--r-- 1 mbergljung staff 9463 20 Sep 09:14 acs-rest-api-java-client-1.0.0-SNAPSHOT.pom
-rw-r--r-- 1 mbergljung staff 1335 20 Sep 10:30 maven-metadata-local.xml
-rw-r--r-- 1 mbergljung staff 490 29 Sep 09:02 resolver-status.properties
Generating an Alfresco Extension Project
We will be customising both the ACS Repository (i.e. alfresco.war) and the APS Application (i.e. activiti-app.war).
Generate the Alfresco project as follows, standing in the directory where you want the project directory created, execute the following command:
brutor-samples mbergljung$ yo
? 'Allo Martin! What would you like to do? (Use arrow keys)
Run a generator
❯ Alfresco Extension Project
Alfresco Adf App
──────────────
Update your generators
Install a generator
Find some help
Select Alfresco Extension Project and hit Enter. Then answer the upcoming questions as follows:
? Parent Project name? Alfresco DBP Sample Solution
? Parent Project description? Alfresco DBP Sample solution using ACS and APS/Activiti
? Maven projects groupId? org.alfresco
? Maven parent project artifactId? alfresco-dbp-sample-solution
? Maven projects version? 1.0.0-SNAPSHOT
? Package for Java classes? org.alfresco
? Would you like to use Community or Enterprise Edition for Repository and Share? Community
? Include project for Alfresco Repository Extension? Yes
? Repository Extension maven artifactId? repo-extension
? Repository Extension Name? Repository Extension
? Repository Extension Description? Repository extension module JAR (to be included in the alfresco.war)
? Package Repo extension as JAR or AMP? JAR
? Include project for Alfresco Repository Aggregator and Repository Docker Build? Yes
? Alfresco Repository Community version? 6.0.7-ga
? Alfresco Repository Community Docker Image version? 6.0.7-ga
? Enable HotSwap Agent and DCEVM for Repository Extension? No
? Include project for Alfresco Share Extension? No
? Include project for Alfresco Share Aggregator and Share Docker Build? No
? Include project for Activiti Extension? Yes
? Activiti extension maven artifactId? activiti-extension
? Activiti Extension Name? Activiti Extension
? Activiti Extension Description? Activiti extension JAR (to be included in the activiti_app.war)
? Package for Activiti Java classes (don't change unless you know what you are doing)? com.activiti.extension.bean
? Include project for Activiti Aggregator and Activiti Docker Build? Yes
? Activiti/APS version? 1.9.0.3
? Activiti/APS Docker Image version? 1.9.0.1
? Enable DCEVM for Activiti Extension? No
? Generate sample source code for all extensions? Yes
? Generate Web Script sample with APS Rest Call in the Repo Extension project? Yes
? Generate Service Task sample with ACS Rest Call in the Activiti Extension project? Yes
? Generate a developer runtime environment based on Docker Compose? Yes
? Enable Inbound Email Server? No
? Enable Outbound Email Server? Yes
For a full explanation of these properties see this article. After the last question is answered the code generator will create all the files, it looks something like this:
Your Alfresco extension project must be inside a directory named alfresco-dbp-sample-solution
This directory will be automatically created.
Creating .yo-rc.json file...
Writing project files...
create pom.xml
create README.md
create build-all.sh
create build-activiti-extension.sh
create build-activiti-docker-image.sh
create update-activiti-container.sh
create build-repo-extension.sh
create build-repo-docker-image.sh
create update-repo-container.sh
create run.sh
create stop.sh
create repo-extension/pom.xml
create repo-extension/src/main/java/org/alfresco/reposamples/Demo.java
create repo-extension/src/main/java/org/alfresco/reposamples/DemoComponent.java
create repo-extension/src/main/java/org/alfresco/reposamples/DemoRepoAction.java
create repo-extension/src/main/java/org/alfresco/reposamples/HelloWorldWebScript.java
create repo-extension/src/main/java/org/alfresco/reposamples/CallApsWebScript.java
create repo-extension/src/main/resources/alfresco/extension/templates/webscripts/alfresco/tutorials/helloworld.get.desc.xml
create repo-extension/src/main/resources/alfresco/extension/templates/webscripts/alfresco/tutorials/helloworld.get.html.ftl
create repo-extension/src/main/resources/alfresco/extension/templates/webscripts/alfresco/tutorials/helloworld.get.js
create repo-extension/src/main/resources/alfresco/extension/templates/webscripts/alfresco/tutorials/callaps.get.desc.xml
create repo-extension/src/main/resources/alfresco/extension/templates/webscripts/alfresco/tutorials/callaps.get.html.ftl
create repo-extension/src/main/resources/alfresco/module/repo-extension/context/bootstrap-context.xml
create repo-extension/src/main/resources/alfresco/module/repo-extension/context/service-context.xml
create repo-extension/src/main/resources/alfresco/module/repo-extension/context/webscript-context.xml
create repo-extension/src/main/resources/alfresco/module/repo-extension/model/content-model.xml
create repo-extension/src/main/resources/alfresco/module/repo-extension/alfresco-global.properties
create repo-extension/src/main/resources/alfresco/module/repo-extension/log4j.properties
create repo-extension/src/main/resources/alfresco/module/repo-extension/module.properties
create repo-extension/src/main/resources/alfresco/module/repo-extension/module-context.xml
create repo-extension/src/main/resources/META-INF/resources/test.html
create repo-aggregator-docker/pom.xml
create repo-aggregator-docker/Dockerfile
create activiti-extension/pom.xml
create activiti-extension/src/main/java/com/activiti/extension/bean/SimpleJavaDelegate.java
create activiti-extension/src/main/java/com/activiti/extension/bean/SimpleSpringJavaDelegate.java
create activiti-extension/src/main/java/com/activiti/extension/bean/CallAcsSpringJavaDelegate.java
create activiti-aggregator-docker/pom.xml
create activiti-aggregator-docker/Dockerfile
create activiti-process-samples/Sample App.zip
create runner/docker-compose/docker-compose.yml
create runner/docker-compose/acs/alfresco-global.properties
create runner/docker-compose/acs/log4j.properties
create runner/docker-compose/aps/activiti-app.properties
create runner/docker-compose/aps/log4j.properties
create runner/docker-compose/aps/enterprise-license/README.md
create runner/docker-compose/docker-postgresql-multiple-databases/create-multiple-postgresql-databases.sh
What we have here is a number of projects supporting the following:
- Repository Extensions (repo-extension)
- Activiti Extensions (activiti-extension)
- Repository Extensions Aggregator and Docker Image builder (repo-aggregator-docker)
- Activiti Extensions Aggregator and Docker Image builder (activiti-aggregator-docker)
- Runner based on Docker Compose (runner)
- A number of scripts that will make life a bit easier, such as build-all.sh and run.sh
The code generator can also generate extension projects for Alfresco Share, but we will not be using this part as we will develop the UI with ADF.
Now, make sure the generated project works as expected. Build it and run it (for more info around this see this article😞
brutor-samples mbergljung$ cd alfresco-dbp-sample-solution/
alfresco-dbp-sample-solution mbergljung$ ./build-all.sh
…
alfresco-dbp-sample-solution mbergljung$./run.sh
If you are on Windows then you cannot run the build-all.sh script. It just contains mvn clean install, so run that instead. The run.sh script contains cd runner/docker-compose and then docker-compose up, so do this manually.
Wait for it to start up, then verify that you can access the following URLs:
- APS: http://localhost:9080/activiti-app - login with admin@app.activiti.com/admin (Note. You need to install a license to use APS, you can request a 30 day trial license here)
- ACS Repository: http://localhost:8082/alfresco
- ACS Share: http://localhost:8080/share/ - login with admin/admin (available even if we don’t build extensions for it)
That’s it, you are now ready to start building some customisation.
Implementing an ACS Content Model
The first thing we are going to do is to implement a content model that we can use to classify files. This is something that you will most likely have to do for any Alfresco project that you are involved in.
The content model will be quite trivial as the idea with this article is to demonstrate how easy it is to build solutions with the ACS and APS services, Alfresco Extension Project Generator, and a couple of ReST API Java Clients. And the focus is on integrating ACS and APS.
We choose to generate the extension projects with sample source code. So there should already be a sample content model available that we can work with. Open up the alfresco-dbp-sample-solution/repo-extension/src/main/resources/alfresco/module/repo-extension/model/content-model.xml file, then replace whatever is there with the following:
<?xml version="1.0" encoding="UTF-8"?>
<model name="acme:contentModel" xmlns="http://www.alfresco.org/model/dictionary/1.0">
<!-- Optional meta-data about the model -->
<description>ACME content model</description>
<author>Alfresco Project Generator</author>
<version>1.0</version>
<imports>
<!-- Import Alfresco Dictionary Definitions -->
<import uri="http://www.alfresco.org/model/dictionary/1.0" prefix="d"/>
<!-- Import Alfresco Content Domain Model Definitions -->
<import uri="http://www.alfresco.org/model/content/1.0" prefix="cm"/>
<!-- Import Alfresco System Model Definitions -->
<import uri="http://www.alfresco.org/model/system/1.0" prefix="sys"/>
</imports>
<!-- Custom namespace for your domain -->
<namespaces>
<namespace uri="http://www.acme.com/model/content/1.0" prefix="acme"/>
</namespaces>
<constraints>
<constraint name="acme:securityClassificationOptions" type="LIST">
<parameter name="allowedValues">
<list>
<value></value> <!-- Empty for default search -->
<value>Public</value>
<value>Client Confidential</value>
<value>Company Confidential</value>
<value>Strictly Confidential</value>
</list>
</parameter>
</constraint>
<constraint name="acme:contractIdFormat" type="REGEX">
<parameter name="expression">
<value><![CDATA[^C\d{3}$]]></value>
</parameter>
<parameter name="requiresMatch">
<value>true</value>
</parameter>
</constraint>
</constraints>
<types>
<type name="acme:document">
<title>ACME Base document type</title>
<parent>cm:content</parent>
<properties>
<property name="acme:documentId">
<title>Document Identification Number</title>
<type>d:text</type>
</property>
</properties>
<mandatory-aspects>
<aspect>acme:securityClassified</aspect>
</mandatory-aspects>
</type>
<type name="acme:contract">
<title>ACME Contract document</title>
<parent>acme:document</parent>
<properties>
<property name="acme:contractName">
<title>Contract Name</title>
<type>d:text</type>
<mandatory>true</mandatory>
</property>
<property name="acme:contractId">
<title>Contract Identification Number</title>
<type>d:text</type>
<constraints>
<constraint ref="acme:contractIdFormat"/>
</constraints>
</property>
</properties>
</type>
</types>
<aspects>
<aspect name="acme:securityClassified">
<title>ACME Security Classified</title>
<description>Content has been security classified</description>
<properties>
<property name="acme:securityClassification">
<type>d:text</type>
<index enabled="true">
<atomic>true</atomic>
<stored>false</stored>
<tokenised>false</tokenised>
<facetable>true</facetable>
</index>
<constraints>
<constraint ref="acme:securityClassificationOptions"/>
</constraints>
</property>
</properties>
</aspect>
</aspects>
</model>This will define an ACME contract document type that we can use to classify files with. The content model also defines the ACME Security Classified aspect that we can set on a file to tell the system the sensitivity of the file.
We can specify labels for these types, aspects, and properties. Create a new file for that called content-model.properties and put it in this alfresco-dbp-sample-solution/repo-extension/src/main/resources/alfresco/module/repo-extension/messages new directory with the following content:
acme_contentModel.type.acme_document.title=ACME Document
acme_contentModel.type.acme_contract.title=ACME Contract
acme_contentModel.aspect.acme_securityClassified.title=ACME Security Classified
acme_contentModel.property.acme_documentId.title=Document Id
acme_contentModel.property.acme_contractName.title=Contract Name
acme_contentModel.property.acme_contractId.title=Contract Id
acme_contentModel.property.acme_securityClassification.title=Security ClassificationThis property file need to be bootstrapped by the system and we can achieve this with the following configuration update to the alfresco-dbp-sample-solution/repo-extension/src/main/resources/alfresco/module/repo-extension/context/bootstrap-context.xml file:
<?xml version='1.0' encoding='UTF-8'?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.0.xsd">
<!--
The bootstrap-context.xml file is used for patch definitions, importers,
workflow, and loading custom content models. -->
<!-- Registration of new models and associated labels-->
<bean id="org.alfresco.repo-extension.dictionaryBootstrap"
parent="dictionaryModelBootstrap"
depends-on="dictionaryBootstrap">
<property name="models">
<list>
<value>alfresco/module/${project.artifactId}/model/content-model.xml</value>
</list>
</property>
<property name="labels">
<list>
<value>alfresco/module/${project.artifactId}/messages/content-model</value>
</list>
</property>
</bean>
</beans>That’s all we need to do for the content model. To test that it loads properly execute the following command from the parent directory of the project:
alfresco-dbp-sample-solution mbergljung$./update-repo-container.sh
This will do the following:
- Build the Repository Extension so we are sure to get the latest changes (contained in the repo-extension project)
- Stop the Repository Container (i.e. the one that runs alfresco.war)
- Remove the Repository Container - so we can build a new image
- Assemble/Aggregate all Repository extension JARs into the target/extensions directory (we could have more than one repo extension, this is handled by the repo-aggregator-docker project)
- Build a new Repository Docker Image with the Extension JAR(s) applied (handled by the Dockerfile contained in the repo-aggregator-docker project)
- Start the Repository Container based on newly built Image
If the changes were OK you should be able to access http://localhost:8082/alfresco again after a successful restart. If something went wrong you will see a message in the logs looking like this:
content_1 | 2018-10-10 13:32:05,901 ERROR [web.context.ContextLoader] [localhost-startStop-1] Context initialization failed
content_1 | org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'org.alfresco.repo-extension.dictionaryBootstrap' defined in class path resource [alfresco/module/repo-extension/context/bootstrap-context.xml]: Invocation of init method failed; nested exception is org.alfresco.service.cmr.dictionary.DictionaryException: 09100001 Could not import bootstrap model 'alfresco/module/repo-extension/model/content-model.xml'
If it did not load, then go back and fix the problem and then run the script again.
Implementing a Review and Approve Contract Process in APS
When a contract document is uploaded to the ACS Repository a ‘Review and Approve’ process will be automatically started in APS. This process will have one User Task and one Service Task.
The User Task will provide the user with a link to view the contract document and a number of fields where contract ID, contract Name, and Security classification can be specified.
If the user is ‘approving’ the document via the User Task, then there will be a Service task that applies the Contract Type to the document and sets the associated properties. The document will also be moved to a special ‘approved contracts’ folder in ACS. If the user ‘rejects’ the document in the User Task, then the Service Task will not be executed.
If you got the solution still running you should be able to access APS at http://localhost:9080/activiti-app.
You can find the source code for the process definition, forms, and process app here, if you would rather just import it instead of defining it by hand.Navigate to the App Designer and create a new process definition called Review and Approve that looks like this:
The Start Form will have an Attach File field representing the contract file that should be reviewed:
The contract file field have the following id: contracttobeapproved
The User Task form looks like this:
The Security Classification drop down will have the following options to choose from matching the content model constraint:
The fields have the following ids: contractid, contractname, securityclassification. The form has two outcomes, Approve and Reject:
Configure the Exclusive Gateway transitions as follows, for the approve flow:
And for the reject flow:
Now let's configure the Service Task. These User Task form field IDs are important as we will use them to define the Service Task class fields as follows:
The alfrescoRepoId is important as it represents the ID of the Repository Tenant that we will talk to when setting ACS metadata from the Service Task implementation. The Service task implementation is done in the ${setContractTypeJavaDelegate} Spring Bean delegate, configure Service Task to use it as follows:
Now save the process definition.
The XML for the process definition looks like this:
<?xml version='1.0' encoding='UTF-8'?>
<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL" ...>
<process id="ReviewandApprove" name="Review and Approve" isExecutable="true">
<documentation>A process that is used to review and approve a contract document.</documentation>
<startEvent id="startEvent1">
</startEvent>
<userTask id="sid-3BFA2E15-445A-4325-A061-0C8C5D224323" name="Set Contract Metadata. Approve or Reject Contract Document." activiti:assignee="$INITIATOR" activiti:formKey="2">
</userTask>
<serviceTask id="sid-762F8377-970D-43D1-9C09-BB9437851F55" name="Apply The Contract Type to the Document in ACS, including associated properties" activiti:delegateExpression="${setContractTypeJavaDelegate}">
<extensionElements>
<activiti:field name="alfrescoRepoId">
<activiti:string><![CDATA[1]]></activiti:string>
</activiti:field>
<activiti:field name="contractId">
<activiti:expression><![CDATA[${contractid}]]></activiti:expression>
</activiti:field>
<activiti:field name="contractName">
<activiti:expression><![CDATA[${contractname}]]></activiti:expression>
</activiti:field>
<activiti:field name="securityClassification">
<activiti:expression><![CDATA[${securityclassification}]]></activiti:expression>
</activiti:field>
</extensionElements>
</serviceTask>
<sequenceFlow id="sid-2CFB0C32-1ACB-442F-8DA2-346BADFBD065" sourceRef="startEvent1" targetRef="sid-3BFA2E15-445A-4325-A061-0C8C5D224323">
</sequenceFlow>
<exclusiveGateway id="sid-907BC573-AD62-42B1-A446-886F254FC53B" activiti:async="true" activiti:exclusive="false">
</exclusiveGateway>
<sequenceFlow id="sid-57CC7D6E-B492-4628-AFB9-5C534A084EDA" sourceRef="sid-3BFA2E15-445A-4325-A061-0C8C5D224323" targetRef="sid-907BC573-AD62-42B1-A446-886F254FC53B">
</sequenceFlow>
<endEvent id="sid-2C232784-A32B-4F4D-8D84-02FA68FB3B8D">
<extensionElements>
</endEvent>
<sequenceFlow id="sid-5F8C88D8-F7AF-4061-980E-2AD0AAD79BAD" sourceRef="sid-762F8377-970D-43D1-9C09-BB9437851F55" targetRef="sid-2C232784-A32B-4F4D-8D84-02FA68FB3B8D">
</sequenceFlow>
<sequenceFlow id="sid-DAB009BC-9F6D-45C3-A55F-8CB476A6D985" name="Rejected" sourceRef="sid-907BC573-AD62-42B1-A446-886F254FC53B" targetRef="sid-2C232784-A32B-4F4D-8D84-02FA68FB3B8D">
<conditionExpression xsi:type="tFormalExpression"><![CDATA[${(activiti_flowConditionsBean.exists(execution, 'form2outcome') && form2outcome == 'Reject')}]]></conditionExpression>
</sequenceFlow>
<sequenceFlow id="sid-025F3633-D251-4C93-B8C9-59B23BA81726" name="Approved" sourceRef="sid-907BC573-AD62-42B1-A446-886F254FC53B" targetRef="sid-762F8377-970D-43D1-9C09-BB9437851F55">
<conditionExpression xsi:type="tFormalExpression"><![CDATA[${(activiti_flowConditionsBean.exists(execution, 'form2outcome') && form2outcome == 'Approve')}]]></conditionExpression>
</sequenceFlow>
</process>
...
</definitions>Note that the Service Task is implemented by a Spring Bean called setContractTypeJavaDelegate that we need to implement next.
Implementing the APS Set Contract Type Service Task
The process definition is now in place, we just need to implement the Set Contract type Service Task for it to be complete. It should create a folder structure in ACS Repository, move the approved contract file there, and finally set the contract type and associated properties. It will do this with the help of the ACS ReST API Java Client.
The Service Task will be implemented as a Spring Bean Delegate class called com.activiti.extension.bean.SetContractTypeJavaDelegate. The Activiti Extension already comes with some useful sample source code that we can use as a starting point.
Open up the alfresco-dbp-sample-solution/activiti-extension/src/main/java/com/activiti/extension/bean/CallAcsSpringJavaDelegate.java file and change its name and code so it looks like this:
package com.activiti.extension.bean;
import com.activiti.domain.integration.AlfrescoEndpoint;
import com.activiti.domain.runtime.RelatedContent;
import com.activiti.service.api.AlfrescoEndpointService;
import com.activiti.service.runtime.RelatedContentService;
import org.activiti.engine.delegate.DelegateExecution;
import org.activiti.engine.delegate.Expression;
import org.activiti.engine.delegate.JavaDelegate;
import org.alfresco.repository.remote.client.ApiClient;
import org.alfresco.repository.remote.client.api.QueriesApi;
import org.alfresco.repository.remote.client.model.*;
import org.apache.commons.codec.binary.Base64;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;
import org.alfresco.repository.remote.client.ApiException;
import org.alfresco.repository.remote.client.api.NodesApi;
import java.io.IOException;
import java.nio.charset.Charset;
import java.text.SimpleDateFormat;
import java.util.*;
import static com.activiti.alfrescoconnector.AlfrescoConnectorConstants.ON_PREM_API_LOCATION;
/**
* A Service Task delegate implemented as a Spring Bean that uses the ACS ReST API Java Client
* to set a type, aspect, and properties on a file and move it to a different folder.
* <p/>
* This requires you to first clone https://github.com/gravitonian/acs-rest-api-java-client
* and then run mvn install so you have this lib in your local maven repo.
*
* @author martin.bergljung@alfresco.com
*/
@Component("setContractTypeJavaDelegate")
public class SetContractTypeJavaDelegate implements JavaDelegate {
private static Logger logger = LoggerFactory.getLogger(SetContractTypeJavaDelegate.class);
private static final String CONTRACT_FILE_VAR_NAME = "contracttobeapproved";
@Autowired
protected AlfrescoEndpointService alfrescoEndpointService;
@Autowired
protected RelatedContentService relatedContentService;
// Service Task fields
private Expression alfrescoRepoId;
private Expression contractId;
private Expression contractName;
private Expression securityClassification;
/**
* Service Task class field injection
*/
public void setAlfrescoRepoId(Expression alfrescoRepoId) {
this.alfrescoRepoId = alfrescoRepoId;
}
public void setContractName(Expression contractName) {
this.contractName = contractName;
}
public void setContractId(Expression contractId) {
this.contractId = contractId;
}
public void setSecurityClassification(Expression securityClassification) {
this.securityClassification = securityClassification;
}
/**
* Service Task implementation
*/
@Override
public void execute(DelegateExecution execution) throws Exception {
String alfrescoRepoIdText = (String) alfrescoRepoId.getValue(execution);
String contractIdText = (String) contractId.getValue(execution);
String contractNameText = (String) contractName.getValue(execution);
String securityClassificationText = (String) securityClassification.getValue(execution);
logger.info("Alfresco Repo ID, should match what's configured in Tenant section: [ID=" + alfrescoRepoIdText + "]");
// Format as Service ID
String repoId = "alfresco-" + alfrescoRepoIdText;
// Get the Alfresco Repository Endpoint configuration from APS
AlfrescoEndpoint endpoint = alfrescoEndpointService.getById(
alfrescoEndpointService.getEndpointIdForServiceId(repoId));
if (endpoint != null) {
logger.info("Alfresco Repo endpoint: [endpointRepoUrl=" + endpoint.getRepositoryUrl() +
"][secret=" + endpoint.getSecret() + "]");
// https://content:8080/alfresco/api/-default-/public/alfresco/versions/1
String url = endpoint.getRepositoryUrl() + "/" + ON_PREM_API_LOCATION.substring(0, ON_PREM_API_LOCATION.length() - 1);
logger.info("ACS ReST API base URL: " + url);
// Generic API client that can be used by the specific API clients
ApiClient client = new ApiClient();
client.setBasePath(url); // TODO: Fix these hard coded credentials...
client.addDefaultHeader("Authorization", getCredential("admin", "admin"));
// Create/Get folder for where to store approved contract
Node monthFolderNode = createFolderStructure(client);
// Move contract file into month folder
String contractFileNodeId = getContractNodeId(execution);
boolean moveSuccessful = moveNode(client, contractFileNodeId, monthFolderNode.getId());
// Set Contract Type and associated properties
if (moveSuccessful) {
setContractType(client, contractFileNodeId, contractIdText, contractNameText, securityClassificationText);
}
}
}
/**
* Create the folder structure for where we will store the approved contracts:
* <p>
* Company Home
* Contract Management
* 2018
* OCT
*
* @param client - the API client to use with base URL and auth
* @return the Node object for the month folder
* @throws Exception
*/
private Node createFolderStructure(ApiClient client) throws Exception {
// Create/Get the main Contract Management folder
String contractManagementFolderName = "Contract Management";
Node contractManagementFolderNode = findNode(client, contractManagementFolderName, "-root-");
if (contractManagementFolderNode == null) {
contractManagementFolderNode = createFolder(client, contractManagementFolderName,
"Management of Contracts",
"All files related to approved contracts",
"");
}
// Create/Get the year folder
Integer year = Calendar.getInstance().get(Calendar.YEAR);
Node yearFolderNode = findNode(client, year.toString(), contractManagementFolderNode.getId());
if (yearFolderNode == null) {
yearFolderNode = createFolder(client, year.toString(),
"Contracts for a Year",
"All files related to approved contracts for year " + year,
contractManagementFolderName);
}
// Create a month folder under year folder
Calendar cal = Calendar.getInstance();
String currentMonth = new SimpleDateFormat("MMM").format(cal.getTime());
Node monthFolderNode = findNode(client, currentMonth, yearFolderNode.getId());
if (monthFolderNode == null) {
monthFolderNode = createFolder(client, currentMonth,
"Contracts for 1 month",
"All contract files for month " + currentMonth,
contractManagementFolderName + "/" + year.toString());
}
return monthFolderNode;
}
/**
* Make the remote call to create a folder in ACS, if it does not exist.
* <p>
* For more info: https://github.com/gravitonian/acs-rest-api-java-client/blob/master/docs/NodesApi.md#createNode
*
* @param client - the API client to use with base URL and auth
* @param folderName the name of the folder
* @param folderTitle the title of the folder
* @param folderDescription the description of the folder
* @param relativeFolderPath path relative to /Company Home
* @return a node object for the newly created node, contains the ID,
* such as e859588c-ae81-4c5e-a3b6-4c6109b6c905
*/
private Node createFolder(ApiClient client,
String folderName,
String folderTitle,
String folderDescription,
String relativeFolderPath) throws IOException {
// Specific API client for working with Repository Nodes
NodesApi apiInstance = new NodesApi(client);
String rootPath = "-root-"; // /Company Home
String folderType = "cm:folder"; // Standard out-of-the-box folder type
List<String> folderAspects = new ArrayList<String>();
folderAspects.add("cm:titled");
Map<String, String> folderProps = new HashMap<>();
folderProps.put("cm:title", folderTitle);
folderProps.put("cm:description", folderDescription);
// The identifier of a node. You can also use one of these well-known aliases: * -my- * -shared- * -root-
String nodeId = rootPath;
NodeBodyCreate nodeBodyCreate = new NodeBodyCreate();
nodeBodyCreate.setName(folderName);
nodeBodyCreate.setNodeType(folderType);
nodeBodyCreate.setAspectNames(folderAspects);
nodeBodyCreate.setProperties(folderProps);
nodeBodyCreate.setRelativePath(relativeFolderPath);
// If true, then a name clash will cause an attempt to auto rename by
// finding a unique name using an integer suffix.
Boolean autoRename = true;
List<String> include = null;
List<String> fields = null;
NodeEntry newNode = null;
try {
newNode = apiInstance.createNode(nodeId, nodeBodyCreate, autoRename, include, fields);
logger.info("Created new folder [name=" + folderName + "]" + newNode);
} catch (ApiException e) {
logger.error("Exception when calling NodesApi#createNode [responseCode=" +
e.getCode() + "][responseBody=" + e.getResponseBody() + "]");
e.printStackTrace();
}
return newNode != null ? newNode.getEntry() : null;
}
/**
* Find a node based on name.
* Search term must be at least 3 characters.
* <p>
* For more info: https://github.com/gravitonian/acs-rest-api-java-client/blob/master/docs/QueriesApi.md#findNodes
*
* @param client - the API client to use with base URL and auth
* @param nodeName the name of the node (i.e. folder or file) that we are looking for, min 3 characters
* @param parentNodeId the parent node under which we expect to find the node
* @return a node object for the found node, or null if not found
*/
private Node findNode(ApiClient client,
String nodeName,
String parentNodeId) {
// Specific API client for working with Queries/Search
QueriesApi apiInstance = new QueriesApi(client);
String term = nodeName; // The term to search for.
String rootNodeId = parentNodeId; // The id of the node to start the search from. Supports the aliases -my-, -root- and -shared-.
Integer skipCount = 0; // The number of entities that exist in the collection before those included in this list. If not supplied then the default value is 0.
Integer maxItems = 100; // The maximum number of items to return in the list. If not supplied then the default value is 100.
String nodeType = null; // Restrict the returned results to only those of the given node type and its sub-types
List<String> include = null;
List<String> orderBy = null;
List<String> fields = null;
NodeEntry nodeEntry = null;
try {
NodePaging result = apiInstance.findNodes(
term, rootNodeId, skipCount, maxItems, nodeType, include, orderBy, fields);
if (result.getList().getEntries().isEmpty() == false) {
nodeEntry = result.getList().getEntries().get(0);
logger.info("Found node [name=" + nodeEntry.getEntry().getName() + "]" + nodeEntry);
return nodeEntry.getEntry();
}
} catch (ApiException e) {
logger.error("Exception when calling QueriesApi#findNodes [responseCode=" +
e.getCode() + "][responseBody=" + e.getResponseBody() + "]");
e.printStackTrace();
}
return null;
}
/**
* Get the Alfresco Node ID for the contract file that we are reviewing and approving/rejecting
* with the process instance.
*
* @param execution execution context
* @return the Alfresco Node ID for contract file, or null if could not be extracted
*/
private String getContractNodeId(DelegateExecution execution) {
List<RelatedContent> contentList = relatedContentService.getFieldContentForProcessInstance(
execution.getProcessInstanceId(), CONTRACT_FILE_VAR_NAME, 1, 0).getContent();
if (contentList != null) {
for (RelatedContent relCon : contentList) {
logger.info("ACS file: " + relCon.getName() + ", created: " + relCon.getCreated());
String acsNodeRef = relCon.getSourceId();
return acsNodeRef;
}
}
return null;
}
/**
* Move a node (file/folder) to a new parent folder.
* <p>
* For more info: https://github.com/gravitonian/acs-rest-api-java-client/blob/master/docs/NodesApi.md#moveNode
*
* @param client - the API client to use with base URL and auth
* @param nodeId the id of the node (i.e. folder or file) that we are moving
* @param newParentNodeId the parent node id where we are moving node
* @return true if node was moved successfully, otherwise false
*/
private boolean moveNode(ApiClient client,
String nodeId,
String newParentNodeId) {
// Specific API client for working with Repository Nodes
NodesApi apiInstance = new NodesApi(client);
// The targetParentId and, optionally, a new name which should include the file extension.
NodeBodyMove nodeBodyMove = new NodeBodyMove();
nodeBodyMove.setTargetParentId(newParentNodeId);
List<String> include = null;
List<String> fields = null;
try {
NodeEntry result = apiInstance.moveNode(nodeId, nodeBodyMove, include, fields);
logger.info("Moved node [name=" + result.getEntry().getName() + "]" + result);
return true;
} catch (ApiException e) {
logger.error("Exception when calling NodesApi#moveNode [responseCode=" +
e.getCode() + "][responseBody=" + e.getResponseBody() + "]");
e.printStackTrace();
}
return false;
}
/**
* Set the content type on passed in contract file to 'Contract Type' and set also associated properties.
* Set also aspect security classified.
*
* @param client - the API client to use with base URL and auth
* @param contractFileNodeId - the Alfresco Node ID for the contract file
* @param contractIdText - the contract ID that we want to set
* @param contractNameText - the contract name that we want to set
* @param securityClassificationText - the security classification that we want to set
*/
private void setContractType(ApiClient client,
String contractFileNodeId,
String contractIdText,
String contractNameText,
String securityClassificationText) {
// Specific API client for working with Repository Nodes
NodesApi apiInstance = new NodesApi(client);
// Get the contract file node first, so we can get to the aspects that are currently set
Node contractFileNode = getNode(client, contractFileNodeId);
if (contractFileNode != null) {
Map<String, String> properties = new HashMap<>();
properties.put("acme:documentId", "D" + getRandomDocNumber());
properties.put("acme:contractId", contractIdText);
properties.put("acme:contractName", contractNameText);
properties.put("acme:securityClassification", securityClassificationText);
List<String> aspectNames = contractFileNode.getAspectNames();
aspectNames.add("acme:securityClassified");
NodeBodyUpdate nodeBodyUpdate = new NodeBodyUpdate(); // The node information to update.
nodeBodyUpdate.setNodeType("acme:contract");
nodeBodyUpdate.setAspectNames(aspectNames);
nodeBodyUpdate.setProperties(properties);
List<String> include = null;
List<String> fields = null;
try {
NodeEntry result = apiInstance.updateNode(contractFileNodeId, nodeBodyUpdate, include, fields);
System.out.println(result);
} catch (ApiException e) {
logger.error("Exception when calling NodesApi#updateNode [responseCode=" +
e.getCode() + "][responseBody=" + e.getResponseBody() + "]");
e.printStackTrace();
}
} else {
logger.error("Failed to set Contract Type, file not found");
}
}
/**
* Get a random number between 1 and 999
*
* @return
*/
private int getRandomDocNumber() {
Random r = new Random();
int n = r.nextInt(998) + 1;
return n;
}
/**
* Get a node (file/folder).
* <p>
* For more info: https://github.com/gravitonian/acs-rest-api-java-client/blob/master/docs/NodesApi.md#getNode
*
* @param client - the API client to use with base URL and auth
* @param nodeId the id of the node (i.e. folder or file) that we want to get
* @return Node object if exist, or null if does not exist
*/
private Node getNode(ApiClient client,
String nodeId) {
// Specific API client for working with Repository Nodes
NodesApi apiInstance = new NodesApi(client);
// A path relative to the **nodeId**. If you set this, information is returned on the node resolved by this path.
String relativePath = null;
List<String> include = null;
List<String> fields = null;
try {
NodeEntry result = apiInstance.getNode(nodeId, include, relativePath, fields);
logger.info("Got node [name=" + result.getEntry().getName() + "]" + result);
return result.getEntry();
} catch (ApiException e) {
logger.error("Exception when calling NodesApi#getNode [responseCode=" +
e.getCode() + "][responseBody=" + e.getResponseBody() + "]");
e.printStackTrace();
}
return null;
}
/**
* Helper method to construct the value of the Basic Auth header
*
* @return
*/
private String getCredential(String username, String pwd) {
String auth = username + ":" + pwd;
byte[] encodedAuth = Base64.encodeBase64(auth.getBytes(Charset.forName("US-ASCII")));
String authHeader = "Basic " + new String(encodedAuth);
return authHeader;
}
}A Service Task implementation is run via the execute() method, which will first get the class fields so it knows the Alfresco Repository ID, Contract ID and Name, and Security Classification. The Alfresco Repository ID is set to 1 in this case and it needs to correspond to the Alfresco Repository Tenant ID in APS, go to Identity management | Tenants | Alfresco Repositories:
The Alfresco Repository needs to be configured like this:
The URLs work inside the Docker network, see the Docker Compose file in the runner/docker-compose/docker-compose.yml file for an explanation of the hostname used in the URLs, they correspond to the service names.
The Service Task will then get the ACS Repository Endpoint URL. Then it will set up an ACS ReST API client that we can use to talk the ACS ReST API from Java. When this is finished it will create a folder structure (createFolderStructure) in the Repository looking like this:
After this the Service Task will get the Alfresco Node ID (getContractNodeId) for the contract file that we are reviewing and approving/rejecting with the process instance. We need it as next we will move the contract file (moveNode) to the month folder. If the move was successful we finish off by setting the type (setContractType) of the Contract file to acme:contract, including associated properties and aspect. You can verify that the properties have been set by just looking at the Properties in the Document Details page in Share:
The properties are not laid out in a nice way, but that’s just because we have not defined a form for the acme:contract type in Alfresco Share. We will not do any customisations in Share but instead focus on using ADF as the main UI.
All the methods uses the ACS ReST API Java Client to talk to ACS. Many API methods in this Java client takes an include and fields argument. They can be used to include extra information in the API responses:
- include: Returns additional information about the Alfresco Repository node. The following optional fields can be requested: allowableOperations, association, isLink, isLocked, path, permissions.
- fields: A list of field names. You can use this parameter to restrict the fields returned within a response if, for example, you want to save on overall bandwidth. The list applies to a returned individual entity or entries within a collection. If the API method also supports the include argument, then the fields specified in the include parameter are returned in addition to those specified in the fields parameter.
That’s all we need to do for the Service Task implementation. To test that it loads properly execute the following command from the parent directory of the project:
alfresco-dbp-sample-solution mbergljung$./update-activiti-container.sh
This will do the following:
- Build the Activiti Extension so we are sure to get the latest changes (contained in the activiti-extension project)
- Stop the Activiti Container (i.e. the one that runs activiti-app.war)
- Remove the Activiti Container - so we can build a new image
- Assemble/Aggregate all Activiti extension JARs into the target/extensions directory (we could have more than one activiti extension, this is handled by the activiti-aggregator-docker project)
- Build a new Activiti Docker Image with the Extension JAR(s) applied (handled by the Dockerfile contained in the activiti-aggregator-docker project)
- Start the Activiti Container based on newly built Image
Implementing the ACS Rule/Policy to start the Review & Approve Process
When somebody uploads a file to the ACS Repository we want to automatically kick off the Review & Approve APS process. When the process is started it should be associated with the uploaded contract file. We will accomplish this with something called a Behavior Policy. You can also call it an Event Handler as it will listen to when files are being created or uploaded and then start the process in APS with the help of the APS ReST API Java Client.
The sample source code already comes with a demo Call APS Web Script that starts a process in APS with associated ACS content file. The code is in the alfresco-dbp-sample-solution/repo-extension/src/main/java/org/alfresco/reposamples/CallApsWebScript.java file.
Let’s change the name of this class to IncomingContractFileEventHandler and convert it from a Web Script to an Upload File Behaviour Policy / Event Handler, here is the new code:
package org.alfresco.reposamples;
import org.activiti.engine.remote.client.ApiClient;
import org.activiti.engine.remote.client.ApiException;
import org.activiti.engine.remote.client.Configuration;
import org.activiti.engine.remote.client.api.ContentApi;
import org.activiti.engine.remote.client.api.ProcessDefinitionsApi;
import org.activiti.engine.remote.client.api.ProcessInstancesApi;
import org.activiti.engine.remote.client.auth.HttpBasicAuth;
import org.activiti.engine.remote.client.model.*;
import org.alfresco.model.ContentModel;
import org.alfresco.repo.node.NodeServicePolicies;
import org.alfresco.repo.policy.Behaviour;
import org.alfresco.repo.policy.JavaBehaviour;
import org.alfresco.repo.policy.PolicyComponent;
import org.alfresco.service.ServiceRegistry;
import org.alfresco.service.cmr.repository.ChildAssociationRef;
import org.alfresco.service.cmr.repository.NodeRef;
import org.json.simple.parser.ParseException;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.io.IOException;
import java.util.Date;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
/**
* When a Contract File is uploaded to the repository start the Review and Approve process.
*
* @author martin.bergljung@alfresco.com
*/
public class IncomingContractFileEventHandler {
private static Logger logger = LoggerFactory.getLogger(IncomingContractFileEventHandler.class);
private PolicyComponent eventManager;
private ServiceRegistry serviceRegistry;
private String apsHost;
private String apsPort;
private String apsUsername;
private String apsPwd;
private String apsProcessDefKey;
private String apsTenantAlfrescoRepositorySource;
/**
* Spring Setter injection
*/
public void setServiceRegistry(ServiceRegistry serviceRegistry) {
this.serviceRegistry = serviceRegistry;
}
public void setPolicyComponent(PolicyComponent policyComponent) {
this.eventManager = policyComponent;
}
public void setApsPwd(String apsPwd) {
this.apsPwd = apsPwd;
}
public void setApsUsername(String apsUsername) {
this.apsUsername = apsUsername;
}
public void setApsPort(String apsPort) {
this.apsPort = apsPort;
}
public void setApsHost(String apsHost) {
this.apsHost = apsHost;
}
public void setApsProcessDefKey(String apsProcessDefKey) {
this.apsProcessDefKey = apsProcessDefKey;
}
public void setApsTenantAlfrescoRepositorySource(String apsTenantAlfrescoRepositorySource) {
this.apsTenantAlfrescoRepositorySource = apsTenantAlfrescoRepositorySource;
}
/**
* Register our event handlers
*/
public void registerEventHandlers() {
eventManager.bindClassBehaviour(
NodeServicePolicies.OnCreateNodePolicy.QNAME,
ContentModel.TYPE_CONTENT,
new JavaBehaviour(this, "onAddFile",
Behaviour.NotificationFrequency.TRANSACTION_COMMIT));
}
/**
* Event handler implementation
*/
public void onAddFile(ChildAssociationRef parentChildAssocRef) throws IOException, ParseException {
NodeRef parentFolderRef = parentChildAssocRef.getParentRef();
NodeRef fileRef = parentChildAssocRef.getChildRef();
// Check if node exists, might be moved, or created and deleted in same transaction.
if (fileRef == null || !serviceRegistry.getNodeService().exists(fileRef)) {
// Does not exist, nothing to do
logger.warn("onAddFile: A new document was added but removed in same transaction");
return;
} else {
logger.info("onAddFile: A new contract file with ref ({}) was just created in folder ({})",
fileRef, parentFolderRef);
// Get the default API client and update with base URL and authentication,
// it will be automatically used by any specific API
ApiClient defaultClient = Configuration.getDefaultApiClient();
// Set base APS API URL
String endpoint = "http://" + apsHost + ":" + apsPort + "/activiti-app/api";
defaultClient.setBasePath(endpoint);
// Configure HTTP basic authorization: basicAuth
HttpBasicAuth basicAuth = (HttpBasicAuth) defaultClient.getAuthentication("basicAuth");
basicAuth.setUsername(apsUsername);
basicAuth.setPassword(apsPwd);
// Get the process definition that we should use when starting the process
String processDefId = getProcessDefId();
if (processDefId != null) {
// Set up a link in APS to ACS contract file, so we can associate with process
Long contentId = uploadAcsContent2Aps(fileRef);
// Start the Review and Approve process
ProcessInstanceRepresentation processInstance = startProcess(processDefId, contentId);
} else {
Map<String, Object> model = new HashMap<String, Object>();
model.put("processInfo", "No process started, no process definition matched " + apsProcessDefKey);
}
}
}
/**
* Get latest version of process def ID matching process definition key.
* <p>
* http://localhost:9080/activiti-app/api/enterprise/process-definitions?latest=true
* <p>
* Sample response:
* {
* size: 1,
* total: 1,
* start: 0,
* data: [
* {
* id: "ReviewandApprove:1:4",
* name: "Review and Approve",
* description: "A process that is used to review and approve a contract document.",
* key: "ReviewandApprove",
* category: "http://www.activiti.org/processdef",
* version: 1,
* deploymentId: "1",
* tenantId: "tenant_1",
* metaDataValues: [ ],
* hasStartForm: true
* }
* ]
* }
*
* @return the latest version of process definition ID that matches process definition key
*/
private String getProcessDefId() {
// Get all the latest process definitions
ProcessDefinitionsApi apiInstance = new ProcessDefinitionsApi();
Boolean latest = true; // [OPTIONAL] get latest versions of process definitions
Long appDefinitionId = null; // [OPTIONAL] get process defs for the process app definition Id
String deploymentId = null; // [OPTIONAL] filter process defs by process definition deployment ID
ResultListDataRepresentationProcessDefinitionRepresentation result = null;
try {
result = apiInstance.getProcessDefinitionsUsingGET(latest, appDefinitionId, deploymentId);
} catch (ApiException e) {
logger.error("Exception when calling ProcessDefinitionsApi#getProcessDefinitionsUsingGET [responseCode=" +
e.getCode() + "][responseBody=" + e.getResponseBody() + "]");
e.printStackTrace();
}
String lastestProcessDefId = null;
if (result != null) {
// Loop over process defs and find the one we are interested in (i.e. the one matching apsProcessDefKey)
List<ProcessDefinitionRepresentation> processDefs = result.getData();
lastestProcessDefId = null;
for (ProcessDefinitionRepresentation processDef : processDefs) {
if (processDef.getId().startsWith(apsProcessDefKey)) {
lastestProcessDefId = processDef.getId();
break;
}
}
}
if (lastestProcessDefId == null) {
throw new RuntimeException("Missing " + apsProcessDefKey + " process definition");
}
return lastestProcessDefId;
}
/**
* Upload/Link ACS content to APS.
* <p>
* Example of upload response:
* {
* "id":25025,
* "name":"Request Text",
* "created":"2018-06-21T15:10:32.464+0000",
* "createdBy":{
* "id":1,
* "firstName":null,
* "lastName":"Administrator",
* "email":"admin@app.activiti.com"
* },
* "relatedContent":false,
* "contentAvailable":true,
* "link":true,
* "source":"alfresco-1-ACS 6",
* "sourceId": "65acc59d-2d01-4701-ac61-de1ea6d241ab",
* "mimeType":"text/plain",
* "simpleType":"content",
* "previewStatus": "queued",
* "thumbnailStatus":"queued"
* }
*
* @param acsContentNodeRef the Alfresco Node Reference for the file that should be linked or uploaded to APS
* @return the Content ID in APS, or null if could not be uploaded or linked
*/
private Long uploadAcsContent2Aps(NodeRef acsContentNodeRef) {
// Get the name of the file
String fileName = (String) serviceRegistry.getNodeService().getProperty(acsContentNodeRef, ContentModel.PROP_NAME);
// Set up content props
ContentApi apiInstance = new ContentApi();
RelatedContentRepresentation relatedContent = new RelatedContentRepresentation();
relatedContent.setName(fileName);
relatedContent.setLink(true); // Keep content only in ACS, do not upload to APS
relatedContent.setSource(apsTenantAlfrescoRepositorySource);
relatedContent.setSourceId(acsContentNodeRef.getId());
relatedContent.setMimeType("text/plain");
// Set up ACS Content Link in APS
RelatedContentRepresentation result = null;
try {
result = apiInstance.createTemporaryRelatedContentUsingPOST(relatedContent);
} catch (ApiException e) {
logger.error("Exception when calling ContentApi#createTemporaryRelatedContentUsingPOST [responseCode=" +
e.getCode() + "][responseBody=" + e.getResponseBody() + "]");
e.printStackTrace();
}
Long contentId = null;
if (result != null) {
contentId = result.getId();
}
return contentId;
}
/**
* Start the process instance in APS with all props and content
*
* @param processDefId the process definition ID to use when starting a new process instance
* @param acsContentId the ACS contract file content ID in APS
* @return the new process instance data, or null if could not be started
*/
private ProcessInstanceRepresentation startProcess(String processDefId, Long acsContentId) {
logger.info("Starting process [processDefinitionId=" + processDefId + "][contentId=" + acsContentId + "]");
// Set up Start form field values
Map<String, Object> formFieldValues = new HashMap<>();
formFieldValues.put("contracttobeapproved", acsContentId.toString());
// Start a new Process Instance in APS
ProcessInstancesApi apiInstance = new ProcessInstancesApi();
CreateProcessInstanceRepresentation startRequest = new CreateProcessInstanceRepresentation();
startRequest.setName("Review and Approve Contract - " + new Date());
startRequest.setProcessDefinitionId(processDefId);
startRequest.setValues(formFieldValues);
ProcessInstanceRepresentation result = null;
try {
result = apiInstance.startNewProcessInstanceUsingPOST(startRequest);
} catch (ApiException e) {
logger.error("Exception when calling ProcessInstancesApi#startNewProcessInstanceUsingPOST [responseCode=" +
e.getCode() + "][responseBody=" + e.getResponseBody() + "]");
e.printStackTrace();
}
return result;
}
}When ACS is running it does not by default know anything about any APS servers. There is no way of configuring APS servers in any ACS UI like you can do for ACS in APS. So we need to come up with custom configuration about where the APS server is running and what process we want to start. We do this in the repo-extension/src/main/resources/alfresco/module/repo-extension/alfresco-global.properties file:
aps.host=process
aps.port=8080
aps.username=admin@app.activiti.com
aps.pwd=admin
aps.processdef.key=ReviewandApprove
aps.tenant.alfresco.repository.source=alfresco-1-ACS 6This will tell the ACS container to talk to the APS container on the Docker Network URL process:8080. ACS will login to the APS ReST API with the admin@app.activiti.com/admin credentials. We also configure what process definition key we are going to use when starting the process, or more specifically what key to use when looking up the latest process definition version to use when starting the process instance (this is the only field you need to update, set it to aps.processdef.key=ReviewandApprove). Finally we also configure what tenant that has been set up in APS to represent the ACS Repository.
These properties are injected into the IncomingContractFileEventHandler class so we have access to them when using the APS ReST API Java Client. The registerEventHandlers method registers the onAddFile method to be called whenever a new file is uploaded or created in the Alfresco Repository.
The onAddFile method will first grab the Alfresco Node Reference for the file that was uploaded and put into the fileRef variable. It will then set up the APS ReST API Java Client with the APS endpoint and the APS credentials.
Then the getProcessDefId method is called to get the latest process definition version for the ReviewandApprove process definition key. The uploadAcsContent2Aps method is then called to set up a link in APS to the uploaded file in ACS. This link will be provided when we start the process. You can also upload the ACS file content to APS, but that does not make sense to me as I don’t like to duplicate content in multiple places.
Finally we start the process from the startProcess method. Note how we set the contracttobeapproved process variable to represent the uploaded file. This variable was defined in the Start Form for the process.
Before we can build the new code we need to update the Spring XML configuration a bit and remove the Web Script definition as the Web Script was converted to an event handler. And we need to add a new Spring bean definition for the event handler.
First, open up the alfresco-dbp-sample-solution-test/repo-extension/src/main/resources/alfresco/module/repo-extension/context/webscript-context.xml file and remove the Web Script definition that we changed to an event handler so it to look like this:
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE beans PUBLIC '-//SPRING//DTD BEAN//EN' 'http://www.springframework.org/dtd/spring-beans.dtd'>
<beans>
<bean id="webscript.alfresco.tutorials.helloworld.get"
class="org.alfresco.reposamples.HelloWorldWebScript"
parent="webscript">
</bean>
</beans>Then, open up the alfresco-dbp-sample-solution-test/repo-extension/src/main/resources/alfresco/module/repo-extension/context/service-context.xml file and add a new Spring bean definition for the event handler as follows:
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE beans PUBLIC '-//SPRING//DTD BEAN//EN' 'http://www.springframework.org/dtd/spring-beans.dtd'>
<beans>
<!-- A simple class that is initialized by Spring -->
<bean id="org.alfresco.repo-extension.exampleBean"
class="org.alfresco.reposamples.Demo"
init-method="init"/>
<!-- A simple module component that will be executed once -->
<bean id="org.alfresco.repo-extension.exampleComponent"
class="org.alfresco.reposamples.DemoComponent"
parent="module.baseComponent">
<property name="moduleId" value="repo-extension"/> <!-- See module.properties -->
<property name="name" value="exampleComponent"/>
<property name="description" value="A demonstration component"/>
<property name="sinceVersion" value="1.0-SNAPSHOT"/>
<property name="appliesFromVersion" value="1.0-SNAPSHOT"/>
<property name="nodeService" ref="NodeService"/>
<property name="nodeLocatorService" ref="nodeLocatorService"/>
</bean>
<bean id="org.alfresco.repo-extension.DemoAction"
class="org.alfresco.reposamples.DemoRepoAction"
parent="action-executer">
</bean>
<bean id="org.alfresco.reposamples.incomingContractFileEventHandler"
class="org.alfresco.reposamples.IncomingContractFileEventHandler"
init-method="registerEventHandlers">
<property name="policyComponent">
<ref bean="policyComponent"/>
</property>
<property name="serviceRegistry">
<ref bean="ServiceRegistry"/>
</property>
<property name="apsHost" value="${aps.host}"/>
<property name="apsPort" value="${aps.port}"/>
<property name="apsUsername" value="${aps.username}"/>
<property name="apsPwd" value="${aps.pwd}"/>
<property name="apsProcessDefKey" value="${aps.processdef.key}"/>
<property name="apsTenantAlfrescoRepositorySource" value="${aps.tenant.alfresco.repository.source}"/>
</bean>
</beans>
That’s all we need to do for the file upload event handler. To test that it loads properly execute the following command from the parent directory of the project:
alfresco-dbp-sample-solution mbergljung$./update-repo-container.sh
This will do the following:
- Build the Repository Extension so we are sure to get the latest changes (contained in the repo-extension project)
- Stop the Repository Container (i.e. the one that runs alfresco.war)
- Remove the Repository Container - so we can build a new image
- Assemble/Aggregate all Repository extension JARs into the target/extensions directory (we could have more than one repo extension, this is handled by the repo-aggregator-docker project)
- Build a new Repository Docker Image with the Extension JAR(s) applied (handled by the Dockerfile contained in the repo-aggregator-docker project)
- Start the Repository Container based on newly built Image
Testing the Solution with Alfresco Share and Activiti App
We can now test the whole solution by using Alfresco Share and Activiti App. When that is done and working we can move on to develop the ADF based UI.
Start in the APS App Designer | Apps and make sure you have created a Process App with the Process Definition included:
Make sure the Process Application has been published.
Then double check that you have the Alfresco Repository tenant configured as we talked about before:
Now jump over to Alfresco Share and upload a file into for example the Guest Home folder:
After a successful upload you will see the following logs in the runner console indicating that the process has been started:
content_1 | 2018-10-19 13:15:57,081 INFO [alfresco.reposamples.IncomingContractFileEventHandler] [http-nio-8080-exec-4] onAddFile: A new contract file with ref (workspace://SpacesStore/c6ceee37-ed06-4416-9111-5f1bb8d131b6) was just created in folder (workspace://SpacesStore/33d83941-87a6-4d44-94c7-94b856a0b1fa)
content_1 | 2018-10-19 13:15:57,510 INFO [alfresco.reposamples.IncomingContractFileEventHandler] [http-nio-8080-exec-4] Starting process [processDefinitionId=ReviewandApprove:3:7504][contentId=5006]
Now, go back to the APS App and click on the "Review and Approve" app, it should take you immediately to displaying the new "Set Contract Metadata User Task":
Fill in the Contract ID (e.g. C001 - format should be as per content model constraint ^C\d{3}$) and Contract Name (e.g. ACME Contract # 1) fields and select Security Classification.
Then click the APPROVE button so the service task is kicked off. It will create the new folder hierarchy, move file, and set metadata. You should see the following in the logs:
process_1 | 01:23:43 [http-nio-8080-exec-7] INFO com.activiti.extension.bean.SetContractTypeJavaDelegate - Alfresco Repo ID, should match what's configured in Tenant section: [ID=1]
process_1 | 01:23:43 [http-nio-8080-exec-7] INFO com.activiti.extension.bean.SetContractTypeJavaDelegate - Alfresco Repo endpoint: [endpointRepoUrl=http://content:8080/alfresco][secret=null]
process_1 | 01:23:43 [http-nio-8080-exec-7] INFO com.activiti.extension.bean.SetContractTypeJavaDelegate - ACS ReST API base URL: http://content:8080/alfresco/api/-default-/public/alfresco/versions/1
process_1 | 01:23:43 [http-nio-8080-exec-7] INFO com.activiti.extension.bean.SetContractTypeJavaDelegate - Created new folder [name=Contract Management]class NodeEntry {
process_1 | entry: class Node {
process_1 | id: 8ea6f77a-0796-4dc3-8d78-49ac44a54190
process_1 | name: Contract Management
process_1 | nodeType: cm:folder
process_1 | isFolder: true
process_1 | isFile: false
process_1 | isLocked: false
process_1 | modifiedAt: 2018-10-19T13:23:43.551Z
process_1 | modifiedByUser: class UserInfo {
process_1 | displayName: Administrator
process_1 | id: admin
process_1 | }
process_1 | createdAt: 2018-10-19T13:23:43.551Z
process_1 | createdByUser: class UserInfo {
process_1 | displayName: Administrator
process_1 | id: admin
process_1 | }
process_1 | parentId: ef7dd0e7-318d-4229-9a2c-aef8fd169c6b
process_1 | isLink: null
process_1 | content: null
process_1 | aspectNames: [cm:titled, cm:auditable]
process_1 | properties: {cm:title=Management of Contracts, cm:description=All files related to approved contracts}
process_1 | allowableOperations: null
process_1 | path: null
process_1 | permissions: null
process_1 | }
process_1 | }
process_1 | 01:23:43 [http-nio-8080-exec-7] INFO com.activiti.extension.bean.SetContractTypeJavaDelegate - Created new folder [name=2018]class NodeEntry {
process_1 | entry: class Node {
process_1 | id: ea2a4bee-c7a9-404e-8c29-1a270421a736
process_1 | name: 2018
process_1 | nodeType: cm:folder
process_1 | isFolder: true
process_1 | isFile: false
process_1 | isLocked: false
process_1 | modifiedAt: 2018-10-19T13:23:43.823Z
process_1 | modifiedByUser: class UserInfo {
process_1 | displayName: Administrator
process_1 | id: admin
process_1 | }
process_1 | createdAt: 2018-10-19T13:23:43.823Z
process_1 | createdByUser: class UserInfo {
process_1 | displayName: Administrator
process_1 | id: admin
process_1 | }
process_1 | parentId: 8ea6f77a-0796-4dc3-8d78-49ac44a54190
process_1 | isLink: null
process_1 | content: null
process_1 | aspectNames: [cm:titled, cm:auditable]
process_1 | properties: {cm:title=Contracts for a Year, cm:description=All files related to approved contracts for year 2018}
process_1 | allowableOperations: null
process_1 | path: null
process_1 | permissions: null
process_1 | }
process_1 | }
process_1 | 01:23:44 [http-nio-8080-exec-7] INFO com.activiti.extension.bean.SetContractTypeJavaDelegate - Created new folder [name=Oct]class NodeEntry {
process_1 | entry: class Node {
process_1 | id: 9d3ce7f7-0e4f-41dc-8c2e-bba1f8b9eaf2
process_1 | name: Oct
process_1 | nodeType: cm:folder
process_1 | isFolder: true
process_1 | isFile: false
process_1 | isLocked: false
process_1 | modifiedAt: 2018-10-19T13:23:44.003Z
process_1 | modifiedByUser: class UserInfo {
process_1 | displayName: Administrator
process_1 | id: admin
process_1 | }
process_1 | createdAt: 2018-10-19T13:23:44.003Z
process_1 | createdByUser: class UserInfo {
process_1 | displayName: Administrator
process_1 | id: admin
process_1 | }
process_1 | parentId: ea2a4bee-c7a9-404e-8c29-1a270421a736
process_1 | isLink: null
process_1 | content: null
process_1 | aspectNames: [cm:titled, cm:auditable]
process_1 | properties: {cm:title=Contracts for 1 month, cm:description=All contract files for month Oct}
process_1 | allowableOperations: null
process_1 | path: null
process_1 | permissions: null
process_1 | }
process_1 | }
process_1 | 01:23:44 [http-nio-8080-exec-7] INFO com.activiti.extension.bean.SetContractTypeJavaDelegate - ACS file: ACME Contract X1.pdf, created: 2018-10-19 13:15:57.436
process_1 | 01:23:44 [http-nio-8080-exec-7] INFO com.activiti.extension.bean.SetContractTypeJavaDelegate - Moved node [name=ACME Contract X1.pdf]class NodeEntry {
process_1 | entry: class Node {
process_1 | id: c6ceee37-ed06-4416-9111-5f1bb8d131b6
process_1 | name: ACME Contract X1.pdf
process_1 | nodeType: cm:content
process_1 | isFolder: false
process_1 | isFile: true
process_1 | isLocked: false
process_1 | modifiedAt: 2018-10-19T13:23:44.150Z
process_1 | modifiedByUser: class UserInfo {
process_1 | displayName: Administrator
process_1 | id: admin
process_1 | }
process_1 | createdAt: 2018-10-19T13:15:56.265Z
process_1 | createdByUser: class UserInfo {
process_1 | displayName: Administrator
process_1 | id: admin
process_1 | }
process_1 | parentId: 9d3ce7f7-0e4f-41dc-8c2e-bba1f8b9eaf2
process_1 | isLink: null
process_1 | content: class ContentInfo {
process_1 | mimeType: application/pdf
process_1 | mimeTypeName: Adobe PDF Document
process_1 | sizeInBytes: 868300
process_1 | encoding: UTF-8
process_1 | }
process_1 | aspectNames: [cm:versionable, cm:titled, cm:auditable, cm:author]
process_1 | properties: {cm:versionLabel=1.0, cm:author=Neil Bendov, cm:versionType=MAJOR}
process_1 | allowableOperations: null
process_1 | path: null
process_1 | permissions: null
process_1 | }
process_1 | }
process_1 | 01:23:44 [http-nio-8080-exec-7] INFO com.activiti.extension.bean.SetContractTypeJavaDelegate - Got node [name=ACME Contract X1.pdf]class NodeEntry {
process_1 | entry: class Node {
process_1 | id: c6ceee37-ed06-4416-9111-5f1bb8d131b6
process_1 | name: ACME Contract X1.pdf
process_1 | nodeType: cm:content
process_1 | isFolder: false
process_1 | isFile: true
process_1 | isLocked: false
process_1 | modifiedAt: 2018-10-19T13:23:44.150Z
process_1 | modifiedByUser: class UserInfo {
process_1 | displayName: Administrator
process_1 | id: admin
process_1 | }
process_1 | createdAt: 2018-10-19T13:15:56.265Z
process_1 | createdByUser: class UserInfo {
process_1 | displayName: Administrator
process_1 | id: admin
process_1 | }
process_1 | parentId: 9d3ce7f7-0e4f-41dc-8c2e-bba1f8b9eaf2
process_1 | isLink: null
process_1 | content: class ContentInfo {
process_1 | mimeType: application/pdf
process_1 | mimeTypeName: Adobe PDF Document
process_1 | sizeInBytes: 868300
process_1 | encoding: UTF-8
process_1 | }
process_1 | aspectNames: [cm:versionable, cm:titled, cm:auditable, cm:author]
process_1 | properties: {cm:versionLabel=1.0, cm:author=Neil Bendov, cm:versionType=MAJOR}
process_1 | allowableOperations: null
process_1 | path: null
process_1 | permissions: null
process_1 | }
process_1 | }
process_1 | class NodeEntry {
process_1 | entry: class Node {
process_1 | id: c6ceee37-ed06-4416-9111-5f1bb8d131b6
process_1 | name: ACME Contract X1.pdf
process_1 | nodeType: acme:contract
process_1 | isFolder: false
process_1 | isFile: true
process_1 | isLocked: false
process_1 | modifiedAt: 2018-10-19T13:23:44.319Z
process_1 | modifiedByUser: class UserInfo {
process_1 | displayName: Administrator
process_1 | id: admin
process_1 | }
process_1 | createdAt: 2018-10-19T13:15:56.265Z
process_1 | createdByUser: class UserInfo {
process_1 | displayName: Administrator
process_1 | id: admin
process_1 | }
process_1 | parentId: 9d3ce7f7-0e4f-41dc-8c2e-bba1f8b9eaf2
process_1 | isLink: null
process_1 | content: class ContentInfo {
process_1 | mimeType: application/pdf
process_1 | mimeTypeName: Adobe PDF Document
process_1 | sizeInBytes: 868300
process_1 | encoding: UTF-8
process_1 | }
process_1 | aspectNames: [cm:versionable, cm:titled, cm:auditable, acme:securityClassified, cm:author]
process_1 | properties: {acme:contractId=C001, acme:documentId=D57, cm:versionType=MAJOR, acme:contractName=ACME Contract # 1, cm:versionLabel=1.0, cm:author=Neil Bendov, acme:securityClassification=Client Confidential}
process_1 | allowableOperations: null
process_1 | path: null
process_1 | permissions: null
process_1 | }
process_1 | }
So we can see here all the new folders that were created and the last operation was applying the metadata.
If we jump over to Alfresco Share we should see that the file is moved from Guest Home and is now located in the month folder of the new folder hierarchy:
If we look at the Document Details page for the file we can see that the Contract Type is set and the associated properties has been applied:
JOB DONE!
Now, let’s see how we can create a UI in ADF so we can work with everything from one application.
Implementing a User Interface for the solution with ADF
The business logic for the solution is now complete and the “only” thing left to do is to implement a consistent user interface (UI) for the solution. Meaning we don’t want to login to different web applications (i.e. Share and Activiti App) with different look and feel to do the work. There should be one consistent UI where we can work with both content and process seamlessly.
We can achieve this with Alfresco Application Developer Framework (ADF), which is based on the familiar Angular JavaScript framework. ADF also provides Yeoman based code generators so we can easily get going with our new UI client.
Prerequisites
Make sure the following is set up before starting with the ADF Generator.
Verify Node.js version
The ADF Yeoman Generator will generate an Angular CLI v6.0 project. This requires Node.js version 8.9.
Check what version you have:
$ node --version
v8.6.0
In this case we need to update, which you can do as follows:
Clear NPM's cache:
$ sudo npm cache clean -f
Install a little helper called 'n':
$ sudo npm install -g n
Install latest stable Node.js version:
$ sudo n stable
$ node --version
v10.12.0
Verify that the same username and password exist in both APS and ACS
The same username and password need to exist in both ACS and APS for you to be able to login to them seamlessly from the ADF application. As APS supports only username in the email format (e.g. admin@app.activiti.com) it is easiest to just add a username in that format in ACS.
In Alfresco Share Admin Console add the user admin@app.activiti.com/admin:
Make sure user is part of Administrators (ALFRESCO_ADMINISTRATORS) so there is full access to the repository content. This is just a demo app so we can use the admin user. But in a real solution scenario you would want this user to just have access to the parts of the repository where it is going to work with content.
Generate the UI Client Project
First, make sure you got the ADF Generator installed:
$ npm install -g generator-alfresco-adf-app
If you already got it installed make sure it is the latest version:
$ npm update -g generator-alfresco-adf-app
Then stand in the folder where you want the UI client code to be generated:
alfresco-dbp-sample-solution mbergljung$ yo alfresco-adf-app
…
? Your project name alfresco-dbp-ui
? Application blueprint Process and Content Services
? Would you like to install dependencies now? Yes
adf-cli-acs-aps-template
create .editorconfig
create .npmignore
create .travis.yml
create angular.json
create docker.md
create Dockerfile
create e2e/app.e2e-spec.ts
create e2e/app.po.ts
create e2e/tsconfig.e2e.json
create karma.conf.js
create LICENSE
create nginx.conf
create package.json
create protractor-ci.conf.js
create protractor.conf.js
create proxy.conf.json
create README.md
create src/app.config.json
create src/app/app-layout/app-layout.component.css
create src/app/app-layout/app-layout.component.html
create src/app/app-layout/app-layout.component.spec.ts
create src/app/app-layout/app-layout.component.ts
create src/app/app.component.html
create src/app/app.component.scss
create src/app/app.component.spec.ts
create src/app/app.component.ts
create src/app/app.module.ts
create src/app/app.routes.ts
create src/app/apps/apps.component.css
create src/app/apps/apps.component.html
create src/app/apps/apps.component.ts
create src/app/documentlist/documentlist.component.css
create src/app/documentlist/documentlist.component.html
create src/app/documentlist/documentlist.component.spec.ts
create src/app/documentlist/documentlist.component.ts
create src/app/file-view/blob-view.component.ts
create src/app/file-view/bob-view.component.html
create src/app/file-view/file-view.component.html
create src/app/file-view/file-view.component.scss
create src/app/file-view/file-view.component.ts
create src/app/home/home.component.css
create src/app/home/home.component.html
create src/app/home/home.component.spec.ts
create src/app/home/home.component.ts
create src/app/login/login.component.css
create src/app/login/login.component.html
create src/app/login/login.component.spec.ts
create src/app/login/login.component.ts
create src/app/services/preview.service.ts
create src/app/start-process/start-process.component.html
create src/app/start-process/start-process.component.scss
create src/app/start-process/start-process.component.spec.ts
create src/app/start-process/start-process.component.ts
create src/app/stencils.module.ts
create src/app/task-details/task-details.component.css
create src/app/task-details/task-details.component.html
create src/app/task-details/task-details.component.spec.ts
create src/app/task-details/task-details.component.ts
create src/app/tasks/tasks.component.css
create src/app/tasks/tasks.component.html
create src/app/tasks/tasks.component.spec.ts
create src/app/tasks/tasks.component.ts
create src/assets/.gitkeep
create src/custom-style.scss
create src/environments/environment.prod.ts
create src/environments/environment.ts
create src/favicon-96x96.png
create src/index.html
create src/main.ts
create src/polyfills.ts
create src/test.ts
create src/tsconfig.app.json
create src/tsconfig.spec.json
create src/typings.d.ts
create tsconfig.json
create tslint.json
…
All the JavaScript libraries will be installed at this point so it might take a while…
Selecting the “Process and Content Services” blueprint generates an application that has support for both process and content ADF components.
Before we can check out the application we need to update the configuration file that is used to tell ADF where ACS and APS is running. Open the alfresco-dbp-ui/proxy.conf.json file and change it to look like this:
{
"/alfresco": {
"target": "http://localhost:8082",
"secure": false,
"changeOrigin": true
},
"/activiti-app": {
"target": "http://localhost:9080",
"secure": false,
"changeOrigin": true
}
}Now, step into the ADF application directory and start the app:
alfresco-dbp-sample-solution mbergljung$ cd alfresco-dbp-ui/
alfresco-dbp-ui mbergljung$ npm start
Access the application at http://localhost:4200:
Click on the Key icon to login and use admin@app.activiti.com/admin as credentials, you should see available Process Apps, including the one you created earlier on:
Click on the Folder icon to see Repository content:
Double click on the Contract Management folder that was created before when we tested the solution. Continue navigating down to the month folder:
We can double click on the file to preview it. However we cannot see the custom contract metadata we applied. We would need to create a custom form for that.
Implementing a form to view Contract File Metadata
By default we only see standard out-of-the-box metadata in ADF for a file. We want to also be able to view the Contract metadata that is applied when a file is approved via the "Review and Approve" process.
We can use the ADF Form component for this. It is very flexible and can display metadata based on an Alfresco Node Reference, a Workflow Task ID, in memory form etc. And the form can be designed with the APS Form Designer. Read more about the <adf-form component in the official docs.
We will actually design two new forms. One for generic file content (i.e. cm:content) that will display the properties for a node as follows:
This form has been designed in APS and the JSON for it downloaded and added to the app. Notice that only two fields are updatable, the title (cm:title) and the description (cm:description). There is a SAVE button at the bottom of the form that can be used to save any updates to the title and description fields. The rest of the fields are readonly as they are controlled by the Alfresco Repository.
The second form will display metadata for contract files and it will look like this:
Next we will have a look at how a form can be created and exported from APS. But first let's just generate the module and component files that we need.
Generating a new document details page and setting up routing
Let's generate a separate details page component to use for the ADF Form implementation. We can easily create a page component with the Angular CLI tool. Standing in the alfresco-dbp-sample-solution directory do the following:
alfresco-dbp-sample-solution mbergljung$ cd alfresco-dbp-ui/src/app
app mbergljung$ ng g component document-details-page --module app
CREATE src/app/document-details-page/document-details-page.component.scss (0 bytes)
CREATE src/app/document-details-page/document-details-page.component.html (40 bytes)
CREATE src/app/document-details-page/document-details-page.component.spec.ts (721 bytes)
CREATE src/app/document-details-page/document-details-page.component.ts (328 bytes)
UPDATE src/app/app.module.ts (2309 bytes)
This creates a document details page that we can use for the contract metadata display via ADF Form. The new component is added to the main app module.
Let’s configure the routing table with the new details page, open up the src/app/app.routes.ts file and update it with the new route to the document details page:
import { ModuleWithProviders } from '@angular/core';
import { RouterModule, Routes } from '@angular/router';
import { AuthGuardBpm, AuthGuardEcm } from '@alfresco/adf-core';
import { HomeComponent } from './home/home.component';
import { LoginComponent } from './login/login.component';
import { AppsComponent } from './apps/apps.component';
import { TasksComponent } from './tasks/tasks.component';
import { TaskDetailsComponent } from './task-details/task-details.component';
import { DocumentlistComponent } from './documentlist/documentlist.component';
import { StartProcessComponent } from './start-process/start-process.component';
import { AppLayoutComponent } from './app-layout/app-layout.component';
import { FileViewComponent } from './file-view/file-view.component';
import { BlobViewComponent } from './file-view/blob-view.component';
import { DocumentDetailsPageComponent } from './document-details-page/document-details-page.component';
export const appRoutes: Routes = [
{ path: 'files/:nodeId/view', component: FileViewComponent, canActivate: [AuthGuardEcm], outlet: 'overlay' },
{ path: 'preview/blob', component: BlobViewComponent, outlet: 'overlay', pathMatch: 'full' },
{
path: '',
component: AppLayoutComponent,
children: [
{
path: '',
component: HomeComponent
},
{
path: 'home',
component: HomeComponent
},
{
path: 'apps',
component: AppsComponent,
canActivate: [ AuthGuardBpm ]
},
{
path: 'apps/:appId/tasks',
component: TasksComponent,
canActivate: [ AuthGuardBpm ]
},
{
path: 'apps/:appId/tasks/:taskId',
component: TaskDetailsComponent,
canActivate: [ AuthGuardBpm ]
},
{
path: 'apps/:appId/start-process',
component: StartProcessComponent,
canActivate: [ AuthGuardBpm ]
},
{
path: 'documentlist',
component: DocumentlistComponent,
canActivate: [ AuthGuardEcm ]
},
{
path: 'documentdetails/:node-id',
component: DocumentDetailsPageComponent,
canActivate: [ AuthGuardEcm ]
}
]
},
{
path: 'login',
component: LoginComponent
}
];
export const routing: ModuleWithProviders = RouterModule.forRoot(appRoutes);
When one of the items in the document list is clicked, and we select the new Details content action, the http://localhost:4200/documentdetails/<node-id> URL will be invoked taking the user to the new DocumentDetailsPageComponent.
Creating and exporting a cm:content metadata form from APS
Before we go ahead and create a form that will display specific contract file metadata we will create a form that can be used for all other non-contract files (i.e. cm:content typed files).
Although it is technically possible to hand craft the JSON that defines the form, it is highly unlikely that you will do that as it is so much easier to do it via the form designer in Alfresco Process Services (APS). You can access the form designer via the App Designer | Forms | Create Form:
After clicking Create new form the following form designer will be displayed:
Here you can drag and drop controls into the form canvas and build up your form layout. While doing this it is important to think about the form field IDs that you are using. They will be used to fill the form with data when creating the details page component class. Our form will display some essential Alfresco Node metadata and look like this:
If we look at one of the form fields, such as Secondary Types (aspects), it has the following configuration:
The important config here is the ID, which has the value secondarytypes. When we fill in the data for the form field in our details page component class we will refer to this field ID. That way the ADF Form Service can match our data with a form field.
To export the JSON for a form we use the Export Form (download) button in the upper right corner:
The source code for this article have the exported JSON for this form in the src/app/repository/alfresco-node-form.ts file. Copy it into your project.
As you can see in the file, the form JSON has been wrapped inside a class and a static function (and it has been reformatted):
export class AlfrescoNodeForm {
static getDefinition(): any {
return {
'id': 3011,
'name': 'Alfresco Node Form',
'description': 'Display basic data for an Alfresco Repository node.',
'version': 1,
'lastUpdatedBy': 1,
'lastUpdatedByFullName': ' Administrator',
'lastUpdated': '2017-10-20T12:34:42.995+0000',
'stencilSetId': 0,
'referenceId': null,
'formDefinition': {
'tabs': [],
'fields': [
{
'fieldType': 'ContainerRepresentation',
'id': '1508502563892',
'name': 'Label',
...We will use this class in our details page component implementation.
You might have noticed that setting a field up as readonly via the APS Form Designer is not possible, at least I cannot find a way of doing it... So I have set up all readonly fields directly in the exported JSON file:
…
'fields': {
'1': [
{
'fieldType': 'FormFieldRepresentation',
'id': 'secondarytypes',
'name': 'Secondary Types',
'type': 'text',
'value': null,
'required': false,
'readOnly': true,
...
Implementing the Document Details page template
We now got the form for generic content ready, so we can start with the first version of our Document Details page. We will begin with the page template, open up the src/app/document-details-page/document-details-page.component.html template file and update it to look like this:
<adf-toolbar *ngIf="node">
<adf-toolbar-title>
<adf-breadcrumb
[folderNode]="parentFolder">
</adf-breadcrumb>
<span *ngIf="node.name">{{ node.name }}</span>
</adf-toolbar-title>
<div class="adf-toolbar--spacer"></div>
<button *ngIf="node.isFile"
mat-icon-button
matTooltip="Download this file"
(click)="onDownload($event)">
<mat-icon>file_download</mat-icon>
</button>
<button mat-icon-button
matTooltip="Delete this content item"
(click)="onDelete($event)">
<mat-icon>delete</mat-icon>
</button>
<adf-toolbar-divider></adf-toolbar-divider>
<button mat-icon-button
class="adf-viewer-close-button"
matTooltip="Close and go back to document list"
(click)="onGoBack($event)"
aria-label="Close">
<mat-icon>close</mat-icon>
</button>
</adf-toolbar>
<mat-tab-group *ngIf="node">
<!-- Currently the Preview has to be the first tab -->
<mat-tab label="Preview" *ngIf="node.isFile">
<div class="adf-not-overlay-viewer">
<adf-viewer
[showViewer]="true"
[overlayMode]="false"
[showToolbar]="false"
[fileNodeId]="node.id">
</adf-viewer>
</div>
</mat-tab>
<mat-tab label="Properties (metadata)">
<mat-card class="adf-card-container">
<adf-form
[form]="form"
[showTitle]="false"
(formSaved)="onSave($event)">
</adf-form>
</mat-card>
</mat-tab>
<mat-tab label="Versions" *ngIf="node.isFile">
<adf-version-manager [node]="node"></adf-version-manager>
</mat-tab>
</mat-tab-group>
There are quite a few properties and events that can be used to implement a form. Here we have used only the most essential ones. The following list explains the properties that you can work with (default values in parenthesis):
- There are a number of ways the form can be created, choose one of the following:
- form: this is the form model that should be used when creating the form. It is of type FormModel and contains the form design (i.e. form field configuration as per exported JSON) and form field values. Typically you can get one of these objects by using the formService.parseForm(formDefinitionJSON, data, readOnly) function. You can also feed this function with just the form definition JSON and get an empty form presented.
- taskId: the APS User Task ID that should be used to fetch the form definition JSON. A user task usually has an associated form (APS needs to be running so the form definition can be downloaded).
- showCompleteButton (true😞 should the complete button be visible for the task.
- disableCompleteButton (false😞 set this to true if the complete button should be disabled.
- nodeId: the ACS node identifier (i.e. node reference). The APS will be searched for a form that has a name that is the same as the content type of the node, such as 'cm:content' or 'cm:folder'. The form will then be populated and displayed.
- formId: the form definition JSON will be fetched from APS based on this form ID.
- formName: the form definition JSON will be fetched from APS based on this form name.
- data: use this to supply the form field values. It is of the type FormValues. You need this if you do not supply data when invoking the formService.parseForm(formDefinitionJSON) function.
- saveMetadata (false😞 can be used to store an APS task form as metadata in ACS. A new node will be created in ACS with all the task field data as metadata.
- path: the path in the Alfresco Repository where the new node should be stored.
- nameNode: the name of the new node.
- showTitle (true😞 Show a form title with a refresh button in the right corner of title.
- showRefreshButton (true😞 If you don't want the refresh button in the title set this to false. The refresh button is relevant if the form data comes directly from a task instance or node instance and can be updated 'live' via the APS or ACS backing services. It is not relevant for example in our scenario in this article where form data is only updated via the app.
- showSaveButton (true😞 Set this to false if the Save button should be hidden. We could potentially use this to hide the button if nothing has changed.
- readOnly (false😞 should the whole form be readonly. Used when you don't pass in this info to the formService.parseForm(formDefinitionJSON) function.
- showValidationIcon (true😞 does not seem to be used...
- showDebugButton (false😞 shows debug related information if set to true.
- fieldValidators: supply your own form field validators of type FormFieldValidator.
- (formSaved😞 when the form is saved this function is called with the current FormModel. We use it in our implementation to store updated properties in the Alfresco Repository.
- (formCompleted😞 called when the user clicked the Complete button.
- (formContentClicked😞 called when content in the form is clicked.
- (formLoaded😞 this function will be called when the data has been loaded into the form fields.
- (formDataRefreshed😞 this function will be called when the data has been updated in the form fields.
- (executeOutcome😞 called after the form service has executed the outcome of a task form.
- (onError😞 called when something went wrong in the form processing.
Implementing the Document Details page component class
Now when we got the template sorted we need to also implement the backing component class. Open up the src/app/document-details-page/document-details-page.component.ts class file and update it to look like this:
import {Component, OnInit} from '@angular/core';
import {MinimalNodeEntryEntity, NodeBody} from 'alfresco-js-api';
import {ContentService, FormModel, FormService, FormValues, NodesApiService, NotificationService} from '@alfresco/adf-core';
import {ActivatedRoute, Router} from '@angular/router';
import {RepositoryContentModel} from '../repository/repository-content.model';
import {RepositoryFormFieldModel} from '../repository/repository-formfield.model';
import {AlfrescoNodeForm} from '../repository/alfresco-node-form';
@Component({
selector: 'app-document-details-page',
templateUrl: './document-details-page.component.html',
styleUrls: ['./document-details-page.component.scss']
})
export class DocumentDetailsPageComponent implements OnInit {
node: MinimalNodeEntryEntity;
parentFolder: MinimalNodeEntryEntity;
form: FormModel;
originalFormData: FormValues = {};
constructor(private router: Router,
private activatedRoute: ActivatedRoute,
private nodeService: NodesApiService,
private contentService: ContentService,
private formService: FormService,
protected notificationService: NotificationService) {
}
ngOnInit() {
const nodeId = this.activatedRoute.snapshot.params['node-id'];
this.nodeService.getNode(nodeId).subscribe((entry: MinimalNodeEntryEntity) => {
this.node = entry;
this.nodeService.getNode(this.node.parentId).subscribe((parentNode: MinimalNodeEntryEntity) => {
this.parentFolder = parentNode;
});
this.setupFormData(this.node);
});
}
private setupFormData(node: MinimalNodeEntryEntity) {
console.log('setupFormData: ', node.id);
// Content file specific props
let size = 'N/A';
let mimetype = 'N/A';
if (node.isFile) {
size = '' + node.content.sizeInBytes;
mimetype = node.content.mimeTypeName;
}
// Aspect properties
let title = '';
let desc = '';
if (node.aspectNames.indexOf(RepositoryContentModel.TITLED_ASPECT_QNAME) > -1) {
title = node.properties[RepositoryContentModel.TITLE_PROP_QNAME];
desc = node.properties[RepositoryContentModel.DESC_PROP_QNAME];
}
// Author can be available if extracted during ingestion of content
let author = '';
if (node.properties && node.properties[RepositoryContentModel.AUTHOR_PROP_QNAME]) {
author = node.properties[RepositoryContentModel.AUTHOR_PROP_QNAME];
}
this.originalFormData = {
'id': node.id,
'type': node.nodeType,
'secondarytypes': node.aspectNames,
'creator': node.createdByUser.displayName,
'created': node.createdAt,
'modifier': node.modifiedByUser.displayName,
'modified': node.modifiedAt,
'sizebytes': size,
'mimetype': mimetype,
'title': title,
'description': desc,
'author': author
};
// Read and parse the form that we will use to display the node
const formDefinitionJSON: any = AlfrescoNodeForm.getDefinition();
const readOnly = false;
this.form = this.formService.parseForm(formDefinitionJSON, this.originalFormData, readOnly);
}
onGoBack($event: Event) {
this.navigateBack2DocList();
}
onDownload($event: Event) {
const url = this.contentService.getContentUrl(this.node.id, true);
const fileName = this.node.name;
this.download(url, fileName);
}
onDelete($event: Event) {
this.nodeService.deleteNode(this.node.id).subscribe(() => {
this.navigateBack2DocList();
});
}
onSave(form: FormModel) {
const titleChanged = this.form.values[RepositoryFormFieldModel.TITLE_FIELD_NAME] &&
(this.form.values[RepositoryFormFieldModel.TITLE_FIELD_NAME] !==
this.originalFormData[RepositoryFormFieldModel.TITLE_FIELD_NAME]);
const descriptionChanged = this.form.values[RepositoryFormFieldModel.DESC_FIELD_NAME] &&
(this.form.values[RepositoryFormFieldModel.DESC_FIELD_NAME] !==
this.originalFormData[RepositoryFormFieldModel.DESC_FIELD_NAME]);
if (titleChanged || descriptionChanged) {
// We got some non-readonly metadata that has been updated
console.log('Updating [cm:title = ' + this.form.values[RepositoryFormFieldModel.TITLE_FIELD_NAME] + ']');
console.log('Updating [cm:description = ' + this.form.values[RepositoryFormFieldModel.DESC_FIELD_NAME] + ']');
// Set up the properties that should be updated
const nodeBody = <NodeBody> {};
nodeBody[RepositoryContentModel.NODE_BODY_PROPERTIES_KEY] = {};
nodeBody[RepositoryContentModel.NODE_BODY_PROPERTIES_KEY][RepositoryContentModel.TITLE_PROP_QNAME] = this.form.values['title'];
nodeBody[RepositoryContentModel.NODE_BODY_PROPERTIES_KEY][RepositoryContentModel.DESC_PROP_QNAME] = this.form.values['description'];
// Make the call to Alfresco Repo and update props
this.nodeService.updateNode(this.node.id, nodeBody).subscribe(
() => {
this.notificationService.openSnackMessage(
`Updated properties for '${this.node.name}' successfully`,
4000);
}
);
} else {
this.notificationService.openSnackMessage(
`Node '${this.node.name}' was NOT saved, nothing has been changed!`,
4000);
}
}
private navigateBack2DocList() {
this.router.navigate(['/documentlist'],
{
queryParams: {current_folder_id: this.parentFolder.id},
relativeTo: this.activatedRoute
});
}
private download(url: string, fileName: string) {
if (url && fileName) {
const link = document.createElement('a');
link.style.display = 'none';
link.download = fileName;
link.href = url;
document.body.appendChild(link);
link.click();
document.body.removeChild(link);
}
}
}This is quite a bit of code to take in at first. But let’s break it down. There are basically two things here, member variables that are mapped in the template, like node, and event handler methods like onDownload() that are also mapped in the template.
Let’s look at the member variables:
- node: The content object that should be displayed in the Details page. It is of type MinimalNodeEntryEntity and it is fetched for the node-id that is passed in as URL path parameter to the details page from the list page. Will be set in the ngOnInit() method. The node-id is an Alfresco node reference and it will look something like this: 53ef6110-ed9c-4739-a520-e7b4336229c0.
- parentFolder: The parent folder object of type MinimalNodeEntryEntity that is fed to the breadcrumbs component so it can display corresponding path. Also set in the ngOnInit() method.
- originalFormData: This is an object that should be populated with the form data that will be injected into the ADF Form when it is created. It’s set up in the setupFormData method based on a MinimalNodeEntryEntity object for the node we want to display properties for.
The ngOnInit() method is implemented as follows:
ngOnInit() {
const nodeId = this.activatedRoute.snapshot.params['node-id'];
this.nodeService.getNode(nodeId).subscribe((entry: MinimalNodeEntryEntity) => {
this.node = entry;
this.nodeService.getNode(this.node.parentId).subscribe((parentNode:
MinimalNodeEntryEntity) => {
this.parentFolder = parentNode;
});
this.setupFormData(this.node);
});
}The first line uses the activatedRoute object that has been injected via the constructor. It represents the application route that was taken to get to this page and it is based on the routing table we set up earlier. We use a snapshot of the route so we can get to the parameters immediately synchronously (otherwise it would be via async call). The routing table contained the node-id parameter for the http://localhost:8080/documentdetails/<node-id> route so we can extract it here as shown.
We then fetch a MinimalNodeEntryEntity object for that node ID with the help of the NodesApiService that was injected via the constructor. This type of object is useful as it gives access to loads of data for the node. We can see that this class extends the MinimalNode class, which in turn extends the Node class that looks like this:
export class Node {
constructor(obj?: any);
id?: string;
name?: string;
nodeType?: string;
isFolder?: boolean;
isFile?: boolean;
isLocked?: boolean;
modifiedAt?: Date;
modifiedByUser?: UserInfo;
adddAt?: Date;
adddByUser?: UserInfo;
parentId?: string;
isLink?: boolean;
content?: ContentInfo;
aspectNames?: Array<string>;
properties?: any;
allowableOperations?: Array<string>;
path?: PathInfo;
permissions?: PermissionsInfo;
createdAt?: Date;
createdByUser?: UserInfo;
}
Lots of these properties are familiar to you if you have worked with Alfresco Repository Nodes before. We can use it to set up the originalFormData variable that should be fed to the form. But before we do that we also fetch the parent node for the node that is displayed. The nodeService.getNode method returns an Observable that we can subscribe to. Most of the stuff in the Angular app world is asynchronous.
The last thing that we do in the ngOnInit() method is to call the setupFormData method. This method sets up the originalFormData that we load the form with and then uses the Form Service to parse the form definition JSON we got from the AlfrescoNodeForm.getDefinition() call.
We can see how we can extract any repository node property from any content model via the node.properties['cm:title'] notation.
If you do some JavaScript debugging you will see that a MinimalNodeEntryEntity object instance looks something like this:
event:
entry:
allowableOperations:(3) ["delete", "update", "updatePermissions"]
content:
encoding:"UTF-8"
mimeType:"application/vnd.oasis.opendocument.text"
mimeTypeName:"OpenDocument Text (OpenOffice 2.0)"
sizeInBytes:32472
__proto__:Object
createdAt:Tue Sep 12 2017 15:25:17 GMT+0100 (BST) {}
createdByUser:{id: "admin@app.activiti.com", displayName: "ADF User"}
id:"35f91e69-2ece-4b21-9f98-2f8dfbd0613f"
isFile:true
isFolder:false
modifiedAt:Tue Sep 12 2017 15:25:17 GMT+0100 (BST) {}
modifiedByUser:{id: "admin@app.activiti.com", displayName: "ADF User"}
name:"Installing Alfresco 4.0 on CentOS 5 using existing MySQL 5.odt"
nodeType:"cm:content"
parentId:"80ca4db6-85dd-43aa-a3d9-84c2fe321aaa"
path:
elements:(2) [{…}, {…}]
isComplete:true
name:"/Company Home/Guest Home"
__proto__:Object
properties:
cm:author:"mbergljung"
cm:lastThumbnailModification:(2) ["doclib:1505226318981", "pdf:1505310067960"]
cm:versionLabel:"1.0"
cm:versionType:"MAJOR”
The next part of the details page component implementation contains the content action handler methods. It starts with the onGoBack method:
onGoBack($event: Event) {
this.navigateBack2DocList();
}
private navigateBack2DocList() {
this.router.navigate(['../'],
{
queryParams: { current_folder_id: this.parentFolder.id },
relativeTo: this.activatedRoute
});
}When you click the close button in the right corner of the toolbar it will take you back to the document list, which is represented by the parent Document List page. When this is done you want to display the document list for the folder you came from, not the folder list for /Company Home. This is done by adding a current folder query parameter (i.e. current_folder_id) to the URL. The good thing with query parameters is that they don’t require a new route definition. We will see later how we can make use of this query parameter in the Document list page component.
The next two event handler methods onDownload and onDelete are straightforward using ADF services to get to the content to be downloaded and to delete the node.
The final thing we need to do is implement the onSave handler for the Save button. We can save the new properties values via the this.nodeService.updateNode call. This call takes the node identifier, which is the Alfresco Node Reference as a string, and an object of type NodeBody.
The NodeBody class looks like this:
export class NodeBody {
constructor(obj?: any);
name?: string;
nodeType?: string;
aspectNames?: Array<string>;
properties?: {
[key: string]: string;
};
relativePath?: string;
association?: NodeBodyAssociation;
secondaryChildren?: Array<ChildAssociationBody>;
targets?: Array<AssociationBody>;
permissions?: PermissionsBodyUpdate;
}So as we can see, we can set up a NodeBody structure as follows to store our new property values:
const nodeBody = <NodeBody> {
'properties':
{
'cm:title': this.titleProp.value,
'cm:description': this.descProp.value
}
};If the call to updateNode is successful, then we display a message with the notification service.
Note that if you plan to update the number of aspects (i.e. secondary types) for a node, then you must first take the existing aspects and add the new one to that list. You cannot just set one aspect to be added, it would replace all existing ones.
Last thing to note here is that I have started to create a Repository Form Field model that will contain all constants for form field names etc. Create the src/app/repository/repository-formfield.model.ts file and put the following into it:
/**
* Form field identifiers when working with ADF Forms
*/
export class RepositoryFormFieldModel {
static readonly TITLE_FIELD_NAME = 'title';
static readonly DESC_FIELD_NAME = 'description';
}Same thing for the Repository Content Model QNames, we will create a file with constants for content model properties, types, aspects etc. Create the src/app/repository/repository-content.model.ts file and put the following into it:
/**
* Alfresco Content Model QNames
* and other Alfresco related constants
*/
export class RepositoryContentModel {
static readonly TITLED_ASPECT_QNAME = 'cm:titled';
static readonly TITLE_PROP_QNAME = 'cm:title';
static readonly DESC_PROP_QNAME = 'cm:description';
static readonly AUTHOR_PROP_QNAME = 'cm:author';
static readonly NODE_BODY_PROPERTIES_KEY = 'properties';
}For the preview to work in this details page we also need add the following CSS to the src/app/document-details-page/document-details-page.component.scss file:
.adf-not-overlay-viewer {
height: 900px;
}Adding the Document Details content action to the Document List page
The Document Details page is now finished and we can create a content action in the List page that takes you to it. We want to implement a Details content action that looks like this:
When the user clicks the Details action for an item in the list the document details page route should be activated (e.g. http://localhost:4200/documentdetails/6bcdad1d-f28f-44ee-9476-b7fdcc964451). First thing we need to do is define the new content action. Open up the src/app/documentlist/documentlist.component.html template file and update it with the new Document Details action:
<adf-toolbar>
<adf-toolbar-title>
<adf-breadcrumb
class="files-breadcrumb"
root="Personal Files"
[target]="documentList"
[folderNode]="documentList.folderNode">
</adf-breadcrumb>
</adf-toolbar-title>
<div class="adf-toolbar--spacer"></div>
<adf-upload-button
[rootFolderId]="documentList.currentFolderId || '-root-'"
[adf-node-permission]="'create'"
(success)="uploadSuccess($event)">
</adf-upload-button>
</adf-toolbar>
<adf-document-list
#documentList
[currentFolderId]="getDocumentListCurrentFolderId()"
(preview)="showPreview($event)"
[contentActions]="true">
<content-actions>
<content-action
title="Details"
[icon]="'insert_drive_file'"
[target]="'document'"
(execute)="onDocumentDetails($event)">
</content-action>
</content-actions>
</adf-document-list>
<adf-file-uploading-dialog></adf-file-uploading-dialog>At the same time as we add the action, we also take the opportunity to add the getDocumentListCurrentFolderId function that will return current folder ID of the Document List. This function will take care of returning a default folder ID, if no navigation has happened yet, or the current folder ID.
The component class then need to implement the so called custom content action with the onDocumentDetails() function. It’s custom as it doesn’t have an out-of-the-box handler implementation, such as ‘delete’. Instead we point to the action implementation via the (execute) event. The new action handler looks as follows, add it to the end of the src/app/documentlist/documentlist.component.ts file:
import { Component, ViewChild, Input, OnInit } from '@angular/core';
import { NotificationService } from '@alfresco/adf-core';
import { DocumentListComponent } from '@alfresco/adf-content-services';
import { PreviewService } from '../services/preview.service';
import { MinimalNodeEntryEntity } from 'alfresco-js-api';
import { ActivatedRoute, Router } from '@angular/router';
import { map } from 'rxjs/internal/operators';
@Component({
selector: 'app-documentlist',
templateUrl: './documentlist.component.html',
styleUrls: ['./documentlist.component.css']
})
export class DocumentlistComponent implements OnInit {
currentFolderId = '-root-'; // By default display /Company Home
@Input()
showViewer = false;
nodeId: string = null;
@ViewChild('documentList')
documentList: DocumentListComponent;
constructor(private notificationService: NotificationService,
private preview: PreviewService,
protected activatedRoute: ActivatedRoute,
protected router: Router) {
}
ngOnInit(): void {
// Check if we should display some other folder than root
const currentFolderIdObservable = this.activatedRoute
.queryParamMap
.pipe(map(params => params.get('current_folder_id')));
currentFolderIdObservable.subscribe((id: string) => {
if (id) {
this.currentFolderId = id;
this.documentList.loadFolderByNodeId(this.currentFolderId);
}
});
}
uploadSuccess(event: any) {
this.notificationService.openSnackMessage('File uploaded');
this.documentList.reload();
}
showPreview(event) {
const entry = event.value.entry;
if (entry && entry.isFile) {
this.preview.showResource(entry.id);
}
}
onGoBack(event: any) {
this.showViewer = false;
this.nodeId = null;
}
getDocumentListCurrentFolderId() {
return this.currentFolderId;
}
onDocumentDetails(event: any) {
const entry: MinimalNodeEntryEntity = event.value.entry;
console.log('DocumentlistComponent: Navigating to details page for document: ' + entry.name);
this.router.navigate(['/documentdetails', entry.id]);
}
}We also implement the logic that will extract the current_folder_id query parameter so we can load the document list with the correct folder data. For this to work a bit better when you click in the left navigation we also need to update the src/app/app-layout/app-layout.component.html file so it passes in the current_folder_id as query parameter like this when you navigate to the document list page:
…
<a mat-list-item class="adf-sidenav-link" [routerLink]="['/documentlist']" [queryParams]="{ current_folder_id: '-root-' }">
<mat-icon matListIcon class="sidenav-menu-icon">folder_open</mat-icon>
<div class="sidenav-menu-label" *ngIf="!isMenuMinimized()">Documents</div>
</a>
...We are now ready to test the new Document Details page implementation for generic files (i.e. standard cm:content typed files). Jump over to the ADF App UI and upload a file into a folder. Then go to the Details page for it. Then click on the Properties tab, you should see the generic form with the standard cm:content metadata.
Creating and exporting an acme:contract metadata form from APS
So we now got the details page working for files that has been typed with the generic content type cm:content. But we cannot see contract metadata for a file that has been processed by our Review and Approve workflow (i.e. acme:contract typed files). Let’s create a form that will look like this for Contract files:
Access the form designer via the App Designer | Forms | Create Form:
After clicking Create new form the following form designer will be displayed:
Our form will display some essential Alfresco Node metadata plus ACME contract metadata. It will look like this:
If we look at one of the form fields, such as Alfresco Node ID, it has the following configuration:
The important config here is the ID, which has the value id. When we fill in the data for the form field in our details page component class we will refer to this field ID. That way the ADF Form Service can match our data with a form field.
To export the JSON for a form we use the Export Form (download) button in the upper right corner:
The source code for this article have the exported JSON for this form in the src/app/repository/contract-node-form.ts file. As you can see in the file, the form JSON has been wrapped inside a class and a static function (and it has been reformatted):
export class ContractNodeForm {
static getDefinition(): any {
return {
'id': 3003,
'name': 'ACME Contract Node Form',
'description': 'This is a form that will display extract contract metadata for files that has been typed as acme:contract',
'version': 1,
'lastUpdatedBy': 1,
'lastUpdatedByFullName': ' Administrator',
'lastUpdated': '2018-10-31T10:15:46.496+0000',
'stencilSetId': 0,
'referenceId': null,
'formDefinition': {
'tabs': [],
'fields': [{
'fieldType': 'ContainerRepresentation',
'id': 'acmecontract',
'name': 'ACME Contract',
...We will use this class in our details page component implementation.
You might have noticed that setting a field up as readonly via the APS Form Designer is not possible, at least I cannot find a way of doing it... So I have set up all readonly fields directly in the exported JSON file:
…
'fieldType': 'FormFieldRepresentation',
'id': 'id',
'name': 'Alfresco Node ID',
'type': 'text',
'value': null,
'required': false,
'readOnly': true,
...Now, let’s update the Document Details component class so it uses this new form for all files with type acme:contract. Open the src/app/document-details-page/document-details-page.component.ts file and update it to look like this:
import { Component, OnInit } from '@angular/core';
import { MinimalNodeEntryEntity, NodeBody } from 'alfresco-js-api';
import { ContentService, FormModel, FormService, FormValues, NodesApiService, NotificationService } from '@alfresco/adf-core';
import { ActivatedRoute, Router } from '@angular/router';
import { RepositoryContentModel } from '../repository/repository-content.model';
import { RepositoryFormFieldModel } from '../repository/repository-formfield.model';
import { AlfrescoNodeForm } from '../repository/alfresco-node-form';
import { ContractNodeForm } from '../repository/contract-node-form';
@Component({
selector: 'app-document-details-page',
templateUrl: './document-details-page.component.html',
styleUrls: ['./document-details-page.component.scss']
})
export class DocumentDetailsPageComponent implements OnInit {
node: MinimalNodeEntryEntity;
parentFolder: MinimalNodeEntryEntity;
form: FormModel;
originalFormData: FormValues = {};
constructor(private router: Router,
private activatedRoute: ActivatedRoute,
private nodeService: NodesApiService,
private contentService: ContentService,
private formService: FormService,
protected notificationService: NotificationService) { }
ngOnInit() {
const nodeId = this.activatedRoute.snapshot.params['node-id'];
this.nodeService.getNode(nodeId).subscribe((entry: MinimalNodeEntryEntity) => {
this.node = entry;
this.nodeService.getNode(this.node.parentId).subscribe((parentNode: MinimalNodeEntryEntity) => {
this.parentFolder = parentNode;
});
this.setupFormData(this.node);
});
}
private setupFormData(node: MinimalNodeEntryEntity) {
console.log('setupFormData: ', node.id);
// Content file specific props
let size = 'N/A';
let mimetype = 'N/A';
if (node.isFile) {
size = '' + node.content.sizeInBytes;
mimetype = node.content.mimeTypeName;
}
// Aspect properties
let title = '';
let desc = '';
if (node.aspectNames.indexOf(RepositoryContentModel.TITLED_ASPECT_QNAME) > -1) {
title = node.properties[RepositoryContentModel.TITLE_PROP_QNAME];
desc = node.properties[RepositoryContentModel.DESC_PROP_QNAME];
}
let securityClassification = '';
if (node.aspectNames.indexOf(RepositoryContentModel.ACME_SECURITY_CLASSIFIED_ASPECT_QNAME) > -1) {
securityClassification = node.properties[RepositoryContentModel.ACME_SECURITY_CLASSIFICATION_PROP_QNAME];
}
// Author can be available if extracted during ingestion of content
let author = '';
if (node.properties && node.properties[RepositoryContentModel.AUTHOR_PROP_QNAME]) {
author = node.properties[RepositoryContentModel.AUTHOR_PROP_QNAME];
}
// If this is a ACME contract file, then fish out those properties
let contractid = '';
let contractName = '';
if (node.nodeType === RepositoryContentModel.ACME_CONTRACT_TYPE_QNAME) {
contractid = node.properties[RepositoryContentModel.ACME_CONTRACT_ID_PROP_QNAME];
contractName = node.properties[RepositoryContentModel.ACME_CONTRACT_NAME_PROP_QNAME];
}
this.originalFormData = {
'id': node.id,
'type': node.nodeType,
'secondarytypes': node.aspectNames,
'creator': node.createdByUser.displayName,
'created': node.createdAt,
'modifier': node.modifiedByUser.displayName,
'modified': node.modifiedAt,
'sizebytes': size,
'mimetype': mimetype,
'title': title,
'description': desc,
'author': author,
'contractid': contractid,
'contractname': contractName,
'securityclassification': securityClassification
};
let formDefinitionJSON;
if (node.nodeType === RepositoryContentModel.ACME_CONTRACT_TYPE_QNAME) {
formDefinitionJSON = ContractNodeForm.getDefinition();
} else {
formDefinitionJSON = AlfrescoNodeForm.getDefinition();
}
// Read and parse the form that we will use to display the node
const readOnly = false;
this.form = this.formService.parseForm(formDefinitionJSON, this.originalFormData, readOnly);
}
onGoBack($event: Event) {
this.navigateBack2DocList();
}
onDownload($event: Event) {
const url = this.contentService.getContentUrl(this.node.id, true);
const fileName = this.node.name;
this.download(url, fileName);
}
onDelete($event: Event) {
this.nodeService.deleteNode(this.node.id).subscribe(() => {
this.navigateBack2DocList();
});
}
onSave(form: FormModel) {
const titleChanged = this.form.values[RepositoryFormFieldModel.TITLE_FIELD_NAME] &&
(this.form.values[RepositoryFormFieldModel.TITLE_FIELD_NAME] !==
this.originalFormData[RepositoryFormFieldModel.TITLE_FIELD_NAME]);
const descriptionChanged = this.form.values[RepositoryFormFieldModel.DESC_FIELD_NAME] &&
(this.form.values[RepositoryFormFieldModel.DESC_FIELD_NAME] !==
this.originalFormData[RepositoryFormFieldModel.DESC_FIELD_NAME]);
if (titleChanged || descriptionChanged) {
// We got some non-readonly metadata that has been updated
console.log('Updating [cm:title = ' + this.form.values[RepositoryFormFieldModel.TITLE_FIELD_NAME] + ']');
console.log('Updating [cm:description = ' + this.form.values[RepositoryFormFieldModel.DESC_FIELD_NAME] + ']');
// Set up the properties that should be updated
const nodeBody = <NodeBody> {};
nodeBody[RepositoryContentModel.NODE_BODY_PROPERTIES_KEY] = {};
nodeBody[RepositoryContentModel.NODE_BODY_PROPERTIES_KEY][RepositoryContentModel.TITLE_PROP_QNAME] = this.form.values['title'];
nodeBody[RepositoryContentModel.NODE_BODY_PROPERTIES_KEY][RepositoryContentModel.DESC_PROP_QNAME] = this.form.values['description'];
// Make the call to Alfresco Repo and update props
this.nodeService.updateNode(this.node.id, nodeBody).subscribe(
() => {
this.notificationService.openSnackMessage(
`Updated properties for '${this.node.name}' successfully`,
4000);
}
);
} else {
this.notificationService.openSnackMessage(
`Node '${this.node.name}' was NOT saved, nothing has been changed!`,
4000);
}
}
private navigateBack2DocList() {
this.router.navigate(['/documentlist'],
{
queryParams: {current_folder_id: this.parentFolder.id},
relativeTo: this.activatedRoute
});
}
private download(url: string, fileName: string) {
if (url && fileName) {
const link = document.createElement('a');
link.style.display = 'none';
link.download = fileName;
link.href = url;
document.body.appendChild(link);
link.click();
document.body.removeChild(link);
}
}
}There is one new import of the ContractNodeForm and the rest of the changes are done in the setFormData function to set up the contract metadata and to select what form to use.
You also need to add a couple of constants to the src/app/repository/repository-content.model.ts file:
/**
* Alfresco Content Model QNames
* and other Alfresco related constants
*/
export class RepositoryContentModel {
static readonly TITLED_ASPECT_QNAME = 'cm:titled';
static readonly TITLE_PROP_QNAME = 'cm:title';
static readonly DESC_PROP_QNAME = 'cm:description';
static readonly AUTHOR_PROP_QNAME = 'cm:author';
static readonly ACME_CONTRACT_TYPE_QNAME = 'acme:contract';
static readonly ACME_CONTRACT_ID_PROP_QNAME = 'acme:contractId';
static readonly ACME_CONTRACT_NAME_PROP_QNAME = 'acme:contractName';
static readonly ACME_SECURITY_CLASSIFIED_ASPECT_QNAME = 'acme:securityClassified';
static readonly ACME_SECURITY_CLASSIFICATION_PROP_QNAME = 'acme:securityClassification';
static readonly NODE_BODY_PROPERTIES_KEY = 'properties';
}Testing the Solution with the ADF Application
We can now test the whole solution by using the new custom ADF application. Start in the ADF application by clicking on the Documents navigation icon, then double click on the Guest Home folder:
Now, upload a file that will represent a contract document:
After a successful upload you will see the following logs in the runner console indicating that the process has been started:
content_1 | 2018-10-19 13:15:57,081 INFO [alfresco.reposamples.IncomingContractFileEventHandler] [http-nio-8080-exec-4] onAddFile: A new contract file with ref (workspace://SpacesStore/c6ceee37-ed06-4416-9111-5f1bb8d131b6) was just created in folder (workspace://SpacesStore/33d83941-87a6-4d44-94c7-94b856a0b1fa)
content_1 | 2018-10-19 13:15:57,510 INFO [alfresco.reposamples.IncomingContractFileEventHandler] [http-nio-8080-exec-4] Starting process [processDefinitionId=ReviewandApprove:3:7504][contentId=5006]
This kicks off the "Review and Approve" workflow with the file attached. To see what review and approve processes that are running click on the Apps navigation item:
From here click in the Review and Approve process app to see any process instances:
Click on the process instance to see the “Set Contract Metadata User Task”:
Fill in the Contract ID (e.g. C002 - format should be as per content model constraint ^C\d{3}$) and Contract Name (e.g. Contract 125 X) fields and select Security Classification.
Then click the APPROVE button so the service task is kicked off. It will create the new folder hierarchy (if not already exist), move file, and set metadata. You should see a lot of logging going on as when we did run the solution the first time:
process_1 | 02:00:16 [http-nio-8080-exec-1] INFO com.activiti.extension.bean.SetContractTypeJavaDelegate - Found node [name=Contract Management]class NodeEntry {
process_1 | entry: class Node {
process_1 | id: 8ea6f77a-0796-4dc3-8d78-49ac44a54190
process_1 | name: Contract Management
process_1 | nodeType: cm:folder
process_1 | isFolder: true
process_1 | isFile: false
process_1 | isLocked: false
process_1 | modifiedAt: 2018-10-19T13:23:43.551Z
process_1 | modifiedByUser: class UserInfo {
process_1 | displayName: Administrator
process_1 | id: admin
process_1 | }
process_1 | createdAt: 2018-10-19T13:23:43.551Z
process_1 | createdByUser: class UserInfo {
process_1 | displayName: Administrator
process_1 | id: admin
process_1 | }
process_1 | parentId: ef7dd0e7-318d-4229-9a2c-aef8fd169c6b
process_1 | isLink: null
process_1 | content: null
process_1 | aspectNames: null
process_1 | properties: null
process_1 | allowableOperations: null
process_1 | path: null
process_1 | permissions: null
process_1 | }
process_1 | }
process_1 | 02:00:16 [http-nio-8080-exec-1] INFO com.activiti.extension.bean.SetContractTypeJavaDelegate - Found node [name=2018]class NodeEntry {
...
So we can see here all the new folders that were created (or found if already existed) and the last operation was applying the metadata.
If we now click on the Documents list and navigate to Contract Management | 2018 | Oct we should see that the file is gone from Guest Home and now located in the month folder of the new folder hierarchy:
If we look at the Document Details page for the file we can see that the Contract Type is set and the associated properties have been applied:
ALL DONE!
Debugging
When working with a bigger project where there are a lot of code you most likely will need to do some debugging from time to time. Here is a link to an article that explains how to debug Repository Java extensions. And here is a link to an article about debugging Activiti Java extensions.
Hot Reloading
When doing a lot of Java coding it’s beneficial to not have to restart the container every time you have built a new version of your Java extension. See this article for information about how to hot reload Repository Java extensions. And see this article for how to hot reload Activiti Java extensions.
