Lesson 3: Root domains and data sets

Goal

Understanding what is meant by a root domain and applying configuration using data sets, as well as reading service transaction data.

Starting code

Start tag: lesson/03

Requirements

Ensure relevant data structures exist that Verne expects relating to top-level domains. This is more of a technical requirement. Having said that, business requirements will arise in the future that will build on or make use of the configuration we’ll add during this lesson.

Steps

In Lesson 1 we added a new business service and a "heroRegister" form which had a record as its root with a domain attribute value of "Hero". At the time we noted there were warnings the logs regarding a missing data set but we’d sort those out later. Well, later has now arrived 🙂

You can easily check the application logs right from your running application when in development mode using the “[Dev tools] – Log Viewer” menu header item. View the logs for the heroes application after you’ve started a new “Register a Super Hero” service and make sure you can see the data set related warnings so we know we definitely fixed them later on. Make sure your looking at the logs from the “heroes” application which you can determine by the presence of the “/heroes” path in the URL (note: it might be easier to add display-menus="true" to the ui:service-layout tag in the “heroRegister” business service so you can select from the “[Dev tools]” menu right from the “Register a Super Hero” form).

Lesson 2 focused on adding attributes to the "heroRegister" form, but in this lesson we’ll step back a bit and look at that data as a whole and how it is stored.

Root/top-level domain

Opening the "heroRegister" form you’ll recall it has a record as it’s root element and we gave that root record a domain attribute value of "Hero". That means the root domain of any service transactions that are created or updated as a result of using this form (created in our case since the "heroRegister" business service is a "Create" mode service).

Service transaction data

But let’s not take our word for it, let’s check the actual data. Start another "Register a Super Hero" service via the main menu item if you’re not already on the form, then click the "Svc Txn (JSON)" or "Svc Txn" links available at the bottom of the page when in development mode, as highlighted in Fig 3.1 below, for the JSON and XML representations of the service transaction data for this service respectively.

Once the new tab showing the current service transation’s data is loaded, you can look for the rootDomainName property and confirm that it has the value "Hero".

Take a bit of time looking at the JSON and XML versions, seeing how they contain exactly the same data even though it’s represented in quite different ways.

It tends to be easier to pick out a service transaction property in the JSON format, as it’s less cluttered and clearer, but the XML is more compact so often easier if you’re wanting to view domain data within the domainTree particularly if there’s a lot of it.

Ensure you look at the data for a brand new "Register a Super Hero" service as well as one after you’ve entered data into some of the fields and see how it’s reflected in the domainTree property‘s details in JSON, and in the domain-tree element in the XML version of the data.

Add a data set

Back to the issue at hand. In the logs you will have seen (or can now if you haven’t already) warnings relating to their not being a data set for the "Hero" domain. Something like:

No data set found for root domain name Hero
Could not find dataset for root domain Hero in cluster verne-registry app heroes ! Please configure one as this will be an error soon

So to add a dataset, open our trusty Create Resource dialog by right-clicking on the heroes application directory (it doesn’t have to be this directory since as mentioned in a previous lesson, once the dialog is open you can update the details to the ones you want regardless) and complete the details as per Fig 3.2 below.

Now because we could only select "Xml File" in the Type value, rather than a specific Dataset type, we just end up with a plain old XML file. But we can quickly populate its content by typing an opening tag character ("<") then pressing Ctrl+Space for completion options, typing a "d" to filter the options and easily select "datasets". The repeat for a dataset element within the datasets wrapper, ending up with the configuration below.

Note you will first need to add the end element to the XML – and change the second line from ema/catcfg-ng” /> to ema/catcfg-ng” >

<datasets>
    <dataset code="TODO"></dataset>
</datasets>

Once these bare bones are in place, simply replace the code attribute’s "TODO" value with "heroes" and add a rootDomainName attribute with a value of "Hero" to match our root domain name of our new service.

That’s the minimum we need do to no longer see the warning in our logs (of course you double checked, right? ;)) but there are plenty of other useful configuration options available for a data set, all of which are documented on the data set reference page (TODO link). We’ll quickly explore just two of these now in the sections below.

Relationship-managed entities

We’ll set the "Hero" data as data user can get authority over, by virtue of being the one who registered it for example, but also where this authority can be managed e.g. granted to another user. You know, just in case Batman’s Alfred needs some assistance managing his profile or something 🙂 . In the registry business we often call this Relationship Management (traditionally it has been called Authority Management) This is done by setting the relatedEntity attribute in the opening tag to "true".

Data Collection and Data Persistence

We’ll ensure the service transactions relating to the "Hero" domain are stored in their own collection to keep things nice and clean and allow performance improvements should they be needed in the future. We’ll do this by adding a <collection name="heroes"/> child element. For more information on Data Persistence read here.

Once done, the data set configuration relating to our "Hero" data should look like the following:

<dataset name="heroes" rootDomainName="Hero" relatedEntity="true"> 
  <collection name="heroes"/>
</dataset>

Recap

We took it pretty easy in this Lesson but touched on a few areas where a lot of configuration options are available, which in turn touches on some new, fairly broad concepts. In summary we got our hands dirty with the following:

• Made use of the application-based log viewer
• Got familiar with the concept of a root domain of a business service/form or service transaction.
• Used the developer tools for viewing service transaction data in both JSON and XML formats and how the domain data is updated as form fields are updated.
• Added a dataset to relate to our “Hero” data that we’re in the process of doing a registration form for.
• Touched on relationships and how they manage authority and how to mark a data set as entity data that is managed by relationships.
• Mentioned MongoDB collections and how we can determine what collection service transaction data relating to a given data set goes in.

Extra credit

For some further reading credit, see links to the related reference documentation already linked to in the lesson above, but summarised again below:

• Data sets (TODO link)
• The service transaction concept and service transaction data details