Difference between revisions of "External Document Storage"

Latest revision as of 12:03, 24 January 2020

> Administration > Account Management > External Document Storage

If the enterprise has an external Content Management System (CMS), the platform can use it for Document Storage for File Fields and Image Fields of AgileApps Live.

Caveat

This functionality is recommended to be used by only new tenants created post the 10.6 upgrade. Enabling it in existing tenants created before 10.6 version, makes the File and Image fields unavailable. So, it is not advised that this feature be used by tenants who are on versions earlier than 10.6.

Compatibility

Any server framework which uses standard OpenCMIS specifications can be used as an External Document Storage for AgileApps File and Image Fields. You can find a list of such server frameworks at https://chemistry.apache.org/java/opencmis.html. Some prominent names are Alfresco 4.X and 5.X, LogicalDOC, Lutece, and so on.

Configuration

Configuration to Content Management System can be set by users with 'Manage Company Capabilities' enabled in their access profile. You can set the configuration by clicking on the > Administration > Account Management > External Document Storage .

Following fields are available for providing connection and authentication information to CMS:

Enabled (Checkbox to enable External Document Storage). The files and images currently stored in the AgileApps File System continue to be accessible even after you enable this option. You can perform all file operations regardless of the system where the file or image is stored. Operations include viewing, downloading, exporting, and deleting the files or images.

Note: If you switch from the CMS to the AgileApps File System, the files and images available in CMS will become inaccessible. Also, if you move from one CMS to another, the files and images stored in the former CMS will become inaccessible. For example, if you move from Alfresco to Lutece, the files and images stored in Alfresco will be inaccessible.

