Export Mania 2017 - Webdrawer

This is the fourth of four posts related to the exportation of records from Content Manager.  Here I'll review a little of the feature functionality within Webdrawer.  You may wish to review the first three posts before continuing below (DataPort, Tag & Task, Record Addin).

The out-of-the-box webdrawer interface provides three opportunities to download an electronic attachment.  Each of these options will direct the user's browser to a URL that delivers the attachment to the browser.  The name of the downloaded file will be the suggested file name property.  

In the screenshot below you can see the download link (appears as 'Document') to the right.  The same link is provided within the viewer, which appears when you select the Preview link. 

Record Detail Page download link

The downloaded file name in this example ends up being "2017-09-28_9-31-37.png".  

The third option exists as an option in the configuration file.  The default setting is "Metadata", but you can change this to "Document".  You could also change it to preview (which shows you the preview, which then provides a download link).  

If I make this change (to Document) then clicking on a link in the search results page results in the file being downloaded.  

I can't say I find that very useful, but it is what it is.  I'll revert this back to a metadata link and then explore options. 

One quick win is to add the "download" attribute to a link.  This works for Chrome and Firefox for sure, but if you're using Internet Explorer STOP IT.  I modified my resultsList.cshtml file (located in the Views/Shared directory) and added a new column with a new button.

To accomplish this I made three changes.  First I added a new column in the table header row, like shown below.

Next I created a variable that contains my desired file name...

var desiredFileName = record.GetPropertyOrFieldString("RecordNumber") + "." + record.GetPropertyOrFieldString("RecordExtension");

Then I added my column, as shown below...

Now these links will download the file using my desired convention!  Next I should go ahead and add a "Download All" link at the top.  That button uses jquery to iterate all of the buttons I added and clicks each one.

Download All clicks all download buttons sequentially

The javascript for this is below.    

function downloadFiles() {
    $('a:not([download=""])').each(function() {
        if ( this.href.indexOf('/Record/') > 0 && this.id.indexOf('.') > 0 ) {
            this.click();
        }
    });
}

In order for it to work, you must also add the desiredFileName value into the anchor's ID property.

<a id="@desiredFileName" download="@desiredFileName" href="@recordUrl">Download</a>

I should also give a meta-data file though too, no?  To accomplish this I add a button at the top and have it call "downloadMetadata".  

The meta-data file includes the title and record number, but it could include anything you want...

To get this to work I first needed to give myself a way to access each row in the results table, as well as a way to access the meta-data values.  I did this by decorating the row with a class and the column values with IDs.  The screenshot below shows these two modifications.

Lastly, I added a new javascript function into the webdrawer.js file.  I've included it below for reference.

function downloadMetadata() {
    var data = [['Title','Number']];
    $('tr.record').each(function() {
        var title = $(this).find('#RecordTitle').text();
        var number = $(this).find('#RecordNumber').text();
        data.push([title, number]);
    });
    var csvContent = "data:text/csv;charset=utf-8,";
    data.forEach(function(infoArray, index){

       dataString = infoArray.join('\t');
       csvContent += index < data.length ? dataString+ "\n" : dataString;

    }); 
    var encodedUri = encodeURI(csvContent);
    var link = document.createElement("a");
    link.setAttribute("href", encodedUri);
    link.setAttribute("download", "meta-data.csv");
    document.body.appendChild(link);
    link.click(); 
}

So much more can be done, like zipping all the results via JSZip.  As mentioned before, I could also include all results of the search, if necessary.  Hopefully this gives the OP some ideas about how to tackle their business requirement.

Export Mania 2017 - Record Addin

This is the third of four posts trying to tackle how to achieve the export of a meta-data file along with electronic documents.  We need/want to have the electronic documents to have the record number in the file names, instead of the standard (read: oddball) naming conventions of the various features.  In this post I'll show how to create a custom record addin that achieves the requirement.

So let's dive right on in!

---

I created a new C# Class library, imported the CM .Net SDK (HP.HPTRIM.SDK), and created an Export class that will implement the ITrimAddin interface.

Next I'll use the Quick Action feature of Visual Studio to implement the interface.  It generates all of the required members and methods, but with exceptions for each.  I immediately reorganized what was generated and update it so that it does not throw exceptions.

