Tuesday, January 31, 2017

How to Change the Alfresco Share Landing Page for all Users

In Alfresco 5.1.x, it’s easy for users to change their own home page. The Use Current Page option in the user menu can be used to change the logged in user’s home page to the current page. And, the home page can also be reset back to the user’s dashboard with the selection of the Use My Dashboard option.

But, what if you want all of your Alfresco users to use the same landing page when they log in to Alfresco Share? Perhaps you’d like it to be your corporate site dashboard or a heavily-used site folder? Instead of having your users individually change their home page, an admin user can easily make a global change for all users like this:
1.      Open the TOMCAT/webapps/share/site-index.jsp file for editing.

a.       Look for the following lines at the bottom of the file:

    // redirect to site or user dashboard as appropriate
     String siteName = request.getParameter("site");
        if (siteName == null || siteName.length() == 0)
        // Get and forward to user's home page
        SlingshotUserFactory slingshotUserFactory =
                (SlingshotUserFactory) FrameworkUtil.getServiceRegistry().getUserFactory();
        String userHomePage = slingshotUserFactory.getUserHomePage(context, userid);
        response.sendRedirect(request.getContextPath() + userHomePage);
        // forward to site specific dashboard page
        response.sendRedirect(request.getContextPath() + "/page/site/" + URLEncoder.encode(siteName) +  "/dashboard");

b.      Set the "siteName" variable to your preferred landing page site name, for example:

  String siteName = request.getParameter("site");
     siteName = "formtek";

      c.       If you want your site dashboard to be the new landing page, you’re done editing the file.                        However, if you want your new landing page to be a folder in your site, you’ll need to make                  one more change to replace “dashboard” in the following line with the document library                        folder of  your choice:

 response.sendRedirect(request.getContextPath() + "/page/site/" +    URLEncoder.encode(siteName) + "/dashboard");

In this example, I’m using the “Policies and Procedures” folder in the site’s document library:

 response.sendRedirect(request.getContextPath() + "/page/site/" +  URLEncoder.encode(siteName) +  "/documentlibrary#filter=path%7C%2FPolicies%2520and%2520Procedures%7C&page=1");

NOTE: To get the correct folder syntax, you can navigate to the folder in Alfresco Share and copy the folder syntax from the browser address bar.

d.      Save your changes and close the file.

2.      Restart Alfresco for the changes to take effect.

Now, when a user logs in to Alfresco Share, the user will be redirected to your newly configured landing page. Here are two different results for the above examples:

The configured site dashboard is the new landing page:

The configured site folder is the new landing page:

It is important to note that if your new landing page restricts site membership (as in the case of the “private” example site above), non-members would see the following upon login:

Clicking the “Back to My Dashboard” button redirects unprivileged users to their own home page. To eliminate this scenario, changes would need to be made to verify site membership and only redirect site members to the new landing page. (Perhaps the discussion of a future post.)

Wednesday, January 25, 2017

Restricting Availability of Alfresco Dashlets by Group

There are two kinds of dashboards in Alfresco Share: User and Site dashboards.  By default, after logging into Share, the user is presented with a customizable dashboard page.  The dashboard page is made up of dashlets that can be arranged using the Customize User Dashboard page, as shown here. Site dashboard pages can be similarly arranged and customized by the site managers.

Developers are able to create new dashlets that can be added to the list of available dashlets. A dashlet is composed of a number of files, one of which is called the descriptor file.  The descriptor file is a brief XML document that describes the name, description and availability information about the dashlet.

Alfresco documentation describes how the <family> tag can be used in the descriptor to specify which of the two dashboards the dashlet can appear: on the user, site, or both of the dashboards.

The family tag can take the following values:
  • user-dashlet - for use on the User Dashboard
  • site-dashlet - for use on the Site Dashboard
  • dashlet - for use on either User or Site Dashboards
