PowerPoint Presentation

Records ManagementHow the module works and how to extend it.

My brief today is to explain to you how the RM module works and then take a quick look at how it can be extended. Im also going to give you a quick demo of the latest work weve done for classified content.1

Intro to RM Module

Im assuming there will be people watching who dont know what Records Management is. Thats not a problem. Im going to explain a little bit about what RM is, and then what Alfrescos RM module is. Feel free to interrupt with questions at any point, dont feel like you need to hold them in until the end.2

Official Docs: http://docs.alfresco.com/

Intro

Im just going to give you a very quick overview now. The official Alfresco Documentation is the best place to go for more information theres a great series of videos tutorials thatll give you an overview of what RM does and how to use it.3

What is Records Management?IntroA record is content that needs to be looked after in a specific way.RM provides tools for the management of a record and its life cycle.Records Management controls important information that needs to be retained over time. It's used in highly regulated environments, [] or where information might be audited.

So, lets start with the basics first. Before I started working on this project, I had no idea what Records Management was. It turns out that Records Management is a branch of ECM devoted to important content. Its used a lot by regulated industries and governments, and anyone who need to be very careful about what content they store, where they keep it, how long for and what they do with it once they no longer need it.

A record is basically a piece of important content with a defined life cycle or disposition schedule in RM speak.

RM is basically content, workflow and rules, so Alfresco is a great platform to build an RM solution on top of our module provides the tools necessary for a record manager to create a file plan, add disposition schedules, manage records, etc. Italso for the end user to declare content as a record and work with those records.4

In-place / transparent RMRecords managed through special RM site in ShareRecords can be uploaded directly, orAdded (filed) directly from another site, orFiled automatically using folder rules.Intro

To manage a record, and everything that goes with it, weve created a special site type in Share. You can only have one of these at the moment, but once youve created that RM site, you can file a record in a couple of ways: - You can upload content directly into the RM site. The site has a File Plan which is an extended version of the Document Library. Or, - the other option is that you file content directly from an existing site thats an in place record..

As you could probably guess records are just nodes with extra aspects and properties as such it can all be automated using folder rules and behaviours, so, for example, you could set up your system to declare everything in your signed contracts folder as a record automatically with no input from the user thats what we mean by transparent RM, and thats useful because weve found that the user may have no knowledge of whether content should be a record or not.5

A records life cycle

Intro

This image is how our official docs explain what happens to a record. Your record gets uploaded/declared, they you add the necessary metadata, complete it and at that point the record follows the life cycle set out in the Disposition Schedule until it leaves the system, either to an archive store or /dev/null.6

Alfresco Records ManagementAn extension to Alfresco One, Built and maintained by Core Alfresco Engineers,Fully open source (no Enterprise-only bits),Certified DOD 5015.02 compliant,Not a single extension, but a collection of Them:Repo AMP:Targets Java services and WebScripts for REST APIShare AMP:three different extension modules (targeting different areas)Intro

Lets look at Alfrescos RM now.

This might be obvious to some, but RM is not a stand alone product, its an extension to our core Alfresco One product, extending both the Repository and Share. Its built and maintained by a team of core engineers, until recently the team was just Roy and Tuna, but now its much larger and is probably one of the largest teams in Engineering: - theres 4 engineers in Maidenhead (myself, Tuna, Neil Mc Erlean and Tom Page), - Roy architects it all from Australia, - Oana - our QA expert in Romania, - along with Andy who does a great job on the docs and UA, Shane shares his UX expertise and Frank is looking at the benchmarking, - with John Iball as our PM and Christine keeping us all on track as our scrum master.

Thats us, now the code:The RM module is fully open source, there arent any enterprise only bits, it works equally well with community or Enterprise editions.

DOD 5015.2 is the US standard for records management. Our RM module has been through the certification process, and were continually checking our new features match or exceed the DOD spec. Other RM specs exist in different regions, and we work with partners to help them fulfil those needs. Thats actually a very good use case for extending RM; not only do standards vary between regions, but they also change with time so the fact that our solution is extendable, means that youll be able to adapt it to suit whatever requirements you have, even if you dont have them yet!

