Difference between revisions of "Structure Explorer"
(→Dimensions Section) |
|||
| (3 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
| − | [[Category: | + | [[Category:Fusion XL]] |
=Prerequisites= | =Prerequisites= | ||
To use the Structure Explorer, you need to have installed the FXL add-in and connected to a Registry from the FusionXL tab in an Excel workbook. [[Connect_FXL_to_a_Registry|Click here to learn how to do that]]. | To use the Structure Explorer, you need to have installed the FXL add-in and connected to a Registry from the FusionXL tab in an Excel workbook. [[Connect_FXL_to_a_Registry|Click here to learn how to do that]]. | ||
| Line 43: | Line 43: | ||
==Structure Retrieval== | ==Structure Retrieval== | ||
| − | There are 4 ways to retrieve structures from the Registry. Regardless of how a structure is retrieved, the retrieval of the structure will result in a new worksheet being opened. Thus, it is possible to have an Excel workbook with multiple worksheets, one for each retrieved structure. | + | There are 4 ways to retrieve structures from the Registry. Regardless of how a structure is retrieved, the retrieval of the structure will result in a new worksheet being opened. Thus, it is possible to have an Excel workbook with multiple worksheets, one for each retrieved structure. Please note that if the Registry contains >1,000 structure Excel is unable to display all structures. |
===Browse Registry=== | ===Browse Registry=== | ||
| Line 224: | Line 224: | ||
* Attributes | * Attributes | ||
* Component Restrictions | * Component Restrictions | ||
| − | |||
| − | |||
===Dimensions Section=== | ===Dimensions Section=== | ||
Latest revision as of 04:34, 4 October 2022
Contents
Prerequisites
To use the Structure Explorer, you need to have installed the FXL add-in and connected to a Registry from the FusionXL tab in an Excel workbook. Click here to learn how to do that.
If you intend to modify structures you will also need to Login with your Registry username and password.
The image below shows the Connected Registry along with the name of the logged in user.
Features Overview
| Button | Function | Usage | |
|---|---|---|---|
 |
Browse Registry | Allows the user to view all of the available structures, broken down by structure type, and maintenance agency. | |
 |
Lookup Structure | Allows users to find structures that reference other structures. For example, look-up ‘Data Structure by Codelist’ enables the user to navigate to a particular codelist, and then discover which Data Structures reference the Codelists. | |
 |
Search Structure | Provides a free-text search for structures. | |
 |
Recent History | FusionXL stores a list of recently viewed structures, allowing the user to easily retrieve recently viewed structures. | |
 |
Create Structure | Allows an authenticated user with the correct permissions to create new structures within the Registry. | |
 |
Delete Structure | Allows an authenticated user with the correct permissions to delete an existing structure. | |
 |
Save Structure | Allows an authenticated user with the correct permissions to save modifications. The Registry will ensure all modifications are valid by performing validation checks. Once successfully validated the structure will be accepted into the Registry. | |
 |
Historical Modification | The Registry keeps track of every modification to every structure. FusionXL allows the user to view historical copies of the structure, providing an easy way to roll-back to an old copy if required. | |
 |
Set Language | FusionXL displays structure names and descriptions in the selected language. FusionXL also makes it easy to add names and descriptions in new languages, by merging uploaded content with existing content. |
These functions are grouped into 3 areas:
- Structure Retrieval
- Structure Action
- Structure Information
Read on to learn more.
Structure Retrieval
There are 4 ways to retrieve structures from the Registry. Regardless of how a structure is retrieved, the retrieval of the structure will result in a new worksheet being opened. Thus, it is possible to have an Excel workbook with multiple worksheets, one for each retrieved structure. Please note that if the Registry contains >1,000 structure Excel is unable to display all structures.
Browse Registry
This button displays a hierarchical menu of all the structures in the connected Registry, broken down by structure type followed by Agency, as shown below.
Once a structure is selected, for example SDMX:CL_UNIT_MULTIPLIER(1.0), FusionXL will obtain this codelist from the connected Registry, and the resulting structure will be shown in the Excel worksheet, as shown in the example below.
Lookup Structure
Lookup Structure provides a drop-down menu of Registry content where the structures have been organised into folders depending on which structures reference them. This is an extremely useful mechanism for quickly finding the desired structure, as well as a useful tool to discover which structures make use of other structures.
It should be noted that whilst then ‘Browse Structures’ menu displays all Registry content, ‘Lookup Structure’ may be showing a subset, depending on the Registry content.
Search Structure
The Search Structure provides a free text search of Registry content. The search terms are applied to Ids, names, descriptions of all Registry structures. A search on OBS_STATUS for example will bring back the concept schemes that contain the OBS_STATUS concept, and Data Structure Definitions with dimension Ids of OBS_STATS, as shown below.
To load a result, either double-click on a search result, or select the result and click the Load Result button.
My Recent History
My recent history shows up to the last 10 structures retrieved against the current Registry connection with the most recently retrieved structure shown first in the menu. If the Registry connection is changed in the Setup, the recent history is updated to show the history of structures retrieved for that connection.
By clicking on a Recent History item, the structure will be retrieved, and the item will be moved to the top of the Recent History menu.
Structure Action
The Structure Action options provide support for the creation, deletion, and modification of structures. Both Delete Structure and Save Structure will only be enabled if a structure has first been retrieved from the Registry. Authentication is performed for any Registry modification, and if authentication is required a login window will be displayed which will enable entry of a username and password.
Create Structure
To create a structure, you need to be logged in to the connected Registry.
The Create Structure button opens window which enables you to select a structure type (please note that only Codelist, Category Schemes and Concepts schemes are functional in the current version of FXL).
Next, select the Agency from the drop-down list. Enter a Valid Structure ID (example CL_NEW), version and the name of the Structure as shown in the example below:
Click Create Structure and a new worksheet will open as shown below.
The data can now be added directly into the spreadsheet. The image below shows some guidance.
When you have finished adding data, you can use the Save Structure Button. The registry will validate the data and then, if successful save the structure to the connected Registry.
Multi-Lingual Structures
Although, as show in the guidance image, it is possible to create multi lingual structures using FXL, you will note that there is only one column for Descriptions and as a result you have to choose either fr or en (in this example I have used fr).
If you require a description in both languages, you can amend the spreadsheet as shown in this example. Using this method, you can add any number of languages. In this example, the language indicator is ru, to identify that the data is in Russian.
If you are using multiple languages, one saved you will be able to use the Language button to display the data in the chosen language.
Save Structure
To save a structure you need to be logged in to the connected Registry. Use this button to Save any modifications made to a structure.
Delete Structure
To delete a structure, you need to be logged in to the connected Registry.
After loading the structure you wish to delete, select the Delete Structure button.
The system will prompt for confirmation and report that the structure has been deleted from the connected Registry, FXL will not close the worksheet thus leaving it available for further modification (alternatively, close the worksheet).
Historical Modifications
The Historical Modifications menu item displays a list of all the modifications for the selected structure. Each time a structure is saved back to the Registry the modification is stored and backed up. This makes it possible to view, and roll back to any previous instance of the structure. To do that, simply select the revision from the list and that version will be loaded into a new FXL worksheet.
Working with Retrieved Structures
As explained in the Retrieval sections above, there are several ways to obtain a structure from the connected Registry but what happens next is the same.
Structure Format
Fusion XL will open the retrieved structure in a new worksheet. Each Structure Type has a defined format in FusionXL, with the header information in rows 1 to 11, followed by the structure specific details. The example below is of a Data Structure.
| Row number | Name | Details |
|---|---|---|
| 1 | FXL Version | Information about the version of the FusionXL communication protocol (note this is not related to the version of the FusionXL plugin), the Registry uses this information to know how to process the message. This value is generated by the Registry and should not be modified. |
| 2 | Type | Determines the type of structure that the worksheet is defining. This value is generated by the Registry and should not be modified. |
| 3 - 11 | Various | Defines information about the structure, and can all be modified as appropriate. |
The layout for the remainder of the worksheet depends on the structure being created/modified.
Category Scheme
A Category Scheme is a hierarchical scheme of Categories. Each category has a mandatory id and name, and an optional description.
The Category Id can contain a period ‘.’ separator to indicate parentage. In the example above category with id ‘1.1’ is a child of category with id ‘1’. A Category may contain more than one ancestor, for example ‘1.1.1’ would be a valid id, denoting category ‘1.1’ as the immediate parent, and category ‘1’ as the grandparent.
Codelist
A Codelist is represented as a flat list of Codes, where each Code has a mandatory Id and Name, with an optional Description and Parent. The Parent column references the Parent Code by Id.
A Codelist can be represented as a hierarchy, but unlike a Category Scheme, the Code Id must not contain a period separator, and each Id must be unique. The parent code can be defined in the Parent column.
The reason for this difference is that SDMX represents a Category Scheme as an actual hierarchy, which allows for Categories at each level of the hierarchy to share the same id (if the parent is different). A Codelist is represented as a flat list, ids must be unique, and parent Codes are referenced by id.
Concept Scheme
A Concept Scheme is represented as a flat list of Concepts, where each Concept has a mandatory Id and Name, with an optional Description and Parent. The Parent column references the Parent Concept by Id.
Content Constraints
A Content Constraint, which is used to define either restrictions on allowable data, or what data are present, come in two flavours: a Series Constraint which defines one or more Series Keys or partial keys; and a Cube Region Constraint which defines one or more Code Ids per constrained Dimension/Attribute.
A Content Constraint, which is used to define either restrictions on allowable data, or what data are present, come in two flavours: a Series Constraint (KeySet) which defines one or more Series Keys or partial keys; and a Cube Region Constraint which defines one or more Code Ids per constrained Dimension/Attribute.
A Content Constraint may also be attached to a Data Structure, Dataflow, Provision Agreement, or Data Provider.
The following image shows the high-level description of a Content Constraint in terms of which structure(s) it attaches to, whether it is defining allowable data, or actual data, and which type of constraint it is.
Row 13 Defines the type of structure that is being constrained. Allowable types are:
- DataStructure
- Dataflow
- ProvisionAgreement
- DataProvider
Row 14 References the actual structure(s) of the given type that are being constrained. The reference is broken down into the following parts:
AgencyId:Id (version)
If the Constraint is attaching to multiple structures of the given type, then the attachments are given as a comma separated list, for example:
METATECH,LFS_SOE_EXTERNAL(1.0), METATECH,LFS_SOE_INTERNAL(1.0)
Row 15 Defines if the constraint is defining data that is known to be present (true) or if it is being used to restrict allowable content (false)'.
Row 16 Defines the type of Content Constraint and cane be set to KeySet or Cube Region.
Row 18 onward are used to specify the constrained Series Keys or Code Ids, depending on the Constraint Type, these are described in the following sections.
Series Constraint
A KeySet Constraint defines the allowed or restricted content by defining it in terms of the series key. A series key comprises of a Code Id per Dimension. Wild carding can be used by specifying the Code Id as
‘*’
Each Series Key is defined as either being Included (present/allowed) or Excluded (not present/not allowed).
Cube Constraint
A Cube Region Constraint defines the allowed or restricted content by defining it in terms of Code Ids per Component (Dimension or Attribute). The Cube Region only needs to specify the Components it is restricting, so it can be a subset of the DSD’s components. If the constraint is attached to multiple DSDs (either directly, or indirectly) then the Component Id must be a component which is shared by all DSDs.
Each Component which is restricted must define one or more code ids, which should be marked as being Included (present/allowed) or Excluded (not present/not allowed).
Data Structure
A Data Structure Definition is made up of three sections:
- Dimensions
- Attributes
- Component Restrictions
Dimensions Section
The Dimensions section contains a flat list of dimensions, each with a mandatory Id, Concept Reference, and Dimension Type. Each Dimension may optionally reference a Codelist and define a Text Type.
Concept references are in the format:
AgencyId:SchemeId(SchemeVersion).ConceptId
Codelist reference are in the format:
AgencyId:CodelistId(Version)
Dimension Types can be any of the following values:
- PrimaryMeasure
There must be a PrimayMeasure Dimension, and there must not be more than one. This dimension must be un-coded and have an Id of OBS_VALUE
- Dimension
MeasureDimension
TimeDimension There must only be one TimeDimension, and it must be un-coded. It is recommended that the TimeDimenison is the last Dimension.
An example of Dimensions is shown in the image below:
The columns F-G define dimension groupings, where dimensions included in the group are depicted by the relevant cell having the content ‘y’. The alias for each grouping is the column header, so in this example the groups ‘Group1’, ‘Group2’, and ‘Group3’ exist. Groups can be referenced by attributes, as described in the following section. If a group alias starts with the word ‘Group’ and is followed by a numerical value (e.g., ‘Group1’) then the generated attribute will reference all of the dimensions included in the group by Id (this is the equivalent SDMX attachment type of ‘Dimension Group’). If the group alias is anything else, then the generated Data Structure will include an explicit Group, with the id being set to the group alias. Any Dimensions that reference an explicit group will reference the Group by Id in the generated Data Structure Definition.
Attributes Section
The Attributes section contains a flat list of Attributes, each with a mandatory Id and Concept Reference. An Attribute must also define if it is Mandatory and what it is attached to. Each Attribute may optionally reference a Codelist and define a Text Type.
Concept references are in the format:
AgencyId:SchemeId(SchemeVersion).ConceptId
Codelist reference are in the format:
AgencyId:CodelistId(Version)
Attribute Attachment must be one of the following:
- Dataset
- Observation
- Group Alias (as defined in Dimensions Section)
An example of Attributes is shown in the image below:
Component Restriction Section
Each Component (Dimension or Attribute) may additionally have added restrictions on their content. This would usually not be the case for a Coded Component, as the Codelist provides the list of allowable enumerated content.
Each Component that has additional restrictions should be listed in this section, along with the value for each restriction. An example is shown below.
Dataflow
A Dataflow simply references a single Data Structure Definition, the reference is by:
AgencyId:Id(Version)
An example is shown below.
Provision Agreement
A Provision Agreement references a Dataflow and a Data Provider.
The Dataflow reference takes the following format:
AgencyId:Id(Version)
The Data Provider reference takes the following format:
AgencyId:DATA_PROVIDERS(1.0).ProviderId
An example is shown below.
Value Lists
Value Lists behave in exactly the same was as Codelists.
