Send system notifications to social media with IBM Tivoli Directory Integrator

Real-time alerts over Twitter

IBM® Tivoli® Directory Integrator (TDI) easily integrates with a wide variety of environments with minimal disruptions. Its plug-and-play nature provides easy prototyping and implementation. In this article, learn how to use the TDI framework to extend integration components and gain easy access to a range of management tools. The tools help you perform system configuration and send real-time notifications to external applications or to social media sites such as Twitter.

Share:

Rita Raj (ritaraj@in.ibm.com), Senior Developer, IBM

Photo of Rita RajRita Raj is a senior developer with Security Systems at the IBM Software Lab in Bangalore, India. She previously worked with IBM Global Business Services. Rita has been involved in design, development, QA, and customer engagements. She is a Sun certified Java programmer and a certified SOA Associate. Her expertise includes design and development of web applications, web services, SOA-based composite business services, and other J2EE applications.



11 December 2012

Introduction

The use of social media has extended beyond saying "I had cereal for breakfast." It's becoming a significant factor that business organizations can use in creative, beneficial ways.

Social media can be a great way to quickly and easily get system notifications to administrators or customers. Though a company might already have a way to notify customers about a system's status, the more channels the company uses, the more likely it is that at least one of the notices will get to the right person. For example, you can use social media to send notifications of system failures as instant notifications. Another notice can be sent when the issue is resolved. This is a good way to:

  • Send real-time notifications to a large audience
  • Receive quick responses
  • Receive an increased number of valuable responses

In this article, learn to send notifications to stakeholders using IBM Tivoli Directory Integrator (TDI) and Twitter. A detailed scenario walks you through the setup and implementation for sending notifications from TDI to Twitter and sending an email notification to the account manager.

You can download and import the examples that are used in this article.

The challenge

There are challenges to sending notifications to social media. Consider how challenging it can be to integrate different systems and their data, especially in the age of cloud computing and virtualization. Integrating just three or four applications might not be overwhelming, but integrating a larger number can become a major stumbling block. Some companies support thousands of applications that each have particular requirements.

There are, however, options for simplifying the integration of applications. One option is to use TDI to fill in gaps where traditional tools are ineffective or inappropriate for financial, technical, or other business reasons. TDI provides ready-to-use tools to quickly put together an integration solution.

Integration projects involving many products can be difficult to deliver and maintain for any company. One challenge is to get the operational report, or notifications, of the integration job to the interested stakeholders through the appropriate channels. Notifications can improve rapid decision-making, constantly update information, directly support the ongoing operation of the system, and report technical problems.

For example, typical notifications for an integration scenario might involve:

  • A system in the integration process needs attention. The appropriate line manager receives a notification indicating which machine is down and what the error is.
  • A production server's event log receives a critical error. The on-call support technician receives a notification that contains the error message.

There are various ways of getting notifications to the stakeholders. Notifications could be sent to a subscriber's cell phone, personal digital assistant (PDA), email account, or even through social media. Because integration jobs contain data from individual transactions at the granular level, the most direct approach is to build notification generation into the integrating system.


Sending system notifications to Twitter using TDI

One integration solution is to send system notifications to Twitter using TDI. The example scenario in this article involves an integration process that's running in the TDI server. The TDI server reports the status of the solution to Twitter and also notifies the appropriate manager through email. All the support personnel following the Twitter account through a browser, PDA, or mobile device get notified of the status. Anyone could respond to the posted status. Similarly, the TDI server following the Twitter account sends an email notification to the manager as soon as a resolution to the issue has been posted on Twitter. Figure 1 shows the architecture for the scenario.

Figure 1. Architecture
Flowchart showing the solution starting with the tdi server to the TDI solution administrator.

The two main components of the solution are TDI and Twitter.

TDI

