Version: Release 2 - 1.2.3.X

Layers

getGalleryLayers

List available gallery layers.

Parameters: None

Usage:

const gallery = await control.getGalleryLayers();

Response

[
	{
		"layerId": "d9ba522d-f7ef-4147-9a85-0d14b15f38ca",
		"layerName": "Contact",
		"layerType": "DataverseLayer",
		"layerDescription": "Person with whom a business unit has a relationship, such as customer, supplier, and colleague.",
		"subLayers": [
			{
				"sublayerId": "7b406359-6d7f-4109-8179-37d62a89638d",
				"sublayerName": "My Active Contacts",
				"sublayerDescription": null
			},
			{
				"sublayerId": "a5e611d9-b6b4-431a-816b-cc6eca6d52b8",
				"sublayerName": "All Contacts",
				"sublayerDescription": null
			}
		]
	}
]

getSublayerAttributes

Gets all sublayers details

Parameters:

Field	Type	Required	Description
layerId	string	Yes	Id of a parent returned by `getGalleryLayers()`.
sublayerId	string	Yes	Id of a sublayer returned by `getGalleryLayers()`.

Usage:

const attributes = await control.getSublayerAttributes(layerId, sublayerId);

Response

{
    "sublayerId": "7b406359-6d7f-4109-8179-37d62a89638d",
    "sublayerName": "My Active Contacts",
    "sublayerDescription": null,
    "subLayerAttributes": [
        {
            "fieldName": "contactid",
            "displayName": "Contact",
            "displayType": "String",
            "isFilterable": true,
            "orderNumber": 1,
            "type": "guid",
            "value": "",
            "visibility": true,
            "enabled": true
        },
        {
            "fieldName": "emailaddress1",
            "displayName": "Email",
            "displayType": "String",
            "isFilterable": true,
            "orderNumber": 2,
            "type": "string",
            "value": "",
            "visibility": true,
            "enabled": true
        },
        {
            "fieldName": "fullname",
            "displayName": "Full Name",
            "displayType": "String",
            "isFilterable": true,
            "orderNumber": 3,
            "type": "string",
            "value": "",
            "visibility": true,
            "enabled": true
        },
        {
            "fieldName": "parentcustomerid",
            "displayName": "Company Name",
            "displayType": "Object",
            "isFilterable": true,
            "orderNumber": 4,
            "type": "object",
            "value": "",
            "visibility": true,
            "enabled": true
        },
        {
            "fieldName": "telephone1",
            "displayName": "Business Phone",
            "displayType": "String",
            "isFilterable": true,
            "orderNumber": 5,
            "type": "string",
            "value": "",
            "visibility": true,
            "enabled": true
        },
        {
            "fieldName": "mtrcore_latitude",
            "displayName": "Latitude",
            "displayType": "Number",
            "isFilterable": true,
            "orderNumber": 262,
            "type": "number",
            "value": "",
            "visibility": true,
            "enabled": true
        },
        {
            "fieldName": "mtrcore_longitude",
            "displayName": "Longitude",
            "displayType": "Number",
            "isFilterable": true,
            "orderNumber": 263,
            "type": "number",
            "value": "",
            "visibility": true,
            "enabled": true
        }
    ]
}

createSublayerInstance

Enable a sublayer based on enabled layers

Parameters:

Field	Type	Required	Description
layerId	string	Yes	Id of a parent returned by `getGalleryLayers()`.
sublayerId	string	Yes	Id of a sublayer returned by `getGalleryLayers()`.

Usage:

await control.createSublayerInstance(layerId, sublayerId);

createSublayerInstanceWithFilter

Enable a sublayer with an initial filter based on enabled layers

Parameters:

Field	Type	Required	Description
layerId	string	Yes	Id of a parent returned by `getGalleryLayers()`.
sublayerId	string	Yes	Id of a sublayer returned by `getGalleryLayers()`.

Usage:

await control.createSublayerInstanceWithFilter(layerId, sublayerId, {
  type: 'ui' // will always be ui,
  expressions: [{ field: 'status', operator: 'equals', value: 'Active' }],
  matchType: 'all'
});

getEnabledSublayerInstances

Return an array of currently enabled (instantiated) sublayer instances.

Parameters: None

Usage:

const enabled = await control.getEnabledSublayerInstances();
console.log(enabled);

