Alfresco Addon Documentation

The Docusign for Alfresco Addon allows you to manage e-signature requests from Alfresco.  It integrates with Docusign so that the signature request process is managed by Docusign while the original and signed documents are stored in your Alfresco Repository.  Furthermore a user can monitor the status of all of their signature requests from within a Signatures Dashboard in Alfresco.

Signature Request from Alfresco Content App

Docusign Email Notifications & Signature Process

Manage Signature Requests

The Docusign for Alfresco Addon allows a user to request an electronic signature for a document from within Alfresco Share or Alfresco Content App.  A signature request can be sent to Multiple Signers and the signature lifecycle then tracked directly from Alfresco.  On completion of the signature request process a copy of the signed document is downloaded from Docusign and stored in the Alfresco Repository.   The video below demonstrates the ease of using the Docusign for Alfresco addon from Alfresco Content App.

Reminders

The Docusign for Alfresco addon supports setting of Docusign Reminder notifications to be sent to signers.  Reminders to prompt signers to sign the document.  Notifications are sent to users based on a default reminder schedule or a schedule specified by the person requesting the signature.  A user can set when an initial reminder should be sent and how often to send a reminder.

Expiry

 The Docusign for Alfresco addon supports setting an expiry schedule for all signature requests.  Signature requests will automatically be removed once the request expiry date has been reached.  Signatories will be sent notifications that the expiry is approaching.  The person sending the signature request has full control to set the required reminder and expiry schedule.

Monitor Signature Requests

From within Alfresco, a Signatures Dashboard, allows a user to monitor the progress of all of their signature requests.  The Dashboard lists all of the original documents to be signed.  Users may filter signature requests by a Docusign Status such as Sent, Completed or Voided.   Once the signature request has been completed a signed document is copied from Docusign into the Alfresco Repository so that it may be maintained as a record.  A link is maintained between the original and signed document allowing a user to quickly navigate between the original sent document and the signed document. 

This section provides information on how to manage signature requests for documents in Alfresco.  It includes managing Digital Signatures from Share or Digitial Workspace.

 

Requesting a Digital Signature for a document

1. From Alfresco Content App navigate to the document you require a signature for.
2. Select the document by clicking on the document.  This highlights the document in the list view and shows actions available for the document on the top right of the page.
3. Click the Request Digital Signature action.  The Digital Signature Request Dialog is opened.  The action is available for formats that are supported by Docusign.  The action is not available if a Digital Signature has already been requested for the document.
4. The Digital Signature Request Dialog allows you to fill in the details that are required for a signature request.  Fill in the details to match your request:
   • Message Title:  This is the title of the signature request and will be the subject of the Docusign email that is sent to Recipients of the signature request.  A default value is supplied.
   • Message Body:  This is added to the body section of the Docusign email notifications sent to recipients on the signature request.  Add an appropriate message to be sent to the recipients.
   • Signed Document Destination Folder: This is the location that the signed document will be stored once the signature request has successfully completed.  By default it stores documents in the same location as the document being sent for signature.  Signed documents have _signed appended to their name so that they can be easily recognised.  You can change where you want the signed document to be stored by clicking on the folder link on the right in the field.
   • Recipient Details:  You can add one or more Recipients for Signature Requests.  A Recipient can either be requested to Sign the document or be sent a Carbon Copy (cc).  At least one Signer must be added to the request.  For each Recipient, add the Name and email address of the recipient.  The Recipients will be requested to sign the document in the order that they are added as recipients to the form.
   • Expire and Reminders:  The Digital Signature request will include values for Reminders and Expiry of the request.  To change these values click on the dropdown arrow and fill in your required values.
5. Once all required values provided, click on the Request Signature button.  The signature request will then be sent to Docusign with the document attached.  An email will be sent to the Recipients in the request to sign the document.

 

 

 

 

 

 

 

 

Multiple Recipients

Managing Recipients

1. You can add more than one Recipient to the Signature Request.  Users will be sent the signature request from Docusign in the order in which you have added them as Recipients on the Dialog.   To add a new recipient click on the Add Recipient button.
   • Select an Recipient Action.  This can either be a recipient that will Sign the document or a recipient who will be sent a Carbon Copy(cc) of the document.
   • Add the user name.
   • Add the Email address.  The format must be valid for an email address.