Collapsed appearance of the class

I find it helpful to organize the members and methods into regions reflective of the features & functionality.  For this particular add-in I will ignore the "Save and Delete Events" and "Field Customization" regions.  Currently my private members and public properties regions look like shown below.

#region Private members
private string errorMessage;
#endregion
 
#region Public Properties
public override string ErrorMessage => errorMessage;
#endregion

If I expand my Initialization region I see two methods: Initialise and Setup.  Initialise is invoked the first time the add-in is loaded within the client.  Setup is invoked when a new object is added.  For now I don't truly need to do anything in either, but in the future I would use the initialise method to load any information needed for the user (maybe I'd fetch the last extraction path from the registry, a bunch of configuration data from somewhere in CM, etc).

#region Initialization
public override void Initialise(Database db)
{
}
public override void Setup(TrimMainObject newObject)
{
}
#endregion

Next I need to tackle the external link region.  There are two types of methods in this region: ones that deal with the display of menu links and the others that actually perform an action.  My starting code is shown below.  

#region External Link
public override TrimMenuLink[] GetMenuLinks()
{
    return null;
}
public override bool IsMenuItemEnabled(int cmdId, TrimMainObject forObject)
{
    return false;
}
public override void ExecuteLink(int cmdId, TrimMainObject forObject, ref bool itemWasChanged)
{
 
}
public override void ExecuteLink(int cmdId, TrimMainObjectSearch forTaggedObjects)
{
}
#endregion

First I'll tackle the menu links.  The TrimMenuLink class, shown below, is marked as abstract.  This means I need to create my own concrete class deriving from it. 

Note that the constructor is marked protected.  Thankfully, because of that, I can eventually do some creative things with MenuLink (maybe another blog post someday).  For now I'll just add a class to my project named "ExportRecordMenuLink".  I apply the same process to it once it's generated, giving me the results below.

using HP.HPTRIM.SDK;
 
namespace CMRamble.Addin.Record.Export
{
    public class ExportRecordMenuLink : TrimMenuLink
    {
        public override int MenuID => 8001;
 
        public override string Name => "Export Record";
 
        public override string Description => "Exports records to disk using Record Number as file name";
 
        public override bool SupportsTagged => true;
    }
}

Now that I've got a Menu Link for my add-in, I go back and to my main class and make a few adjustments.  First I might as well create a private member to store an array of menu links.  Then I go into the intialise method and assign it a new array (one that contains my new addin).   Last, I have the GetMenuLinks method return that array.  

private TrimMenuLink[] links;
 
public override void Initialise(Database db)
{
    links = new TrimMenuLink[1] { new ExportRecordMenuLink() };
}
public override TrimMenuLink[] GetMenuLinks()
{
    return links;
}

The IsMenuItemEnabled method will be invoked each time a record is "selected" within the client.  For my scenario I want to evaluate if the object is a record and if it has an electronic document attached.  Though I also need to ensure the command ID matches the one I've created in the ExportRecordMenuLink.

public override bool IsMenuItemEnabled(int cmdId, TrimMainObject forObject)
{
    return (links[0].MenuID == cmdId && forObject.TrimType == BaseObjectTypes.Record && ((HP.HPTRIM.SDK.Record)forObject).IsElectronic);
}

Almost done!  There are two methods left to implement, both of which are named "ExecuteLink".  The first deals with the invocation of the add-in on one object.  The second deals with the invocation of the add-in with a collection of objects.  I'm not going to waste time doing fancy class design and appropriate refactoring.... so pardon my code.  

public override void ExecuteLink(int cmdId, TrimMainObject forObject, ref bool itemWasChanged)
{
    HP.HPTRIM.SDK.Record record = forObject as HP.HPTRIM.SDK.Record;
    if ( (HP.HPTRIM.SDK.Record)record != null && links[0].MenuID == cmdId )
    {
        FolderBrowserDialog directorySelector = new FolderBrowserDialog() { Description = "Select a directory to place the electronic documents", ShowNewFolderButton = true };
        if (directorySelector.ShowDialog() == DialogResult.OK)
        {
            string outputPath = Path.Combine(directorySelector.SelectedPath, $"{record.Number}.{record.Extension}");
            record.GetDocument(outputPath, false, string.Empty, string.Empty);
        }
    }
}