TDI is a lightweight but extremely powerful, flexible integrator toolkit. It acts as middleware that manages the technical aspects of connecting to various data sources that need to be integrated. TDI removes the details of the APIs, transports, protocols, and formats, letting you focus on the business requirements instead of on data. TDI is an integration solution designer that helps you plan, develop, and deploy robust integration solutions. It also provides ready-to-use tools. However, for all but the most trivial jobs, you need to customize and extend the built-in capabilities of the product by writing JavaScript.

TDI is pure Java™ code. Whenever you issue a command to TDI, work with components and objects, or manipulate data in your flow, you're working with Java objects. Customization, however, is done in JavaScript. The combination of the two provides an opportunity to quickly create a custom component in TDI.

Twitter

Twitter, a free service, is essentially a combination of a micro-blogging tool and a social networking site. Twitter has two main components. Similar to social networking sites such as MySpace or Facebook, with Twitter you can add followers and also follow other people; they receive your updates and you'll receive theirs. Twitter is unique in that your messages are limited to 140 characters, which is why some people call it a micro-blogging tool.

Twitter's API lets you read and write Twitter messages, with minimal coding, in nearly any programming language. There are many resources for Twitter API developers because TDI supports Java code and JavaScript. Twitter's Java library Twitter4J is used for the project in this article.

Advantages of social media

Advantages of using social media include:

Integrating business systems
Your existing notification service or business systems can be integrated with social media for a greater reach with quick and increased responses.
Notifications from anywhere, to anyone
Social media can be accessed from any public place with Internet access. You can still get access even if your cell phone's battery dies, if you're in a no-service zone, if your PDA device is down, or if you simply left your cell phone at home.
Customer and user involvement
Many companies have services that customers or users depend upon for support. With appropriate use of social media, even if your existing notification service is down you can notify customers about a server failure from any mobile device if they're following your social media account.

Configuring TDI and Twitter

This section covers the Twitter REST API, configuring Twitter and TDI, and developing the Twitter Connector.

Twitter's REST API

Because Twitter's founders view it as a platform, and not simply a website for entering and reading messages, they provided an API to easily build your own software to send and receive Twitter messages. (See Resources for Twitter's API documentation.) The mechanism involves the caller making an HTTP GET or POST request and Twitter replying with content in the form of XML, JSON, RSS feed, or ATOM feed.

The REST API lets you do just about anything with your Twitter account using the forms on the Twitter website. For example, through the API you can retrieve the last 20 tweets of the accounts you subscribe to, of all unprotected users, or of a specific user. You can send and delete tweets, and work with direct messages, friendships, notifications, account blocking, favorite messages, and much more by sending the right URLs to Twitter's servers.

Certain functions require authentication, however. If you want to use Twitter's REST API to take advantage of those functions, you must include your credentials in the request. Twitter no longer supports basic authentication, so you must use the OAuth authentication. OAuth authentication is an authentication protocol that allows users to approve applications to act on their behalf without sharing their password (see Resources).

Configuring Twitter

To implement the scenario that is described in the previous section, first register in Twitter and get a Twitter account. The account is used to log status from the TDI integration solution.

To use the Twitter OAuth authorization scheme, you need to register the example application, as in Figure 2 and Figure 3, at http://twitter.com/oauth_clients/new to acquire a Consumer Key and Consumer Secret in advance. Also, request Access Token and Access Token secret.

Figure 2. Register
The Twitter registration window
Figure 3. Enter organization
A Twitter registration window to enter your organization and website

Most client libraries offer easy ways to pass in a username/password pair, making it simple to authenticate with Twitter. There are already good libraries for accessing Twitter with built-in OAuth support, so there's no need to reinvent the wheel. Twitter has ActionScript, Python, Java code, JavaScript, and many more. Because TDI supports Java code and JavaScript, Twitter's Java library Twitter4J was chosen for the example in this article. (See Resources for download information.)

Configuring TDI

To set up TDI:

  1. Download version, TDI 7.1.1, from XtremeLeverage (IBM Internal) or download a 90-day trial licensed version of Tivoli Directory Integrator 7.1.1.
  2. Install TDI using the instructions in the BM Tivoli Directory Integrator Installation and Administrator Guide Version 7.1.1.
  3. Copy the Twitter4J library twitter4j-core-2.2.5.jar into the TDI Installation folder /jars/3rdParty.