2. To Remove a recipient,  from the recipient list click the Remove button for the recipient you want to remove.
3. You must have at least one Recipient who will sign the document in order to finish the signature request.

Review and Expiry

Review and Expiry

1. The Request Digital Signature dialog allows you to configure when Review and Expiry Notifications will be sent to signers by Docusign.  A digital signature request will be Voided by Docusign if it is not completed when it reaches its Expiration date.   The default values for a signature request are to send notifications to signers 2 days after the Signature request was first sent and to expire the request 14 days after the request was sent.
2. Expiry:  You can set values for Expiry by clicking on the dropdown arrow. The following can be set:
   • Days until Expiry:  Update this value to set the number of days before the signature request is expired.
   • Send Warning before Expiry(days):  This value will determine when an expiry notification should be sent to users.  The default value of 2 days is applied and means that a notification will be sent to Recipient who needs to sign the document 2 days before the Signature request will expire.
3. Reminders:  You can set when reminders should be set to Recipients by clicking on the drowdown arrow.  The values that may be set are:
   • Send Reminder After(days):  Select a value for when you want the first reminder to be sent.  A reminder email will be sent from Docusign for Recipients who have not signed the document yet this number of days after the Signature request was started.
   • Send Reminder Every(days) after:  Select a value to determine how often a reminder email notification should be sent after the first reminder is sent.

Once created, the progress of a Docusign Digital Signature Request can be monitored from the Signatures dashboard in Alfresco Content App.  This allows a user to understand the current status of all requests that have been sent to Docusign.  The Signatures dashboard lists all documents that have been sent to Docusign and allows you to quickly filter them based on a Docusign envelope status such as Sent, Completed or Voided.   Any status changes in docusign, such as completion by all Recipients of their signing actions will be synchronised with the Docusign status for the document in Alfresco.  Users can therefore determine if their signature requests have been successful without the need to login to Docusign.

Signatures Dashboard

1. Signature Requests can be managed from the Signatures Dashboard.  To open the Signatures Dashboard click on the Signatures link at the bottom the left hand column in Digital Workspace.  The Digital Signatures Dashboard will show documents that are in the Sent state and therefore have not completed the signature request process yet.
2. The Digital Signatures Dashboard opens and displays details for each document that has been sent to Docusign by a Digital Signature Request.
3. Ordering:  Documents in the list are ordered by Date Sent descending by default.  You can sort the list by any column in the list.   The list of documents displayed has the following columns:
   • Name:  This shows the name of the document being sent for signature.  You can also access the document in the Repository by clicking on the name link.  This will open the document preview page for the document in its current location.
   • Request Status: This shows the current Docusign lifecycle status for the document Signature Request process.
   • Recipients:  Displays a list of Recipients.  Each Recipient includes details on the order that the Recipient was added to the Request, the Name and email of the Recipient and  finally the Recipient action (Sign or Carbon Copy (cc)).  An example is 1. Brian – bgoneill@seedim.com.au (sign)
   • Sent By:  The username of the person who requested the digital signature.
   • Sent Date:  The date the request was sent.  This is the default sort field when the Dashboard loads.
   • Completion Date:  The date the signature request was completed.  This will only be populated if a signature request has reached the completed state.

Filter by Status

The Signature Dialog can be filtered to allow a user to find signature requests and monitor their progress.  When a Signature Request is first created a document will have the Sent state.  If a Recipient has viewed the signature request but not completed the signature the status will be changed to Delivered.  If all users have signed the document the status will be set to completed.  Any signature requests that have expired without signature or been deleted in Docusign by a user will have a status of Voided.

• The default status filter value is Sent.  You can change the status by clicking on the Status filter and selecting another value.  Therefore to see all completed documents change the Status value to Completed.  The page then refreshes the list to show all signature requests that were completed through Docusign.
• To see all documents regardless of their current status select the All value from the status filter.

Filter by Requester

It is also possible to filter the displayed documents by who sent the signature request to Docusign.  The default value for the Dashboard is to display only documents with a signature request that was initiated by the current user.

