IBM Connections 4: Develop and Use

IBM Connections 4 Part 5: Developing and Using

IBM® Connections 4 Part 5: Developing and Using

Developing

Find out how to use the Atom APIs provided with IBM Connections and how to add select IBM Connections applications to third-party products.

What's new in developing?

Lists the programmatic applications that are new, changed, or deprecated in version 4.


IBM Connections 4: New APIs

Common API

The applications are more consistently using a common set of parameters.

Activities

There are no new APIs being introduced for this application in this release.

Blogs

There are no new APIs being introduced for this application in this release.

Bookmarks

There are no new APIs being introduced for this application in this release.

Communities

There are no new APIs being introduced for this application in this release.

Files

There are no new APIs being introduced for this application in this release.

Forums

News repository

  • There are no new APIs being introduced for this application in this release.

Profiles

There are new APIs being introduced for this application in this release.

Search

There are no new APIs being introduced for this application in this release.

Wikis

The documentation has been updated to cover how to retrieve the following feeds:


IBM Connections 4: New SPIs


IBM Connections 4: Deprecated APIs

Profiles

The message board APIs have been deprecated and are being replaced by the News repository feeds, see Get News repository feeds for details.

The following APIs were specific to the message board and have been deprecated:

Search

The following APIs are being deprecated in this release.

Integrate web applications into IBM Connections

IBM Connections provides the ability for third-party application developers to integrate iWidgets into the IBM Connections user interface for use in the Communities, Home page, and Profiles applications.

In IBM Connections, many areas of the user interface are constructed using iWidgets. Developers and administrators can extend the IBM Connections user interface with new capabilities and also replace existing capabilities that are shipped with the product by developing their own iWidgets using the iWidget specification and integrating them with IBM Connections.

For more information about developing iWidgets for use in IBM Connections, go to: http://www-10.lotus.com/ldd/lcwiki.nsf/dx/development-guide

Integrate IBM Connections into web applications

A subset of the IBM Connections applications can be surfaced in other products programmatically.

The procedures described in this section require you to have some programming knowledge. In addition to surfacing applications in other products programmatically, you can also install prebuilt plug-ins that do not require programming abilities. These plug-ins surface IBM Connections applications in a predefined list of products. For more information about these plug-ins, see the Extending section of the product documentation.


Extend bookmarks

Use the API provided with IBM Connections to extend the Bookmarks application of IBM Connections.

Add dynamic IBM Connections bookmarks to your application. Or, add a hypertext link to a web page in your application that enables your users to bookmark your application and add the bookmark to their Bookmarks collection in IBM Connections.


Add a set of bookmarks to a web page

Embed a set of bookmarks into your web pages. Your web application can use this resource to enable users to see and navigate to a selected set of bookmarks relevant to your web page.

Table 1. Atom API request details

Resource Description
/snippet Retrieves bookmarks matching search criteria. Returns JavaScript code that emits XHTML containing the search results, with each result specified in a <div> element.
Use one or more of the input parameters to narrow the search. Separate multiple parameters with an ampersand (&).

Table 2. Input parameters

Parameter Description
access Filters the bookmarks based on whether they are private or public. Options are:

any

Returns all bookmarks only if the request is made over secure http (https). If the request is made over https, it is redirected to the /mybookmarks URI. If the request is made over http, only public bookmarks are returned. This value is the default value.

private

Only returns private bookmarks. Private bookmarks can only be accessed by their owner, and only if the owner is authenticated. The user is prompted to log in and is redirected to the /mybookmarks URI from which only private bookmarks are returned.

public

Only returns public bookmarks.
base Returns only bookmarks to pages hosted by a given web site. For example, to retrieve only bookmarks to pages on the web site www.w3c.org/TR, specify "base=www.w3.org/TR"
email Internet email address. Returns bookmarks created by the user specified by the email address. Format the HTTP request using the proper URL encoding. For example, the encoded form of the @ symbol is %40 as in:

adam_eventide%40garden.com

