Last modified 2 months ago

Advanced Server Customization

Config.xml

Defines community settings. Comments are embedded into the file below: 

<config>
        <!-- 
                The community's locale (language + dates/currency/etc) 
        -->
        <globalization locale="en|fr|..." />

        <!-- 
                How encryption of passwords is handled. Can only be changed during
                system setup.
                
                TYPE
                plaintext = no encryption
                bcrypt = encrypt with bcrypt algorithm
        -->
        <encryption type="plaintext|bcrypt" />

        <!--
                How browser sessions are handled.

                TYPE
                basic = log user off when browser is closed
                persistent = only log user off if they clear their cache or click
                             "logout"
        -->
        <sessions type="basic|persistent" />

        <!--
                The type of authentication to use.

                TYPE
                basic = built-in authentication
                ldap = ldap authentication; details must be set in web.config
                eventrestrictedldap = ldap + event-based authentication; details 
                                      must be set in web.config (5.0.26+)
        -->
        <authentication type="basic|ldap|eventrestrictedldap" />

        <!--
                The search engine to use.

                TYPE
                basic = A basic search engine
                lucene = A search engine powered by Lucene.NET (experimental!)
        -->
        <searching type="basic|lucene" />

        <!-- Misc. settings that affect only this community -->
        <communitySettings>
                <!-- 
                        The timezone name to display. Has no side effects.      
                -->
                <add key="timezone" value="<string>" />

                <!--
                        Timezone offset. A number (positive or negative) that time
                        should be offset from server time.
                -->
                <add key="timezone_offset" value="<integer>" />
        </communitySettings>

        <!-- Global plugin settings -->
        <plugins>

                <!-- Settings for <PluginName -->
                <plugin name="<PluginName>">
                                
                        <!-- Plugin settings; each plugin defines its own settings -->
                        <settings>
                                <set name="<settingName>" value="<settingValue>" />
                        </settings>
                </plugin>
        </plugins>

        <!-- Layout; defines the pages of the site -->
        <layout>

                <!-- 
                        Defines a page. Shows up in the main menu.
                        
                        DISPLAY (optional)
                        <null> = Default, show in main menu
                        Hide = Hide from main menu
                -->
                <page type="<PageId>" name="<DisplayName>" display="<null>|Hide">
        
                        <!--
                                Defines a plugin that goes on the page. Plugin defined by
                                <PluginName> must exist. <PluginView> must be a valid
                                view for the plugin.

                                AREA
                                See diagram:
                                --------------------------
                                |           Top          |
                                --------------------------
                                |   Content    | Sidebar |
                                |-------------------------
                        -->
                        <plugin name="<PluginName>" area="Sidebar|Content|Top"
                                view="<PluginView>">
                                <settings>
                                        <set name="<settingName>" value="<settingValue>" />
                                </settings>
                        </plugin>
                </page>
        </layout>
</config>

Table of Contents

  1. Config.xml
  2. Web.config
    1. App Settings
  3. LDAP configuration
  4. User Plugins (can be used anywhere)
    1. LiveEventSchedule
      1. Views
      2. Settings
    2. Presentation
      1. Settings
    3. PastEventsList
    4. ArbitraryHtml
      1. Settings
  5. Presentation Plugins (only to be used on live and on-demand viewing pages)
    1. PresentationUI
      1. Settings
    2. Comments
      1. Settings
    3. PresentationInfo
    4. Share
  6. System Plugins (should not be instantiated on pages)
    1. TopMenu
    2. Footer
      1. Settings
    3. Menu
  7. Managing additional content with the Documents tool
    1. Creating a new page
    2. Editing an existing page
    3. Deleting a page
    4. Incorporating the new page in the ePresence portal
  8. Custom Plugins
    1. Creating a new plugin
      1. Additional pointers for creating plugins
  9. jQuery Plugins
  10. API
    1. Introduction
    2. SSO
  11. Advanced Tasks
    1. Changing Archive Duration (6.0+)

Web.config

App Settings

