Use URL Parameters—ArcGIS Knowledge Server | Documentation for ArcGIS Enterprise

ArcGIS Knowledge Studio can be integrated with other apps by using links to open Knowledge Studio. For example, you can create app links to launch and open Knowledge Studio and create or update specific content from another Esri app, a web map pop-up, or a simple hyperlink in an email or website.

A URL parameter is a name-value pair. In each parameter, the name and value are separated by an equal sign (=).

Note:

Throughout this topic, values that are specific to the context of the url request are wrapped in greater than and less than signs (<>). For example, in this urlhttps://<YourPortal>/apps/knowledge-studio/main?, <YourPortal> should be replaced by the location of your portal.

Share Knowledge Studio project content

You can share a url to a specific content item, stored query, entity or relationship in a Knowledge Studioproject. Each map, link chart, data card, stored query, the dashboard view and the selected record in the knowledge graph view have a unique url that you can share to link to a specific content item or entity or relationship in the project.

To share maps, link charts, stored queries and data cards, you must save your project. You can share a url to a specific entity or relationship from any project.

Base URL

A Knowledge Studio project automatically generates URLs that you can use to share a specific content item, entity or relationship in the Knowledge Graph view or stored query. You can also use these URL components to create URLs with the URL Authoring Parameters to create new content, add entities and relationships to existing content or execute stored queries.

Knowledge Studio Projects URLs have the following structure:

The first section directs you to Knowledge Studio.

https://<YourPortal>/portal/apps/knowledge-studio/main?

The Knowledge Studio project id is added after the question mark (?). If you are using a Knowledge Studio project you have saved to the portal, it's portal item id is used. If you have not saved the project, the portal item id of the knowledge graph service you are exploring is used as the project id until you save the project.

id=b1ce0d5b814c40ba8809fb3625f476db

Content ids

All parameters after the project id are added with an ampersand (&) and specify which content items is selected with additional parameters depending on that content item. Since a Knowledge Studio project can only contain one of each default view -- dashboard, query and knowledge graph-- these views have a named id. All other content items are given a unique identifier in the project.

&selectedContentId=<contentID>


Content Item	Content Id
Knowledge Graph View	dataExplorer
Query View	queryViewer
Dashboard View	dashboard
Maps and link charts	Generated by the project when the content item is added or created in the format cb4449dd-886c-4623-837b-7a5685a76fc7

View specific parameters

The Knowledge Graph View and Query View can have additional parameters that provide additional context. All parameters must be followed by an equal sign (=) and then the value.


Content Item	Additional Parameters	Values	Details
Knowledge Graph View	selectedContentElement	The unique identifier of the selected entity or relationship.	The URL Encoded unique identifier for an entity or a relationship. For example if the id is {B1FF2B9A6-C146-4913-A364-BC81F66A025D} the curly brackets ({}) must be encoded to %7B1FF2B9A6-C146-4913-A364-BC81F66A025D%7D.
Knowledge Graph View	selectedContentInstruction	entity relationship	Specifies if the id is for an entity or a relationship.
Query View	selectedContentElement	The unique identifier for a stored query	Only added when a Stored Query is selected in the formatcb4449dd-886c-4623-837b-7a5685a76fc7

An example of a URL that will take you to a specific entity in the Knowledge Graph view

https://<YourPortal>/portal/apps/knowledge-studio/main?id=ddd37b4f73904c7ba073d9fed75dba6c&selectedContentId=dataExplorer&selectedContentElement=%7B29018C8F-A061-4889-B5BB-77714E4ACC3D%7D&selectedContentInstruction=entity

An example of a URL that will take you to a specific stored query in the Query view. Sharing stored queries this way is only possible if the project has been saved.

https://<YourPortal>/portal/apps/knowledge-studio/main?id=ddd37b4f73904c7ba073d9fed75dba6c&selectedContentId=queryViewer
&selectedContentElement=cb4449dd-886c-4623-837b-7a5685a76fc7

URL Authoring Parameters