Now you are ready to set up the Twitter Connector in TDI to tweet from TDI as well as read the tweets.

Developing (scripting) the Twitter Connector

  1. To create a project in TDI, select File > New > Project and name it TwitterConn, as shown in Figure 4.
    Figure 4. Project name
    A window showing TwitterConn as the project name

    A new project is created in TDI, as shown in Figure 5.

    Figure 5. New project
    window showing twitterconn as an option under the properties folder
  2. Select Resources > Connectors. Right click Connectors and select New Connector, as shown in Figure 6.
    Figure 6. New Connector
    window showing a pop-up window with new connector highlighted
  3. In the window, select Script Connector, change the Name to TwitterConnector, and click Finish, as shown in Figure 7.
    Figure 7. Choose Component
    window allowing you to choose your component with script connector highlighted

    To tweet into Twitter from TDI, the Connector should be scripted for AddOnly mode. To read the tweets from Twitter into TDI, the connector should be scripted in Iterator mode. For now, choose AddOnly.

    The configuration parameters for the connector in both of the modes are the User Name, Consumer Key, Consumer Secret, Access Token, and Access Token Secret.

  4. Create the form to accept the configuration parameters. As shown in Figure 8, right click the TwitterConnector you created and select Open With > Forms Editor. Then, select Yes.
    Figure 8. Create form
    Window showing TwitterConnector, Open With, Forms Editor.
  5. The Form Editor opens. Select Fields, click Add Field, and enter User Name, as shown in Figure 9. Click OK.
    Figure 9. Add field
    Window showing User Name in the Field Name text box.
  6. Complete the fields as shown in Figure 10. Enter UserName in the Label field. Enter the user name for the Twitter account in the ToolTip field. Enter AddOnly and Iterator in the Mode selection field.
    Figure 10. User Name
    Window showing generic text in the label, tooltip, and mode selection fields
  7. Select Sections > General and click Add Field to add the configuration parameter User Name to the General section of the Connector configuration, as shown in Figure 11.
    Figure 11. Add field
    Window showing the General section highlighted.
  8. In the resulting window, check User Name and click OK, as shown in Figure 12.
    Figure 12. Select user name
    The selection needed window showing User Name checked.

Follow the same procedure to add the other configuration parameters that are based on the connector modes. After you're finished, the screen should look similar to Figure 13. The fields that are displayed are:

  • UserName
  • Access Token
  • Access Token Secret
  • Consumer key
  • Consumer Secret
  • $GLOBAL.script
  • debug
Figure 13. Script Connector Form
A completed TwitterConnector screen.

$GLOBAL.script lets you write the JavaScript that will make this Connector do the required work. The debug field in Figure 14 is a parameter that you can use for detailed logging.

Figure 14. Debug
A window showing the debug field options.

Open the connector in the Connector Editor by right-clicking Resources > Connectors > TwitterConnector and selecting Open With > Connector Editor, as shown in Figure 15.

Figure 15. Open Connector
Window showing open with and connector editor.

Select the Connection tab, and the screen should look like Figure 16, ready to enter the information for the Script Connector fields.

Figure 16. TwitterConnector
Script connector window with empty fields.

Click Edit Script. The scripting window appears, as shown in Figure 17, with default demo implementations for the methods.

Figure 17. Edit script
Window showing the Script Connector.script code

Methods

In this section, you'll start implementing the methods for the Twitter Connector.

Implementing the initialize method

The initialize method is called by the AssemblyLine. In general, anybody who creates and uses a connector programmatically should call the initialize() method after constructing the connector and before calling any other method.

The initialize() method reads the Connector's parameters and makes the necessary preparations for the actual work (creates a connection, and so on). In this method, the Twitter4J API is initialized to gain access to Twitter through Oauth by providing the obtained Consumer Key, Consumer Secret, Access Token, and Access Token Secret. Listing 1 shows an example.

