Creating parammapping.xml and MappingDefinitions.json

Before creating MappingDefinitions.json, make sure to study How Editable Parameter Defaults Work to understand the connections from library part parameters to attributes in your Archicad Plan file.

To be able to change parameter defaults on a library, the library packages have to contain a MappingDefinitions.json file. The meaning names listed in the MappingDefinitions.json can be referenced in the Mapping Value tables: this means you have to know what is in the MappingDefinitions.json so you know what can be referenced.

Because accessing MappingDefinitions.json requires extracting library packages, Graphisoft releases Mapping Value Tables for the official library, containing all editable parameter meanings. This way, the users do not have to extract library packages to know what names can be used in Mapping Value Tables, as all available ones are already included.

This article guides you through all other cases: if you want to improve the existing library or create your own library. Your main goal is to have a MappingDefinitions.json file for your library package. While you can make this JSON file by hand, it can also be created by the LP_XMLConverter during the building process. For this to happen, you have to create parammapping.xml files for your library parts in hsf.

On the process of converting to hsf format, read Conversion Between Library Formats, and continue with these steps afterwards:

  • Navigate to your hsf folder and step into a library part’s folder.
  • Copy the example parammapping.xml file from the example provided in Create a New libpack from Scratch/Upgrade .lcf to .libpack.
    • It should be copied into the same folder as libpartdata.xml, the root folder of a single library part.
  • Open and edit parammapping.xml.
    • The example file gives you an overview of how such a file is formatted: 
      <?xml version="1.0" encoding="UTF-8"?>
<ParameterMapping>
	<Parameter Name="A" Meaning="Shape/A" />
	<Parameter Name="B" Meaning="Shape/B" />
	<Parameter Name="ZZYZX" Meaning="Shape/ZZYZX" />
	<Parameter Name="iShapeType" Meaning="Shape/iShapeType" />
	<Parameter Name="gs_fill_type" Meaning="Shape/gs_fill_type" />
	<Parameter Name="gs_cont_pen" Meaning="Shape/gs_cont_pen" />
	<Parameter Name="gs_fill_pen" Meaning="Shape/gs_fill_pen" />
	<Parameter Name="gs_back_pen" Meaning="Shape/gs_back_pen" />
	<Parameter Name="surfShape" Meaning="Shape/surfShape" />
</ParameterMapping>

      • While the example file contains no such parameter types, parammapping.xml can also be applied to one-dimensional arrays:

        <Parameter Name="story_name_above" Row="1" Meaning="Elevator/story_name_above[1]" />
<Parameter Name="story_name_above" Row="2" Meaning="Elevator/story_name_above[2]" />

      • And two-dimensional arrays:

        <Parameter Name="defaultSizes" Row="1" Column="1" Meaning="Length_8.47" />
<Parameter Name="defaultSizes" Row="1" Column="2" Meaning="Length_2.56" />
  • Add a line for each parameter of your current library part that you wish to have a changeable default value for:
    • Parameter name : The names of parameters can be found in two places:
      • Archicad’s GDL Editor/Parameters tab/Variable column:

      • In hsf format’s paramlist.xml, marked with the Name tag.

        		<Length Name="B">
			<Description><![CDATA["Dimension 2"]]></Description>
			<Fix/>
			<Value>0.52</Value>
		</Length>
    • Meaning is a given name that can be referenced in Mapping Value Tables.
      • If the same Meaning name is used for multiple parameters (either in the same or separate library parts), the defaults of those parameter values can only be set to the same (this is why Graphisoft gave unique meaning names for every parameter of each library part – so that customization is entirely up to the user).
  • Repeat this process for each library part you have.
    • Macros can have parammapping.xml as well, but placeable library parts that call it will overwrite the parameter values that are transferred via the call.

    • You can add parammapping to library parts selectively: you can decide for each whether to have one or not.

After you are done with the parammapping files, generate MappingDefinitions.json with the following steps:

  • Create a folder in which the library can be built
  • Run the LP_XMLConverter with the following arguments:
  • The MappingDefinitions.json file is created directly in the library folder.