The RM module isnt one extension, its a few different ones, wrapped up in two AMPs. The Repo AMP adds new Java Services for working with records, as well as extending existing Alfresco services. It also adds and modifies existing WebScript based REST APIs. The Share AMP is actually a combination of 3 different Share extension modules, and they all work together to produce the RM UI within in Share.7

http://localhost:8080/share/page/modules/deploy

Intro

This is the Surf module deployment page for my local version of Alfresco for those not familiar with this page, if youre doing any extensions of Share, this is a great page to bookmark. On the right you can see the modules weve got deployed and in use, on the left weve got the modules that are installed but not in use. The bottom 4 modules on the right have been added by RM were upgrading the Aikau version, and then weve got the three Share extensions. Theyre poorly named, but the first on, RM Global, is where the RM specific extensions are added within an RM site this maps to rm/customizations inside our AMP. The second one, RM Site applies only within the RM site itself and maps specific component overrides to create the File Plan, and such like. Lastly, the RM Config applies everywhere within the RM install and adds functionality like classified content that exists independent of an RM Site.8

Github:

Intro

All our commits to SVN are mirrored on our GitHub project, so you can see what were working on, almost as we write it. As RM is an extension written by engineers familiar with the core code, its worth considering the module almost a reference extension. We dont always do everything perfectly, but theres usually a reason why weve done things the way we have. If youre writing an extension to some Alfresco code that we extend, it may be worth looking to see how weve done it. The best place to take a look is on our GitHub page.

Timing ~ 10mins.9

Quick look at upcoming community releaseClassified records and classified documents

Now for a quick look at some unreleased features. Were really close to a community release for RM which will be 2.4.a and will contain the ability to classify records in an RM site, as well as classify documents that arent associated with RM in any way. Weve also added some clearance management UI to allow you to define what classification level each user is allowed to see.10

rm-classification-levels.json:[ { "name" : "TS", "displayLabel" : "rm.classification.topSecret" }, { "name" : "S", "displayLabel" : "rm.classification.secret" }, { "name" : "C", "displayLabel" : "rm.classification.confidential" }]

So first things first, we need to bootstrap the classification levels into the repo. Thats done automatically, using the levels defined in this JSON file. By default we use DOD ones, Top Secret, Secret and Confidential, but they can be changed if you like. In addition, theres always a classification level of Unclassified which is slightly different to content that has never been classified, but only in that content that has been classified as Unclassified has the classification metadata attached.11

rm-classification-reasons.json:[ { "id" : "1.4(a)", "displayLabel" : "rm.classification-reason.14a" }, { "id" : "1.4(b)", "displayLabel" : "rm.classification-reason.14b" }, { "id" : "1.4(c)", "displayLabel" : "rm.classification-reason.14c" }, { "id" : "1.4(d)", "displayLabel" : "rm.classification-reason.14d" }, { "id" : "1.4(e)", "displayLabel" : "rm.classification-reason.14e" }, { "id" : "1.4(f)", "displayLabel" : "rm.classification-reason.14f" }, { "id" : "1.4(g)", "displayLabel" : "rm.classification-reason.14g" }]

You also need to bootstrap in the classification reasons, which well see in the demo in a moment.12

9mins.

Video showing: Classifying recordsClassifying documents, Searching for documents,Seeing classified label,Doc details page & seeing properties,Assigning a user clearance, Logging in as that user and not being able to see documents above that classification level

13

Extending RMExample extension

The RM module is not some magic black box, its an extension of our core product, built using the same extension points youre all used to using in your own code. The best way to demonstrate that is to extend our extension and hopefully explain a little bit about how weve extended things as we go. If that makes sense.14

PreviouslySummit 2014, London and San Francisco:Deep dive from Roy on Customizing RM: https://summit.alfresco.com/san-francisco/sessions/customizing-alfresco-records-managementCode examples form part of the Alfresco SDK Samples: https://github.com/Alfresco/alfresco-sdk-samples/tree/master/samples/alfresco-rm-customTodays code builds on that and extends things a little further.Code Im showing will be merged to the location above and tagged TTL-SEPT-2015Sample project recreated using SDK 2.1.0 AIO, against Alfresco 5.0.1.Temporarily at: https://github.com/davidcognite/alfresco-sdk-samples/tree/master/samples/alfresco-rm-custom