In the code above I prompt the user for the destination directory (where the files should be placed).  Then I formulate the output path and extract the document.  I should be removing any invalid characters from the record number (slashes are acceptable in the number but not on the disk), but again you can do that in your own implementation.

I repeat the process for the next method and end up with the code shown below.

public override void ExecuteLink(int cmdId, TrimMainObjectSearch forTaggedObjects)
{
    if ( links[0].MenuID == cmdId )
    {
        FolderBrowserDialog directorySelector = new FolderBrowserDialog() { Description = "Select a directory to place the electronic documents", ShowNewFolderButton = true };
        if (directorySelector.ShowDialog() == DialogResult.OK)
        {
            foreach (var taggedObject in forTaggedObjects)
            {
                HP.HPTRIM.SDK.Record record = taggedObject as HP.HPTRIM.SDK.Record;
                if ((HP.HPTRIM.SDK.Record)record != null)
                {
                    string outputPath = Path.Combine(directorySelector.SelectedPath, $"{record.Number}.{record.Extension}");
                    record.GetDocument(outputPath, false, string.Empty, string.Empty);
                }
            }
        }
    }
}

All done!  Now, again, I left out the meta-data file & user interface for now.  If anyone is interest then add a comment and I'll create another post.  For now I'll compile this and add it to my instance of Content Manager.  

Here's what it looks like so far for the end-user.

A wise admin would encourage users to place this on a ribbon custom group, like shown below.

When I execute the add-in on one record I get prompted for where to place it...

Success!  It gave me my electronic document with the correct file name.

Now if I try it after tagging all the records, the exact same pop-up appears and all my documents are extracted properly.

Hopefully with this post I've shown how easy it is to create custom add-ins.  These add-ins don't necessarily need to be deployed to everyone, but often times that is the case.  That's the main reason people shy away from them.  But deploying these is no where near as complicated as most make it seem.

You can download the full source here.

Export Mania 2017 - Tag and Task

Warning: this post makes the most sense if you've read the previous post....