• You can also filter the results to show Everyones Documents by clicking on the filter and selecting Everyones Documents.  This will display signature requests for documents that other users have requested.
• The current user however must have access to view the document for it to appear in the list.

Locate Signed Documents

It is possible to navigate to the signed document associated with a a completed the Signature Request from the Signatures Dashboard.

1. Change the Status filter to show completed documents in the Dashboard list by selecting Completed from the Status filter.
2. In the list, Select the target document that was sent for signature.
3. From the three dot (elipsis) menu select View Signed Document action.  You will then be navigated to the Document Details page for the document that has been signed.  Note:  Documents that do not have an associated signed document will show the View Signed Document link but it will be greyed out.

 

You can request for a document to be signed from Alfresco Share by following the steps described below.

1. Navigate to the desired document.

2. Hover over the document and then click on the Request Signature action.

The Digital Signature Request form is opened.  The action is available for formats that are supported by Docusign.  The action is not available if a Digital Signature has already been requested for the document.

3. The Digital Signature Request form allows you to fill in the details that are required for a signature request.  Fill in the details to match your request.

• Message Title:  This is the title of the signature request and will be the subject of the Docusign email that is sent to Recipients of the signature request. The default title is ‘Please Sign the attached document’.
• Message Body:  This is added to the body section of the Docusign email notifications sent to recipients on the signature request.  Add an appropriate message to be sent to the recipients.
• Signed Document Destination Folder: This is the location that the signed document will be stored once the signature request has successfully completed.  By default it stores documents in the same location as the document being sent for signature.  Signed documents have _signed appended to their name so that they can be easily recognised.  You can change where you want the signed document to be stored by clicking on the folder link on the right in the field.
• Recipient Details:  You can add one or more Recipients for Signature Requests.  A Recipient can either be requested to Sign the document or be sent a Carbon Copy (cc).  At least one Signer must be added to the request.  For each Recipient, add the Name and email address of the recipient.  The Recipients will be requested to sign the document in the order that they are added as recipients to the form.
• Expire and Reminders:  The Digital Signature request will include values for Reminders and Expiry of the request.  To change these values click on the dropdown arrow and fill in your required values.

4. Once all required values provided, click on the Request Signature button.  The signature request will then be sent to Docusign with the document attached.  An email will be sent to the Recipients in the request to sign the document.

Review and Expiry

1. The Digital Signature Request form allows you to configure when Review and Expiry Notifications will be sent to signers by Docusign.  A digital signature request will be Voided by Docusign if it is not completed when it reaches its Expiration date.   The default values for a signature request are to send notifications to signers 2 days after the Signature request was first sent and to expire the request 14 days after the request was sent.
2. Expiry:  You can set values for Expiry by clicking on the dropdown arrow. The following can be set:
   • Days until Expiry:  Update this value to set the number of days before the signature request is expired.
   • Send Warning before Expiry(days):  This value will determine when an expiry notification should be sent to users.  The default value of 2 days is applied and means that a notification will be sent to Recipient who needs to sign the document 2 days before the Signature request will expire.
3. Reminders:  You can set when reminders should be set to Recipients by clicking on the drowdown arrow.  The values that may be set are:
   • Send Reminder After(days):  Select a value for when you want the first reminder to be sent.  A reminder email will be sent from Docusign for Recipients who have not signed the document yet this number of days after the Signature request was started.
   • Send Reminder Every(days) after:  Select a value to determine how often a reminder email notification should be sent after the first reminder is sent.

The progress of a Docusign Digital Signature Request can be monitored from the Signatures pages in Alfresco Share.  This allows a user to understand the current status of all requests that have been sent to Docusign.  The Signatures pages lists all documents that have been sent to Docusign and allows you to quickly filter them based on a Docusign envelope status such as Sent, Completed or Voided. The Signatures menu link  is available from Alfresco Share’s main menu and is comprise of two sub menu links

• My Documents
• Everyone’s Document

 

My Documents 

The My Documents page shows signature documents sent by the logged in user and Signature document status filter defaults to Sent.

Everyone’s Document

The Everyone’s Document page shows signature documents which the logged in user has access to and sent by all users and Signature document status filter defaults to Sent.