Do not use this parameter if IBM Connections is configured to prevent email addresses from being displayed. Use the userid parameter instead.

font_family Specify a font family for the embedded bookmarks. For example, arial.
font_color Specify a font color for the embedded bookmarks. For example, red|EEE|34EEFF.
font_size Specify a font size for the embedded bookmarks. For example, 10| 10px|10em|10pt
lang Language code. Language for strings in the output. If not specified, the language specified by the first matching client, typically the web browser, is used, if available. The server then redirects the request to add this parameter to the URL. Specify this parameter to avoid the redirect.
network Filters the bookmarks based on the network that it is available from. Options are:

  • all . Default. Returns all bookmarks.

  • internet . Only returns the bookmarks that link to Internet resources, which are visible outside the intranet firewall.

  • intranet . Only returns the bookmarks that link to resources available on the corporate intranet, that is, resources that are not externally visible.
page Page number. Specifies the page to be returned. The default value is 1, which returns the first page.
ps Page size. Specifies the number of entries to return per page. The default value is 10. The maximum value you can specify is 50.
search Well-formed full text search query. Performs a text search on the title, description, and tags of all bookmarks. Orders results by relevance. Respects other constraints. See Advanced search options in the Using section of the wiki for details on the search operators you can use in the search query to perform advanced searches for bookmarks.

When you use this parameter, the search can only find bookmarks that the indexer has processed. The indexing interval is stored in a configuration property that your administrator can configure. See Managing search and index operations in the Administering section of the wiki for more details.

searchOperator Default operator between search terms. Options are:

  • and

  • or
The default value is set by your system administrator. Use in conjunction with "search" parameter to override the system default operator for search queries.
show_icon Includes links to bookmark icons (also known as "favorite icons") in the response. Bookmarks uses link relation "http://www.ibm.com/xmlns/prod/sn/icon" to identify this link in a bookmark Atom entry. Boolean. Options are:

  • false . Default. Links to bookmark icons are not included.

  • true . Includes links to bookmark icons.
show_person True or false. True displays the person link.
show_tag True or false. True displays the tag link.
since Includes in the resulting feed all bookmarks updated after a specified date. Set the date using a date-time value that conforms to RFC3339. Use an upper case "T" to separate the date and time, and an uppercase "Z" in the absence of a numeric time zone offset. For example: 2009-01-04T20:32:31.171Z.
sortBy Specifies how the results should be sorted. Options are:

created

Sorts the entries by the date the item was created.

popularity

Sorts the entries by how popular the item is.

This parameter replaces the sort parameter. The sort parameter and its associated options (date and popularity) are supported for backwards compatibility only; they will be deprecated in a future release.

sortOrder

Specifies the order in which to sort the results. The options are:

asc

Sorts the results in ascending order.

desc

Sorts the results in descending order.
The default value is asc.
tag Returns bookmarks with the specified tag. You can search for multiple tags; separate the tags with a space or comma. If you use a space, URL-encode the space using %20.
url A well-formed web address. Returns bookmarks for the given web address. When you use this parameter, all other search parameters are ignored.
userid Unique ID that represents a specific person.


Output

Content-Type: text/html. Indicates payload contains data in html format.


Example

To add a current list of bookmarks matching the search criteria to a web page, add the following HTML code to the source code of your web page. This example uses the email parameter to qualify the search; you can use any of the search parameters listed in Table 2.

<iframe 
    src="http://yourcompany.com/dogear/snippet?userid=someuserid&lang=en">
</iframe>

...where yourcompany.com is the fully qualified domain name of the server hosting the Bookmarks application and someuserid is a valid user ID as defined in their <snx:userid> element.


Add a list of bookmarks to a web page

Embed a list of bookmarks into your web pages. Your web application can use this resource to enable users to see and navigate to a selected list of bookmarks relevant to your web page.

Table 3. Atom API request details

Resource Description
/lisnippet Retrieves bookmarks matching search criteria. Returns JavaScript code that emits XHTML containing the search results, with each result specified in a <li> element.