Listing 1. Initializing the API
function initialize() {
	
	userName = connector.getParam("User Name")
	access_Token = connector.getParam("Access Token")
	access_Token_Secret = connector.getParam("Access Token Secret")
	consumer_Key = connector.getParam("Consumer key")
	consumer_Secret = connector.getParam("Consumer Secret")
	
	accessToken = new twitter4j.auth.AccessToken(access_Token, 	
                      access_Token_Secret);
	twitter = new twitter4j.TwitterFactory().getInstance();
	twitter.setOAuthConsumer(consumer_Key, consumer_Secret);
    	twitter.setOAuthAccessToken(accessToken);
    	
}

Implementing the querySchema method

The optional querySchema method returns the schema of the connected data source. If you implement the querySchema method, the Config Editor presents the returned values as the Connector's schema. These return values are stored as a list of entry objects—one for each column or attribute in the schema. Schemas are displayed in the Connector Input/Output Map. You can create the input schema for the Connector with the code in Listing 2.

Listing 2. Create input schema
function querySchema ()
{
	for (var i = 0; i < entries.length; i++)  {
		list.add(addEntry("User Screen Name","java.lang.String"));
		list.add(addEntry("Tweet","java.lang.String"));
		list.add(addEntry("Date of Creation","java.util.Date"));
	}		
	result.setStatus (1);
}

function addEntry(name,syntax){
	var e = system.newEntry();
	e.addAttributeValue("name",name);
	e.addAttributeValue("syntax",syntax);
	return e;
}

Figure 18 shows the result, a list of three different schemas.

Figure 18. Schema
Window with three schemas shown, along with their optional paramaters.

Implementing the selectEntries method

The selectEntries method, which is required for Iterator mode, is called only when the Connector is used in Iterator mode and after it has been initialized.

The selectEntries method contains the code that must be run prior to starting to iterate over the entries returned. When the Connector operates on a database, that code could be an SQL SELECT query, which returns a result set. When the Connector operates on an LDAP directory, that code could be a search operation that returns a result set. The result of selectEntries (result set, and so on) is later used by the getNextEntry() method to return a single entry on each call or AssemblyLine iteration. You might not need any preparation to iterate over the entries (as is the case with the File Connector), in which case there is no need to implement selectEntries. The code in Listing 3 connects to the Twitter account and picks the most recent 20 tweets.

Listing 3. selectEntries method
function selectEntries()
{
	try {
	entries = twitter.getUserTimeline(userName);
	}
	catch (TwitterException) {
        throw TwitterException
    }	
	entryCnt = 0
}

Implementing the getNextEntry method

The getNextEntry method is called on each iteration of AssemblyLine when the Connector is in Iterator mode. It is expected to return a single entry that feeds the rest of the AssemblyLine. getNextEntry retrieves data from the data source and must create an Entry object and populate it with attributes. The code in Listing 4 iterates through the Twitter data that is sent from the SelectEntries method. The Twitte4J API pulls the tweets from the Twitter account and the tweets in JSON format are parsed. The parsed data User Screen Name, Tweet text, and the creation date are put into an entry.

Listing 4. getNextEntry method
function getNextEntry ()
{
	if (entries == null || entryCnt >= entries.length) {
		result.setStatus (0);
		return;
	}
	entry["$rowNumber"] = entryCnt
	entry["$totalRows"] = entries.length
	var status = entries.get(entryCnt);
	var user = status.getUser();
	entry["User Screen Name"] = user.getScreenName();
	entry["Tweet"] = status.getText();
	entry["Date of Creation"] = status.getCreatedAt();
    
    	entryCnt++;
	result.setStatus (1);
	return entry
}

The $rowNumber attribute contains the row number of the obtained tweets. The $totalRows attribute contains the total number of tweets that are obtained in the current run.

Implementing the putEntry method

