Lesson 8: Filings and presenter details

NOTE: This lesson needs to be reworked following filing changes in Verne. The theory can still be looked at, but the steps will likely not result in the filings appearing as expected as per the screenshots.

Goal

Create filings as a result of a applying our Register Super Hero business service so we can view the official record of the changes made.

Starting code

Start tag: lesson/08

Requirements

We want a filing created that shows all of the details added as part of our Super Hero Registration but show the details similar to when they’re viewed. This filing is called "Super Hero Registration". Additionally, a second filing, called "Airspace Registration", should be created if one of the super hero’s powers is "Flight" and this one should just say "This super hero commands the power of flight – up, up and away!". These should be available within a "Filings" tab within the super hero view once successfully applied.

Steps

Read the filings documentation to see how they fit into the registry ecosystem.

Associate the filings

There is some excellent documentation on configuring filing instructions, the key to associating one or more filings to a given service instance, so be sure to check that out and give it a thorough read through.

With that documentation doing most of the heavy lifting in terms of information regarding this step, we’ll just dive right in and configure them. Create a new filingInstructions.xml resource within the heroes directory, then have a go at adding the appropriate filings using the documentation as a guide. You should be able to manage the first one since it’s a straight forward one-to-one relationship with the "heroRegister" business service.

For the second one, we want the filing to only apply for a certain value of a certain attribute, the super powers. You will hopefully be able to figure out the required filingScope configuration required to achieve this from the documentation, but this is futher complicated (once again) by the super powers field being an attribute that can have multiple values as a CSV. So instead of a match against the value "flight" you’ll have to instead do a "contains" match.

Once done, your filing instructions configuration should look similar to that shown below.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<catcfg:Configuration xmlns="http://www.fostermoore.com/schema/cat-ng" xmlns:catcfg="http://www.fostermoore.com/schema/catcfg-ng">
  <filingInstructions>

    <filingInstruction name="heroRegister" filingCode="heroRegister" textKey="heroRegister.filing">
      <filingScope service="heroRegister"/>
    </filingInstruction>
    <filingInstruction name="heroFlight" filingCode="heroFlight" textKey="hero.filing.flight">
      <filingScope attribute="SuperPowers" attributeMatch="contains" attributeValue="flight"/>
    </filingInstruction>

  </filingInstructions>
</catcfg:Configuration>

You can now do some registrations and using the Svc Txn Repository view in System Administration check that the filings are associated to the service transaction as you’d expect based on the data entered, as per Fig 8.1 below. Make sure you also register a flying super hero to confirm you also get the second filing in those cases.

View the filings

Now that we’ve got our filings correctly being associated with our service instances, it’s on to the next (and last) step regarding filings – viewing them. For this we’ll turn to the view super hero form that we created in lesson 5.

We’re going to add another tab using the Section component and include the filing details using the aptly-named filings fragment, but we’ll do this via the SectionInclude component. This will result in the following configuration being added to our "heroView" form below the HeroDetails component.

<component:Section shortCode="filings" textKeyPrefix="tab.filings">
  <component:SectionInclude code="filings" fragmentName="filing/filings" textKeyPrefix="section.filings"/>
</component:Section>

Once done view one of your registered heroes via the application again and see what happens…

(Wait for applause to die down). Wow! Just like that we get a wealth of functionality as shown in Fig 8.2 below. Too easy!

Unfortunately, when you click on any of the filing links themselves nothing happens, but it was fun for a while ?

Log viewer

So why don’t the links work? Your first port of call when things aren’t working as expected should always be to check the logs. We’ll turn once again to our trusty system administration tools for this, this time using the Log Viewer view. If you click the "Clear Logs" button then select one of the filing links again in the application, you should see something similar to Fig 8.3 below.

Notice that red error line saying "Could not determine default service for mode ‘ViewFilingChange’ on dataset for domain ‘Hero’ so cannot build the filing view"? That sounds quite relevant. Hopefully it even makes sense given our knowledge of data sets and default services that can be defined on them covered in previous lessons. So add a default service to the heroes data set for the mode "ViewFilingChange", and since the requirements state the filing details are the same as the view details, let’s just reference our "heroView" business service as the value and see what happens.

