0

External Reference Sources

  • updated 3 yrs ago

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/<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  
Reply Oldest first
  • Oldest first
  • Newest first
  • Active threads
  • Popular
Like Follow
  • 3 yrs agoLast active
  • 35Views
  • 4 Following

Home