The putEntry method is called every time a Connector is used in AddOnly mode. (It's also called in Update mode when no matching entry is found in the connected data source.) Use this method to add, save, or store the entry that is passed in as a parameter to this method into the Connector's data source. Listing 5 shows the code for putEntry.

Listing 5. putEntry method
function putEntry (){
	tweet(entry.getAttribute("TwitterText").getValue())
}

function tweet(tweetText){
    try {
        twitter.updateStatus(tweetText);
    } catch (TwitterException) {
        throw TwitterException
    }
}

You can add an attribute in the Output Map to add or map the tweet text that gets added to the Twitter account in AddOnly mode of this connector, as shown in Figure 19.

Figure 19. Add or map tweet text
Window showing the twittertext schema name

Implementing the terminate method

The terminate method is called by the AssemblyLine after it has finished cycling and before it terminates. You can put any clean-up code, such as release connections or resources you created in the initialize method or later, during processing. Listing 6 shows an example.

Listing 6. terminate method
function terminate() {
	entries = null
}

Building the solution

Now that the Connector is implemented, it's time to build the solution. The first step is to add an AssemblyLine that will send notifications from TDI to Twitter and an email notification to the account manager. Another AssemblyLine will iterate on the Twitter account, read the response tweets from Twitter, and notify the account manager. (Notifications from Twitter to users through mobile and PDA devices or email are not covered in this article. They can be configured in Twitter's settings in the Twitter Account.)

Tweet from TDI and notify account manager

I'll begin with an over-simplified process of collecting the status from a CSV file. In real-world scenarios, the AssemblyLine running the solution sends the status of the solution. To demonstrate the use of the Connector, this example reads the status from a CSV file containing the status of the example.

  1. Create a file with textual data on disk (for example, <TDI solution-directory>/Twitter_Tutorials/Status.csv), as in Listing 7.
    Listing 7. Textual data
    <TDI solution-directory>/Twitter_Tutorials/Status.csv
    
    Status
    TAMIT Error: BMXAA1496E - TLOAMSWCATALOG does not exist. Cannot update or delete.,
    TAMIT Status: An asset is in OPERATING status but its record is in an UPDATE status,
    TAMIT Error: Error java.lang.Exception at psdi.mbo.MboSet.fetchMbosActual
  2. Set up a File Connector to read the CSV file. Add an AssemblyLine, as in Figure 20.
    Figure 20. New AssemblyLine
    Window showing New AssemblyLine highlighted
  3. Name it TweetNotify, as shown in Figure 21.
    Figure 21. Specify Name
    Window showing TweetNotify in the Name field
  4. Add a File Connector to the AssemblyLine in Iterator mode to read the CSV file and name it Read Status, as shown in Figure 22.
    Figure 22. Add File Connector
    Read Status shown in the Name field of the choose connector window
  5. As shown in Figure 23, configure the connector to read the Status.csv file by adding <TDI Solution Directory>/Twitter_Tutorials/status.csv to the File Path field.
    Figure 23. Configure connector
    Configure connector window
  6. Configure the CSV parser for the connector, as shown in Figure 24 by entering the CSV parser options.
    Figure 24. Configure CSV parser components
    Window showing empty CSV parser options
  7. Add a control flow component IF, named Choose Status, to the AssemblyLine, as shown in Figure 25. This is a decision component to pick only the needed error status from the CSV file.
    Figure 25. Add IF
    Window showing the IF component selcted on the Choose Components window
  8. If the status contains "error," as shown in Figure 26, the message gets tweeted to Twitter and an email notification is sent to the account manager.
    Figure 26. Branch Conditions
    Branch conditions window with an integrationstatus attribute showing error
  9. Add the TwitterConnector in AddOnly with the configuration in Figure 27.
    Figure 27. Add TwitterConnector
    the TwitterConnector options screen with the parameters shown in AddOnly mode
  10. Set the Output Map configuration, as in Figure 28, with work.IntegrationStatus set as the Assignment and TwitterText set as the Component Attribute.
    Figure 28. Output Map
    Window showing work.IntegrationStatus set as the Assignment and TwitterText set as the Component Attribute
  11. Add a SendEMail function component using the configuration in Figures 29 and Figure 30.
    Figure 29. Add SendEMail
    Completing the SendEMail function component options.
    Figure 30
    Setting the Advanced options
  12. Set the InputMap configuration, as in Figure 31, with status showing as the Work Attribute and conn.status showing as the Assignment.
    Figure 31. Input Map configuration
    status showing as the Work Attribute and conn.status showing as the Assignment.
  13. Set the Output Map configuration, as in Figure 32, with work.IntegrationStatus showing as the Work Attribute and body showing as the Component Attribute.
    Figure 32. Output Map configuration
    work.IntegrationStatus showing as the Work Attribute and body showing as the Component Attribute

