> For the complete documentation index, see [llms.txt](https://community-test.logicnets.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://community-test.logicnets.com/release-9/platform-documentation/system-administration/system-settings/external-reference-sources.md).
# External Reference Sources
## Description
LogicNets allows you to create applications that provide reference material to guide users or to provide additional information where necessary. You can include these references in your LogicNets-based project but you can also point to sources outside of LogicNets.
## External Reference Configuration
If you want to include reference material that exists outside of your LogicNets Designer, you must edit the configuration *settings.cfg* file to point to the source. To configure the reference source, follow these steps:
1\. To edit the configuration file, add the following basic structure:
```
_session = {
reference_sources = {}
}
```
2\. For each source, add the following structure inside *reference\_sources* for each source = { }
```
{
name = "NAME",
caption = "CAPTION",
browser_uri = "BROWSER_URI",
show_uri = "SHOW_URI",
icon = "ICON_LINK"
},
```
The following is a full example of a company *settings.cfg* file (reference source section).
```
_session = {
reference_sources = {
{
name = "external_topic",
caption = "External Topic",
browser_uri = "http://topics/InsertTopicLink.aspx?ContentId=$(project_id)&external_id=$(external_session_id)&requestUrl=$(redirect_url)",
show_uri = "http://topics/opentopic.aspx?topicId=$(topicId)&bookmarkId=$(bookmarkId)&view=web",
icon = "/lncore/icons/fileupload.png"
},
{
name = "external_graphic",
caption = "External Graphic",
browser_uri = "http://topics/InsertGraphicLink.aspx?ContentId=$(project_id)&external_id=$(external_session_id)&requestUrl=$(redirect_url)",
show_uri = "http://topics/graphicpreview.aspx?graphicId=$(graphicIdId)",
icon = "/lncore/icons/fileupload.png"
}
}
}
```
### Configuration Requirements
The interface to an external reference source consists of two parts:
1. The external reference source must provide a web-based reference browser. This enables a Designer user to select a reference and have the system return the reference information back to the LogicNets Designer.
2. A LogicNets-based application must be able open the reference in the application, either in an iframe or in a separate browser tab.
### List of Configuration Parameters
The administrator can configure the LogicNets system to use external reference sources. This configuration must be placed in the company specific configuration file (*/dat/bnt//settings.cfg*). A full list of configuration parameters and their specification is below.
| Property Name | Type | Value |
| ----------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| \_session\[].reference\_sources\[] | Collection | This is a list of all configuration reference sources. |
| \_session\[].reference\_sources\[].name | String | This is the unique name of source. It is saved with the reference and used in runtime to produce the right reference link. Changing this may invalidate all existing references that use this source. |
| \_session\[].reference\_sources\[].caption | String | This is the displayable name of the external source (displayed in the Designer). You can change it. |
| \_session\[].reference\_sources\[].browser\_uri | String | This is the URL to the web-based topic browser. You can use $(…) to allow flexibility in how the redirect URI and other parameters are passed.
You can use the following parameters: $(redirect\_uri), $(project\_id), and $(external\_session\_id).
|
| \_session\[].reference\_sources\[].show\_uri | String | This is the URL used to show a topic in its own web view, such as an iframe or browser tab. You can use the $(..) format to parametrize the use of this URL.
You can use the following parameters: $(id), $(url), or any other property that is passed back by the topic browser. \_session\[].reference\_sources\[].load\_uri string.
|
| \_session\[].reference\_sources\[].load\_uri | String | (Optional) This is the URL used to load the topic content. You can use the $(..) format to parametrize the use of this URL.
You can use the following parameters: $(id), $(url), or any other property that is passed back by the topic browser.
|
| \_session\[].reference\_sources\[].icon | String | This is the URL to an icon that displays in the Designer text editors to open the specific reference browser. |
## Topic Browser
Referencing the process flow below, the LogicNets Designer opens a panel (2) when the Designer user adds an external reference (1). In this panel, the system loads an iframe with the URL of the external reference browser (3). As query-parameter of this URL the LogicNets Designer will provide the redirect URI, which is URL-encoded. The external reference browser must redirect the iframe to this redirect URI when the user selects a reference or cancels the browser action (5). The external reference browser must pass the result of the browser action via the URL query parameter of the redirect URI.
An example of the redirect\_uri passed by LogicNets is as follows:
```
http://www.logicnets.com/company/logicnets.lns?session_id=12324&verb=step
Example of Step 3 URL
http://externalbrowser.com/opentopicbrowser?redirect_uri=http%3A%2F%2Fwww.logicnets.com%2Fcompany%2Flogicnets.lns%3Fsession_id%3D12324%26verb%3Dstep
```
When a topic is selected the reference browser must redirect the iframe back to the LogicNets Designer and providing the selected topic details. These reference details should be placed in the following JSON structure:
| Property Name | Type | Required | Value |
| ---------------- | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| guid | String | No | Reference unique ID |
| url | String | Yes | Relative URL to show the reference contents |
| name | String | No | Name of the reference |
| description | String | No | Description of the reference |
| shortDescription | String | No | Short title of the reference (can be used as tooltip) |
| status | String | No | \[active\|inactive] |
| … | String \| Number | No | Any other property that the topic browser wants to pass to LogicNets designer. All these properties are exported to the LN project and package meta-data file. |
The LogicNets interface allows you to set multiple references at once. Therefore, the above JSON structure is embedded in a JSON array.
**Example**
```
[{
"guid": "93216B36-3CB3-205B-E187-8B31F16E19F0",
"description": "topic 1",
"url": "/topic?id=1#page=34",
"my_param": "my_value"
}, {
"guid": "E71F30F0-7B24-B669-D5EF-91A857E6277A",
"description": "topic 33",
"url": "/topic?id=33",
"my_param": "my_value2"
}]
```
The URL that is used to redirect to the LogicNets Browser will look as follows:
```markup
http://www.logicnets.com/company/logicnets.lns?session_id=12324&verb=step&references=%5B%7B%0D%0A%09%22guid%22%3A%20%2293216B36-3CB3-205B-E187-8B31F16E19F0%22,%0D%0A%09%22description%22%3A%20%22topic%201%22,%0D%0A%09%22url%22%3A%20%22%2Ftopic%3Fid%3D1%23page%3D34%22,%0D%0A%09%22my_param%22%3A%20%22my_value%22%0D%0A%7D,%20%7B%0D%0A%09%22guid%22%3A%20%22E71F30F0-7B24-B669-D5EF-91A857E6277A%22,%0D%0A%09%22description%22%3A%20%22topic%2033%22,%0D%0A%09%22url%22%3A%20%22%2Ftopic%3Fid%3D33%22,%0D%0A%09%22my_param%22%3A%20%22my_value2%22%0D%0A%7D%5D%0D%0A
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://community-test.logicnets.com/release-9/platform-documentation/system-administration/system-settings/external-reference-sources.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.