If I use the thick client I can tag one or more records and then execute any task (I prefer to refer to these as commands, since that's how the SDK references it).  In this post I'll show these tasks, the output, and how they may (or may not) achieve my goal.  My goal being the export of a meta-data file with corresponding electronic documents (where the file name is the record number).

The commands we can execute include:

1. Supercopy
2. Check-out
3. Save Reference
4. Print Merge
5. Export XML
6. Web Publish

If I tag several records and then initiate any of these commands, I'll get prompted to confirm if I'm intending to use the highlighted item or tagged items.  You can suppress this by unchecking the checkbox, but I let it alone (so there's no confusion later).  Once I click OK I can see the dialog for the selected task.

As you can see below, the supercopy command let's me save just the electronic documents into a folder on my computer or my offline records tray.  The resulting electronic documents are titled using the suggested file name property of the record(s).

The resulting files contain just the suggest file name.  It does not include record number, dataset id, or any additional information.  I also cannot get a summary meta-data file.  So this won't work for my needs.

Check-out does the exact same thing as supercopy, but it updates CM to show that the document(s) are checked-out.  Since emails cannot be checked-out, this task fails for 2 of my selected records.  That means they won't even export.  

So supercopy and check-out don't meet my requirements.  Next I try the "Make reference" feature, which gives me two options:

Here's what each option creates on my workstation...

Single Reference File

Multiple Reference Files

When I click the single reference file Content Manager launches and shows me a search results window with the records I tagged & tasked.  The multiple reference files all did the same thing, with each record in its' own search results window.  In both cases there are no electronic documents exported.

Single Reference File

Multiple Reference Files

Now I could craft a powershell script and point it at the results of my reference file(s).  The reference file includes the dataset ID and the unique record IDs. As you can see below, the structure of the file is fairly easy to decipher and manage.

Single reference file format

I don't really see a point in writing a powershell script to make references work.  Next on the list is Print Merge. As shown below, this is a nightmare of a user interface.  It's one of the most often complained about user interfaces (from my personal experience).  The items are not in alphabetical order! 

It's funny because this feature gives me the best opportunity to export meta-data from within the client, but it cannot export electronic documents.  So I need to move onto the next option: web publisher.

The web publisher feature would have been cool in 1998.  I think that's when it was built and I don't think anyone has touched it since.  When I choose this option I'm presented with the dialog below.

I provided a title and then clicked the KwikSelect icon for the basic detail layout.  I didn't have any, so I right-clicked and selected New.  I gave it a title, as shown below.

Then I selected my fields and clicked OK to save it.  

When I selected the new basic layout and then clicked OK, I get the following results.  Take note of the file naming convention.  That makes 3 different conventions so far (DataPort, Supercopy, Webpublisher).

Opening the index file shows me this webpage...

I'm pretty sure the idea here was to provide a set of files you could upload to your fancy website, like a city library might do. I tell people it's best for discovery requests... where you can burn someone a CD that let's them browse the contents. 

Time to move onto the last option: XML.  When I first saw this feature my mind immediately thought, whoa cool!  I can export a standardized format and use Excel source task pane to apply an XML map.  Then when I open future XML exports I can easily apply the map and have a fancy report or something.  I was wrong.

Here's the dialog that appears when you choose XML Export... I pick an export file name, tell it to export my documents, and throw in some indents for readability.  Note the lack of meta-data fields and export folder location.

Then I let it rip and check out the results...

I would gladly place a wager that these 4 different naming conventions were created by 4 different programmers.  The contents of the XML isn't really surprising...

<?xml version="1.0" encoding="ISO-8859-1" standalone="no" ?>
<TRIM version="9.1.1.1002" siteID="sdfsdfsdfsdfd" databaseID="CM" dataset="CMRamble" date="Sunday, October 15, 2017 at 10:46:50 PM" user="erik">
  <RECORD uri="1543">
    <ACCESSCONTROL propId="29">View Document: &lt;Unrestricted&gt;; View Metadata: &lt;Unrestricted&gt;; Update Document: &lt;Unrestricted&gt;; Update Record Metadata: &lt;Unrestricted&gt;; Modify Record Access: &lt;Unrestricted&gt;; Destroy Record: &lt;Unrestricted&gt;; Contribute Contents: &lt;Unrestricted&gt;</ACCESSCONTROL>
    <ACCESSIONNUMBER propId="11">0</ACCESSIONNUMBER>
    <BARCODE propId="28">RCM000016V</BARCODE>
    <CLASSOFRECORD propId="24">1</CLASSOFRECORD>
    <CONSIGNMENT propId="22"></CONSIGNMENT>
    <CONTAINER uri="1543" type="Record" propId="50">8</CONTAINER>
    <DATECLOSED propId="7"></DATECLOSED>
    <DATECREATED propId="5">20170928093137</DATECREATED>
    <DATEDUE propId="9"></DATEDUE>
    <DATEFINALIZED propId="31"></DATEFINALIZED>
    <DATEIMPORTED propId="440"></DATEIMPORTED>
    <DATEINACTIVE propId="8"></DATEINACTIVE>
    <DATEPUBLISHED propId="111"></DATEPUBLISHED>
    <DATERECEIVED propId="1536">20170928093449</DATERECEIVED>
    <DATEREGISTERED propId="6">20170928093449</DATEREGISTERED>
    <DATESUPERSEDED propId="1535"></DATESUPERSEDED>
    <DISPOSITION propId="23">1</DISPOSITION>
    <EXTERNALREFERENCE propId="12"></EXTERNALREFERENCE>
    <FOREIGNBARCODE propId="27"></FOREIGNBARCODE>
    <FULLCLASSIFICATION propId="30"></FULLCLASSIFICATION>
    <GPSLOCATION propId="1539"></GPSLOCATION>
    <LASTACTIONDATE propId="21">20171015224650</LASTACTIONDATE>
    <LONGNUMBER propId="4">00008</LONGNUMBER>
    <MANUALDESTRUCTIONDATE propId="122"></MANUALDESTRUCTIONDATE>
    <MIMETYPE propId="82">image/png</MIMETYPE>
    <MOVEMENTHISTORY propId="33"></MOVEMENTHISTORY>
    <NBRPAGES propId="83">0</NBRPAGES>
    <NOTES propId="118"></NOTES>
    <NUMBER propId="2">8</NUMBER>
    <PRIORITY propId="13"></PRIORITY>
    <RECORDTYPE uri="2" type="Record Type" propId="1">Document</RECORDTYPE>
    <REVIEWDATE propId="32"></REVIEWDATE>
    <SECURITY propId="10"></SECURITY>
    <TITLE propId="3">2017-09-28_9-31-37</TITLE>
    <RECORDHOLDS size="0"></RECORDHOLDS>
    <ATTACHEDTHESAURUSTERMS size="0"></ATTACHEDTHESAURUSTERMS>
    <LINKEDDOCUMENTS size="0"></LINKEDDOCUMENTS>
    <CONTACTS size="4">
      <CONTACT uri="6185">
        <FROMDATETIME propId="157">20170928093449</FROMDATETIME>
        <ISPRIMARYCONTACT propId="161">No</ISPRIMARYCONTACT>
        <LATESTDATETIME propId="158">20170928093449</LATESTDATETIME>
        <LOCATION uri="5" type="Location" propId="155">erik</LOCATION>
        <NAME propId="150">erik</NAME>
        <RETURNDATETIME propId="159"></RETURNDATETIME>
        <TYPEOFCONTACT propId="152">0</TYPEOFCONTACT>
        <TYPEOFRECORDLOCATION propId="151">3</TYPEOFRECORDLOCATION>
      </CONTACT>
      <CONTACT uri="6186">
        <FROMDATETIME propId="157">20170928093449</FROMDATETIME>
        <ISPRIMARYCONTACT propId="161">No</ISPRIMARYCONTACT>
        <LATESTDATETIME propId="158">20170928093449</LATESTDATETIME>
        <NAME propId="150">FACILITY-HRSA-4647 (At home)</NAME>
        <RETURNDATETIME propId="159"></RETURNDATETIME>
        <TYPEOFCONTACT propId="152">1</TYPEOFCONTACT>
        <TYPEOFRECORDLOCATION propId="151">0</TYPEOFRECORDLOCATION>
      </CONTACT>
      <CONTACT uri="6187">
        <FROMDATETIME propId="157">20170928093455</FROMDATETIME>
        <ISPRIMARYCONTACT propId="161">No</ISPRIMARYCONTACT>
        <LATESTDATETIME propId="158">20170928093455</LATESTDATETIME>
        <NAME propId="150">FACILITY-HRSA-4647 (In container)</NAME>
        <RETURNDATETIME propId="159"></RETURNDATETIME>
        <TYPEOFCONTACT propId="152">2</TYPEOFCONTACT>
        <TYPEOFRECORDLOCATION propId="151">1</TYPEOFRECORDLOCATION>
      </CONTACT>
      <CONTACT uri="6188">
        <FROMDATETIME propId="157">20170928093449</FROMDATETIME>
        <ISPRIMARYCONTACT propId="161">No</ISPRIMARYCONTACT>
        <LATESTDATETIME propId="158">20170928093449</LATESTDATETIME>
        <LOCATION uri="5" type="Location" propId="155">erik</LOCATION>
        <NAME propId="150">erik</NAME>
        <RETURNDATETIME propId="159"></RETURNDATETIME>
        <TYPEOFCONTACT propId="152">0</TYPEOFCONTACT>
        <TYPEOFRECORDLOCATION propId="151">2</TYPEOFRECORDLOCATION>
      </CONTACT>
    </CONTACTS>
    <RELATEDRECORDS size="0"></RELATEDRECORDS>
    <RENDITIONS size="0"></RENDITIONS>
    <REVISIONS size="0"></REVISIONS>
    <CONTENTSOF>
    </CONTENTSOF>
    <FORRECORD>
    </FORRECORD>
    <ELECTRONICDOCUMENTLIST>
      <FILE>records_1543.PNG</FILE>
    </ELECTRONICDOCUMENTLIST>
  </RECORD>

On the positive side, I do get the file name, title, and record number.  However, the uniqueness of this XML structure is for the birds.  I could craft a powershell script to tackle renaming the files and such, but I refuse to do so.  I protest the rubbish in this file.  Fly away little Xml document.... fly, fly away.

All this tagging and tasking helps me know my options for the future, but it also demonstrates clearly that I'm looking in the wrong places.  Unique requirements like these (exporting documents with numbered file names) means I need to either build something custom.  In the next posts I'll show several options for custom exporting.