5.0+

  • reportingEnabled: Enables reporting functions that record when/how long visitors view events.
    • true | false
  • ldap: Defines the global LDAP host.
    • <host>[:<port>]
  • ldapUsers: Defines the path to users in LDAP.
    • <path string>; ie: ou=People,dc=<domain>,dc=com
  • webCaptureEnabled: Defines whether Web Capture is enabled.
    • true | false
  • localRed5: Defines the host for the local Red5 server. Default is the web server host.
    • <host>[:<port>]

5.0.x+

  • ldapFilters: Defines any additional LDAP user filters.
    • 5.0.26+
    • [<filter key1>[,<filter key2>]]; ie: sAMAccountName
  • registrationDisabled: Disabled registration. This tag overrides any default behaviour of the authentication method. To use the default behaviour of the authentication method, this setting must be removed.
    • 5.0.26+
    • true | false

6.0+

  • singleLoginEnabled: Defines whether single login enforcement is enabled.
    • true | false
  • redirectToSSL: If set to true, redirects all web requests that are handled by Monorail to the HTTPS.
    • true | false
  • showPasswordsInUserExport: If set to true, passwords will be displayed in the user list export. Note: If encryption is enabled, the encrypted password will be displayed.
    • true | false
  • pseudoStreamingEnabled: If set to true, uses pseudo streaming for H264 F4V slides.
    • true | false
  • ocrEnabled: If set to true, enables OCR in Producer. The server must first be configured to perform OCR.
    • true | false