You can provide additional parameters to a Knowledge Studio URL to author content in a Knowledge Studio project from another Esri app, a web map pop-up, or a simple hyperlink in an email or website. The following actions are supported through authoring parameters.

Create new maps and link charts
Add entities and relationships to existing maps and link charts
Create new maps and link charts from a template
Create new stored query
Run existing stored query with new parameters

The base URL for using authoring parameters is:

https://<YourPortal>/portal/apps/knowledge-studio/studioApiContent?

After the question mark the following parameters are required for all authoring actions:


Parameter	Value	Details
version	The ArcGIS Enterprise version number
operation	createNew addToExisting executeQuery createQuery	The operation you want to perform with the URL parameters. You can create new content, add to existing content or execute queries.
id	Knowledge Studio Project item id or Knowledge Graph Service item id	The portal item id for a Knowledge Studio project or a knowledge graph service. You can create new content using a Knowledge Studio project portal item or a new unsaved project initialized form a Knowledge Graph Service portal item. Adding to existing content and executing existing queries can only be done with a Knowledge Studio project portal item.

Each operation has additional required parameters depending on the action you want to take.

URL Encoding

When passing a parameter to a dashboard at run time, make sure to encode its value. Encoding ensures that invalid characters are replaced with the percent sign (%) followed by their hexadecimal equivalent. To include multiple parameters, you must separate them with ampersands (&).

Note:

One way to create encoded parameters is to use ArcGIS Arcade. The UrlEncode function allows you to define a collection of key value pairs that represent each parameter and produce a URL with appropriate encoding.

Note:

The order of the parameters does not matter. For example, param=value&param2=value2 and param=value&param2=value2 produce the same result.

Create new content items

You can create a new map or link chart with entities and relationships in a Knowledge Studioproject. You can also create a new map or link chart using an existing content item of the same type as a template. New content can be created in an existing project or in a new project.

Note:

Linked portal content items cannot be used as a template to create new content items.

To create a new content item in an existing project, provide the project item id in the id parameter. To create a map or link chart in a new unsaved project, provide the knowledge graph service item id in the id parameter. The following parameters are used to create new maps and link charts:


Parameter	Value	Details
entityIds	Array of unique IDs	An array of the unique identifiers for the entities to add to the content item.
relationshipIds	Array of unique IDs	An array of the unique identifiers for the relationships to add to the content item. If you provide only relationship ids, their origin and destination entities will automatically be added.
contentType	map linkChart	The type of content item to create in the project
properties	linkChartProperties object	layoutType object	The link chart layout type to use on the new link chart. SeeLayout Types for the supported layout types.
properties	linkChartProperties object	layoutSettings object (optional)	Layout settings for any organic or chronological layouts. See Layout Settings for more details on the configurable settings
contentId (optional)	Knowledge Studio Project content id	The id of the content item to use as a template. If provided the layer definition of the content item will be used to create the new content item. The template content item must be of the same content type as the new content item.

An example of a linkChartProperties object with just the layoutType specified:

{ "linkChartProperties" : { "layoutType" : "force-directed" } }

An example layoutSettings object for geographic layout. Layout settings are optional and are only supported for organic and chronological layouts. See Layout Settings for additional layout settings options. These objects must be encoded to work as a URL parameter value.

{
    "linkChartProperties":{
        "layoutType":"geographic-organic-standard",
        "layoutSettings":{
            "organicLayoutSettings": {
                "absoluteIdealEdgeLength": 5,
                "computationBudgetTime": 2,
                "autoRepulsionRadius": false,
                "idealEdgeLengthType": "absolute-value"
                "multiplicativeIdealEdgeLength": 1,
                "repulsionRadiusMultiplier": 1
            }
        }
    }
}

Add to existing content items

You can add entities and relationships to an existing map or link chart in a Knowledge Studio project. You can only add to existing content using a Knowledge Studio project content item.


Parameter	Value	Details
entityIds	Array of unique IDs	An array of the unique identifiers for the entities to add to the content item
relationshipIds	Array of unique IDs	An array of the unique identifiers for the relationships to add to the content item. If you provide only relationship ids, their origin and destination entities will automatically be added
contentId	Knowledge Studio Project content id	The identifier for the content item to. This can be found in the Knowledge Studio project URL when the content item is the open tab