Response

[
    {
        "sublayerInstanceId": "fba870dc-284d-4b7d-a37f-84ed3a9ada8d",
        "sublayerId": "81c285b6-5962-437c-8ae4-a1312441809d",
        "sublayerName": "Active Accounts",
        "subLayerAttributes": [
            {
                "fieldName": "accountid",
                "displayName": "Account",
                "displayType": "String",
                "isFilterable": true,
                "orderNumber": 1,
                "type": "guid",
                "value": "",
                "visibility": true,
                "enabled": true
            },
            {
                "fieldName": "address1_city",
                "displayName": "Address 1: City",
                "displayType": "String",
                "isFilterable": true,
                "orderNumber": 2,
                "type": "string",
                "value": "",
                "visibility": true,
                "enabled": true
            },
            {
                "fieldName": "name",
                "displayName": "Account Name",
                "displayType": "String",
                "isFilterable": true,
                "orderNumber": 3,
                "type": "string",
                "value": "",
                "visibility": true,
                "enabled": true
            },
            {
                "fieldName": "_primarycontactid_value",
                "displayName": "Primary Contact Id",
                "displayType": "String",
                "isFilterable": true,
                "orderNumber": 4,
                "type": "lookup",
                "value": "",
                "visibility": true,
                "enabled": true
            },
            {
                "fieldName": "_primarycontactid_value@OData.Community.Display.V1.FormattedValue",
                "displayName": "Primary Contact",
                "displayType": "String",
                "isFilterable": true,
                "orderNumber": 4,
                "type": "string",
                "value": "",
                "visibility": true,
                "enabled": true
            },
            {
                "fieldName": "telephone1",
                "displayName": "Main Phone",
                "displayType": "String",
                "isFilterable": true,
                "orderNumber": 5,
                "type": "string",
                "value": "",
                "visibility": true,
                "enabled": true
            },
            {
                "fieldName": "accountprimarycontactidcontactcontactid.emailaddress1",
                "displayName": "Email",
                "displayType": "String",
                "isFilterable": true,
                "orderNumber": 1,
                "type": "string",
                "value": "",
                "visibility": true,
                "enabled": true
            },
            {
                "fieldName": "mtrcore_latitude",
                "displayName": "Latitude",
                "displayType": "Number",
                "isFilterable": true,
                "orderNumber": 180,
                "type": "number",
                "value": "",
                "visibility": true,
                "enabled": true
            },
            {
                "fieldName": "mtrcore_longitude",
                "displayName": "Longitude",
                "displayType": "Number",
                "isFilterable": true,
                "orderNumber": 181,
                "type": "number",
                "value": "",
                "visibility": true,
                "enabled": true
            }
        ]
    },
    {
        "sublayerInstanceId": "ab27366c-9450-4d1b-9b56-a883b4380212",
        "sublayerId": "a5e611d9-b6b4-431a-816b-cc6eca6d52b8",
        "sublayerName": "All Contacts",
        "subLayerAttributes": [
            {
                "fieldName": "contactid",
                "displayName": "Contact",
                "displayType": "String",
                "isFilterable": true,
                "orderNumber": 1,
                "type": "guid",
                "value": "",
                "visibility": true,
                "enabled": true
            },
            {
                "fieldName": "emailaddress1",
                "displayName": "Email",
                "displayType": "String",
                "isFilterable": true,
                "orderNumber": 2,
                "type": "string",
                "value": "",
                "visibility": true,
                "enabled": true
            },
            {
                "fieldName": "fullname",
                "displayName": "Full Name",
                "displayType": "String",
                "isFilterable": true,
                "orderNumber": 3,
                "type": "string",
                "value": "",
                "visibility": true,
                "enabled": true
            },
            {
                "fieldName": "parentcustomerid",
                "displayName": "Company Name",
                "displayType": "Object",
                "isFilterable": true,
                "orderNumber": 4,
                "type": "object",
                "value": "",
                "visibility": true,
                "enabled": true
            },
            {
                "fieldName": "statecode",
                "displayName": "Status",
                "displayType": "Object",
                "isFilterable": true,
                "orderNumber": 5,
                "type": "object",
                "value": "",
                "visibility": true,
                "enabled": true
            },
            {
                "fieldName": "telephone1",
                "displayName": "Business Phone",
                "displayType": "String",
                "isFilterable": true,
                "orderNumber": 6,
                "type": "string",
                "value": "",
                "visibility": true,
                "enabled": true
            },
            {
                "fieldName": "mtrcore_latitude",
                "displayName": "Latitude",
                "displayType": "Number",
                "isFilterable": true,
                "orderNumber": 264,
                "type": "number",
                "value": "",
                "visibility": true,
                "enabled": true
            },
            {
                "fieldName": "mtrcore_longitude",
                "displayName": "Longitude",
                "displayType": "Number",
                "isFilterable": true,
                "orderNumber": 265,
                "type": "number",
                "value": "",
                "visibility": true,
                "enabled": true
            }
        ]
    }
]