Search can only find bookmarks that the indexer has processed. The indexing interval is stored in a configuration property that your administrator can configure. See the Administer Bookmarks section of the IBM Connections product documentation for more details.

Use one or more of the input parameters to narrow the search. Separate multiple parameters with an ampersand (&).

Table 4. Input parameters

Parameter Description
access Filters the bookmarks based on whether they are private or public. Options are:

any

Returns all bookmarks only if the request is made over secure http (https). If the request is made over https, it is redirected to the /mybookmarks URI. If the request is made over http, only public bookmarks are returned. This value is the default value.

private

Only returns private bookmarks. Private bookmarks can only be accessed by their owner, and only if the owner is authenticated. The user is prompted to log in and is redirected to the /mybookmarks URI from which only private bookmarks are returned.

public

Only returns public bookmarks.
base Returns only bookmarks to pages hosted by a given web site. For example, to retrieve only bookmarks to pages on the web site www.w3c.org/TR, specify "base=www.w3.org/TR"
email Internet email address. Returns bookmarks created by the user specified by the email address. Format the HTTP request using the proper URL encoding. For example, the encoded form of the @ symbol is %40 as in:

adam_eventide%40garden.com

Do not use this parameter if IBM Connections is configured to prevent email addresses from being displayed. Use the userid parameter instead.

font_family Specify a font family for the embedded bookmarks. For example, arial.
font_color Specify a font color for the embedded bookmarks. For example, red|EEE|34EEFF.
font_size Specify a font size for the embedded bookmarks. For example, 10| 10px|10em|10pt
lang Language code. Language for strings in the output. If not specified, the language specified by the first matching client, typically the web browser, is used, if available. The server then redirects the request to add this parameter to the URL. Specify this parameter to avoid the redirect.
network Filters the bookmarks based on the network that it is available from. Options are:

  • all . Default. Returns all bookmarks.

  • internet . Only returns the bookmarks that link to Internet resources, which are visible outside the intranet firewall.

  • intranet . Only returns the bookmarks that link to resources available on the corporate intranet, that is, resources that are not externally visible.
page Page number. Specifies the page to be returned. The default value is 1, which returns the first page.
ps Page size. Specifies the number of entries to return per page. The default value is 10. The maximum value you can specify is 50.
search Well-formed full text search query. Performs a text search on the title, description, and tags of all bookmarks. Orders results by relevance. Respects other constraints. See Advanced search options in the Using section of the wiki for details on the search operators you can use in the search query to perform advanced searches for bookmarks.

When you use this parameter, the search can only find bookmarks that the indexer has processed. The indexing interval is stored in a configuration property that your administrator can configure. See Managing search and index operations in the Administering section of the wiki for more details.

searchOperator Default operator between search terms. Options are:

  • and

  • or
The default value is set by your system administrator. Use in conjunction with "search" parameter to override the system default operator for search queries.
show_icon Includes links to bookmark icons (also known as "favorite icons") in the response. Bookmarks uses link relation "http://www.ibm.com/xmlns/prod/sn/icon" to identify this link in a bookmark Atom entry. Boolean. Options are:

  • false . Default. Links to bookmark icons are not included.

  • true . Includes links to bookmark icons.
show_person True or false. True displays the person link.
show_tag True or false. True displays the tag link.
since Includes in the resulting feed all bookmarks updated after a specified date. Set the date using a date-time value that conforms to RFC3339. Use an upper case "T" to separate the date and time, and an uppercase "Z" in the absence of a numeric time zone offset. For example: 2009-01-04T20:32:31.171Z.
sortBy Specifies how the results should be sorted. Options are:

created

Sorts the entries by the date the item was created.

popularity

Sorts the entries by how popular the item is.

This parameter replaces the sort parameter. The sort parameter and its associated options (date and popularity) are supported for backwards compatibility only; they will be deprecated in a future release.

sortOrder

Specifies the order in which to sort the results. The options are:

asc

Sorts the results in ascending order.

desc