Figure 33 shows the complete TDI AssemblyLine flow.

Figure 33. TDI AssemblyLine flow
Window showing the work attributes, assignments, and component attributes.

Now that the AssemblyLine is complete, click Run to run the assembly line. Ideally, the AssemblyLine is configured to run as a scheduled task so that the status can be tweeted regularly.

Regardless of the method of execution, when the AssemblyLine is executed successfully the result should be a tweet entry that is created in Twitter. Figure 34 shows the example tweets.

Figure 34. Example tweets
Twitter window showing two tweets.

Matthew, the fictitious account manager, also gets notified through email, as shown in Figure 35.

Figure 35. Email notification
A sample email to the account manager.

Read the response tweets in TDI and notify the account manager of the resolution

Use the following steps to read the response tweets and notify the account manager of the resolution.

  1. Add an AssemblyLine and name it Read Tweets. This AssemblyLine connects to the Twitter account, collects the 20 most recent tweets from Twitter, and picks up the resolution posted on Twitter. Then, the account manager, Matthew, gets notified of the resolution through an email that is sent from TDI.
  2. Add and configure a Twitter Connector in Iterator mode. An example is shown in Figure 36.
    Figure 36. Add Twitter Connector
    TwitterConnector Script Connector window with various fields
  3. Set the Input Map, as in Figure 37, with an asterisk in the Work Attribute field and (Map all Attributes) in the Assignment field.
    Figure 37. Set Input Map
    an asterisk in the Work Attribute field and (Map all Attributes) in the Assignment field.
  4. Add a control flow component IF, named Choose Tweet to the AssemblyLine and configure it as shown in Figure 38 and Figure 39.
    Figure 38. Add IF component
    Window showing the IF component selcted on the Choose Components window
    Figure 39. IF branch
    IF branch window showing Tweet as the Attribute and its operator and value
  5. Add a SendEMail function component to notify the account manager of the resolution posted in the Twitter Account.

    Figure 40 shows the TDI AssemblyLine flow.

    Figure 40. TDI AssemblyLine flow
    The Read Tweets window with the work attributes, assignments, and component attributes shown.

Now that the AssemblyLine is complete, you can add a response tweet, as in Figure 41, in the Twitter account for one of the notifications.

Figure 41. Response tweet
A sample Twitter tweet.

Run the AssemblyLine. The response tweet "@TDI Account" is picked up by TDI and the notification is sent to the account manager, Matthew, as shown in Figure 42.

Figure 42. Updated notification
Sample email sent to the account manager.

Conclusion

This article demonstrated an effective use of social media and Tivoli Directory Integrator's extensibility options. You can quickly get a solution set up by prototyping an out-of-the-box connector using TDI's Java-JavaScript framework.

The solution in this article can be implemented for other social media sites as well. Notifications can be posted to all social media sites at once, providing:

  • A larger audience and larger response
  • An automated notification service from machine to machine

Download

DescriptionNameSize
Source code examples for articleTwitterConnectorSolution.zip7KB

Resources

Learn

Get products and technologies

Discuss

  • Get involved in the My developerWorks community. Connect with other developerWorks users while exploring the developer-driven blogs, forums, groups, and wikis.

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Security on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Security, Open source
ArticleID=848596
ArticleTitle=Send system notifications to social media with IBM Tivoli Directory Integrator
publish-date=12112012