But, there is another use for the family tag which isn't well documented.  The family tag can also be used to restrict availability of a dashlet by group. In that case, the name of the group is included in the family tag, like this:


Here we refer to the Alfresco administrators group called ALFRESCO_ADMINISTRATORS.  Note that the group name used within Alfresco code prefixes all names with GROUP_. We see the group is referenced here as GROUP_ALFRESCO_ADMINISTRATORS, even though it is displayed as ALFRESCO_ADMINISTRATORS in the Group Browser of the Share UI.

Now, let's consider a specific case. When developing the Formtek Peer Association Extension, we had the need for a dashlet to be available only to administrators from their user dashboards. To enforce both restrictions, we used the following dashlet descriptor file with two family tag elements:

   <shortname>Remove Peer Association</shortname>  
   <description>Removes Formtek Peer Association Metadata</description>  

Thursday, December 22, 2016

Alfresco: API to Delete a Specific Document Version

Version 2.3 of the Formtek Version Browser for Alfresco 5.1 was released this week.  A new feature in this release is a delete action that allows users to delete specific versions of a document.

The Delete Version action is shown highlighted by the red box in the screenshot shown here:

This same functionality can be accessed programmatically.

Installation of the Version Browser also activates two different APIs for deleting a version: either as a REST webscript service call or by using an Alfresco server-side Javascript.  I'll describe briefly here how that functionality can be accessed.

GET REST Service Call

Versions can be deleted with the following GET REST webscript.

Here the parameters are:
    {item_store_type}/{item_store_id}/{item_id} - The nodeRef of the document (not the specific version)
    {delversion} - The version label of the version being deleted.  Note that a hyphen is used here and not a period to separate the major from the minor part of the version label.

Here is an example that deletes version 1.0 of a document:


Running this in a browser will return with the following result:

Javascript API call

You can also use a Formtek-defined Javascript method in your server-side Javascript programming for webscripts and rules to delete a version.

The method can be called as follows:

        ftkver.delete(nodeRef, verlabel);

    nodeRef = String with the nodeRef id of the main document
    verlabel = String with the version label

This method returns a boolean that is true when the version is successfully deleted.

Note again that this functionality is not a standard Alfresco capability and available only with the Formtek Version Browser.

Wednesday, December 14, 2016

After an Alfresco upgrade or content refresh some users are unable to login.

How can it be that after an Alfresco upgrade or content refresh most users can log in but a few users are unable to log into Alfresco? It's possible that some of the data is corrupted. This could be the case if Tomcat was left running while the database backup copy was created. Whatever the reason there is a common cause that is easily verified and corrected.  

Before moving on to the verification and solution section below make sure you are in a situation where only a few selected users are unable to login. Here you go:

1. Under the Admin Tools, via the node browser, find one of users that is unable to login: Search in the node browser for “/sys:system/sys:people/ cm:UserName” using XPATH where ‘Username’ is the user’s login.

Example:  /sys:system/sys:people/cm:jsmith

2. Expand the workspace preference and locate the content url from the “cm:preferenceValues”. It should look similar to: contentUrl=store://2016/11/19/13/43/da13c437-488b-48b5-9a30-9edc85677020.bin|mimetype=text/plain|size=1974|encoding=UTF-8|locale=en_US_|id=1922

3. Now go to your contentstore folder location and make sure the listed ‘bin’ file exist in that path in the contentstore.

4. If it does not exists the user will not be able to login. So, if the file is not there create a file with the exact name as shown in the “cm:preferenceValues”bin in the corresponding directory. NOTE: If the folders don’t exist you will have to create these directories. Create a plain text file and simply put in empty json brackets; ‘{}’.

5. If it exists open it via text editor and fix the existing file by adding simple ‘{}’ json brackets.

6. Look through the rest of the values and identify any with a ‘bin’ file in the contentstore. If you find any you should verify that the file is there and contains the ‘{}’ json brackets.

NOTE: You should not have to restart Alfresco for this change to take effect. Simply have the user retest their login.