showSublayerInstance

Once a sublayer is available in layer panel then you can toggle its visibility

Parameters:

Field	Type	Required	Description
subLayerInstanceId	string	Yes	Id of the enabled sublayer instance to make visible.

Usage:

await control.showSublayerInstance(sublayerInstanceId);

hideSublayerInstance

Once a sublayer is available in layer panel then you can toggle its visibility

Parameters:

Field	Type	Required	Description
subLayerInstanceId	string	Yes	Id of the enabled sublayer instance to hide.

Usage:

control.hideSublayerInstance(sublayerInstanceId);

removeSublayerInstance

Removes the layer instance from the layer panel and the map. This action fully disables the layer until it is re-added.

Parameters:

Field	Type	Required	Description
subLayerInstanceId	string	Yes	Id of the enabled sublayer instance to remove entirely.

Usage:

control.removeSublayerInstance(sublayerInstanceId);

navigateToSublayerInstance

Pans and zooms the map to the geographic extent of the specified enabled layer instance.

Parameters:

Field	Type	Required	Description
subLayerInstanceId	string	Yes	Id of the enabled sublayer instance whose extent to navigate to.

Usage:

control.navigateToSublayerInstance(sublayerInstanceId);

filterSublayerInstance

Apply or replace a filter on an existing sublayer instance. Each call overwrites the previous filter of the same filter type.

Parameters:

Field	Type	Required	Description
subLayerInstanceId	string	Yes	Target enabled sublayer instance.
filter	Filter	Yes	Object with `type`, `expressions[]`, `matchType` ('all' or 'any'). Overwrites previous filter of same `type`.

Usage:

control.filterSublayerInstance(instanceId, {
	type: 'ui',
	expressions: [{ field: 'priority', operator: 'greaterThanOrEquals', value: 3 }],
	matchType: 'all',
});

tip

Use distinct type values (e.g. ui, search, action) to layer multiple logical filters if supported.

clearFilterFromSublayerInstance

Removes any filter applied to an active sublayer in the panel

Parameters:

Field	Type	Required	Description
subLayerInstanceId	string	Yes	Id of the enabled sublayer instance to clear filters from.

Usage:

control.clearFilterFromSublayerInstance(sublayerInstanceId);

updateSublayerInstanceOpacity

Change the visual opacity (transparency) of a sublayer instance.

Parameters:

Field	Type	Required	Description
subLayerInstanceId	string	Yes	Id of the enabled sublayer instance to modify.
opacity	number	Yes	0 (transparent) to 100 (opaque). Values outside range are clamped.

Usage:

await control.updateSublayerInstanceOpacity(instanceId, 50);

getVisibleSublayerInstanceData

Retrieve a paged set of features currently within the map view for a given instance.

Parameters:

Field	Type	Required	Description
subLayerInstanceId	string	Yes	Instance whose visible features to fetch.
pageNumber	number	Yes	1-based page index.
pageToken	string	Optional	Continuation token from prior call if paging further.

Usage:

const page1 = await control.getVisibleSublayerInstanceData(instanceId, 1);
if (page1?.nextPageToken) {
	const page2 = await control.getVisibleSublayerInstanceData(instanceId, 2, page1.nextPageToken);
}

Response

