Loading...
 

MindLink Social Connector

Version 1.3.0

Introduction

The MindLink Social Connector is a utility to facilitate interaction between users and channels using Microsoft OCS/Group Chat and RSS feed providers and subscribers. It allows users and channels to subscribe to RSS feeds, receiving timely updates whenever a new item is posted, and also allows channels to be published as RSS feeds themselves, so their content can be syndicated. Besides RSS feeds the MindLink Social Connector also supports subscriptions to Twitter searches.

Subscribing to an RSS feed allows you to see the latest news from within your OCS or Group Chat client:

image008.jpg 

Figure 1: MindLink Social Connector announcing new items in an IM

 

While publishing a channel allows you to subscribe to messages in a feed reader, or easily publish the content of a channel on a website or portal:

image010.jpg 

Figure 2: Viewing a published channel's feed in a web browser

 

The MindLink Social Connector has a self-service website which allows you to subscribe to feeds and publish channels (depending on your permissions within Group Chat) without the need to involve an administrator.

The website can be accessed using Microsoft Internet Explorer 6+, Mozilla Firefox 2+, Safari 3+, Google Chrome 3+, and Opera 9+.

This user guide describes the functionality of the application.

Getting Started

To start the application, launch a browser and navigate to the designated URL. A screen will be presented, as shown in Figure 3.

image012.jpg 

Figure 3: Website loading screen

 

The website will attempt to authenticate you using your current Windows credentials. If this succeeds, you will see the main menu. However, depending on your web browser and network configuration, you may be prompted to log in manually using your Windows credentials, as shown in Figure 4.

image014.jpg 

Figure 4: The login screen

Logging In

On the login screen, enter your details:

       Enter your user name (domain_name\username)

       Enter your password

       Click the ‘Login’ button

An error message will pop up if the login is unsuccessful. Otherwise the login window will disappear and you will see the main menu, as shown in Figure 5.

image016.jpg 

Figure 5: MindLink Social Connector home page

At the top of the page, you can see the account that you are logged in as (displayed as a SIP address). Beneath this is the main menu, which will be displayed on every page on the MindLink Social Connector website to allow easy navigation between different sections. Clicking on ‘Home’ will bring you to the homepage (pictured above), while hovering over ‘Subscriptions’ or ‘Published channels’ will give you access to more pages relating to those features:

image018.jpg 

Figure 6: MindLink Social Connector menus

The home page also gives you quick access to all features of the MindLink Social Connector via the links in the ‘Subscribe’, ‘Publish’ and ‘Manage’ categories.

Creating and Managing Subscriptions

The MindLink Social Connector allows you to create and manage two types of subscriptions – personal and channel. Channel subscriptions result in messages being sent to a Group Chat channel whenever a new item is posted, while personal subscriptions result in one-to-one instant messages from the MindLink Social Connector directly to you.

Creating a Subscription

To create a new subscription, simply select ‘Create Personal’ or ‘Create Channel’ from the ‘Subscriptions’ menu on the MindLink Social Connector’s web interface. You will see a form for creating a new subscription:

image020.jpg 

Figure 7: Basic subscription settings

Note: The RSS functionality can be disabled by the System Administrator and in that case you will not be able to click the ‘Subscribe to an RSS or Atom feed’ text and be able to subscribe to RSS or Atom feeds. The ‘Subscribe to an RSS or Atom feed’ text will still be present, but it will be greyed out to indicate that it is not available for selection.

 

Note: The Twitter functionality can be disabled by the System Administrator and in that case you will not be able to click the ‘Subscribe to a Twitter search’ text and be able to subscribe to Twitter searches. The ‘Subscribe to a Twitter search’ text will still be present, but it will be greyed out to indicate that it is not available for selection.

The process described here is for creating a channel subscription. If you are creating a personal subscription, then the process is the same except that you are not required to enter a channel name.

The subscription form allows you to either subscribe to a traditional RSS or Atom feed, or to quickly subscribe to a Twitter search. The settings for adding a traditional feed consists of several required fields, and four optional ‘Advanced’ settings. You can get help and more information about any of the settings by hovering your cursor over the blue and white help icon to the right of each field.

Advanced options are hidden by default. You may see them by clicking on the small arrow next to the ‘Advanced’ heading:

image022.jpg 

Figure 8: Advanced subscription settings for RSS feed

 