Wednesday, November 30, 2016

Using Luke to Troubleshoot Ephesoft FuzzyDB Searches

Ephesoft’s FuzzyDB feature is a great way to use values extracted from a document to retrieve an index value from a database table.
We’ve made great use of this feature to identify a vendor name in a document when the vendor’s name only appears inside a logo, and doesn’t appear in actual text.  We configured our FuzzyDB table with one column that contains the vendor name, and several other columns that contain the vendor’s address and/or unique strings from the vendor's paperwork (like a company slogan).  
When Ephesoft processes a document, it compares the text of the document to an indexed version of the contents of the address column, and returns the vendor name for the row with the best match.
Sometimes the results returned by the FuzzyDB search aren’t what we expected to find, and it can be helpful to troubleshoot the search using Luke, a Lucene tool included in the Ephesoft installation.
  1. Open Luke by running luke.bat from the following directory:  <Ephesoft-Home>\Dependencies\luke
  2. The following window should appear by default.  If not, choose File->Open Lucene Index.
  3. Browse to the path of the Lucene index you want to view, then click OK.  For Ephesoft FuzzyDB work, choose the path to your FuzzyDB table name in the following folder:<Ephesoft-Home>\SharedFolders\BC<Number>\fuzzydb-index\ephesoft\<table-name> (It’s best to open the index file in Read-Only mode, just to be safe.)
  4. This will take you to the following window:
  5. Click on the Search tab at the top, then go to the Analysis tab on the right and change the drop-down list to “org.apache.lucene.analysis.standard.StandardAnalyzer”
  6. Enter some search criteria the upper-left text box and click Search (ensure that there are no punctuation characters in your search string).
  7. Results will be displayed in the Results list.  Note the "rowID" values that are returned:
  8. Open your FuzzyDB table in a SQL tool like Heidi, and you can see that the rowID values returned from the search above map to rowID values in theFuzzyDB table:
The above procedure is useful for generic testing.  However, if you have a document in a specific batch that is giving you problems, you can use the following steps to test FuzzyDB retrieval for an entire page.
  1. On the Ephesoft server, find the HOCR.xml file for that page, then copy the HOCR value from the last line of the XML file.
  2. Paste that entire line into an editor like Notepad++ and remove all special characters (see the end of this page for an easy way to clean out special characters in Notepad++).
  3. Convert the entire string to lowercase (Edit -> Convert Case to -> Lowercase).
  4. Paste the cleaned, lowercase string into the Luke search dialog, and click Search.
What to do with Your Search Results?
When you do your page-specific search test, you may find that multiple vendor rows are being returned, or maybe you're simply getting the wrong vendor.  Typically this means that the values you've entered in the searchable columns of your FuzzyDB table aren't clear enough to return the proper result.

Edit the values in the searchable columns of the FuzzyDB table, and repeat your search. Continue editing/searching until you get the desired results.  Look for values that are unique to that vendor's paperwork, such as company name, address, ZIP code, company slogans, or distinct wording that appears on each of that vendor's documents.  You can even use personal names if the vendor's paperwork always has the same person's name on it.

When you're satisfied with the results inside Luke, make sure to do a Learn DB inside Ephesoft to recreate the Lucene indexes within Ephesoft based on the changes you've made to the FuzzyDB table.

Avoid Reserved Words in your Luke Search Expression
The words “AND” and “OR” in uppercase are reserved words in Luke.  Ending a search string with either of those words will cause an error.  Using AND or OR inside a search string is likely to return unexpected results as those words will be treated as part of the query.

Removing Special Characters in Notepad++
To remove special characters from a string in Notepad++, open the Find/Replace dialog (Ctrl+F) and click on the Replace tab.  Select the Regular Expression radio button at the bottom left, then type :punct: in the Find What field, and click the Replace All button to remove those characters (:punct: is a regular expression that will find all punctuation characters in the string).