Signature Document List

The user can filter the signature documents list by clicking on the filter on the right hand corner as shown below.

The user can click on the signature document name link to get to the document details page of the signature document in Alfresco and can go to the Signed Document by clicking on the Actions button then clicking on Go to Signed Document. An error message is show if no signed document is found.

Signature Document Status Indicators

There are signature document indicators in Alfresco Share to allow users to easily identify signature documents based on their status. The user can hover over the indicator to see actual status of the signature document.

Installing Alfresco and Share AMPs

Installing the Alfresco Docusign Angular Application (Alfresco Content App)

The following install instructions are for installing the Angular Application on the Tomcat that you are running Alfresco on. However, it does not need to be co-located with the Alfresco application and could be installed on nginx or apache web server.

• Download the alfresco-docusign.zip from the release section of the alfresco-community-docusign project in Github.
• Extract the alfresco-docusign.zip folder and copy the alfresco-docusign folder to Tomcat webapps directory.
• Update the app.config.json (in the root of the alfresco-docusign folder). Set “ecmHost”: “<URL to your Alfresco application>.eg http://localhost:8080”

Configure the Docusign for Alfresco Addon

The Docusign for Alfresco uses Docusign to manage the digital signature request process.  The addon must be configured with connection details to your companies Docusign account.  Alfresco will then use the configured details to integrate with Docusign for Signature request processing and user notifications.

See Configuring Docusign for Alfresco

 

 

1.0 Once Alfresco has started, browse to Repository > Data Dictionary.

2.0 You should see a folder called Docusign-Config. Hover over it and click on Edit Properties > All Properties. The following form is shown.

3.0 Fill in the JWT Authentication details for your Docusign Account

• Docusign Client Id (API ID): <YOUR Docusign API ID>
• Docusign User Id: <YOUR Docusign USER ID>
• Target Account:FALSE
• Docusign Auth Server URL: account.docusign.com
• Docusign Private Key

4.0 Open your Docusign Private API with your favourite text editor, copy and paste its content in the Docusign Private Key box. (Should)

5.0 Lastly hit save.

Note

Docusign Auth Server URL can be set to account-d.docusign.com for testing purposes.

Buying Items

The Alfresco Shopfront Addon turns Alfresco into an eCommerce site.  Shoppers can use Alfresco to find content by either browsing or searching and add content to a shopping cart.  Users cannot download content unless they have purchased it.  On Checkout, users are directed to a Credit Card payment checkout page so that they can pay for the content.  Once paid for the users can download or print out the content items they have purchased.

 

Managing a Shop in Alfresco

The addon assumes that you will set up a Site for the content you are selling.  This will be available to users of the Shopfront addon if they are a member of the Site.  You may also setup multiple sites if you want to categorise your items into different shop types, eg one selling Books and another selling Images.

An item may be purchased by a shopper through the Alfresco Shopfront application if:

1. They have access to read the content in a Site to which they are a member.
2. The SKUItem aspect has been added to the content item and a price applied.

Creating a Shop Site

The following steps may be used to create a Shop.  It is assumed you will carry out these steps using Share or the ACA application.

• The first step in selling your content is to setup an Alfresco Site (eg My Exhibition) and add any shoppers you want as members to the Site.  Their Role should be set to Consumer.
• In the Document Library for the My Exhibition Site add the content you want users to purchase.  You can add any folder structure you want.  Shoppers will be able to browse through the folder structure or search to find content.
• For each item being sold add the SkuItem aspect and set the price for the item.  You could set the aspect and a default price for each item in your library by adding an apply aspect rule to the top level folder of the library which also sets the price metadata field to your default price.
• Note:  It is important that shoppers only have Consumer access to any content you are selling.  If a user  has consumer access or able to other Sites then they will be able to purchase items from those Sites and potentially change content if their permission in that content allows.

 

 

Project Setup

The frontend solution is developed using Angular  by customising the Alfresco Content Application.  A library called seedim-cart-ext was created and includes configuration for the Alfresco Content App and any additional components, services etc required to create the Shop functionality.  The Stripe Library and Angular Shop Libraries were included as dependencies of the library project and installed in the Alfresco Content Application.

Repository

