Summary

It is a common feature to supply a list of available countries to the end user so that he or she chooses one. This list rarely changes, but it sometimes does, which is not in control of the company. One can regard this metadata as information retrieved from the interface layer, and it should not be part of the domain layer.

Problem

The problem which is addressed in this example is that the rate of change of the content of the value list is different than the lifecycle of the application itself. If these are coupled, then a new version of the application has to be created when the master data changes. When the master data changes is outside the span of control of the project. For a larger discussion on Master Data in different forms, see How to handle Master Data.

In our example of the municipalities, these change almost every year in the Netherlands. In 2005 467 municipalities existed and there were 458 municipalities in 2006. The general trend is there are less and less municipalities, and 2017 counted 388 municipalities.

An important aspect of this is that we want to maintain this list outside Blueriq, as it does not affect the behavior of the application (generally) and the data does not belong to the business for which we create the model. When the data changes, no new Blueriq application should have to traverse the DTAP street.

Solutions

Webservice

When there is a web service available which returns all municipalities as instances, then the AQ_InstanceLinker can simulate a value list. This pattern fullfills the requirement that the list is always up-to-date and that the model does not need changing when the list changes. This pattern is suitable for this amount of instances, but would not be if there would be much more municipalities, as otherwise too many instances would be present in the profile, reducing performance.

Expand to see the Webservice call pattern characteristics

 

 

	Type	Score	Description
Knowledge characteristics	User set or System set	User set	User-set values enter the profile, which are set from the returning message and the subsequent data mapping.
	Parameters or complex model	Parameters	Only simple input/output parameters could be used with Web services (BaaS). The input and output parameters are neatly defined in the contract of the web service. You are able to steer what values are set in the data mapping. If you want to fill in the  parameters differently for different calls from the same module, an additional data mapping and AQ_WebServiceClient service call needs to be created.
	Enhanced by Blueriq Functionality		Blueriq can use dependencies up to the contract. There are no decision requirement graphs or dependencies possible between the calling application and the BAAS.
Maintainability characteristics It should be possible to quickly make changes to business rules independent of other functionality.	Focus on Internal or External Use	External	A web service is intended for external use, and relies on an official contract definition.
	Low Implementation complexity		You get two additional modules in your project, and a second project next to it. As you are in control of the information being send, the structure will be similar to what you use in the application module. Therefore the mapping should be easy (1 to 1). You have to create your own contract for the communication, and keep this updated.
	Internals invisible (encapsulation)		Internals are not visible and/or accessible of a web service.
	Autonomous		The business rules are executed in a separate profile, and no side-effects are possible.
	Highly Testable		Webservices are easily testable.
	Highly Reusable		A BaaS implementation is not very reusable because of a lack of parameter support. Hence, for every web service call a mapping must be defined.
	Out of the Box		No custom code required in general.
Deployment characteristics	Part of Application or Separate Deployment (=deployment)	Separate Deployment	As soon as a new version is deployed, all consumers directly use the new version. When web services are versioned, the calling party can decide itself when to migrate to a new version.

 

 

AQ_CscConnectivityService

The AQ_CsvConnectivityService can be used to load a CSV file into the profile. It is shown as value list with the AQ_InstanceLinker, similar as above. The main difference is that the CSV file is maintained by the project, and not by an external party. This can be both an advtantage as well as a disadvantage.

Issues and considerations

For the municipality case, we advice to use the external Value list. Although the implementation effort may be somewhat larger because of the custom coding, it awoids a large number of instances in the profile. It also keeps the model clean, as no additional relations or containers are needed as are with solutions which use the AQ_InstanceLinker.

For a larger discussion on Master data, see How to handle Master Data.