The settings for an RSS/Atom subscription are:

       Channel (channel subscriptions only) – the name of the Group Chat channel where messages should be sent. You must be a member of this channel in order to add a subscription.

       Address – the address (url) of the feed you wish to subscribe to.

       Title – A name to assign to this subscription. This will be displayed in the subscription management pages, and may be included in messages sent by the MindLink Social Connector (depending on your “Format” settings, below)

       Username and Password (optional) – if the feed you are subscribing to requires you to authenticate in order to access it, enter the username and password here.

       Filter – the MindLink Social Connector allows you to filter feeds so that you can exclude items you are not interested in or only include items you are interested in. Enter a filter here to filter this feed. See “Filters”, section 3.3.

       Format – enter a custom format to change how the MindLink Social Connector structures its message. See “Formats”, section 3.4.

To subscribe to a Twitter search, click on the “Subscribe to a Twitter search” button: 

image024.jpg 

Figure 9: Subscribing to a Twitter search

 

As the traditional RSS feed, the ‘subscribe to a Twitter search’ does also have advanced options and they are hidden by default. You may see them by clicking on the small arrow next to the ‘Advanced’ heading: 

 

image026.jpg 

Figure 10: Advanced subscription settings for Twitter searches

The settings for a Twitter search are:

       Channel (channel subscriptions only) – the name of the Group Chat channel where messages should be sent. You must be a member of this channel in order to add a subscription.

       Search query – the words or hashtags to search for on Twitter. The operators available are listed below:

Operator

Finds tweets…

from:username

sent from the specified user.

this is my house

containing the 4 words, but not necessarily in the given order.

“this is my house”

containing that exact phrase.

car -used

containing "car" but not "used".

#hashtag

containing the hashtag.

@mention

containing the mention.

house OR car

containing "house" or "car". Can be used with other operators e.g. from:user1 OR from:user2

       Filter – the MindLink Social Connector allows you to filter tweets so that you can exclude tweets you are not interested in or only include tweets you are interested in. Enter a filter here to filter this feed. See “Filters”, section 3.3.

       Format – enter a custom format to change how the MindLink Social Connector structures its message. See “Formats”, section 3.4.

 

Once you have entered your desired settings, click on the ‘Subscribe’ button. The MindLink Social Connector will validate your settings and display any problems. If the subscription is created successfully, you will be taken to the relevant management page, which will list the new subscription.

3.2             Managing Subscriptions

To view and modify your subscriptions, simply choose “Manage personal” or “Manage channel” from the subscription menu. You will be shown a list of all personal or channel subscriptions which you have created, or which have been created for you or for channels you manage:

image028.jpg 

Figure 11: Managing personal subscriptions

 

For each subscription, you can choose to unsubscribe (which will stop any further messages being received for that subscription) or edit the subscription’s properties (see below for descriptions).

To remove a subscription, simply press the “Unsubscribe” button and the subscription will be removed from your list. To change the properties for a feed, click on the “Edit” button:

image030.jpg 

Figure 12: Editing a subscription

 

As with the create subscription pages, the edit subscription box has an Advanced section, for further properties of the feed:

image032.jpg 

Figure 13: Advanced subscription settings for edit subscription

Simply change the properties as desired, and press the “Update” button to update the subscription with the new details. Click on the “Cancel” button to go back to the management page without changing the subscription.

3.2.1          Sorting Subscriptions

The lists of subscriptions are by default ordered by channel name and if a channel has multiple subscriptions, the subscriptions belonging to the channel are ordered by feed name, as shown in Figure 14.

image034.jpg 

Figure 14: Subscriptions default sort order

 

To sort the list in another order, you can press the column header names, except for the ‘Manage’ column. When the mouse is moved over a sortable column header, the header name turns blue to indicate that this column is sortable, as shown in Figure 15.

image036.jpg 

Figure 15: Indication of a sortable column

 

Clicking on the column header once will order the list by the selected column in ascending order. An arrow pointing down will be added next to the column header in order to show in which direction the list is ordered, as shown in Figure 16.

image038.jpg 

Figure 16: Sorted Feed column in ascending order

 

Clicking the same column name again, will re-order the list in descending order and change the arrow to point upwards, as shown in Figure 17.

image040.jpg 

Figure 17: Sorted Feed column in descending order

Filters

When creating a new subscription, you may specify a filter. Filters allow you to exclude items that contain a certain word in their title or description, or to only include items that do have a certain word in their title or description.

A basic filter is a set of space-separated words, such as “Hello World”. Each word in the filter must be present somewhere in either the item’s title or description. The words may be in any order, and are not case sensitive. The “Hello World” filter would therefore match a feed with the title “world at war” with the description “HELLO!”

