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:
- 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.
- 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/<company>/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:
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