Sorts the results in descending order.
The default value is asc.
tag Returns bookmarks with the specified tag. You can search for multiple tags; separate the tags with a space or comma. If you use a space, URL-encode the space using %20.
url A well-formed web address. Returns bookmarks for the given web address. When you use this parameter, all other search parameters are ignored.
userid Unique ID that represents a specific person.


Example

To add a current list of bookmarks matching the search criteria to a web page, add the following HTML code to the source code of your web page. This example uses the email parameter to qualify the search; you can use any of the preceding search parameters.

<iframe
language="javascript" type="text/javascript"
src="http://yourcompany.com/dogear/lisnippet?userid=someuserid&lang=en">
</iframe>

...where yourcompany.com is the fully qualified domain name of the server hosting the Bookmarks application and someuserid is a valid user ID as defined in their <snx:userid> element. The resulting page displays a bulleted list of documentation links.


Add popular bookmarks to a web page

Embed the most popular bookmarks into your web pages. Your web application can use this resource to enable users to see and navigate to the most popular bookmarks embedded on your web page.

This lists the bookmarks that multiple users have bookmarked recently. It captures the bookmarks that are displayed in the Most Bookmarked in the last 30 days section of the Popular tab of the Bookmarks application. The administrator can change the number of days from 30 to something different. To find out how to add all bookmarks to a page, retrieve the resources described in Add bookmarks to a web page and Add a list of bookmarks to a web page.

Search can only find bookmarks that the indexer has processed. The indexing interval is stored in a configuration property that your administrator can configure. See Administer Search for more details.


Resource information

/lisnippet/popular

Retrieves popular bookmarks. Returns JavaScript code that emits XHTML containing the search results, with each result specified in a <li> element.

/snippet/popular

Retrieves popular bookmarks. Returns JavaScript code that emits XHTML containing the search results, with each result specified in a <div> element.
Use one or more of the input parameters to narrow the search. Separate multiple parameters with an ampersand (&).

Table 5. Input parameters

Parameter Description
lang Language code. Language of the strings in the output. If not specified, the first matching browser language is used, if available. The server then redirects the request to add this parameter to the URL. Specify this parameter to avoid a redirect.
page Page number. Specifies the page to be returned. The default value is 1, which returns the first page.
ps Page size. Specifies the number of entries to return per page. The default value is 10. The maximum value you can specify is 50.
font_family Specify a font family for the embedded bookmarks. For example, arial.
font_color Specify a font color for the embedded bookmarks. For example, red|EEE|34EEFF.
font_size Specify a font size for the embedded bookmarks. For example, 10| 10px|10em|10pt
show_icon Includes links to bookmark icons (also known as "favorite icons") in the response. Bookmarks uses link relation "http://www.ibm.com/xmlns/prod/sn/icon" to identify this link in a bookmark Atom entry. Boolean. Options are:

  • false . Default. Links to bookmark icons are not included.

  • true . Includes links to bookmark icons.
show_person True or false. True displays the person link.
show_tag True or false. True displays the tag link.
type Filters the bookmarks returned in the feed. You can filter by the following values:

popular

Returns a list of the most bookmarked web sites. This value is the default value.

visited

Returns a list of the bookmarks that are accessed most often.


Example

You can add code similar to the HTML used in this example to display the popular bookmarks returned by either the /snippet/popular or /lisnippet/popular resource in a web page.

<iframe src="http://yourcompany.com/dogear/lisnippet/popular?lang=en">
  <p>Your browser does not support iframes.</p>
</iframe>


Add the Add Bookmark link to a web page

To simplify the process of adding a bookmark to one's bookmark collection in IBM Connections, the product provides an Add Bookmark button that users can add to their toolbar and can click to add the current web page to their collection. You can add similar functionality to your web application by adding an Add Bookmark link to a page. When a person clicks the link, the web page is added to the user's IBM Connections bookmark collection. The Bookmarks application provides the following resources to help you create the Add Bookmark link:

  • JavaScript library: A single file named doglink.js that defines a JavaScript object named "DogLink" and contains a post_to_dogear() method. The file is available from the following web address: http://{your_bookmarks_server}/dogear/tools/doglink.js

  • Icon resource: A file named favicon.gif that is located at the following web address: http://{your_bookmarks_server}/dogear/misc/favicon.gif