To exclude items containing a word, you may prefix it with a ‘!’. You can combine this with a normal filter, such as “hello world

 

Formats

The MindLink Social Connector supports a basic templating system to control how messages about new feed items are structured. A format is specified when creating a new subscription. By default, the MindLink Social Connector will use a format of “%FEEDTITLE% - %LINK% - %DESC|150%”, which means a new item will be announced by giving the title of the feed (as entered when creating the subscription), followed by a link to the item (including its title), and then up to the first 150 characters of its description. If you wish to change this format, you may use the following substitutions:

       %FEEDTITLE% - The title of the feed, as entered when creating a subscription

       %LINK% - A link to the feed item, including its title

       %TITLE% - The title of the item

       %DESC% - The feed item’s description

       %DESC|n% - The first n characters of the feed item’s description

       %AUTHOR% - The name of the person who wrote the item

       %AUTHOR-DISPLAY% - Usable only in published channel feeds. If %AUTHOR% prints a SIPaddress, then switch to %AUTHOR-DISPLAY% to print the name from the SIP-address.

You may include any other text in the format to customize how the MindLink Social Connector makes its announcements, for example “New item from %FEEDTITLE%: %LINK% (%DESC|150%)”.

Publishing Channels

In addition to allowing you to subscribe to published feeds, the MindLink Social Connector has the ability to publish its own feeds containing the recent history from a Group Chat channel. This allows users to subscribe to the feed in their desktop feed readers, or for website developers to easily integrate recent messages into their websites.

To publish a new channel, select the “Create” option from the “Published channels” menu.

image042.jpg 

Figure 18: Publishing a new channel

Simply enter the name of the channel you wish to publish and click on the “Publish” button. The MindLink Social Connector will attempt to publish the channel and report any errors back to you. When the channel has been successfully published, you will see the management screen:

image044.jpg 

Figure 19: Managing published channels

From the management page, you can see the feed address of each published channel. Use this address in your feed reader or other software to subscribe to messages from the channel.

You can stop a channel being published at any time by clicking the ‘Unpublish’ button. The feed for the channel will then be removed entirely.

FAQ

This section contains answer to the most frequent asked questions from users.

5.1        RSS feed address is not well formed

When subscribing to an RSS feed with an incorrect formed URL, a “Feed address is not well formed” error occurs. This occurs if the URL contains query string parameters that are not URL-encoded. The steps below walks through how to URL-encode a URL in order to fix the error:

1.       Assuming the URL we need to subscribe to is: 

http://domain.com/rss.aspx?title=Feeds (Top 10)&query=SELECT * FROM Feeds LIMIT 10

2.       It is only the query string values that needs to be URL-encoded, so in order to find the values, we will be focusing on everything after the question mark, as that marks the beginning of the query string: title=Feeds (Top 10)&query=SELECT * FROM Feeds LIMIT 10

3.       A query string consist of one or multiple key-value pairs. A key-value pair are specified with an equals sign between the key and value (key=value) and multiple pairs are separated with an ampersand (&).  In the above query we have two key-value pairs, which are:

title=Feeds (Top 10) query=SELECT * FROM Feeds LIMIT 10

4.       We can now deduce that the values that needs to be URL-encoded is:

Feeds (Top 10)

SELECT * FROM Feeds LIMIT 10

5.       By using the website http://www.url-encode-decode.com/ and decode one value at time, we get the following encoded values:

Feeds+_display'>click="javascript:toggle_dynamic_var(";">Feeds+");" title="Click to edit dynamic variable: ;">Feeds+">NaVFeeds+_edit" style="display:none;">Feeds+" type="text" value="NaV" />28Top+10%29

SELECT+*+FROM+Feeds+LIMIT+10

6.       In order to create the final URL that we can subscribe to, the values in the URL must be exchanged with the URL-encoded values we got in step 5. Doing this will result in the following, well-formed URL:

http://domain.com/rss.aspx?title=Feeds+_display'>click="javascript:toggle_dynamic_var(";">http://domain.com/rss.aspx?title=Feeds+");" title="Click to edit dynamic variable: ;">http://domain.com/rss.aspx?title=Feeds+">NaVhttp://domain.com/rss.aspx?title=Feeds+_edit" style="display:none;">http://domain.com/rss.aspx?title=Feeds+" type="text" value="NaV" />28Top+10%29&query=SELECT+*+FROM+Feeds+LI

MIT+10