Create new queries

You can create and execute new queries in a Knowledge Studio project. New content can be created in an existing project or in a new project.

To create a new query in an existing project, provide the project item id in the id parameter. To create a query in a new unsaved project, provide the knowledge graph service item id in the id parameter. The following parameters are used to create new maps and link charts:

The following properties can be used to create a new query:


Parameter	Value	Details
properties	name	The name of the new stored query to create.
	openCypherQuery	The openCypher query to execute.Learn more about openCypher queries
	description (optional)	A description of the new stored query.
	provenanceBehavior (optional)	Specifies whether or not the query results should include or exclude provenance results. If not specified the default is exclude. include exclude
	bindParameters (optional)	An array of objects for each parameter to use in the query. Parameters are optional, however if you use a parameter in your query you must provide the parameter information in the bindParameter URL parameter. The URL parameters for the objects are listed in the table below. Learn more about using parameters in queries

Using parameters in you query is optional, however if you use a parameter in your query you must provide the parameter information in the bindParameter URL parameter. The bindParameter is an array of objects for each parameter to use in the query. Learn more about bind parameter options.

The URL parameters for the objects are listed in the table below:


Parameter	Details
title (optional)	Title of the bind parameter
parameterName	The bind parameter name that is used in the openCypher query.
parameterType	The type of the value of the bind parameter. This type should match the type of the property in the query where you are using the parameter. The types are listed below: esriBindParameterTypeString esriBindParameterTypeNumber esriBindParameterTypeDateTime esriBindParameterTypeDate esriBindParameterTypeTime esriBindParameterTypeTimestampOffset esriBindParameterTypeEntityId esriBindParameterTypeRelationshipId esriBindParameterTypeGeometry
value	The value for the bind parameter. This can be a single value of the type specified in parameterType or it can be array of values of that type.

An example of the structure of the bind parameters array before encoding:

"bindParameters": [
      {
        "parameterName": "facilities",
        "parameterType": "esriBindParameterTypeEntityId",
        "value": ["2344","2342"]
      }
    ]
  };

Run existing queries

You can execute existing stored queries in a Knowledge Studio project. If the query has parameters you can send new parameter values using the URL parameters. You can only execute existing queries using a Knowledge Studio project content item.

The following properties can be used to run an existing query:


Parameter	Value	Details
storedQueryId	Knowledge Studio Project stored query id	The id of the stored query. This can be found in the Knowledge Studio project URLL when the stored query is selected in the Query View
properties	openCypherQuery	The openCypher query to execute. Learn more about openCypher queries
	description (optional)	A description of the new stored query.
	provenanceBehavior (optional)	Specifies whether or not the query results should include or exclude provenance results. If not specified the default is exclude. include exclude
	bindParameters (optional)	An array of objects for each parameter to use in the query. Parameters are optional, however if you use a parameter in your query you must provide the parameter information in the bindParameter URL parameter. The URL parameters for the objects are listed in the table below. Learn more about using parameters in queries

The URL parameters for the objects are listed in the table below:


Parameter	Details
title (optional)	Title of the bind parameter
parameterName	The bind parameter name that is used in the openCypher query.
parameterType	The type of the value of the bind parameter. This type should match the type of the property in the query where you are using the parameter. The types are listed below: esriBindParameterTypeString esriBindParameterTypeNumber esriBindParameterTypeDateTime esriBindParameterTypeDate esriBindParameterTypeTime esriBindParameterTypeTimestampOffset esriBindParameterTypeEntityId esriBindParameterTypeRelationshipId esriBindParameterTypeGeometry
value	The value for the bind parameter. This can be a single value of the type specified in parameterType or it can be array of values of that type.

An example of the structure of the bind parameters array before encoding:

"bindParameters": [
      {
        "parameterName": "facilities",
        "parameterType": "esriBindParameterTypeEntityId",
        "value": ["2344","2342"]
      }
    ]
  };

Feedback on this topic?