Exercise 1.8 - Create Valuesets

In this exercise you will meet another player on the Hopp field, the Valueset. A Valueset is actually a simple little thing, just a table of data with rows and columns. But this is Data Migration, so trust us to make a simple thing complicated :-) 

This video explains about the Valuesets:

Valuesets

Working on a Valueset in Studio, you will be concerned with 2 different aspects of the Valueset. First you must define the name and datatype of the columns of the Valueset and - secondly - you must decide where the data content of the Valueset is going to come from.

For the second part - where does data come from - you have these options:

A Valueset - a table of data- is not doing much good on its own. The main purpose of a Valueset is to be used for lookups performed by Rules, more on that later.

Create the static Valueset CardStatus

In a static Valueset, data can be entered and modified from Studio only. Use a static Valueset when the data content does not need to change and you do not want to load the data content at runtime.

First you must create the new Valuset and define its columns. 

• Locate the Valueset folder node in Project Explorer, right click and select New in the context menu
• Change the name to CardStatus and provide the Description: List of valid card status
• Select the Definition tab, choose Valueset Type Static, and provide the column names and formats below
  
• Select the Data tab and type in the data content into the Valueset. 

• Save (ctrl-s)

  
  

  
  

Create the dynamic Valueset CardTypes

In a dynamic valueset, you do not type the data in Studio. Rather you provide the parameters for the data to be loaded at runtime. It is very common for at dynmaic Valueset to have a runtime Constant value as paraneter, for instance a date, so data loaded in the Valueset are retreived based on the runtime value of this Constant.

Dynamic Valuesets are commonly used to load data from the Target System, allowing rules to perform very qualified validations based on actual data from the Target System. Dynamic Valuesets are loaded as the first step in a migration iteration avoiding constant acces to data in the Target System during the execution of the migration - with possible negative performance impact.

To begin with there is no difference, you must create and name the new Valueset and supply the column definitions. 

• Locate the Valueset folder node in Project Explorer, right click and select New in the context menu
• Change the name to CardTypes and provide the description: List of Card types per bank 
• Select the Definition tab, choose Valueset Type Dynamic, and provide the column names and formats below
  
• Select the Data tab. in the Provider dropdown select From File
• Parameter values:
  • Folder override: Null
  • File: Literal, provide the value CardTypes.xlsx
  • Worksheet index: Null
• Save (ctrl-s)

A couple of points about dynamic valuesets:

• Defining the data part of a dynamic Valueset is actually a multipart process:
  1. First of all, an extension must be installed and available. Try to open the Target Map itself (double click the mother of all nodes in the project Explorer named 'Workshop'). Here you can see that the extension Migration Default is installed, and that it comes with functionality to provide Metadata and also Valuesets from Excel spreadsheets
  2. Then a Valueset provider must be created to use the extension to provide Valueset data. You can find this provider in the Project Explorer treeview: Valueset Provider -> FromFile. If you open that one, you can see that the provider uses the Valueset Provider of the extension and takes a Parameter to know the folder where the Excel spreadsheets with Valueset data are located
  3. And finally, on the dynamic Valueset itself, you then choose to this provider FromFile to give you the data for the Valueset. In case you wondered about the parameter FolderOverride - this merely gives you the option to say that the Excel spreadsheet for this specific Valuset is in a different folder from the one specified on the Valueset Provider FromFile
• Parameters for Valueset extensions and providers are given by the installed extensions and in fact unknown to Hopp and Studio. Studio simply presents the parameters that are defined and required by the extension and lets you provide values for them. It follows that a different, installation specific extension most probably will require parameters totally different from the default extension above. For instance the URL of a web service to call to retrieve data from the Target System - just guessing, of course...

Test dynamic Valueset CardTypes

Though the data will not be saved in Studio, you nevertheless have the possibility to test your dynamic Valueset to verify that it gets the data as expected. This is especially valuable in a real life situation for instance for somebody implementing a web service (or something else) to get data from the Target System. Studio provides an easy way to test the web service.

• In Project Explorer, locate and open valueset CardTypes
• Select the Data tab, and click the Test button
• A Test window appears allowing to modify the parameter values before calling the extension
  • For the FolderOverride value type: D:\MigFx\Training\Trainee\XX\MigFx\Runtime\Track\01\Files\Valuesets, where XX is trainee number
• Click on Get Data to test that data are retrieved from the extension
• Note that data are discarded when you close the dialog. It is for test purposes only and data are not saved by Studio.

What happened here?

You got the notion that a Valueset is simply a table of data. To create a Valueset you must provide the names and the data types of the columns in the Valueset.

After that, it is a question of where the data content for the Valueset is going to come from:

• Static: You type the data in Studio
• Dynamic: The data is retrieved by calling functionality external (an unknown) to Hopp 
• Translation: The Valueset will appear in the Tracker web application for users to enter the data

For the dynamic Valuesets, data is in the end provided by an extension that lives outside Hopp. Hopp does not really know anything about this extension, only that it complies with an interface published by Hopp. This is a very clear and sharp separation that makes it possible to create installation specific extensions to get data for dynamic Valuesets, for instance from inside the Target system

A technical note

As a part of this interface, the extension can tell Hopp about the parameters it needs to get the data.

In this training setup you are using the extension that comes in the Hopp box: MigFx Excel. This extension simply knows how to read data from an Excel spreadsheet or a CSV file. In order to do this, it tells the Studio that it need the Folder and FileName parameters to do its job.

So the Studio in turn asks you to provide the values for these parameters. But Studio does not have any idea how the extension actually works and thus what it uses the parameters for. So the Studio does not know that the extension in reality wants a file name. This is why the Studio does not give you the option to browse for a file - it has no clue that the parameter is actually a file name.

In case you wondered....