{
    "features": [
        {
            "id": "1757988822653",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    121.85909,
                    -27.4556179
                ]
            },
            "properties": {},
            "centroid": {
                "x": 121.85909,
                "y": -27.4556179,
                "z": 0
            },
            "extent": {
                "xmin": 121.85909,
                "ymin": -27.4556179,
                "xmax": 121.85909,
                "ymax": -27.4556179,
                "zmin": 0,
                "zmax": 0,
                "spatialReference": {
                    "wkid": 4326,
                    "latestWkid": 4326
                }
            },
            "totalCoordinateCount": 1,
            "levelOfDetail": 0,
            "layerInstanceId": "fba870dc-284d-4b7d-a37f-84ed3a9ada8d"
        },
        {
            "id": "1757988822654",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    122.1263031,
                    -27.636399
                ]
            },
            "properties": {},
            "centroid": {
                "x": 122.1263031,
                "y": -27.636399,
                "z": 0
            },
            "extent": {
                "xmin": 122.1263031,
                "ymin": -27.636399,
                "xmax": 122.1263031,
                "ymax": -27.636399,
                "zmin": 0,
                "zmax": 0,
                "spatialReference": {
                    "wkid": 4326,
                    "latestWkid": 4326
                }
            },
            "totalCoordinateCount": 1,
            "levelOfDetail": 0,
            "layerInstanceId": "fba870dc-284d-4b7d-a37f-84ed3a9ada8d"
        }
    ],
    "allDataReturned": true
}

getAllSublayerInstanceData

Retrieve paged features ignoring current map extent (full dataset slice for the instance, subject to server limits).

Parameters:

Field	Type	Required	Description
subLayerInstanceId	string	Yes	Instance whose full dataset slice to fetch.
pageNumber	number	Yes	1-based page index.
pageToken	string	Optional	Continuation token from prior call if paging further.

Usage:

control.getAllSublayerInstanceData(sublayerInstanceId, 1);

querySublayerInstanceData

Retrieve paged features with custom filtering by map extent, search text, and filter expressions. Unlike getAllSublayerInstanceData, which returns only features already filtered by the map's default filters and search mechanisms, this function allows direct querying of the layer with your own custom parameters, giving you full control over the results.

Parameters:

Field	Type	Required	Description
sublayerInstanceId	string	Yes	Instance to query.
mapExtent	Extent	Yes	Geographic extent to filter by; pass `undefined` to ignore extent filtering.
pageNumber	number	Yes	1-based page index.
nextPageToken	string	Optional	Continuation token from prior call if paging further.
searchText	string	Optional	Free-text search string to match against indexed fields.
searchFilter	FilterGroup	Optional	Structured filter expressions to apply in addition to search text.
searchWithinFilteredAreas	boolean	Optional	If true, search is constrained to areas already filtered by other mechanisms.
abortSignal	AbortSignal	Optional	Signal to cancel the request if still pending.

Usage:

const control = globalThis.MaptaskrControlManager.getControl(controlId);

const preloadedSublayerID = 'a5e611d9-b6b4-431a-816b-cc6eca6d52b8'; //the sublayer you are looking for

// Wait for sublayerInstanceId to become available
async function waitForSublayerInstanceId(timeoutMs = 10000, intervalMs = 1000) {
	const start = Date.now();

	while (Date.now() - start < timeoutMs) {
		const instances = control.getEnabledSublayerInstances();
		const match = instances.find((i) => i?.sublayerId === preloadedSublayerID);

		if (match) {
			console.log('Sublayer instance found:', match.sublayerInstanceId);
			return match.sublayerInstanceId;
		}

		console.log('Waiting for sublayer instance to be available...');
		await new Promise((resolve) => setTimeout(resolve, intervalMs));
	}

	console.warn('Timed out waiting for sublayer instance.');
	return null;
}

const sublayerInstanceId = await waitForSublayerInstanceId();

if (!sublayerInstanceId) {
	console.error('Cannot proceed without sublayerInstanceId');
	return;
}

const filterField = 'fullname';
const filterOperator = 'contains';
const filterValue = 'steve';

const results = await control.querySublayerInstanceData(
	sublayerInstanceId, // this is the SUBLAYERINSTANCEID not SUBLAYERID - you need to find the instances with getEnabledSublayerInstances
	undefined, // either an extent (see getMapExtent) or undefined
	1, // the page number starting at 1
	undefined, // the next page token, if you dont need it, set it to undefined
	undefined, // the free text search field, if you dont want to search, set this to undefined
	{
		filters: [
			//filter object must exist.
			{
				type: 'search', // this MUST be the word 'search'
				expressions: [
					{
						field: filterField, // the field name to filter by
						operator: filterOperator, // the operator to use (equals, contains, etc...)
						value: filterValue, // the value of the field to filter
					},
				],
				matchType: 'all', // match type can be 'any' or 'all'
			},
		],
	},
	false, // set to true if you wish to only return results in filtered areas, false if you wish to search the world
	undefined // the abort signal (used to abort the call if required), set to undefined if you dont know what this means
);

