A path from Share to ADF

Editor's Notes

• #3:  Hello, good afternoon, for those of you I don’t know yet, I’m David Webster. I’m currently the Director of Engineering at Exari, but the last time I was at an Alfresco event like this, I was on the Alfresco Engineering team. I was at Alfresco for over 8 years - I spent a good chunk of that time working on Share, before moving to the records management or governance services team. Now, I lead the engineering team at one of Alfresco’s OEM partners, Exari, which gives me both the internal perspective on how we got here, and the external view on why it’s a problem - it’s the fact that I’m at the intersection of those perspectives that made me want to come and present a session here.
• #4: I hope to provide you a treasure map of sorts, helping you answer the question of how do I from A to B, where A is Share, the app development platform we’ve been using for the last decade or so - I’ll let that timeframe sink in for a bit. Yes it’s been that long -  & B is ADF, which is the future, or the present, depending on who you talk to!  To be honest, while I’ve got ADF in the title of this session, the tips apply regardless of your tech choices. If you feel ADF isn’t mature enough yet, or that Angular or Material Design aren’t the direction you want to go in, then that’s not a problem - this session should still be useful. Perhaps even more useful. When Alfresco started focusing on being a platform and on the builder experience, they didn’t put a high priority on existing customers, and the partner & community ecosystem and on the experience for those already loyal and already using Alfresco as a platform.  They recognise that now & they’re starting to make amends - towards the end of last year, they announced that they’ve got an out of the box UI, the digital workspace, with vitally, support for extension points - for quite a while I thought that wasn’t going to happen & also vitally, they’re now supporting the SDK. But some things are falling through the cracks - the new identity service looks useful, but won't work with Share in 6.1 so isn't really usable for now in my mind. So, anyway, where we are now is at A, but we want to get to B. There’s still no officially recommended route for customers already invested in Share for getting from A to B, to take the advice in this session as a series of hopefully helpful tips as to how you might implement it.
• #5:  The Agenda for the next half hour is fairly straight forward: I’m going to give you some background context on the problem so we’re all on the same page to begin with, then I’ll explore the problem in more detail. Exari’s situation is just one example I could use, but I think it’s a useful one as we’ve been invested in the Alfresco ecosystem for quite some time.  Then - and hopefully this will be the most useful part, I’m going to talk you through some potential solutions to that problem. At the end, assuming I don’t waffle too much, there should be some time for questions, so if you think of any while I’m talking, make a note of them and we can address them all at the end.  And I've added it here so I don’t forget - I’m also going to point out that Exari are hiring, and you should come talk to me if that interests you.
• #6: {TIME: 4min} At Exari we're an OEM partner of Alfresco's and we use customised versions of ACS and APS (but not yet AGS) as part of our suite of tools that allow us to provide end to end contract lifecycle management.   We do that for top international banks, insurance, energy and healthcare companies. Basically any organisation whose business model is dependent on being able to make sense of the data that’s typically locked up in complex contracts.   Using our product suite and concepts we’ve created, like the Universal Contract Model or UCM, and combine that with the AI powered data extraction engine our team has built and we provide what our marketing team like to call "100% Contract Certainty” to our customers.  So that’s the marketing spiel 
• #7: From a technical perspective, on to this slide, which was drawn up to show the data flow within our system shows how embedded Alfresco is. We’ve got the DocGen application here, which is entirely Exari code, but then that is fed from, and feeds into this box, which is a heavily customised version of ACS, extending both the Repo and Share. We’re currently stuck on the 5.x branch waiting for the SDK upgrades before we move. That part of the system links through to some more of our custom code and external systems, but also to APS. Now you’ve seen that picture, let’s look at what that looks like from an end user’s perspective.
• #8: {Time: 6:30 }  This is the user journey we’re going to cover, it’s clearly intentionally chosen to touch all the bases, but I don’t think this scenario is too contrived.  Our user, let’s call him David, imports some pre-existing contracts. Our system analyses them and then he then wants to make some changes to them. Those changes hit some of the compliance rules we’ve got set up, so they trigger a workflow that sends them off for review. Once they’ve been approved, David then wants to send one of those specific contracts to the counter party, through DocuSign for their signature.  Now, I’m not going to demo that all live, but I do have screenshots to give you some idea of the the problem.
• #9: {Time: 7:30} So, we’ll start off in DocQ DocQ - This is a new Angular UI we’ve built using Material Design from our own components. DocQ takes the contracts we’ve uploaded and submits them to DocGen for processing.
• #10: Then over to DocGen, that’s an old school web app, which was themed to look like like Share circa v3.2 or 4.0. That wasn’t done through any retro nostalgia or anything, that’s just what was current when that work was done, but clearly when that theming was done, the form behaviours weren’t modified. So there are some inconsistencies there. After DocGen, we move over to contracts. 
• #11: Contracts is a customised version of Share, so this dashboard should look familiar to most people here – although we’ve added a few dashlets ourselves
• #12: We’ve got some more customisations on the contract details page. Which you can use to view all the contract specific metadata and associated content.  Then if you want to amend that contract, 
• #13: you can do that in our Mass Actions tool, which we’ve built out recently and uses Angular and Material Design, with a mixture of ADF components and custom ones - this one, we’re pretty proud of. We designed and built this ourselves, and the user experience in this is better than anywhere else in the app.  Ok, but say that amendment triggered one of our compliance rules,
• #14: Well, you’re back in Share. Compliance Manager which is an entirely custom UI we’ve built inside Share, but it looks like Share, And then our workflows, which compliance manager triggers, are using APS, so we’ve got two whole new UI styles here. 
• #15: Workflows are modelled and administered using activiti-app, which is a entirely different to anything else as it was built in isolation, using an old version of Angular that is incompatible with the latest stuff.
• #16: {Time: 10mins} And to complete the workflow, you’re dropped into a modified version of the “Process Workspace”, which I’m sure is a wonderful showcase of ADF components, and built on top of Material Design, but from a UX perspective is littered with as many inconsistencies as Share.
• #17: Then once the contract is reviewed, you’ll get the email notification. You might then go back to Contracts and search for the document. Congratulations, you’ve found the one Share page that managed to use Aikau before that project was mothballed.
• #18: Put all these things together and you’re no-where near the coherent cohesive app suite that we need to be for the level we’re operating at. We started off with Angular & Material Design - move on to old school Share with funky forms, back to current Share, then to ADF, through Share and Angular v1 to a different Angular Material Design app, before coming back to Aikau. This isn’t demoware. We’re selling this. People are using this, and are being successful with our products. We’re getting good recognition from the industry. 
• #19: In its latest report, Forrester analysts called out Exari as one of the leaders in the CLM space, with hands-down the best strategy, but if you look past that and read the full report, they said we’re there in-spite of the usability, which receives below average scores.
• #20: We scored 3 on this graph.
• #21: Now remember, that user journey I went through. That touched a lot of different areas, most of them, most of our UI interactions are using design concepts that we’ve inherited from Alfresco, and we’re at the point now where that’s not good enough. Exari are expanding and growing and we’ve realised that we need to increase our focus on both UX and UI architecture - we can’t just focus on the business logic and the intelligence behind the scenes - we need in-house expertise to provide a tailored user experience to our customers. That’s my first tip:
• #22: Develop in-house UX and UI expertise That way you can focus on building the products your customers need, the way that’s most suited to their requirements. Our customers may not be the same as Alfresco’s customers and we shouldn’t rely on their decisions. One of the many things that I learnt at The Place in Maidenhead, where Alfresco builds its software, is that UX is much more than what a product looks like - it’s about building the right product for the right people. If you outsource that, you’re capping your potential, so take UX seriously and invest in in-house capabilities.  {Time: 14mins} Now, let’s step back a bit. I may bemoan our inconsistent UI, but the pragmatist in me is pointing back to the history of our products. I’ve only been at Exari a few months, and haven’t been directly involved in the decisions behind some of these technology adoptions, but for the most part, it’s working. Exari is a thriving, growing company and doing so due to our software innovation. The Engineering team I lead is going flat out. We’ve not stopped to catch our breath and rewrite our entire UI. We won’t, we’ve got too many ideas on how to continue innovating for customers like Uber who have lots of contracts to create on the fly and use our tech to achieve that.
• #23: {Time: 15:30mins } {Quick time check. Should be about half way through now ~ 15:15} The solution, or I should say A solution, 
• #24: because this is just one idea, and there are many other potential options and routes you could go down and I don’t want to give you the wrong idea that this is the only options.  But before we get to the solution, let’s discuss UI architecture. Let me look at an architectural concept that’ll help us: Micro UIs aka micro apps, or micro frontends.
• #25: I could spend the whole session talking about this, but I won’t, I’ll cover the idea briefly and look at how it can help us. I first came across the term “Micro Frontends” in the 2016 ThoughtWorks’ Tech Radar, where they bemoan monolithic UI applications and set up this concept as a natural pairing to back end microservices, allowing independent development, iteration and deployment of slices of the front end.  To me, this feels like a natural side effect of UI development maturing and being taken more seriously. People are increasingly thinking about UI architecture as something that needs to be designed and considered in its own right and are creating reusable architectural patterns as a result. {Time:17mins} There’s a website called micro-frontends.org that goes through lots of technical details about how you can actually implement a micro UI architecture, but one of the best sources of information I’ve found is Manfred Steyer’s blog (softwarearchitekt.at) - he ran a series of articles on Micro Apps last year and goes through many worked examples. He also gave a brief primer on it at the AngularConnect conference in London a couple of months back. I’m not going to repeat all of his explanation here, but suffice to say that it’s a way of splitting up one large, unmanageable UI project into smaller more maintainable chunks. I’d advocate making that split based on user persona, or feature set or some other logical separation between parts of the UI. However you split it, he identified two main techniques for working with micro apps. UI Composition via hyperlinks or a Single Page Application (SPA) shell app that embeds other applications, either with iframes if you want strong isolation, or some other, like multiple modules.
• #26: At Exari we’ve got a mixture of those approaches. This diagram shows roughly how our UI architecture currently is set up.  We’ve got a few logical apps that are composed together via URLs  DocGen UI Share. ExariCM UI Activity Manager Activiti-app  And additionally, ExariCM UI is our container app, for the other UI apps to manage Mass Actions, Legal Entities, DocQ, and other apps - this allows state to be shared between those apps & means we can benefit from combined tree shaking, faster load times, etc, but in future we may break those out into their own applications if we want to be able to release updates those features independently.
• #27:  To get around issues with Single Sign On, we’re actually deploying them slightly differently - as per this picture, we’re deploying ExariCM UI and Activity Manager inside Share. The way we’ve achieved that is that the index page for those applications is bundled up as a WebScript & Share extension module, that WebScript controller also passes the some useful variables from the server to the client, like the auth token.  At build time, npm packages it into a JAR and pops it inside our existing Share AMP. Which then gets applied to the Share WAR during deployment. That works really well for now, but longer term, we’d be much happier to see a proper SSO option across all the UIs. Including Share.
• #28: For second tip. Consider your UI architecture, and whether micro apps would be useful.  {Time: 21mins}  Ok, so, that’s the UI architecture, now let’s look at the UX for the end-user. Our first concern should be consistency of their experience - we need to make things appear cohesive and not confuse the user. This requires a style guide that’s consistent across every UI app in our suite.
• #29: Just using "material design" is not enough. These sites all use material design, they all look different. MD gives you a good starting point and helps you when you get to choices about how things should look or work, but if you’re just using MD components, that’s no guarantee that the button will be where the user expects it. Or that the information that a user needs to complete their task is on the page where they can access it. That’s where you need to be effectively wire framing and understanding your user’s expectations before you start writing the code. A style guide goes a long way to codifying some of those principals and helping promote consistency across your applications.
• #30: So, that's my next tip. Ok, so if you've been following along thus far - you’ve got the UI architecture that allows you to incrementally update individual parts of your UI without having to do a Big Bang rewrite. You're building new micro apps in a visually consistent way, but how do you avoid having inconsistencies when going from the old to the new. First you have to invest a little bit more effort in the old and change how it looks. Skin the old app to look like the new one. It doesn’t need to be a huge investment, and this isn’t a time to focus on perfection. What you want is good enough. It also doesn’t need to be the full application that gets skinned. I went through Exari’s most common use cases with one of the team and we identified 3 pages that get hit by every user. If we just attacked and skinned those ones we’d hit a large percentage of use-cases.  In the case of Share, the original authors were kind enough to make the themes sufficiently flexible that it can be skinned. So that’s my request to Alfresco: Can we please have a material design theme for Share?
• #31: My final tip, and I hesitated with this one, because I’m speculating here and I don’t like recommending stuff I’ve not personally tried, but I’m optimistic that this is an idea that’s time has almost come. I remember before ADF was called ADF sitting down with Mario, discussing options. It’s fair to say that we didn’t agree on everything, but one thing we did agree on was that at that time WebComponents was a fantastic idea, but not usable in practice.   However, I believe Angular elements might be there now. So this is my final tip: consider using framework agnostic components, e.g. through Angular Elements, which creates native custom elements that render in the browser without requiring a full angular app. For example using this technique, you’d be able to write a header component that could be used across multiple applications regardless of whether one was written in Angular and the other used, I don’t know, YUI.
• #32: So, those are my tips for how you can take your users on a journey from Share to ADF without having to down tools and rewrite everything: Take UX seriously and develop in-house expertise for it Split your UI up into Micro UIs Create a visual style guide for your apps and theme existing apps to match it as close as possible. Look at techniques like, Angular Elements to reuse components across technologies to enhance consistency.  If you do all those, then you’ll find the path from Share to ADF is much easier to travel.
• #33: So, almost question time, but first one more plug
• #34: If you like Alfresco and want to work at a company that’s doing cool things with machine learning, and you’re based in Newbury/Reading or London or even Boston or Melbourne, please get in touch. I'm currently hiring for several roles including a dev ops lead, a full stack engineer and at least one more for the research team that manage the AI side of our products. My email address is on screen.  And now, are there any questions?