AtomPub URL (e.g., Alfresco AtomPub URL is http://host:port/alfresco/cmisatom)
Username - username that should be used to connect to the CMIS server.
Password - password that should be used to connect to the CMIS server.
Repository Id - This is the Unique identifier for your CMIS server repository version. Repository Id for Alfresco can be found by using the following URL,

http://<your-host-name>:<alfresco-port>/alfresco/service/enterprise/admin/admin-repositoryinfo

Repository id for Alfresco looks like 3e901a5d-b9d8-4aae-9b65-f6818dfa64bc

Root Folder Id - Root Folder Id is not a required field and if a dedicated root folder id is not provided for the tenant, the default root folder of the repository is used to store the documents. If you have multiple tenants or sandboxes in the AgileApps server, we recommend you have a dedicated root folder for each tenant.

In Alfresco, you can create a Folder at http://<your-host-name>:<alfresco-port>/share/page/repository. After creation of the Folder, use the mouse cursor to hover over the folder name in Alfresco UI to access the 'View Details' of that folder. Click on the 'View Details' link and copy the share link of the current page (Found on the right side bar). The folder id is the 'nodeRef' value present in the share link. This folder id needs to be configured in the 'Root Folder id' in AgileApps External Document Storage configuration.

For example, folder id looks like workspace://SpacesStore/4d02a41e-eda3-417b-8116-caf05f618b50

Default Document Type - This is the tenant-level default document type. The system uses this value to store any files or documents for the selected object, if it does not find any document-type mapping for the said object.

If External Document Storage is enabled, URL, Username, Password and Repository Id are required fields.

Note: If you use Alfresco as your external document storage system, then append D: to the custom document type. For example, D:<custom_document_type_name>.

Platform Behavior and User Experience

After the configuration has been set, files and images uploaded to the File Fields and Image Fields are stored in the CMS. The path used to store the documents is in the format {objectId}/{recordId}/{fieldTableColumn}/FileName under the root folder.

Clicking the file field and image field values in the record page, downloads the files from the CMS server and the user can view the file content.

Files from CMS are deleted when

a file/image is removed from the AAL record by editing the record and removing it
an object record with file/image fields is deleted forever from Recycle Bin.
a file or image field is deleted from the Object Fields page (Customization in setup).
an object is deleted forever from Recycle Bin (Customization in setup)
When a tenant is deleted and if the Root Folder Id is set in the configuration, then the given root folder and its contents are removed from CMS.
If root folder Id is not specified, then the files are not deleted when you delete the tenant. This approach is used to not accidentally delete the files in case if the default repository root folder is used for many tenants.

What is a Document Type

All CMIS objects have an object type. There are four base types, of which the following two must be supported by a repository:

cmis:document
cmis:folder

The other two base types may or may not be supported by a repository. They are:

cmis:relationship
cmis:policy

Therefore, all documents created by a customer by default are of type cmis:document. The default value becomes applicable if you have not configured or mapped any document type for the object in the External Document Storage settings. The document or files that are created as cmis:document does not support any metadata modification.

The hierarchy of custom document type mapping is as follows:

1. Object level

2. Tenant level at External Document Storage

3. cmis:document

Support for CMIS Custom Document Type

You can create documents of any custom type using a CMIS tool and can be configured in the AgileApps External Document Storage configuration screen. This feature allows you to have additional storage for any files or documents saved in AgileApps through objects or records. It also allows you to capture the metadata for the documents saved in the CMIS tool using which you can search, identify, and categorize them in the CMIS server.

Note: The application uses a read-only document-type to store any file or document uploaded by the guest users as they have limited access to the CMIS configurations. Hence, no metadata is updated for the document. However, for all other users, the system will fetch dynamically the saved or configured document type against the object.

Example Code Snippet

Following is an example of a class used to map AgileApps fields with CMIS doc properties.

@@ Line 5: / Line 5: @@
 __TOC__
 ===Caveat===
-This functionality is highly recommended to be used by only new tenants after 10.6 upgrade. Enabling it in existing tenants created before 10.6 version will make the File and Image fields usage unavailable.
+This functionality is recommended to be used by only new tenants created post the 10.6 upgrade. Enabling it in existing tenants created before 10.6 version, makes the File and Image fields unavailable. So, it is not advised that this feature be used by tenants who are on versions earlier than 10.6.
+===Compatibility===
+Any server framework which uses standard OpenCMIS specifications can be used as an External Document Storage for AgileApps File and Image Fields. You can find a list of such server frameworks at https://chemistry.apache.org/java/opencmis.html. Some prominent names are Alfresco 4.X and 5.X, LogicalDOC, Lutece, and so on.
 ===Configuration===
 Configuration to Content Management System can be set by users with 'Manage Company Capabilities' enabled in their access profile.
-Configuration can be set by clicking on the '''[[File:GearIcon.png]] > Administration > Account Management > External Document Storage''' .
+You can set the configuration by clicking on the '''[[File:GearIcon.png]] > Administration > Account Management > External Document Storage''' .
-Following fields are available for providing connection and authentication information to CMS
+Following fields are available for providing connection and authentication information to CMS:
-:* Enabled (Checkbox to enable External Document Storage)
+:* Enabled (Checkbox to enable External Document Storage). The files and images currently stored in the AgileApps File System continue to be accessible even after you enable this option. You can perform all file operations regardless of the system where the file or image is stored. Operations include viewing, downloading, exporting, and deleting the files or images.
+{{Note| If you switch from the CMS to the AgileApps File System, the files and images available in CMS will become inaccessible. Also, if you move from one CMS to another, the files and images stored in the former CMS will become inaccessible. For example, if you move from Alfresco to Lutece, the files and images stored in Alfresco will be inaccessible.}}
 :* AtomPub URL (e.g., Alfresco AtomPub URL is http://host:port/alfresco/cmisatom)
-:* Username
+:* Username - username that should be used to connect to the CMIS server.
-:* Password
+:* Password - password that should be used to connect to the CMIS server.
-:* Repository Id
+:* Repository Id - This is the Unique identifier for your CMIS server repository version. Repository Id for Alfresco can be found by using the following URL,
-:* Root Folder Id
+:::http://<your-host-name>:<alfresco-port>/alfresco/service/enterprise/admin/admin-repositoryinfo
-If External Document Storage is enabled, URL, Username, Password and Repository Id are required fields. Root Folder Id is not a required field and if dedicated root folder is not provided for this tenant, Repository's root folder will be used to store the documents.
+:::Repository id for Alfresco looks like 3e901a5d-b9d8-4aae-9b65-f6818dfa64bc
+:* Root Folder Id - Root Folder Id is not a required field and if a dedicated root folder id is not provided for the tenant, the default root folder of the repository is used to store the documents. If you have multiple tenants or sandboxes in the AgileApps server, we recommend you have a dedicated root folder for each tenant.
+:::In Alfresco, you can create a Folder at http://<your-host-name>:<alfresco-port>/share/page/repository. After creation of the Folder, use the mouse cursor to hover over the folder name in Alfresco UI to access the 'View Details' of that folder. Click on the 'View Details' link and copy the share link of the current page (Found on the right side bar). The folder id is the 'nodeRef' value present in the share link. This folder id needs to be configured in the 'Root Folder id' in AgileApps External Document Storage configuration.
+:::For example, folder id looks like workspace://SpacesStore/4d02a41e-eda3-417b-8116-caf05f618b50
+:*Default Document Type - This is the tenant-level default document type. The system uses this value to store any files or documents for the selected object, if it does not find any document-type mapping for the said object.
-===Platform Behavior, User Experience and Administration===
+If External Document Storage is enabled, URL, Username, Password and Repository Id are required fields.
-When a user logs in, the platform carries out the following sequence of activities:
+{{Note|If you use Alfresco as your external document storage system, then append D: to the custom document type. For example, D:<custom_document_type_name>.}}
-:* If their [[User]] record was created in the platform, they log in with those settings.
-:* If the user is not known to the platform, the LDAP directory is searched for a matching entry.
-::* If none is found, access is denied.
-::* If a matching entry exists, a new LDAP-enabled [[User]] record is created.
-:* Thereafter, when the user logs in, their password is validated against the LDAP directory.
-:* At the same time, any changes made to the user's LDAP settings are synchronized with the platform.
-As far as the user is concerned, therefore, they simply log in to the platform using the same
+===Platform Behavior and User Experience===
-credentials they use everywhere else.
-And as far as admins are concerned, user information is maintained in one place--the LDAP server.
+After the configuration has been set, files and images uploaded to the File Fields and Image Fields are stored in the CMS. The path used to store the documents is in the format {objectId}/{recordId}/{fieldTableColumn}/FileName under the root folder.
-Any changes made there are automatically seen by the platform.
-===Effect on User Profiles===
+Clicking the file field and image field values in the record page, downloads the files from the CMS server and the user can view the file content.
-When a user has an entry in an LDAP directory, most of their profile information is maintained in the LDAP server. The platform reads that information from the server. It can no longer be modified in the platform. The exception is profile information that is specific to the platform.
-In particular:
+Files from CMS are deleted when
-:* In the initial dialog a user sees when they log in, the '''Reset Password''' option is disabled.
+:* a file/image is removed from the AAL record by editing the record and removing it
-:* In the user's [[Personal Settings]] page, only the user's [[Team]] affiliation and default [[Application]] can be modified. Other settings can be viewed, but not changed.
+:* an object record with file/image fields is deleted forever from Recycle Bin.
-:* In the admin's [[Access Management]] > [[Users]] page:
+:* a file or image field is deleted from the Object Fields page (Customization in setup).
-::* The option to [[Users#Reset a User Password|Reset Password]] is disabled for LDAP users.
+:* an object is deleted forever from Recycle Bin  (Customization in setup)
-::* The user's [[Team]] affiliation and default [[Application]] can be modified. Other settings can be viewed, but not changed.
+:* When a tenant is deleted and if the Root Folder Id is set in the configuration, then the given root folder and its contents are removed from CMS.
+:* If root folder Id is not specified, then the files are not deleted when you delete the tenant. This approach is used to not accidentally delete the files in case if the default repository root folder is used for many tenants.
-===LDAP Address Expressions===
-In its simplest form, LDAP can be thought of as a hierarchy of directories, each of which contains entries for users and other entities. But instead of using a URL to address those directories, you use a combination of syntax elements.
-For example, consider the URL <tt><nowiki>http://yourCompany.com/united_states/california/users/yourLDAPdata</nowiki></tt>.
-<br>That path is specified in LDAP elements using the elements below:
-:*'''DC (Domain Controller)''' Used to specify the LDAP domain.
-::: For example: <tt>DC=yourCompany, DC=com</tt>, which corresponds to <tt>yourCompany.com</tt> in the URL.
-:*'''OU (Organizational Unit)''' A group that can contain other groups. (Effectively, an "intermediate" group.)
+===What is a Document Type===
-::: For example: <tt>OU=california, OU=united_states</tt>, which corresponds to the URL path <tt>/united_states/california</tt>.
+All CMIS objects have an object type. There are four base types, of which the following two must be supported by a repository:
+::*cmis:document
+::*cmis:folder
-:*'''CN (Common Name)''' A group that can contain individual entries, but which cannot contain subgroups.
+The other two base types may or may not be supported by a repository. They are:
-::: For example: <tt>CN=users</tt>, which corresponds to the final directory in the URL.
+::*cmis:relationship
-::: Within that directory, the entry <tt>yourLDAPdata</tt> can be found.
+::*cmis:policy
-===Considerations and Limitations===
+Therefore, all documents created by a customer by default are of type '''cmis:document'''. The default value becomes applicable if you have not configured or mapped any document type for the object in the External Document Storage settings. The document or files that are created as cmis:document does not support any metadata modification.
-:* '''Active Directory''' is currently supported.
-:* A single LDAP server is supported, for now.
-:* The search for a matching user does not yet span multiple groups, so a <tt>CN</tt> entry must be included either in the specification of the search directory, in the user or group directory designation, or in one of their filters. The search path cannot terminate at an Organizational Unit (<tt>OU</tt>) directory, as that would require searching the multiple subdirectories it contains.
-:* The user's Team cannot currently be configured using LDAP attributes. The default team is always used for a new user.<br>(The team setting can be changed in the platform after the user logs in.)
-:* Similarly, to give a user access to multiple applications, or to change the user's initial application modify the [[Application Access]] settings after the user has logged in to the platform.
-==Working with LDAP ==
+The hierarchy of custom document type mapping is as follows:
+:1. Object level
+:2. Tenant level at External Document Storage
+:3. cmis:document
-===Configuring LDAP ===
+===Support for CMIS Custom Document Type===
-# Examine the configuration settings below to see which individual-user attributes can be populated from LDAP.
+You can create documents of any custom type using a CMIS tool and can be configured in the AgileApps External Document Storage configuration screen. This feature allows you to have additional storage for any files or documents saved in AgileApps through objects or records. It also allows you to capture the metadata for the documents saved in the CMIS tool using which you can search, identify, and categorize them in the CMIS server.
-# If desired, create attributes for those settings in your LDAP server.
+{{Note|The application uses a read-only document-type to store any file or document uploaded by the guest users as they have limited access to the CMIS configurations. Hence, no metadata is updated for the document. However, for all other users, the system will fetch dynamically the saved or configured document type against the object.}}
-#: (If all users will have the same settings, this step is not necessary. They'll use the default settings you configure below.)
+====Example Code Snippet====
-# Go to '''[[File:GearIcon.png]] > Administration > Account Management > LDAP Configuration'''
+Following is an example of a class used to map AgileApps fields with CMIS doc properties.
-# Fill in the configuration settings
+[[File:cmis_code_snippet.png|1000px]]
-# Click '''[Save]'''
-===Configuration Settings===
-:*'''Server Type -''' The type of LDAP server. '''Active Directory''' is the default.
-:*'''Server URL -''' The server domain and optional portal. Secure portal #636 is the default.
-::: For example: <tt>our.LDAPserver:998</tt>
-::<hr width="500">
-:* '''Login DN -''' The ''Distinguished Name'' of a user that has admin privileges.
-:* '''Password -''' The admin user's password.
-::<hr width="500">
-:* '''Starting Search Directory'''
-::: A comma-separated list of <tt>DC</tt> and <tt>OU</tt> expressions that leads to the start of the search path.
-::: Optionally, include a <tt>CN</tt> directive as well, to completely specify the directory to be searched.
-::<hr width="500">
-:* '''User DN -''' Optional. An LDAP expression that designates a path to an LDAP user directory, starting from the initial directory.
-:* '''User DN Filter -''' Optional. An expression that limits the LDAP entries that will be examined.
-::: For example, use a setting like this one to exclude disabled users: <tt>!(userAccountControl=514)</tt>
-::: '''Note:''' The <tt>(objectCategory=person)</tt> and <tt>(objectClass=user)</tt> parameters do not need to be specified. They are included automatically.
-::<hr width="500">
-:* '''Group DN -''' Optional. An LDAP expression that designates a path to an LDAP "group" (distribution list) directory, starting from the initial directory.
-:* '''Group DN Filter -''' Optional. An expression that limits the LDAP entries that will be examined.
-::: For example, use a setting like this to exclude entries that include the word "test": <tt>!(mail=*test*)</tt>
-::: '''Note:''' The <tt>(objectCategory=group)</tt> parameter does not need to be specified. It is included automatically.
-::<hr width="500">
-{{:Common:SAML_LDAP_Settings}}
-<noinclude>
-[[Category:Installable Version]]
-</noinclude>
-Overview
-Ability to connect to an external Content Management System for document storage for File Fields and Image Fields of AgileApps Live.
-Please Note: This functionality is highly recommended to use only in new tenants after 10.6 upgrade. Enabling it in existing tenants (before 10.6) will make the File and Image fields usage unavailable.
-Configuration
-Configuration to Content Management System can be set by users with 'Manage Company Capabilities' enabled in their access profile.
-Configuration can be set by clicking on the Gear icon --> Administration --> Account Management --> External Document Storage
-Following fields are available for providing connection and authentication information to CMS
-Enabled (Checkbox to enable External Document Storage)
-AtomPub URL (e.g., Alfresco AtomPub URL is http://{host}:{port}/alfresco/cmisatom)
-Username
-Password
-Repository Id
-Root Folder Id
-If External Document Storage is enabled, URL, Username, Password and Repository Id are required fields. Root Folder Id is not a required field and if dedicated root folder is not provided for this tenant, Repository's root folder will be used to store the documents.
-Functionality
-After the configuration has been set, files and images uploaded to the File Fields and Image Fields are stored in the CMS. The path used to store the documents is in the format {objectId}/{recordId}/{fieldTableColumn}/FileName under the root folder.
-Clicking on file field and image field values in the record page, downloads the files from CMS server and shows it to the user.
-Files from CMS are deleted when
-a file/image is removed from the AAL record by editing the record and removing it
-an object record with file/image fields is deleted forever from Recycle Bin.
-a file or image field is deleted from the Object Fields page (Customization in setup).
-an object is deleted forever from Recycle Bin  (Customization in setup)
-When a tenant is deleted and if the Root Folder Id is set in the configuration, then the given root folder and its contents are removed from CMS.
-If root folder Id is not specified then the files are not deleted when deleting tenant. This approach is used to not accidentally delete the files in case if the default repository root folder is used for many tenants.

Search

where to start

Feedback

customize and design

resources

Tools

Personal tools