showVisibleDataTabForSublayerInstance

Displays the data tab for the specified sublayer instance, automatically filtering the table to show only the features currently visible within the user's map view. Parameters:

Field	Type	Required	Description
subLayerInstanceId	string	Yes	Instance whose data tab should display filtered to current map view.

Usage:

control.showVisibleDataTabForSublayerInstance(subLayerInstanceId);

moveLayerZOrder

Changes the Z-order of an enabled sublayer instance so it draws in front of or behind other sublayers in the map and layer panel. Parameters:

Field	Type	Required	Description
sublayerInstanceId	string	Yes	Instance of the sublayer you want to reposition.
orderAction	string	Yes	One of `sendBackward`, `sendToBack`, `bringForward`, `bringToFront` describing whether to move the layer back or front.

Usage:

control.moveLayerZOrder(subLayerInstanceId, orderAction);

Example

const control = globalThis.MaptaskrControlManager.getControl(controlId);

async function MoveLayerToBack() {
	try {
		// Get all enabled instances
		const enabled = await control.getEnabledSublayerInstances();

		// Filter out all bar the one you want to move
		const contactSublayer = enabled.findLast((sublayer) => sublayer.sublayerName === 'All Contacts');

		if (!contactSublayer) {
			console.warn('No enabled "All Contacts" sublayers found.');
			return;
		}

		// Move the selected sublayer to the back of the Z-order
		control.moveLayerZOrder(contactSublayer.sublayerInstanceId, 'sendToBack');
	} catch (error) {
		console.error('Error in MoveLayerToBack:', error);
	}
}

showAllDataTabForSublayerInstance

Displays the data tab for the specified sublayer instance, displaying all data for that sublayer.

Parameters:

Field	Type	Required	Description
subLayerInstanceId	string	Yes	Instance whose full data tab should display (ignores current view extent).

Usage:

control.showAllDataTabForSublayerInstance(subLayerInstanceId);

hideDataTabForSublayerInstance

Hides the data tab for the specified sublayer instance.

Parameters:

Field	Type	Required	Description
subLayerInstanceId	string	Yes	Instance whose data tab should be hidden.

Usage:

control.hideDataTabForSublayerInstance(subLayerInstanceId);

hideAllDataTabs

Hides all data tabs on the map.

Parameters:

Field	Type	Required	Description
subLayerInstanceId	string	Yes	(Optional usage) Provided if API supports targeted hide; otherwise hides all tabs regardless.

Usage:

control.hideAllDataTabs(subLayerInstanceId);

getGalleryLayers​

getSublayerAttributes​

createSublayerInstance​

createSublayerInstanceWithFilter​

getEnabledSublayerInstances​

showSublayerInstance​

hideSublayerInstance​

removeSublayerInstance​

navigateToSublayerInstance​

filterSublayerInstance​

clearFilterFromSublayerInstance​

updateSublayerInstanceOpacity​

getVisibleSublayerInstanceData​

getAllSublayerInstanceData​

querySublayerInstanceData​

showVisibleDataTabForSublayerInstance​

moveLayerZOrder​

showAllDataTabForSublayerInstance​

hideDataTabForSublayerInstance​

hideAllDataTabs​

getGalleryLayers

getSublayerAttributes

createSublayerInstance

createSublayerInstanceWithFilter

getEnabledSublayerInstances

showSublayerInstance

hideSublayerInstance

removeSublayerInstance

navigateToSublayerInstance

filterSublayerInstance

clearFilterFromSublayerInstance

updateSublayerInstanceOpacity

getVisibleSublayerInstanceData

getAllSublayerInstanceData

querySublayerInstanceData

showVisibleDataTabForSublayerInstance

moveLayerZOrder

showAllDataTabForSublayerInstance

hideDataTabForSublayerInstance

hideAllDataTabs