6.1+

  • s3AccessKey: The access key to use for uploading to S3 publishing points.
  • s3SecretKey: The secret key to use for uploading to S3 publishing points.
  • thumbnailUrl: The alternate URL to use to capture thumbnails if using Cloudfront to stream videos, since Cloudfront does not support video sample access.
    • [<protocol>://]<host>[:<port>]/<app>
  • ocrServiceUrl: The URL for an external OCR service.
    • <host>[:<port>]
  • ldapUsernameAttr: The LDAP field used (in conjunction with the 'ldapUsers' app setting) to identify users. Defaults to 'uid' if unspecified.
  • ldapGivenNameAttr: The LDAP field used for ePresence users' given names. Defaults to 'givenName' if unspecified.
  • ldapSurnameAttr: The LDAP field used for ePresence users' surnames. Defaults to 'sn' if unspecified.
  • ldapMailAttr: The LDAP field used for ePresence users' email address. Defaults to 'mail' or 'userPrincipalName' if unspecified ('mail' has priority if both are present).
  • ldapCompanyAttr: The LDAP field used for ePresence users' company. Defaults to 'company' if unspecified.

7.0+

  • cupertinoHost: If streaming on-demand videos through Cloudfront, this parameter specifies an alternate streaming server host that can stream S3 videos to iOS.
  • cupertinoAppName: If streaming on-demand videos through Cloudfront, this parameter specifies the corresponding application name (ie: vods3) on the host specified by cupertinoHost.

7.1+

  • allowPasswordReset: Password-reset feature available. Note that the mail variables below must be configured for password reset to work.
  • mailServer: The mail server.
  • mailPort: The SMTP port.
  • mailUsername: The mail username.
  • mailPassword: The mail password.
  • mailUseSSL: Whether to use SSL when connecting to the mail server.

LDAP configuration

LDAP must be configured in the web.config. There are three relevant appSetting keys: 

<add key="ldap" value="<LDAP IP Address>" />

<!-- ie: ou=People,dc=mydomain,dc=com -->
<add key="ldapUsers" value="<Location to find users>" /> 

<!-- ie: sAMAccountName -->
<add key="ldapFilterOptions" value="<Additional filters for LDAP>" />

Additionally, the community configuration needs to be updated to specify the correct authenticator to use (either ldap or eventrestrictedldap [5.0.26+]).

User Plugins (can be used anywhere)

LiveEventSchedule

Displays a schedule. Primarily for live events, however, in full calendar view (month, day), also shows archived events.

Views

  • Default: Displays a condensed live event schedule of upcoming events that fits nicely in a sidebar.
  • MonthCalendar: Displays a calendar (month view) with live and archived events.
  • DayCalendar: Displays a calendar (day view) with live and archived events.
  • List: Displays a simple live event schedule. Shows all upcoming events.

Settings

  • MinYear = <int>: If in a calendar view, defines the minimum year that can be accessed via the UI.
  • MaxEvents = <int>: If the view has an event limit, this number defines that max number of events to display.

Presentation

Displays a link to a presentation.

Settings

  • show_overlay = true|false: Defines whether we show the overlay on top of the thumbnail (play arrow).
  • show_viewcount = true|false: Defines whether we show the view count publicly.
  • show_date = true|false: Defines whether we show the date of publication.
  • show_mp3 = true|false: Defines whether we display the mp3 link alongside the presentation.

PastEventsList

Displays recently published events.

ArbitraryHtml

Displays an arbitrary block of HTML.

Settings

  • Filename = <string>: The HTML file to display. Must be a valid HTML file that was created using the Documents tool.

Presentation Plugins (only to be used on live and on-demand viewing pages)

PresentationUI

  • Renders the presentation.
  • Requires version 6.0.

Settings

  • EventType = live | archive: defines whether the presentation is a live or archived event.

Comments

  • Allows users to view and post comments regarding a presentation.
  • Requires version 6.0.

Settings

  • ItemsPerPage = <int>: The number of comments to display on each page of comments (defaults to 10).

PresentationInfo

  • Shows information about the current presentation - i.e. Title, Date, Thumbnail Image, Presenter, Number of views, Description of presentation.
  • Requires version 6.0.

Share

  • Provides urls/tags for linking to/embedding the current presentation, and sharing it via social media sites (Facebook, etc.).
  • Requires version 6.0.

System Plugins (should not be instantiated on pages)

TopMenu

The rounded menu that includes the search box and links to login/join.

The page footer.

Settings

  • left_text = <string>: The text to show on the left side of the footer.
  • right_text = <string>: The text to show on the right side of the footer.

The main menu of the site.

Managing additional content with the Documents tool

Additional content can be added to the ePresence server in the form of HTML pages using the Documents tool. The Documents tool can be accessed through the ePresence server admin interface under the Customization -> Settings heading. Click the "Documents" link to open the document editor.

Creating a new page

  1. Select "Create new document" from the drop-down box in the document editor, and enter a filename for the new HTML page.
  1. Enter the HTML content for the page in the large text box.
  1. Click "Save Changes" to create the page.

Editing an existing page

  1. Select the file you would like to edit from the drop-down box.
  1. Edit its HTML contents in the large text box.
  1. Click "Save Changes" to update the page.

Deleting a page

  1. Select the file you would like to delete from the drop-down box.
  1. Click the red "x" beside the item you would like to delete.
  1. You will be prompted to confirm the deletion. Once you have done so, the page will be deleted.

Incorporating the new page in the ePresence portal

Content made with the Documents tool can be incorporated into the ePresence portal by editing a community's configuration file (config.xml). To do this, add an ArbitraryHtml? plugin to the desired page, and set its Filename parameter to the name of a file created with the Documents tool.

Custom Plugins

Creating a new plugin

The following files are required for all plugins:

  • A C# class <MyPlugin>.cs in App_Code\View\Components\Plugins that extends PluginComponent. This class is responsible for passing values to the view. Knowledge of Castle Monorail is useful, but in many cases, looking at other existing plugins provides enough guidance. The ArbitraryHtml? plugin is very simple and can be used as a guide for creating new plugins.
  • A directory in Views\components exactly named <MyPlugin>Component that contains at least one view file named default.vm. This is an NVelocity file that renders the view (HTML, Javascript, etc) given provided values from the C# class above.
  • Optional: A folder in Content\plugins exactly named <MyPlugin> that contains 3 folders: css, img, and js, containing CSS stylesheets, images, and Javascript files, respectively. All css and js files are loaded automatically when the plugin is instantiated. Any images that are new and used by the new plugin should be placed in the img directory. Note that if you use any of our Javascript files, things may need to be changed/fixed after upgrades.

Once these files are in place, you can instantiate your plugin by following the instructions for pages/plugins in config.xml.

Additional pointers for creating plugins

  • The database should never be accessed directly. The classes in App_Code\Models provide an API for accessing data in the database.
  • Database access should be treated in most cases as read-only. While it's possible to make updates, it is not recommended nor supported, because it can lead to unexpected side-effects now or down the road. If you require to store additional data for your plugin, you should create a new database (for instance, in SQLite) or an XML file to store your data.
  • No files in App_Code\Controllers or App_Code\Core should be altered.

jQuery Plugins

Using the Portal plugin system, it is possible to include custom JavaScript files on your Portal instance. However, please note the following. Portal uses  RequireJS to organize and optimize JavaScript code.  jQuery is loaded using the RequireJS system. One consequence is that  jQuery plugins must also be loaded using the same system.

For example, say you have a jQuery plugin called jquery.nicestuff.js which looks something like this: 

/*
 * Nice stuff - v0.0.1alpha
 * A nice jQuery extension that does stuff.
 * Optimized.
 */
(function(j){j.fn.niceStuff=function(){/*...*/}/*...*/})(jQuery);

To make this JavaScript module visible to the RequireJS system, place this file in the Content\js folder and edit it: 

define(['jquery'], function(jQuery) {
/*
 * Nice stuff - v0.0.1alpha
 * A nice jQuery extension that does stuff.
 * Optimized.
 */
(function(j){j.fn.niceStuff=function(){/*...*/}/*...*/})(jQuery);
});

Note the additions on the first and last line.

Then, instead of including the script directly, include this HTML snippet somewhere in your Portal plugin. 

<script type="text/javascript">
require(['jquery.nicestuff']);
</script>

If you have more than one plugin, and you place them in the directory Content\js\custom, then you would require them all like this: 

<script type="text/javascript">
require(['custom/firstPlugin', 'custom/secondPlugin', 'custom/thirdPlugin']);
</script>

Note that you do not specify the .js extension.

API

Introduction

The ePresence API is a SOAP interface for accessing Server data. The public API is divided into 2 groups: Archives and Configuration. Instructions for accessing the API are described below. These instructions assume basic knowledge about accessing/consuming SOAP web services. Full definitions can be found by inspecting the WSDL or by importing the WSDL into a web service testing tool such as SoapUI ( http://www.soapui.org/).

SSO

Each user in our system can be identified by a special encrypted key. To implement SSO, each user in the 3rd party application must be created in the Portal application. Once the user is created in Portal, they are identified by their encrypted key, which is requested from Portal by the 3rd party application. The workflow for implementing basic SSO is as follows:

  1. Try to get a user's encrypted key using the web service method WebServices.Config.GetEncryptionKey. If this returns a key, the user has already been created. Pass this key into the embedded presentation by adding the following key-value pair to the embed URL: encryptedKey=<encryptedKey>. An example URL would be: http://<site>/1/embed.aspx?eventId=1&embedded=true&clickToGoHome=true&templateType=Archive&autoStart=false&encryptedKey=<encryptedKey>. If this returns null, go to step 2.
  1. You must create a corresponding user in Portal. Call WebServices.Config.CreateUser. This user will then be identified to Portal by the 3rd party application by the "username" value. Proceed with step #1 above.

Stricter security can be implemented using the WebServices.Config.GenerateViewToken method in place of WebServices.Config.GetEncryptionKey. This will generate a different type of encrypted key that expires after a short period of time. This prevents users from sharing the generated embed code. To use this key, pass it into the embedded presentation with the following key-value pairs: encryptedKeyType=ShortLived&encryptedKey=<encryptedKey>.

Advanced Tasks

Changing Archive Duration (6.0+)

You can change the duration of an archive using the following web request:

 http://<server_root>/1/ajax/UpdateDuration.aspx?id=<archive_id>&durationSeconds=<duration_in_seconds>

Note: You must be logged into the site as the main admin user.