Extension

So, Previously, for those of you subscribed to the Alfresco YouTube account, or those who attended one of the two Summits last year, you may well have seen the talk Roy gave in both London and San Francisco about customizing RM. That was a technical deep-dive session and packed a lot of into into a short space of time. For the sake of our sanity, Im not going to go over the same content he did. The video and slides are available at that link; Id recommend watching that video if you havent already.

The code samples he used, are part of the SDK samples project on Github, so you can check them out there. Ive built on that base extension for this demo, and with lots of help from Ole and Samuel, have updated that sample project to use version 2.1.0 of the SDK, as well as the latest RM snapshots. Youll need to build those snapshots locally as I dont think we publish them publicly Im afraid. It also points to the latest Enterprise release, 5.0.1. It should also work against 5.0.d. Ive not personally tried against the 5.1 code base yet, but we do normally try to make sure that theres an RM release that works with each core community release.

The code Im demoing is on my fork of that alfresco-sdk-sample, but Ill push it back to the main branch once weve got an RM release out of the door and you dont need to build locally anymore.15

Extension ScenarioWhen you file a record we want to:See who is responsible for a record (through custom Compliance Officer property)Display that metadata in the search results and in the File Plan

Extension:Add custom metadata to modelExtend faceted-search results page to display data.Extend metadata-template to include propertiesExtension

Im going to focus a little more on the UI side of things for todays extensions, purely because thats what Im most comfortable with.

The scenario were looking is fairly straight forward, our fictional RM set up has the notion of a compliance officer who is individually responsible for the metadata on a record and for responding to any queries regarding the content we want to model that as a new property on the record, and then to make it easier for our record managers, we want to display that content on the search results page and also in the document library.

Were going to achieve that by updating our custom content model to add a new complianceOfficer property, were then going to extend the Aikau based faceted-search results page to display it there and then also extend the metadata-template for the document library, using XML config, to show it there as well.16

my-rm-model.xml:

Compliant Record Compliance ID d:text true Compliance Officer d:text false

Adding a new piece of metadata to a record is something thats quite common. One Roy pointed out during his Summit session something that Im going to repeat here: its worth remembering that theres a distinction between content metadata, which is information about the content and record metadata which is information about the record in this case weve got metadata that is only relevant to a record, so adding it here makes sense, otherwise youll want to create a different aspect that you can apply to content and add the metadata to the content directly.

This is the my-rm-model.xml file from the sample app, Ive added a new property, shown in bold, to the myComplianceRecordMetaData aspect. Its an optional field and is plain text.17

my-rm.properties:#### My RM messages##

# my custom compliance namemycustomcompliance=My Custom Compliance

# Metadata property group titlelabel.set.rm-metadata-myrm-myComplianceRecordMetaData=Record Compliance Information

# Compliance Officer Property Labellabel.renderer.myComplianceID=Compliance IDlabel.renderer.myComplianceOfficer=Compliance Officer

# Indicator popup labelstatus.indicator.myrm.complianceRecordMetadata=Compliant Record

My-rm.properties defines the UI strings that enable us to display labels for those custom properties within Share. Weve added one for the Compliance ID and for the Compliance Officer.18