Once done, click on the filing again and see what you get. Better, but still not quite right. The fields are fine but we also get the ‘back’ link and on the "Entity snapshot" tab we’re also getting the filing details section again as per Fig 8.4 below… in fact, it’s a bit of an infinity mirror type situation ?

Add a ViewFilingChange mode business service

So let’s go ahead and add a new business service that’s specific to the "ViewFilingChange" mode in the data set. We’ll call this "heroViewFilingChange". The business service configuration will be minimal (there’s no requirement to restrict access based on permissions yet), and we’ll also create a "heroViewFilingChange" form that has the same content as the "heroView" form apart from the filings and button components. Have a go at adding those in now before comparing with the configuration snippets below.

<businessService code="heroViewFilingChange" mode="ViewChange" formItem="heroViewChange"/>

<record shortCode="heroViewFilingChange" domain="Hero">
  <component:HeroDetails/>
</record>

Now load up the filing view and see how things look. Much better ?

Customise the flight filing

So now that we have the filings appearing OK we need to turn our attention to the flight-related filing view. It should say "This super hero commands the power of flight – up, up and away!". We’ll do this using a specific business service (and form) for this filing. We’ll do this by adding a viewChangeService attribute to the "heroFlight" filing. Let’s set the value to "heroFlightViewFilingChange". We’ll also have to add a business service with this code, and a form (use the same name for the form) and add a <text> element to it that has the required text for the flight filing associated to it, and nothing else. Have a go and making those changes before comparing the new business service and form configuration shown below.

<businessServices>
  <businessService code="heroFlightViewFilingChange" mode="View" formItem="heroFlightViewFilingChange">
  </businessService>
</businessServices>

<record shortCode="heroFlightViewFilingChange" domain="Hero">
  <text shortCode="flightText" textKeyPrefix="heroFlightViewFilingChange.flightText"/>
</record>

Plus of course the "heroFlightViewFilingChange.flightText.label" localised text entry. Now that that’s all setup and this new business service associated to the filing, let’s view the "Airspace Registration" again and see how it looks. It should look as per Fig 8.5 below – if it does, give yourself a wee pat on the back ?

Presenter details

Now that the main filing content is looking OK, we can pay attention to some of the smaller details. You may have noticed the odd looking text within the line starting "Submitted by…", which can be seen top-right in Fig 8.6 below.

Once again this is where a bit of registry experience comes in, so trust us when we say the concept of a presenter is a common one. It’s perhaps easiest to think in terms of old fashioned paper form submissions in this case, where the presenter is the person who instigated the process. Every action requires this, which is why it’s expected to be present in the filing details, so we’ll add one in.

We’ll turn to our trusty components again to help us out, the PresenterSection component in this case, and we’ll add it to both the "heroRegister" form so the details are captured on registration, and the "heroViewFilingChange" and "heroFlightViewFilingChange" forms so the details are available for display on each of the filings. Go ahead and add this component to the top of these forms, then register a new super hero and view the filings to make sure we now get proper presenter details appearing, as per Fig 8.7 below.

Tabbed view

The only thing left now to meet the requirement that the filings be on their own tab within the view. We’ll introduce another component to help with this. There’s the Tabs component, which sounds very promising. There’s also a WizardWithView one, which can also be useful when wanting to use the same configuration for both edits (i.e. "Create" or "Change" mode business services) and view. But we’ll stick with the Tabs one since we’re on a view business service form and not shared.

Add a Tabs component as a wrapper around the "heroView" form’s main content, so the HeroDetails component is on one tab, and the Filings component is on a second tab. Have a play around with the options, as well as putting Section component wrappers around the content containers with appropriate text keys prefixes to associate some tab label text. Once done, your view service should look a little something like Fig 8.8 below.

Congratulations, you’ve just completed another training lesson! ?

Add tests

Create new tests for search and view services. Understand how to:

• Randomize tests
• Create multiple scenarios using 1 single test via outlines
• Use random variables
• Automate Search and View services
• Filing History record

The information about the test lesson can be found at Lesson 4: Scenario outline, variables, search, view and filings

Wrap up

OK, so let’s see what we covered this lesson… we’ll give you a clue: filings, filings and more filings ?

• Associating one or more filings to a service instance
• Configuration required to viewing the filings
• Using the Log viewer tool
• Adding a custom business service for a particular filing
• Presenter details and including this on your forms
• Adding a tabbed layout