Section Name Repair

This is actually two demo projects, showing how easy it is to create integration applications using Estrelica.Core versus coding directly against the Archer APIs.

Task Requirements

Imagine a hypothetical scenario where an Archer admin called you and said:

"Someone entered a bunch of new policy records in Archer, but they misspelled the Section names in some cases. I need you to fix all the Section names where the user spelled 'Control' or 'Controls' with double 'L's, e.g. 'Controll' or 'Controlls'."

After a couple of phone calls and emails, the admin confirmed that these names are stored in the "Section Name" Text field in the "Section" level of the "Policies" application, and advised there may be some legitimate names involving words like "Controller" or "Controlling", so we need to be careful not to modify those occurrences.

UsingArcherAPIs.csproj

This project demonstrates how a typical implementation of this scenario would go, in a world where Estrelica.Core is not available. Note, in particular:

  • The eye-glazing size of the resulting code (over 400 lines, including all the comments necessary to understand what's going on with Archer and in regard to the actual requirements)
  • The complexity of the code, with multiple helper functions needed to make the API calls and parse the results.
  • The lack of any strong typing in the parameters and results (everything is passed around as strings, occasionally an integer gets involved)
  • The lack of any domain specificity in the parameters and results (e.g. a field's type is expressed as an integer, with no indication (apart from the comments) what any particular integer means, and all metadata properties are referenced by string keys which are easy to misspell or forget)
  • The amount of code needed to create the XML Search Options that gets sent to the Archer search API in order to identify the offending records.
  • How long the code takes to write, debug and review

UsingEstrelicaCore.csproj

This project demonstrates how the same task would be implemented using Estrelica.Core. Note in this case:

  • The reduced size of the code (~50 lines, including comments that are specifically about the requirements, not about infrastructural code needed to communicate with Archer)
  • The simplicity of the code. Each statement expresses direct intent of what is to be done, without the need for helper functions to make any API calls or process their results.
  • The absence of any direct API calls. While it does support and enhance direct API calls (via core.APIFacade) if that's the way you want to do things, Estrelica.Core also provides an object model view of your Archer metadata and content that's much simpler to work with.
  • Strong typing of all parameters and results. Some string identifiers (e.g. application, level and field names) are unavoidable1, but the results returned for those entities are strongly typed as IArcherApplication, IArcherLevel and IArcherField objects, each with similarly strongly-typed properties and methods.
  • There's no need for complex XML when performing a search. The IArcherLevel.Content() method provides an easy way to build the search criteria using an options callback.
  • How quickly it can be implemented, debugged, and reviewed by a manager who knows little about Archer

1 Not yet anyway. Stay tuned for updates.

A picture is worth a thousand words

Here's a side-by-side visual comparison of the codebase of each approach. Consider this in deciding which approach you'd rather use while coding, reviewing, debugging, supporting, maintaining and delegating your next Archer integration project: