Difference between revisions of "Explain Plan Web Services"

From Fusion Registry Wiki
Jump to navigation Jump to search
(→‎Overview)
 
(72 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
[[Category:WebService]]
 
[[Category:WebService]]
 +
[[Category:How_To]]
 
= Overview =
 
= Overview =
−
'''Note:''' this is the explanation for the Web Services in Fusion Registry version 10.
+
'''Note: this is the explanation for the Web Services in Fusion Registry Version 11.'''
  
 
The Registry has the User Interface feature "Test Mapping" which can be used to test an input file against a Mapping.  This feature is very useful when debugging why a mapping did not occur.  This page details how to directly call the Web Services that perform the explanation of a mapping
 
The Registry has the User Interface feature "Test Mapping" which can be used to test an input file against a Mapping.  This feature is very useful when debugging why a mapping did not occur.  This page details how to directly call the Web Services that perform the explanation of a mapping
  
−
== The Web Services ==
+
There are 2 Web Services.  The firsts "explains" what series dimensions of an input file would be mapped and which would be unmapped with regards to a specifc Map, the second analyses a particular Series Key.
−
There are 2 Web Services.  The firsts "explains" what series dimensions of an input file would be mapped and which would be unmapped with regards to a specifc Map, the second goes into detail abot a Series Key.
 
  
−
=== 'Explain Map' Web Service ===
+
== 'Explain Map' Web Service ==
  
−
For the supplied file and the URN of the mapping structure, returns a JSON obejct stating which series were mapped and which were unmapped from the input.
+
From the supplied file and the specified mapping structure URN, returns a JSON object stating which series were mapped and which were unmapped from the input.
  
 
{| class="wikitable"
 
{| class="wikitable"
Line 24: Line 24:
 
|style="background-color:#eaecf0"|<b>Accepts</b> || SDMX-ML, SDMX-JSON or SDMX-EDI structure message
 
|style="background-color:#eaecf0"|<b>Accepts</b> || SDMX-ML, SDMX-JSON or SDMX-EDI structure message
 
|-
 
|-
−
|style="background-color:#eaecf0"|<b>Content-Type</b> || <p>1. multipart/form-data (if attaching file) – the attached file must be in field name of uploadFile</p>
+
|style="background-color:#eaecf0"|<b>Content-Type</b> || application/text or application/xml</p>
−
<p>2. application/text or application/xml (if submitting data in the body of the POST)</p>
 
 
|-
 
|-
 
|style="background-color:#eaecf0"|<b>Response Format</b> || JSON object
 
|style="background-color:#eaecf0"|<b>Response Format</b> || JSON object
 
|-
 
|-
 
|style="background-color:#eaecf0"|<b>Response Statuses</b> || <p><b>200</b> - Query Ok<p>
 
|style="background-color:#eaecf0"|<b>Response Statuses</b> || <p><b>200</b> - Query Ok<p>
−
<p><b>401</b> - Unauthorized (if access has been restricted)</p>
+
<p><b>400</b> - Missing Header 'URN' or Unrecognised file input</p>
 +
<p><b>401</b> - Unauthorized</p>
 +
<p><b>404</b> - Cannot resolve reference to Structure Map specified in URN parameter
 
|}
 
|}
  
−
=== 'Explain Plan' Web Service ===
+
=== HTTP Headers ===
 +
The following header parameters must be specified:
  
−
Given the supplied Key and Map, returns a JSON obejct stating the input, mappings and output for that series key
+
{| class="wikitable"
 +
|-
 +
!|HTTP Header || Purpose || Allowed Values
 +
|-
 +
|style="background-color:#eaecf0"|<b>URN</b> || <p>(Mandatory) States the mapping structure to map the input data against.</p> || <p>A valid URN for a Mapping.  E.g. urn:sdmx:org.sdmx.infomodel.mapping.StructureMap=MAPPING_TEST:SS_DF(1.0).DF_MAP_TEST
 +
|}
 +
 
 +
=== Output ===
 +
The output JSON object has 4 fields: 
 +
* source - the URN of the DSD or Dataflow that was used as the source of the mapping
 +
* target - the URN of the DSD or Dataflow that was used as the target of the mapping
 +
* mapped - a JSON object. Each field is a unique input key that mapped. For each field is a String stating what it mapped to.
 +
* unmapped - a JSON Array of Strings showing which keys from the input were unmapped
 +
 
 +
=== Example Output ===
 +
 
 +
<pre>
 +
{
 +
    "source": "urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=MAPPING_TEST:DF_DSD1(1.0)",
 +
    "target": "urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=MAPPING_TEST:DF_DSD2(1.0)",
 +
    "mapped": {
 +
        "A:B:BEL": "AAAB:BEL:FIXED_EER",
 +
        "A:C:BEL": "AAAC:BEL:FIXED_EER",
 +
        "XXX:C:BAR": "AACC:BAR:FIXED_EER"
 +
    },
 +
    "unmapped": [
 +
        "C55BCX:C:BEL"
 +
    ]
 +
}
 +
</pre>
 +
 
 +
 
 +
=== HTTP Headers ===
 +
The following header parameters must be specified:
 +
 
 +
{| class="wikitable"
 +
|-
 +
!|HTTP Header || Purpose || Allowed Values
 +
|-
 +
|style="background-color:#eaecf0"|<b>URN</b> || <p>(Mandatory) States the mapping structure to map the input data against.</p> || <p>A valid URN for a Mapping.  E.g. urn:sdmx:org.sdmx.infomodel.mapping.StructureMap=MAPPING_TEST:SS_DF(1.0).DF_MAP_TEST
 +
|}
 +
 
 +
=== Output ===
 +
The output JSON object has 4 fields: 
 +
* source - the URN of the DSD or Dataflow that was used as the source of the mapping
 +
* target - the URN of the DSD or Dataflow that was used as the target of the mapping
 +
* mapped - a JSON object. Each field is a unique input key that mapped. For each field is a String stating what it mapped to.
 +
* unmapped - a JSON Array of Strings showing which keys from the input were unmapped
 +
 
 +
=== Example Output ===
 +
 
 +
<pre>
 +
{
 +
    "source": "urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=MAPPING_TEST:DF_DSD1(1.0)",
 +
    "target": "urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=MAPPING_TEST:DF_DSD2(1.0)",
 +
    "mapped": {
 +
        "A:B:BEL": "AAAB:BEL:FIXED_EER",
 +
        "A:C:BEL": "AAAC:BEL:FIXED_EER",
 +
        "XXX:C:BAR": "AACC:BAR:FIXED_EER"
 +
    },
 +
    "unmapped": [
 +
        "C55BCX:C:BEL"
 +
    ]
 +
}
 +
</pre>
 +
 
 +
== 'Explain Plan Series' Web Service ==
 +
'''Available from Version 11.9.6 onwards''' - ''the output is the same as the now deprecated 'Explain Plan' Web Service''
 +
 
 +
Given the specified Key and Map, returns a JSON object stating the input, mappings and output for that series key  
 +
 
 +
{| class="wikitable"
 +
|-
 +
|style="background-color:#eaecf0"|<b>Entry Point</b> || style="min-width:500px;" | <b> ws/secure/structuremap/explainmapseries</b>
 +
|-
 +
|style="background-color:#eaecf0"|<b>Access</b> || <span style='color:red'><b>Secure</b></span>
 +
|-
 +
|style="background-color:#eaecf0"|<b>Authentication</b> || HTTP Basic Authentication
 +
|-
 +
|style="background-color:#eaecf0"|<b>Http Method</b> || POST
 +
|-
 +
|style="background-color:#eaecf0"|<b>Accepts</b> || JSON message
 +
|-
 +
|style="background-color:#eaecf0"|<b>Content-Type</b> || application/json</p>
 +
|-
 +
|style="background-color:#eaecf0"|<b>Response Format</b> || JSON object
 +
|-
 +
|style="background-color:#eaecf0"|<b>Response Statuses</b> || <p><b>200</b> - Query Ok<p>
 +
<p><b>400</b> - Missing required field in JSON input</p>
 +
<p><b>401</b> - Unauthorized</p>
 +
<p><b>404</b> - Cannot resolve reference to Structure Map specified in URN parameter
 +
|}
 +
 
 +
=== Example Input ===
 +
<pre>
 +
{
 +
    "StructureMap": "urn:sdmx:org.sdmx.infomodel.structuremapping.StructureMap=MAPPING_TEST:DF_MAP(1.0)",
 +
    "Series": "A B.C.BAR.2003",
 +
    "MapFrom": "source",
 +
    "ComponentValues": {
 +
        "OBS_STATUS": "5D",
 +
        "OBS_VALUE": "9993"
 +
    }
 +
}
 +
</pre>
  
−
* Takes the parameters "dsd", "map", "key"
+
=== Output ===
 +
The output JSON object has the fields: 
 +
* reverseMapping - whether this was a reversed mapping or not
 +
* input a JSON object stating the dimensions and attributes input.  The dimensions will be the same as that passed in as the input parameter "key", but whereas the key only specified the value, this field shows the ID and value relationship.
 +
* unmapped - a list of any Dimensions that are unmapped
 +
* mappings - states the input mappings that were mapped as well as any fixed values output
 +
* output - a JSON object with a field of "dimensions". This field lists the IDs of the output DSD or Dataflow and states what the values would be.  If a dimension has a value of "null" it is unmapped. If it has a single value it was successfully mapped. If it has multiple values there this is also a failure as it is ambiguous as to what should be output.
  
 +
=== Example Output ===
 +
 +
<pre>
 +
{
 +
    "reverseMapping": false,
 +
    "input": {
 +
        "dimensions": {
 +
            "FREQ": "C55BCX",
 +
            "BIS_TOPIC": "C",
 +
            "REF_AREA": "BEL"
 +
        },
 +
        "attributes": {
 +
            "OBS_STATUS": null,
 +
            "OBS_PRE_BREAK": null,
 +
            "OBS_CONF": null,
 +
            "BREAKS": null,
 +
            "COVERAGE": null
 +
        }
 +
    },
 +
    "unmapped": [],
 +
    "mappings": {
 +
        "REF_AREA:BEL": {
 +
            "REF_AREA": [
 +
                "BEL"
 +
            ]
 +
        },
 +
        "OBS_VALUE:*": {
 +
            "EER_TYPE": [
 +
                "FIXED_EER"
 +
            ],
 +
            "COVERAGE": [
 +
                "FIXED_CVRG"
 +
            ]
 +
        }
 +
    },
 +
    "output": {
 +
        "dimensions": {
 +
            "INSTRUMENT_TYPE": [
 +
                null
 +
            ],
 +
            "REF_AREA": [
 +
                "BEL"
 +
            ],
 +
            "EER_TYPE": [
 +
                "FIXED_EER"
 +
            ]
 +
        }
 +
    }
 +
}
 +
</pre>
 +
 +
== 'Explain Plan' Web Service ==
 +
'''Deprecated in Fusion Registry version 11.9.6: Use 'Explain Plan Series Key' Web Service instead''' - ''The new POST service generates the same output as this Web Service''
 +
 +
Given the specified Key and Map, returns a JSON object stating the input, mappings and output for that series key
  
 
{| class="wikitable"
 
{| class="wikitable"
Line 53: Line 220:
 
|-
 
|-
 
|style="background-color:#eaecf0"|<b>Response Statuses</b> || <p><b>200</b> - Success</p>
 
|style="background-color:#eaecf0"|<b>Response Statuses</b> || <p><b>200</b> - Success</p>
 +
<p><b>400</b> - Missing or invalid parameter </p>
 
<p><b>401</b> - Unauthorized </p>
 
<p><b>401</b> - Unauthorized </p>
 +
<p><b>404</b> - Cannot resolve reference to Structure Map specified in "map" parameter
 +
|-
 
|}
 
|}
 +
 +
=== HTTP Query Parameters ===
 +
 +
{| class="wikitable"
 +
|-
 +
!| Request Parameter || Required || Purpose
 +
|-
 +
|style="background-color:#eaecf0"|<b>dsd</b>|| Yes || The URN of the DSD or Dataflow to map against. Depending on whether the source or target DSD / Dataflow is provided, the mapping can be reversed.
 +
|-
 +
|style="background-color:#eaecf0"|<b>map</b>|| Yes || The URN of the Structure Map to use in the mapping
 +
|-
 +
|style="background-color:#eaecf0"|<b>key</b>|| Yes || This is the token that was passed back from the Fusion registry server on the publication request
 +
|-
 +
|}
 +
 +
'''Note:''' in versions prior to Fusion Registry 10.9.4, the "dsd" parameter must specify a DSD and not a Datflow URN.
 +
 +
=== Output ===
 +
The output JSON object has the fields: 
 +
* reverseMapping - whether this was a reversed mapping or not
 +
* input a JSON object stating the dimensions and attributes input.  The dimensions will be the same as that passed in as the input parameter "key", but whereas the key only specified the value, this field shows the ID and value relationship.
 +
* unmapped - a list of any Dimensions that are unmapped
 +
* mappings - states the input mappings that were mapped as well as any fixed values output
 +
* output - a JSON object with a field of "dimensions". This field lists the IDs of the output DSD or Dataflow and states what the values would be.  If a dimension has a value of "null" it is unmapped. If it has a single value it was successfully mapped. If it has multiple values there this is also a failure as it is ambiguous as to what should be output.
 +
 +
=== Example Output ===
 +
 +
<pre>
 +
{
 +
    "reverseMapping": false,
 +
    "input": {
 +
        "dimensions": {
 +
            "FREQ": "C55BCX",
 +
            "BIS_TOPIC": "C",
 +
            "REF_AREA": "BEL"
 +
        },
 +
        "attributes": {
 +
            "OBS_STATUS": null,
 +
            "OBS_PRE_BREAK": null,
 +
            "OBS_CONF": null,
 +
            "BREAKS": null,
 +
            "COVERAGE": null
 +
        }
 +
    },
 +
    "unmapped": [],
 +
    "mappings": {
 +
        "REF_AREA:BEL": {
 +
            "REF_AREA": [
 +
                "BEL"
 +
            ]
 +
        },
 +
        "OBS_VALUE:*": {
 +
            "EER_TYPE": [
 +
                "FIXED_EER"
 +
            ],
 +
            "COVERAGE": [
 +
                "FIXED_CVRG"
 +
            ]
 +
        }
 +
    },
 +
    "output": {
 +
        "dimensions": {
 +
            "INSTRUMENT_TYPE": [
 +
                null
 +
            ],
 +
            "REF_AREA": [
 +
                "BEL"
 +
            ],
 +
            "EER_TYPE": [
 +
                "FIXED_EER"
 +
            ]
 +
        }
 +
    }
 +
}
 +
</pre>
 +
 +
= Simple Example =
 +
The file attached defines a number of Structural Metadata artefacts in the Agency "MAPPING_TEST" that can be loaded into a Registry. The structures files contain 2 Dataflows and 2 DSDs. 2 Concept Schemes, 2 Codelists and 1 Structure Map (with Representation Map) which maps the Dataflows. All structures are for the agency "MAPPING_TEST".
 +
* [[:File:STRUCTURES EXPLAINPLAN.zip|Structures SDMX 3.0]] - a zipped file for FMR 11 as is in SDMX 3 format
 +
* [[:File:EXPLAINPLAN-DATA.zip|Test Data]] - this data file should be unzipped before use, to give a small SDMX-ML data file. This file can be loaded against the Dataflows from the Structure file.
 +
 +
== Invoking the Explain Map ==
 +
Once the above Structural Metadata is loaded into your Registry, invoking the "Explain Map" Web Service by performing a POST call (using Curl, Python or POSTMAN) to:
 +
<pre>
 +
<your registry>/ws/secure/structuremap/explainmap
 +
</pre>
 +
 +
This also requires the Header parameter '''URN''' to be specified as '''urn:sdmx:org.sdmx.infomodel.mapping.StructureMap=MAPPING_TEST:SS_DF(1.0).DF_MAP_TEST'''
 +
<br/>
 +
The body should be the test file (above).
 +
<br>
 +
The resultant output will show that 3 series are mapped and the series "C55BCX:C:BEL" is unmapped.  Part of the output will show:
 +
<pre>
 +
"mapped": {
 +
        "A:B:BEL": "AAAB:BEL:FIXED_EER",
 +
        "A:C:BEL": "AAAC:BEL:FIXED_EER",
 +
        "XXX:C:BAR": "AACC:BAR:FIXED_EER"
 +
    },
 +
    "unmapped": [
 +
        "C55BCX:C:BEL"
 +
    ]
 +
</pre>
 +
 +
== Invoking the Explain Plan ==
 +
Now that we know that "C55BCX:C:BEL" is unmapped, we want to call the "explain plan" Web Service, to understand more about the unmapped series "C55BCX:C:BEL".  The query needs to specify the Structure Map and specifying the "dsd" to be the Dataflow Reference:
 +
<br>
 +
=== Version 10.9.4 and above Registries===
 +
The Dataflow URN can be specified as the "dsd" parameter like so:
 +
<pre>
 +
<your registry>/ws/secure/structuremap/explainplan?dsd=urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=MAPPING_TEST:DF_DSD1(1.0)&map=urn:sdmx:org.sdmx.infomodel.mapping.StructureMap=MAPPING_TEST:SS_DF(1.0).DF_MAP_TEST&key=C55BCX:C:BEL
 +
</pre>
 +
 +
=== Version 10.9.3 and below Registries===
 +
If the query used the DSD that the Dataflow is referencing (in the "dsd" parameter) the same result is achieved. The call with the underlying DSD is:
 +
<pre>
 +
<your registry>/ws/secure/structuremap/explainplan?dsd=urn:sdmx:org.sdmx.infomodel.datastructure.DataStructure=MAPPING_TEST:DSD1(1.0)&map=urn:sdmx:org.sdmx.infomodel.mapping.StructureMap=MAPPING_TEST:SS_DF(1.0).DF_MAP_TEST&key=C55BCX:C:BEL
 +
</pre>

Latest revision as of 06:23, 11 October 2023

Overview

Note: this is the explanation for the Web Services in Fusion Registry Version 11.

The Registry has the User Interface feature "Test Mapping" which can be used to test an input file against a Mapping. This feature is very useful when debugging why a mapping did not occur. This page details how to directly call the Web Services that perform the explanation of a mapping

There are 2 Web Services. The firsts "explains" what series dimensions of an input file would be mapped and which would be unmapped with regards to a specifc Map, the second analyses a particular Series Key.

'Explain Map' Web Service

From the supplied file and the specified mapping structure URN, returns a JSON object stating which series were mapped and which were unmapped from the input.

Entry Point ws/secure/structuremap/explainmap
Access Secure
Authentication HTTP Basic Authentication
Http Method POST
Accepts SDMX-ML, SDMX-JSON or SDMX-EDI structure message
Content-Type application/text or application/xml

Response Format JSON object
Response Statuses

200 - Query Ok

400 - Missing Header 'URN' or Unrecognised file input

401 - Unauthorized

404 - Cannot resolve reference to Structure Map specified in URN parameter

HTTP Headers

The following header parameters must be specified:

HTTP Header Purpose Allowed Values
URN

(Mandatory) States the mapping structure to map the input data against.

A valid URN for a Mapping. E.g. urn:sdmx:org.sdmx.infomodel.mapping.StructureMap=MAPPING_TEST:SS_DF(1.0).DF_MAP_TEST

Output

The output JSON object has 4 fields:

  • source - the URN of the DSD or Dataflow that was used as the source of the mapping
  • target - the URN of the DSD or Dataflow that was used as the target of the mapping
  • mapped - a JSON object. Each field is a unique input key that mapped. For each field is a String stating what it mapped to.
  • unmapped - a JSON Array of Strings showing which keys from the input were unmapped

Example Output

{
    "source": "urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=MAPPING_TEST:DF_DSD1(1.0)",
    "target": "urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=MAPPING_TEST:DF_DSD2(1.0)",
    "mapped": {
        "A:B:BEL": "AAAB:BEL:FIXED_EER",
        "A:C:BEL": "AAAC:BEL:FIXED_EER",
        "XXX:C:BAR": "AACC:BAR:FIXED_EER"
    },
    "unmapped": [
        "C55BCX:C:BEL"
    ]
}


HTTP Headers

The following header parameters must be specified:

HTTP Header Purpose Allowed Values
URN

(Mandatory) States the mapping structure to map the input data against.

A valid URN for a Mapping. E.g. urn:sdmx:org.sdmx.infomodel.mapping.StructureMap=MAPPING_TEST:SS_DF(1.0).DF_MAP_TEST

Output

The output JSON object has 4 fields:

  • source - the URN of the DSD or Dataflow that was used as the source of the mapping
  • target - the URN of the DSD or Dataflow that was used as the target of the mapping
  • mapped - a JSON object. Each field is a unique input key that mapped. For each field is a String stating what it mapped to.
  • unmapped - a JSON Array of Strings showing which keys from the input were unmapped

Example Output

{
    "source": "urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=MAPPING_TEST:DF_DSD1(1.0)",
    "target": "urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=MAPPING_TEST:DF_DSD2(1.0)",
    "mapped": {
        "A:B:BEL": "AAAB:BEL:FIXED_EER",
        "A:C:BEL": "AAAC:BEL:FIXED_EER",
        "XXX:C:BAR": "AACC:BAR:FIXED_EER"
    },
    "unmapped": [
        "C55BCX:C:BEL"
    ]
}

'Explain Plan Series' Web Service

Available from Version 11.9.6 onwards - the output is the same as the now deprecated 'Explain Plan' Web Service

Given the specified Key and Map, returns a JSON object stating the input, mappings and output for that series key

Entry Point ws/secure/structuremap/explainmapseries
Access Secure
Authentication HTTP Basic Authentication
Http Method POST
Accepts JSON message
Content-Type application/json

Response Format JSON object
Response Statuses

200 - Query Ok

400 - Missing required field in JSON input

401 - Unauthorized

404 - Cannot resolve reference to Structure Map specified in URN parameter

Example Input

{
    "StructureMap": "urn:sdmx:org.sdmx.infomodel.structuremapping.StructureMap=MAPPING_TEST:DF_MAP(1.0)",
    "Series": "A B.C.BAR.2003",
    "MapFrom": "source",
    "ComponentValues": {
        "OBS_STATUS": "5D",
        "OBS_VALUE": "9993"
    }
}

Output

The output JSON object has the fields:

  • reverseMapping - whether this was a reversed mapping or not
  • input a JSON object stating the dimensions and attributes input. The dimensions will be the same as that passed in as the input parameter "key", but whereas the key only specified the value, this field shows the ID and value relationship.
  • unmapped - a list of any Dimensions that are unmapped
  • mappings - states the input mappings that were mapped as well as any fixed values output
  • output - a JSON object with a field of "dimensions". This field lists the IDs of the output DSD or Dataflow and states what the values would be. If a dimension has a value of "null" it is unmapped. If it has a single value it was successfully mapped. If it has multiple values there this is also a failure as it is ambiguous as to what should be output.

Example Output

{
    "reverseMapping": false,
    "input": {
        "dimensions": {
            "FREQ": "C55BCX",
            "BIS_TOPIC": "C",
            "REF_AREA": "BEL"
        },
        "attributes": {
            "OBS_STATUS": null,
            "OBS_PRE_BREAK": null,
            "OBS_CONF": null,
            "BREAKS": null,
            "COVERAGE": null
        }
    },
    "unmapped": [],
    "mappings": {
        "REF_AREA:BEL": {
            "REF_AREA": [
                "BEL"
            ]
        },
        "OBS_VALUE:*": {
            "EER_TYPE": [
                "FIXED_EER"
            ],
            "COVERAGE": [
                "FIXED_CVRG"
            ]
        }
    },
    "output": {
        "dimensions": {
            "INSTRUMENT_TYPE": [
                null
            ],
            "REF_AREA": [
                "BEL"
            ],
            "EER_TYPE": [
                "FIXED_EER"
            ]
        }
    }
}

'Explain Plan' Web Service

Deprecated in Fusion Registry version 11.9.6: Use 'Explain Plan Series Key' Web Service instead - The new POST service generates the same output as this Web Service

Given the specified Key and Map, returns a JSON object stating the input, mappings and output for that series key

Entry Point ws/secure/structuremap/explainplan
Access Secure
Authentication HTTP Basic Authentication
Http Method GET
Response Format JSON object
Response Statuses

200 - Success

400 - Missing or invalid parameter

401 - Unauthorized

404 - Cannot resolve reference to Structure Map specified in "map" parameter

HTTP Query Parameters

Request Parameter Required Purpose
dsd Yes The URN of the DSD or Dataflow to map against. Depending on whether the source or target DSD / Dataflow is provided, the mapping can be reversed.
map Yes The URN of the Structure Map to use in the mapping
key Yes This is the token that was passed back from the Fusion registry server on the publication request

Note: in versions prior to Fusion Registry 10.9.4, the "dsd" parameter must specify a DSD and not a Datflow URN.

Output

The output JSON object has the fields:

  • reverseMapping - whether this was a reversed mapping or not
  • input a JSON object stating the dimensions and attributes input. The dimensions will be the same as that passed in as the input parameter "key", but whereas the key only specified the value, this field shows the ID and value relationship.
  • unmapped - a list of any Dimensions that are unmapped
  • mappings - states the input mappings that were mapped as well as any fixed values output
  • output - a JSON object with a field of "dimensions". This field lists the IDs of the output DSD or Dataflow and states what the values would be. If a dimension has a value of "null" it is unmapped. If it has a single value it was successfully mapped. If it has multiple values there this is also a failure as it is ambiguous as to what should be output.

Example Output

{
    "reverseMapping": false,
    "input": {
        "dimensions": {
            "FREQ": "C55BCX",
            "BIS_TOPIC": "C",
            "REF_AREA": "BEL"
        },
        "attributes": {
            "OBS_STATUS": null,
            "OBS_PRE_BREAK": null,
            "OBS_CONF": null,
            "BREAKS": null,
            "COVERAGE": null
        }
    },
    "unmapped": [],
    "mappings": {
        "REF_AREA:BEL": {
            "REF_AREA": [
                "BEL"
            ]
        },
        "OBS_VALUE:*": {
            "EER_TYPE": [
                "FIXED_EER"
            ],
            "COVERAGE": [
                "FIXED_CVRG"
            ]
        }
    },
    "output": {
        "dimensions": {
            "INSTRUMENT_TYPE": [
                null
            ],
            "REF_AREA": [
                "BEL"
            ],
            "EER_TYPE": [
                "FIXED_EER"
            ]
        }
    }
}

Simple Example

The file attached defines a number of Structural Metadata artefacts in the Agency "MAPPING_TEST" that can be loaded into a Registry. The structures files contain 2 Dataflows and 2 DSDs. 2 Concept Schemes, 2 Codelists and 1 Structure Map (with Representation Map) which maps the Dataflows. All structures are for the agency "MAPPING_TEST".

  • Structures SDMX 3.0 - a zipped file for FMR 11 as is in SDMX 3 format
  • Test Data - this data file should be unzipped before use, to give a small SDMX-ML data file. This file can be loaded against the Dataflows from the Structure file.

Invoking the Explain Map

Once the above Structural Metadata is loaded into your Registry, invoking the "Explain Map" Web Service by performing a POST call (using Curl, Python or POSTMAN) to: 

<your registry>/ws/secure/structuremap/explainmap

This also requires the Header parameter URN to be specified as urn:sdmx:org.sdmx.infomodel.mapping.StructureMap=MAPPING_TEST:SS_DF(1.0).DF_MAP_TEST
The body should be the test file (above).
The resultant output will show that 3 series are mapped and the series "C55BCX:C:BEL" is unmapped. Part of the output will show: 

"mapped": {
        "A:B:BEL": "AAAB:BEL:FIXED_EER",
        "A:C:BEL": "AAAC:BEL:FIXED_EER",
        "XXX:C:BAR": "AACC:BAR:FIXED_EER"
    },
    "unmapped": [
        "C55BCX:C:BEL"
    ]

Invoking the Explain Plan

Now that we know that "C55BCX:C:BEL" is unmapped, we want to call the "explain plan" Web Service, to understand more about the unmapped series "C55BCX:C:BEL". The query needs to specify the Structure Map and specifying the "dsd" to be the Dataflow Reference:

Version 10.9.4 and above Registries

The Dataflow URN can be specified as the "dsd" parameter like so: 

<your registry>/ws/secure/structuremap/explainplan?dsd=urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=MAPPING_TEST:DF_DSD1(1.0)&map=urn:sdmx:org.sdmx.infomodel.mapping.StructureMap=MAPPING_TEST:SS_DF(1.0).DF_MAP_TEST&key=C55BCX:C:BEL

Version 10.9.3 and below Registries

If the query used the DSD that the Dataflow is referencing (in the "dsd" parameter) the same result is achieved. The call with the underlying DSD is: 

<your registry>/ws/secure/structuremap/explainplan?dsd=urn:sdmx:org.sdmx.infomodel.datastructure.DataStructure=MAPPING_TEST:DSD1(1.0)&map=urn:sdmx:org.sdmx.infomodel.mapping.StructureMap=MAPPING_TEST:SS_DF(1.0).DF_MAP_TEST&key=C55BCX:C:BEL
Retrieved from "https://wiki.sdmxcloud.org/index.php?title=Explain_Plan_Web_Services&oldid=6488"