faceted-search.get.js:function addMyRMComplianceMetadata(){ // Get the search result widget from the model. var result = widgetUtils.findObject(model.jsonModel.widgets, "id", "FCTSRCH_SEARCH_RESULT");

// Preserve existing config if it's there, but create if not. result.config = result.config || {}; result.config.widgetsBelow = result.config.widgetsBelow || [];

// Render our custom properties. result.config.widgetsBelow.push({ name: "alfresco/renderers/Property", config: { propertyToRender: "node.properties.myrm_myComplianceID", label: "label.renderer.myComplianceID", renderOnNewLine: true } }); result.config.widgetsBelow.push({ name: "alfresco/renderers/Property", config: { propertyToRender: "node.properties.myrm_myComplianceOfficer", label: "label.renderer.myComplianceOfficer", renderOnNewLine: true } });}

addMyRMComplianceMetadata();

faceted-search.get.js: This is the extension to the JS Controller for one of the few pure Aikau pages that exists in Share out of the box. Here, we grab the search result config using the widgetUtils root object and then add two property renderers into the widgetsBelow array, one for each property. widgetsBelow is one of a number of extension points that was added to the search results widget in a recent Aikau release, which will hopefully enable you to extend the search results much more easily that was previously possible. Extending the search results is something that seems to have cropped up a couple of times in IRC and elsewhere, so it might be worth having a quick look at that, as an aside from this extension.19

RMs Faceted Search ExtensionsProblem:Search Results contain a limited subset of a nodes propertiesSolution:Create custom RM Search API that extends existing slingshot Search APIExtend faceted-search to configure Aikau SearchService to use new APIUse new SearchResult extension pointsExtension

The faceted search page in Share uses a Slingshot API that only includes the node properties that are directly relevant to the search result as displayed out of the box this obviously makes extending the search results to show extra information somewhat harder than it should be. Our solution in RM has been to create a new search API based on the existing one, adding in all the node properties. Weve then extended the faceted search JS Controller to replace the default SearchService with a configured SearchService (the Aikau SearchService now allows you to configure the API endpoints it uses), and then weve extended the search results using the previously mentioned extension points on the Aikau widget.

Its worth noting that RM has its own search page that enables you to drill down into the records in a bit more detail, but Ive included the faceted-search page in my demo to show an example Aikau extension (and because I worked on the faceted-search page previously and think its quite useful).

Timecheck: 7:30 in section. (27:30 overall, 12:30mins remaining?)20

my-rm-share-config.xml:

evaluator.myrm.complianceRecordMetadata {myrm:myComplianceID label.renderer.myComplianceID} {myrm:myComplianceOfficer label.renderer.myComplianceOfficer}

Extend metadata templates. This what Id consider a classic old school Share extension. XML config galore, going into my-rm-share-config.xml. The indicator stuff was in there previously, weve just added the metadata-template section that adds our properties to the rmRecord template. These only show up when the content is a completed record and only when the complianceRecordMetadata aspect has been applied.21

alfresco-my-rm-custom-extension.xml:

Alfresco :: My Records Management Custom Global 1 true

.* rm-site-dashboard true org.alfresco org.alfresco.custom.rm.customizations

Alfresco-my-rm-custom-extension.xml. This is a fairly minor change to the module definition. The auto deploy index here needs to be low in order for out new module to be applied after the RM modules have all been deployed otherwise were going to be trying to extend code that doesnt exist yet, so thats a good tip to take to your own RM extension if its not working properly, check the deployment order of your extensions.

Timing check: 8:30ish in section.22

Extension

8:40mins.

Video showing:Creating RM site of compliance type.Configure Pre-existing RM site to auto-declare content in a folder.Upload content to that folder.Show its been auto declared. Add record metadataUpdate Compliance Officer infoSearch for record, show propertiesGo to Doclib, show metadata template

23

Summit 2014 Session: https://summit.alfresco.com/san-francisco/sessions/customizing-alfresco-records-managementOfficial Docs: http://docs.alfresco.com/Source Code: https://github.com/Alfresco/records-management/My Blog: http://blogs.alfresco.com/wp/dwebster/Twitter: @davidcognite Alfresco Days: https://www.alfresco.com/alfresco-dayEmail: david.webster@alfresco.com

More InfoandQuestions:

Right, thats everything Ive got to talk about or show off to you. If you want more info, check out these links:

Last years summit session, the awesome docs, and the github project, they were all mentioned earlier. Im trying to blog a little more at the moment theres at least one blog thatll be heading out the door soon, so keep an eye that link. If you follow me on twitter, I sometimes tweet about Alfresco stuff. Were also working with Ole to try and get good RM representation at the Alfresco Days events, so its possible that one of the team will be coming to a city near you soon.

This slide deck will be on SlideShare soon. Ill tweet the link. If youve got any questions, let me know now, and Ill hang around in IRC for a bit as well. If you think of something later, feel free to get in touch and let me know.

Id also be interested to hear whether this session was what you hoped or wanted, or if theres anything you felt was skimmed over, included unnecessarily, etc. so send that too, either directly to me, or through Ole.24

Sept 2015

@alfresco

Thats it. Thanks for your time.25