Add custom symbol sets

Esri Maps for IBM Cognos provides a default set of symbols used to style point features on the map. In addition to modifying the default symbols, administrators can add their own custom symbol sets to the list of picture marker symbols report authors and consumers use to style their maps.

In Esri Maps for IBM Cognos, custom picture marker symbols are packaged in folders according to theme. These custom picture marker set folders are added to the esri-maps-em4c extension pack folder.

A custom picture marker symbol set folder contains the following:

A set of themed picture marker symbol files
A Picture Marker Set definition file (JSON) that describes each picture marker in the set

Once you have created the custom picture marker symbol set and added it to the esri-maps-em4c extension pack folder, you must modify the extension pack manifest file to include your custom symbol set.

Create a custom symbol set folder

Create a folder inside the esri-maps-em4c extension pack folder to store your symbol set files.

Browse to <em4c_location>\webcontent\esrimap\esri-maps-em4c.
Create a new folder and name it according to the theme of your picture marker set—for example, CrimeSymbols.
In the new folder, create a subfolder named images. This folder will store the picture marker symbol files you create.

Create custom picture markers

To ensure that the symbols display properly in the Symbol drop-down menus and on the map, create custom picture marker symbols that measure 20x20 pixels and save them in PNG format to preserve transparency.

Using your preferred graphics software, create a series of symbols that best represent your data.
For best visibility on the map, keep the symbols simple. To ensure that the symbols display properly in the Symbol drop-down menus and on the map, create symbols that measure 20x20 pixels, and save them in PNG or JPG format. Use the PNG format to preserve transparency, as shown in the following images.
JPG symbols
PNG symbols with transparency
Save the image files in the images folder you created—for example, CrimeSymbols\images.

Create a Picture Marker Set definition file

The Picture Marker Set definition is a JSON file that describes each of the picture marker symbols in your set.

In the following JSON example, each of the three custom symbol markers (*.png) is a separate object. Objects are enclosed in curly brackets ({ }) and separated by commas. Multiple objects are enclosed in square brackets ([ ]) to indicate an array. Each JSON object contains properties formatted as name-value pairs that represent data.

[
    {
        "type": "esriPMS",
        "url": "esri-maps-em4c/CrimeSymbols/images/crimeSymbol1.png",
        "width": "20",
        "height": "20",
        "xoffset": "0",
        "yoffset": "10"
    },
    {
        "type": "esriPMS",
        "url": "esri-maps-em4c/CrimeSymbols/images/crimeSymbol2.png",
        "width": "20",
        "height": "20",
        "xoffset": "0",
        "yoffset": "10"
    },
    {
        "type": "esriPMS",
        "url": "esri-maps-em4c/CrimeSymbols/images/crimeSymbol3.png",
        "width": "20",
        "height": "20",
        "xoffset": "0",
        "yoffset": "10"
    }
]

For each picture marker symbol in your set, you create a JSON object that includes the following properties. The type, url, width, and height properties are required; others are optional.

type—Specifies the type of symbol. The type property for a picture marker symbol is esriPMS.
url—Specifies the URL used to retrieve the image from the server.
width—Specifies the width, in points, of the symbol. To display the symbol in its original size, omit the width and height properties. To resize the symbol image, specify only the desired height, in points.
height—Specifies the height, in points, of the symbol. To display the symbol in its original size, omit the width and height properties. To resize the symbol image, specify only the desired height, in points.

Optional properties include the following:

xoffset—Specifies the horizontal offset, in points, of the marker symbol from the actual point location. Positive values offset to the right; negative values offset to the left.
yoffset—Specifies the vertical offset, in points, of the marker symbol from the actual point location. Positive values offset upward; negative values offset downward.
angle—Specifies the number of degrees (0 to 360) by which a marker symbol is rotated. Rotation occurs from east in a counterclockwise direction, where east is the 0° axis.
imageData—Specifies the base-64 encoded image data. This is used only when sharing layers or maps on ArcGIS Online.
contentType—Specifies the type of image data; for example, image/png. Used only if imageData is specified.

In your new symbol set folder (for example, CrimeSymbols), create a new JSON file, name it according to your custom marker set theme, and give it a .json.txt extension—for example, crimeSymbols.json.txt.
Tip:
Refer to the example provided with Esri Maps for IBM Cognos in <em4c_location>\webcontent\esrimap\esri-maps-em4c\symbols.json.txt.default.
Using your preferred text editor, create an array by typing opening and closing square brackets on separate lines. This array will contain the JSON objects that describe the picture marker symbols. For example:
```
[
]
```
Create a JSON object to describe the first custom picture marker.
Inside the array brackets, type a set of curly brackets, and then type the required name-value pairs that describe the picture marker symbol. Be sure to separate each property with a comma, and enclose each name-value element within quotation marks. Indent your code appropriately to ensure readability. For example:
```
[
	{
		“type” : “esriPMS”,
		“url” : “esri-maps-em4c/CrimeSymbols/images/symbol1.png”,
		“width” : “20”,
		“height” : “20”,
		“xoffset” : “0”,
		“yoffset” : “10”

	}
]
```

Create a new JSON object for each picture marker symbol in your set, adding a comma after the closing curly bracket of the previous object. A comma is not required after the last object in the array. For example:

[
	{
		“type” : “esriPMS”,
		“url” : “esri-maps-em4c/CrimeSymbols/images/symbol1.png”,
		“width” : “20”,
		“height” : “20”,
		“xoffset” : “0”,
		“yoffset” : “10”

	},
	{
	...
	}
]

Validate your JSON code using a validation tool such as JSONLint.
Save and close the definition file.

Modify the manifest file

The esri-maps-em4c extension pack folder contains a manifest file named manifest.json.txt that defines any custom picture marker set you create for Esri Maps for IBM Cognos, in addition to other tools and behaviors. To add your custom picture marker set to this file, you specify a name and label for the set, as well as the location and name of the set's definition file.

Browse to <em4c_location>\webcontent\esrimap\esri-maps-em4c.
In a text editor, open manifest.json.txt.
Modify the file to include your custom picture marker set. For example, add the following code to the end of the file:
```
,
	"pictureMarkerSets": [{
		"name": "crimesymbols",
		"label": "Crime Symbols",
		"location": "./CrimeSymbols/CrimeSymbols.json.txt"
	}]
```
The name property refers to the name of the set.
The label property specifies the label that appears in the drop-down menu of available symbol sets.
The location property points to the location of the custom picture marker set's definition file (for example, crimeSymbols.json.txt).
Tip:
Refer to the example provided with Esri Maps for IBM Cognos in <em4c_location>\webcontent\esrimap\esri-maps-em4c\manifest.json.txt.default.
Validate the updated JSON code using a validation tool such as JSONLint.
Save and close the file.

Test your custom picture marker symbols

Verify that your custom picture markers are available to Esri Maps for IBM Cognos report authors and consumers.

Restart your web server and clear the browser cache.
In Esri Maps Designer, open a map to edit it.
From the map's Contents pane, expand a point layer styled with icon symbols and click the icon to view a list of symbol sets. Your custom picture marker set should appear at the bottom of the list.
Perform the same test in consumer mode by viewing the report in Cognos Connection to ensure that the appropriate symbols appear in the list.

Your custom picture marker set is now ready to use.