The post_to_dogear() method is invoked when a user clicks the Add Bookmark link. It opens a separate web browser window in which the user can modify the description or other fields, and then save the bookmark to her collection in the Bookmarks application.

To add the Add Bookmark link to your web page, complete the following steps:

  1. Include the JavaScript library in the <head> HTML block of your web page. For example, use the following HTML element, replacing "www.example.com/dogear" with the address of your Bookmarks server:

    <script 
     type="text/javascript" 
     src="http://www.example.com/dogear/tools/doglink.js"/>

  2. In the web page, at the location in which you want the Add Bookmark link to be displayed, add an onClick event that calls the following method:

    post_to_dogear(url, title, tags, description)

    Table 6. post_to_dogear() method parameters

    Parameter Description
    description Description of the page. You can leave the field blank. If your pages have a <meta> tag for descriptions, you can use JavaScript code to get it and fill the field.
    tags Tags are labels that people can associate with a page to categorize it. You can leave this parameter blank or include default tags that you want people to use. Enter tags as a single word, separated by commas or spaces.
    title Title of the page. Specify document.title to refer to the title of the current page.
    url web address of the page. Specify location.href to refer to the current page.
    For example:

    <a 
      href="#" 
      style="text-decoration:none;" 
      onclick="DogLink.post_to_dogear(location.href,document.title,'','');
      return false;">
        Add Bookmark
    </a>

  3. Recommended: Include a bookmark icon that is displayed on the page in front of the Add Bookmark link text.

    <a 
      href="#" 
      style="text-decoration:none;" 
      onclick="DogLink.post_to_dogear(location.href, document.title, '', '');
      return false;">
      <img 
         height=16 
         src="http://www.example.com/dogear/misc/favicon.gif" 
         width=16 
         border=0> 
       Add Bookmark
    </a>

    Replace www.example.com with the address of your Bookmarks server.


Example

Example:

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 
 "http://www.w3.org/TR/html4/loose.dtd"> 
 <html> 
  <head> 
    <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 
    <title>Sample Bookmark-able web Page</title> 
    <script 
     type="text/javascript" 
     src="http://www.example.com/dogear/tools/doglink.js">
    </script> 
  </head> 
  <body> 
    <h2>A sample web page with a bookmark link</h2> 
    <p>Your content here. </p> 
    <a 
     href="#" 
     style="text-decoration:none;" 
     onclick="javascript:DogLink.post_to_dogear(location.href, document.title, 
      'tag1,tag2 tag3', '');
     return false;"> 
      <img 
       height=16 
       src="http://www.example.com/dogear/misc/favicon.gif" 
       width=16 border=0/> 
         Add Bookmark
    </a> 
  </body> 
</html> 


Integrate business cards in to your web application

Add the Profiles business card to your web application to provide a useful summary of a person's professional role, business location, and contact details. Integrating the community card enables users to easily navigate to a community from your web application.


Add a file picker to your web application

Use a Javascript API to select from a list of files stored in the IBM Connections Files application, and use those files and their metadata in a callback function.

To see documentation on the file picker arguments and callback values, and working sample code, paste the following URL into your browser:

http://<ibm_connections_server>/connections/resources/web/lconn.core/test/filepicker/sample.html
For example:

http://connections.enterprise.example.com/connections/resources/web/lconn.core/test/filepicker/sample.html

IBM Connections APIs

The IBM Connections applications (Activities, Blogs, Bookmarks, Communities, Files, Forums, Profiles, and Wikis) and the IBM Connections Home page all provide application programming interfaces (APIs) that enable you to integrate them with other applications. Using the interfaces, you can programmatically access and update much of the same information that you can access and update through the IBM Connections user interface.

Starting in release 4, the IBM Connections API documentation is located in the IBM Social Business Development Wiki.