The solution includes a custom content model with supporting Share forms and a number of webscripts required for Stripe payment which are backed by a service.   The Angular app will call these webscripts as required when a user Checks out and pays for their content via Stripe.   The customisations have been built using the SDK v 4.3.

Stripe Integration

The solution uses Stripe Checkout to manage credit card payments.  Credit Card details are not stored in Alfresco and payment forms are managed by Stripe.   The Cart Checkout button click action results in the Angular application sending a request to an Alfresco Webscript (StripeSessionWebscript) to create a Stripe Session.   The Stripe Session is created from the backend to ensure that the Stripe private key is not accessible from the frontend application and also to ensure that a user cannot change the price for items in their cart that they will purchase.  The StripeSessionWebscript creates a Session in Stripe  (a session includes a list of the items , their price, quantity etc.) and passes back the sessionId to the Angular app running on the users browser.  The browser then redirects to Stripe Checkout using the sessionId. A credit card payment is then managed by Stripe Checkout which collects the credit card details and manages the payment.  Once the payment has been successful, Stripe Checkout responds to Alfresco using the success url configured in the Stripe Session.  An Alfresco Webscript (StripeCheckoutSuccessWebscript) has been configured to service requests on the Success URL.  The StripeCheckoutSuccessWebscript receives the sessionId for the successful payment and a status for the payment.  If the payment has been successful it copies all items from the users cart into the /<company-home>/cart/userid folder.  We copy files to this folder to ensure that the content will be available to users even if the original content that they selected is deleted or moved.

Installing Alfresco AMPs

This requires the installation of the Repository and Share amps.

• Download the required AMPs from the Alfresco-Shopfront Github project https://github.com/boneill/Alfresco-Shop/releases
• Stop Alfresco
• Copy cart-platform-1.0-SNAPSHOT.amp to $AlfrescoHome/amps
• Copy cart-share-1.0-SNAPSHOT.ampto $AlfrescoHome/amps_share
• Run <AlfrescoHome>/bin/apply_amps.sh -force
• Restart Alfresco and verify that the install has been successful by adding the SKUItem Aspect to a content item in your Repository

Installing the Alfresco Shopfront Angular Application

The following install instructions are for installing the Angular  Application on the Tomcat that you are running Alfresco on.  However, it does not need to be co-located with the Alfresco application and could be installed on nginx or apache web server.

• Download the alfresco-shopfront.zip from Github
• Extract the alfresco-shopfront.zip folder and copy the alfresco-shopfront folder to Tomcat webapps directory.
• Update the app.config.json (in the root of the alfresco-shopfront folder).  set “ecmHost”: “<URL to your Alfresco application>.  eg http://localhost:8080”

Configuring Stripe Connection

The step includes providing configuration options for Alfresco to be able to connect to Stripe for accepting Credit Card Payments.  You must setup a Stripe account prior to configuring Alfresco to connect to it.  Stripe provides private and public API keys to manage secure connections.  Stripe provides both Test and Production Keys.  We strongly advise you to test the addon using your Test Stripe keys.  (see https://stripe.com/) for details no setting up and managing your Stripe account.

The following values should be configured in alfresco-global.properties on your Alfresco

• server.seedim.shop.stripe.apiPrivateKey=$YOUR_STRIPE_API_PRIVATEKEY

Keep this secret as it is your private access key to Stripe.  See https://stripe.com/docs/keys to understand how to access and manage your stripe api keys.

• seedim.shop.stripe.taxRateId=$YOUR_STRIPE_TAXRATEID

You can create a Tax Rate in Stripe.  A Tax Rate once created is given a unique Key.  The key once configured will be used by Stripe to add the tax to the purchased items to determine the required payment.  See https://stripe.com/docs/billing/taxes/tax-rates for more information on setting up and managing stripe tax rates.

• seedim.shop.app.url=$YOUR_ALFRESCO_URL

This is is used by stripe to connect back to your Angular Application once a payment has been processed.  For production mode this must be over ssl/https.  eg https://localhost:4200

Instructions for building from Source are included in the Readme file in the Github Repository https://github.com/boneill/Alfresco-Shop

The github repository includes the Angular project and the Share and Alfresco projects.