TIBCO ActiveMatrix BusinessWorks Plug-in for …...Plug-In Overview TIBCO ActiveMatrix BusinessWorks...

TIBCO ActiveMatrix BusinessWorks™ Plug-infor Facebook User's GuideSoftware Release 6.0May 2014

Two-Second Advantage®

Important Information

SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCHEMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY(OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THEEMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANYOTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE.

USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS ANDCONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTEDSOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THECLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOADOR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE)OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USERLICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THESOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, ANDYOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BEBOUND BY THE SAME.

This document contains confidential information that is subject to U.S. and international copyright lawsand treaties. No part of this document may be reproduced in any form without the writtenauthorization of TIBCO Software Inc.

TIBCO, Two-Second Advantage, TIBCO ActiveMatrix BusinessWorks, TIBCO Business Studio, andTIBCO Enterprise Administrator are either registered trademarks or trademarks of TIBCO SoftwareInc. in the United States and/or other countries.

Enterprise Java Beans (EJB), Java Platform Enterprise Edition (Java EE), Java 2 Platform EnterpriseEdition (J2EE), and all Java-based trademarks and logos are trademarks or registered trademarks ofOracle Corporation in the U.S. and other countries.

All other product and company names and marks mentioned in this document are the property of theirrespective owners and are mentioned for identification purposes only.

THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOTALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASEDAT THE SAME TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWAREVERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM.

THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OFMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICALERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESECHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCOSOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S)AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME.

THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY ORINDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE,INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.

Copyright © 2012-2014 TIBCO Software Inc. ALL RIGHTS RESERVED.

TIBCO Software Inc. Confidential Information

2

TIBCO ActiveMatrix BusinessWorks™ Plug-in for Facebook User's Guide

Contents

TIBCO Documentation and Support Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4

Plug-In Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6

Creating a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Designing a Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6

Debugging and Running a Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Checking the Activity Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7

Deploying an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8

Generating an EAR File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Authentication and Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Introduction to Facebook Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Introduction to Authentication Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Getting Access Token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Generating Extended Authentication Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Facebook Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12

Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Graph Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

FQL Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18

Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20

RealTimeListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Working with the Sample Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Importing the Sample Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Working with the ParsingPageFeeds-ProductDirection Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25

Configurations for the ParsingPageFeeds Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26

Configurations for the ProductDirection Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Managing Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Log Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Setting Up Log Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Exporting Logs to a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

3


TIBCO Documentation and Support Services

All TIBCO documentation is available in the TIBCO Documentation Library, which can be found here:

https://docs.tibco.com

Product-Specific Documentation

The following documents for this product can be found in the TIBCO Documentation Library:

● TIBCO ActiveMatrix BusinessWorks Plug-in for Facebook Installation● TIBCO ActiveMatrix BusinessWorks Plug-in for Facebook User's Guide● TIBCO ActiveMatrix BusinessWorks Plug-in for Facebook Release Notes

The following documents provide additional information and can be found in the TIBCODocumentation Library:

● TIBCO ActiveMatrix BusinessWorks Documentation● TIBCO Enterprise Administrator User's Guide

How to Contact TIBCO Support

For comments or problems with this manual or the software it addresses, contact TIBCO Support asfollows:

● For an overview of TIBCO Support, and information about getting started with TIBCO Support,visit this site:

http://www.tibco.com/services/support

● If you already have a valid maintenance or support contract, visit this site:

https://support.tibco.com

Entry to this site requires a user name and password. If you do not have a user name, you canrequest one.

How to Join TIBCOmmunity

TIBCOmmunity is an online destination for TIBCO customers, partners, and resident experts. It is aplace to share and access the collective experience of the TIBCO community. TIBCOmmunity offersforums, blogs, and access to a variety of resources. To register, go to:

http://www.tibcommunity.com

4


https://docs.tibco.com

http://www.tibco.com/services/support

https://support.tibco.com

http://www.tibcommunity.com

Plug-In Overview

TIBCO ActiveMatrix BusinessWorks Plug-in for Facebook allows you to publish, search, delete, query,and listen to Facebook data.

TIBCO ActiveMatrix BusinessWorks is a scalable, extensible, and easy to use integration platform thatallows you to develop integration projects. TIBCO ActiveMatrix BusinessWorks uses TIBCO BusinessStudio to define business processes and the TIBCO ActiveMatrix BusinessWorks process engine toexecute the business processes. For detailed discussion, see TIBCO ActiveMatrix BusinessWorks Concepts.

TIBCO ActiveMatrix BusinessWorks supports plug-in that extends the palette functionality. Afterinstalling the plug-in, activities for the plug-in become available in the TIBCO Business Studio. Add theplug-in activities to the business process you are designing, and integrate them with the process flow.At runtime, the plug-in activities are executed as part of the ActiveMatrix BusinessWorks processexecution.

This manual focuses on an overview of each activity. For details, see Facebook DeveloperDocumentation.

TIBCO ActiveMatrix BusinessWorks Plug-in for Facebook is unique in its powerful integrationcapabilities, and also unique in its dependency on another company's product. Because the plug-in usesthe public API of the platform, in this case, the Facebook Graph API, any open issues that have beenreported against the third-party API result in problems with the plug-in. If Facebook makes changes totheir public API, the plug-in functionality might become limited or might change.

5


Getting Started

A typical workflow to start with the plug-in consists of creating a project, designing a process, anddeploying the application.

TIBCO ActiveMatrix BusinessWorks enables users to create services, integrate applications, and deploythem at runtime. It uses the Eclipse graphical user interface (GUI) to define business processes and theprocess engine to execute them.

To design a process and deploy it at runtime, follow this workflow:

1. Creating a Project

2. Designing a Process

3. Debugging and Running a Process

4. Deploying an Application

Creating a ProjectBusinessWorks application modules are Eclipse projects, they are created in TIBCO Business Studioand contain various resources.

Procedure

1. Start TIBCO Business Studio.

2. Select File > New > BusinessWorks Resources.

3. Click the BusinessWorks Application Module resource in the BusinessWorks Resource wizard.

Click Next. Or click the Create a new BusinessWorks Application Module icon.

4. Type a name for the project in the Project name field.

5. Select the Create empty process check box and type a process name in the Name field.

6. Select the Create Application check box and type an application name in the Name field. ClickFinish.

Result

A project with the default settings opens in the Project Explorer view.

Designing a ProcessProcesses capture and manage the business information flow in an enterprise between different datasources and destinations. Design a process by using activities and adding conditions.

By default, an empty process is created when you select the Create empty process check box when Creating a Project.

See TIBCO ActiveMatrix BusinessWorks Application Deployment for more details about creating processes.

Prerequisites

The plug-in uses the OAuth 2.0 protocol to authenticate and authorize access to Facebook applications.Before configuring activities in the process, ensure that you generate an access token. See Authentication and Authorization for more details.

6


Procedure

1. In the Process editor, select and drop an activity from the Palette view.For example, select and drop a Timer activity from the General Activities folder and a Publishactivity from the Facebook folder.

2. Click to link the activities and configure the condition types.

3. Configure the added activities, as described in Facebook Palette.

4. Click File > Save to save the process.

Debugging and Running a ProcessDebug the application configuration to ensure its correctness.

Procedure

1. Open the process that you have configured in TIBCO Business Studio.

2. On the toolbar, click Run > Debug Configurations.

3. Click BusinessWorks Application > BWApplication in the left panel.

4. Ensure only the application you want to debug and run is selected in the Applications tab in theright panel.

5. Click the Advanced tab and click Browse to locate the logback file.By default, the log file resides in the TIBCO_HOME/bw/6.0/config/design/logback directory. See Managing Logs for more details.

6. Click Debug.

Result

TIBCO Business Studio changes to the Debug perspective. Logs are displayed in the Console view.

Checking the Activity OutputAfter debugging the application, check the output of activities.

Procedure

1. In the Debug perspective, expand BWApplication and click the activity in the upper left panel.

2. In the upper right panel, click the Job Data view and click Output.

Result

The output of the activity is displayed.

7


You can also check the activity output in the plug-in logs. See Managing Logs for moreinformation.

Deploying an ApplicationAfter deploying BusinessWorks applications, manage the applications in TIBCO EnterpriseAdministrator.

Prerequisites

Before deploying an application, you need to generate an EAR file. See Generating an EAR File fordetails.

A complete workflow of deployment includes:

1. Building an EAR file.

2. Uploading the EAR file.

3. Deploying the EAR file.

4. Starting the application.

You can generate an application EAR file from TIBCO Business Studio, and then deploy the EAR file byusing the command-line mode with the bwadmin utility. See TIBCO ActiveMatrix BusinessWorksAdministration for more details about how to deploy an application.

Generating an EAR FileApplication archives are the enterprise archive (EAR) files that have been created in TIBCO BusinessStudio. An EAR file is required when deploying an application.

Prerequisites

An application project has already been created, as explained in Creating a Project.

8


Procedure

1. Go to File Explorer and click the Open Directory to Browse icon.

2. Select the folder where you want to generate the EAR file and click OK.A new folder is displayed in the File Explorer view

3. Drag the application from the Project Explorer to the new folder in the File Explorer.

The EAR file is generated with the name <application>_<version>.ear.

9


Authentication and Authorization

The plug-in uses the OAuth 2.0 protocol for authentication and authorization. Before using the plug-in,you need to get the authentication parameters to authorize Facebook applications.

The protocol itself and how Facebook uses the protocol might change. Therefore, this document onlyprovides an example.

Introduction to Facebook AuthenticationFacebook authentication is required to conduct plug-in activities.

Each activity in the plug-in includes a token field in the Input tab. You must specify an appropriateauthentication token in the token field to run the process.

The Facebook implementation of the OAuth 2.0 protocol consists of three steps:

User authenticationEnsures that the user who logs into Facebook is a valid Facebook user, that is, a user with a validFacebook user name and password.

App authorizationEnsures that when your app asks a user for access, the user knows exactly what data and capabilitiesthey are providing to your application.Most ActiveMatrix BusinessWorks Plug-in for Facebook applications do not ask users for access butwork with publicly available user data instead.

App authenticationEnsures that users are giving data to your app rather than a different app.

After your app completes these steps, the app is issued an access token that allows the app to access theuser's information if it has appropriate permissions. For example, your app might be able to examinethe posts of a user and of all friends of the user.

For background information on Facebook Authentication, go to the Core Concepts section of theFacebook Developer Documentation and select Authenticating an App in the sidebar. Do not click one ofthe authentication flow links on the first page.

Introduction to Authentication TokensAn authentication token stores information related to permissions, token generation and expiration.

Access Token

An access token is a random string that gives an app temporary and secure access to Facebook APIs.An access token is created on behalf of a person, a Facebook Page or an app. The token is generatedduring the last step of the login flow. Facebook SDKs handle the generation and storage of tokensautomatically. Apps using other methods need to follow the login flow to create tokens.

A token stores information about granted permissions, when the token expires and which appgenerates it. To maintain information security, almost all API calls at Facebook need to have an accesstoken that passed in the parameters of the request.

User TokenUser tokens enable you to test your apps. They expire like any other user access token and should notbe hard coded into your apps.

App TokenApp tokens do not expire and should be kept confidential as they are related to your app secret.

10


Getting Access TokenAn access token is required for authorizing the access to Facebook applications.

Procedure

1. Log into https://developers.facebook.com/tools/explorer/.

2. Select your application from the Apps list at the top of the page.

3. Click the Get Access Token button.Grant necessary permissions to your application so that the token generated have sufficient rightsfor your API call.

Result

The access token is generated in the Access Token field. You can use the access token ID in the tokenfield in the Input tab of different activities.

Generating Extended Authentication TokensBy default, a Facebook authentication token expires after two hours. You can extend the token to bevalid for sixty days.

The precise expiration for tokens and extended tokens depend entirely on the settings that Facebookassigns to those tokens.

Procedure

1. Log into https://developers.facebook.com/tools/explorer/.

2. Select Graph API Explorer from the Apps list at the top of the page.

3. Click the Get Access Token button.

4. On the Select Permissions window, click the Extended Permission button, select necessarypermissions, and then click the Get Access Token button.

Result

The extended access token is generated in the Access Token field.

11


https://developers.facebook.com/tools/explorer/

https://developers.facebook.com/tools/explorer/

Facebook Palette

The Facebook Palette contains six activities to search, query, publish, delete, and listen to Facebookdata.

After installing the plug-in, a Facebook palette is available in TIBCO BusinessWorks Studio, whichcontains the following activities:

● Search

The Search activity allows you to search public objects in the social graph. Searchable objectsinclude public post, user, page, event, group, and place.

● Graph Query

The Graph Query activity allows you to search for a specific object and its details. It does not returnresults across all Facebook objects like Search but focuses on a single object. A Graph Querysearches a much smaller space than a Search activity.

● FQL Query

The FQL Query activity allows you to define and execute a Facebook Query Language (FQL) query.FQL Query queries the data available in the Facebook social graph. In contrast to the Graph Queryactivity and the Search activity, search results are narrowed down.

● Publish

The ActiveMatrix BusinessWorks Plug-in for Facebook process publishes to the Facebook socialgraph using HTTP POST requests.

● Delete

The Delete activity allows you to delete objects in the social graph. For example, you are able todelete a comment or delete a like for a post.

● RealTimeListener

The RealTimeListener activity is a TIBCO ActiveMatrix BusinessWorks starter activity. It enablesActiveMatrix BusinessWorks customers to subscribe to changes in data in Facebook. By listening tochanges, rather than polling the Facebook servers, an ActiveMatrix BusinessWorks applicationimproves reliability and decreases load times.

SearchUse the Search activity to search public objects in the social graph. Searchable objects include publicpost, user, page, event, group, and place.

When you use the Search activity, you need to add quotes around strings that include specialcharacters. If the string for which you want to search includes double quotes, or if some text repeats inthe string, you need to add a set of single quotes. For example, to search for "fun fun fun" , enter the text'"fun fun fun"'.

General

The General tab lists information in the following table.

FieldModuleProperty? Description

Name Yes Name of the Search activity.

12



ObjectType

Yes The Facebook objects to search on. Available object types are User,Event, Group, Page, Post, Place.

Description

Optionally used to provide a short description for this activity.

Input

The Input tab lists information in the following table.

Input ItemDataType Description

searchText String Text used to search for data in Facebook.

maxNumOfPages Integer The maximum number of pages that used to display retrievedrecords that the process performs. The default value is 1.

If you set it to -1, all the retrieved records that Facebook returns aredisplayed, regardless of the page size limit.

pageSize Integer Number of items displayed on one page.

If you specify -1 for maxNumOfPages, the value of pageSize isignored.

The number of results returned is not always equal to thevalue of maxNumOfPages multiplies pageSize. For detailson this, see https://developers.facebook.com/blog/post/478/.

additionalParams String Additional parameters, depending on the object you select in theGeneral tab.

token String The Facebook authentication token (OAuth token) to access thedata.

center String The center of your search location, you specify latitude andlongitude in this parameter.

This field appears only if you select Place from theObject Type list in the General tab.

distance String The distance between the center and search range. Along withcenter, the parameter is used to narrow your search to a specificlocation range.

This field appears only if you select Place from theObject Type list in the General tab.

13


https://developers.facebook.com/blog/post/478/

https://developers.facebook.com/blog/post/478/

Output

XML representation of the returned object. The information available in the object depends on theobject selected in the General tab and on the permission settings for that object.

Fault

The Fault tab lists exceptions that are thrown by the activity.

Fault Thrown When...

FBPluginException The plug-in does not send the request or parse the response. A summaryof the error returned from Facebook is displayed in a dialog.

If you get this error with a process that previously worked properly,Facebook might have added fields to the object that the activity is using.Check the input field of the activity for missing input, and see Facebookdocumentation for details.

FBConnectionException The HTTP connection to Facebook is not available, or another connectionproblem that is unrelated to authorization exists.

FBOauthException If your token is invalid, your token expires, or you do not havepermissions to retrieve or publish the information you want to retrieveor publish.

The error message from Facebook is not specific and you have to explorewhether the problem is related to the token or to permissions.

Graph QueryUse the Graph Query activity to query social graph.

Facebook social graph represents connections between Facebook objects such as users, links, and pages.The Graph Query activity allows you to search for a specific object and its details. It does not returnresults across all Facebook objects like the Search activity but focuses on a single object. A Graph Queryactivity searches a much smaller space than a Search activity, and it requires the ID of the object youquery.

General

The General tab of the Graph Query activity allows you to specify the query name, select an object toquery, and specify the connections of the object that you are interested in.


Name Yes Name of the Graph Query activity.

Object Yes One of the Facebook objects to be queried.

Query Edges(Connection )

No Select this check box to query edge or connections between objects.

14



Edge(Connection)

Yes Type of edge or connection to query. Edges are the connections, orrelationships, between nodes, such as friendships between people,likes of Pages, or the list of comments on a photo.

For example, if you select Post from the Object list, the Edge(Connection) list allows you to select Comments and Likes.

See the Facebook Developer Documentation for details.

This field displays only when you select the Query Edges(Connection) check box.

Description


Input

Information in the Input tab varies according to Object specified in the General tab.


graphObjectID String Run the process twice to retrieve information, with different valuesin the Input tab.

1. Use your own user ID or the string "me", including the doublequotes to retrieve the object you want to query. For example, ifyou want to query a friend's connections, you need that friend'suser ID.

2. In the second Graph Query activity, specify the ID of the objectthat you want to retrieve information about.

friendID String ID of a user's friend.

This field displays only when you select User in theObject list and Mutualfriends in the Edge (Connection)list in the General tab.

maxNumOfPages Integer The maximum number of pages that is used to display retrievedrecords that the process performs. The default value is 1.

If you set it to -1, all the retrieved records that Facebook returns aredisplayed, regardless of the page size limit.

pageSize Integer Number of items displayed on one page.

If you specify -1 for maxNumOfPages, the value of pageSize isignored.

15



recordOffset Long A number that will be deducted from the retrieved records number.

This field displays only when you select the Edge(Connection) check box in the General tab.

since String The start time of what you want to query.

until String The end time of what you want to query.

BuildInDelay Integer The minimum sleep time a process needed to run the activity.

additionalParams String Additional parameters, depending on the selection you made in theGeneral tab.

token String The Facebook authentication token (OAuth token) to access thedata.

Output

The returned object is displayed in the XML format. The information available in the object depends onthe object selected in the General tab and the permissions settings for that object. For example, if youselect Link from the Object list, and select Comments from the Edge (Connection) list to get allcomments on a link, the following fields are listed.

● id● metadata● type● from● message● createdTime● likes

Fault






16





FQL QueryUse the FQL Query activity to define and execute a Facebook Query Language (FQL) query. FQLQuery queries the data available in the Facebook social graph. In contrast to the Graph Query activityand the Search activity, search results are narrowed down.

See the Facebook Developer Documentation for details on how FQL Query works.

General

The General tab allows you to define the query that you want to conduct.


Name Yes Name of the FQL Query activity.

Table Yes List of tables over which you run the FQL Query. See the FacebookDeveloper Documentation for details on the definition of each table.

For example, Comment queries this table to obtain commentsassociated with a Facebook object, for example, comments associatedwith a Post, Link, Video, or Photo.

Columns Yes An FQL table that documents columns in other FQL tables.

Click Pick Columns to display a multi-choice table, select propercheck boxes, and click OK.

Where No WHERE clause for the FQL Query.

Description


Input

The Input tab lists information in the following table.

17



whereClause String Optional field to specify the WHERE clause of the FQL Query activityat runtime. It overrides the whereClause specified in the General tabat runtime.

Use this field if a BusinessWorks activity feeds data to this activity, andyou want to use something in the input data as the query string.

Specify the WHERE clause only. If the syntax of the text inthis field does not match the WHERE clause syntax, an errorresults.

token String The Facebook authentication token (OAuth token) to access the data.

Output

The information available in the object depends on the object selected in the General tab and thepermissions associated with the token.

The plug-in supports a subset of the output that are returned by the Facebook FQL Query API. But ifthe Facebook Query API changes, those fields are possibly not available.

Fault








PublishUse the Publish activity to publish to the Facebook social graph by using HTTP POST requests.

To publish to the Facebook social graph using the HTTP POST requests, you must have anauthentication token. Not all objects are able to be published.

The Post section in the Graph API Facebook Developer Documentation includes details on a post'sfields. The Publish activity includes only a subset of these fields.

18


General

The General tab allows you to specify what you want to publish.


Name Yes Name of the Publish activity.

Connections Yes The Connections list contains all potential connections you want topublish.

Description


Input

The Input tab contains information in the following table.


<firstelement>

String The name and contents of the first element depends on the selection youmake in the General tab. For example, if you choose Comments (of anObject), specify the ID of the post that you want to publish a commentto, and the parameters for the comment.

parameters String The precise parameters depend on the selection you make in theGeneral tab. For example, if you select Comments (of an Object),specify the message of the comment.


Output

The Output tab includes information in the following table.

OutputItem Data Type Description

publishResult

String Typically the ID of the published object.

For connection such as Attending (of an Event), Maybe (of anEvent), Declined (of an Event), Invited and Likes (of anObject), the Publish activity returns true; otherwise, an error occursin the process.

Fault


19








DeleteUse the Delete activity to delete objects in the social graph, for example, delete a comment, or a like foran object.

General

The General tab includes information in the following table.


Name Yes Name of the Delete activity.

Object Yes Select the type of object you want to delete from the Object list. Sixobjects are available: Link, Post, Page, Event, Comment, and Other.If you select Other, specify other objects by specifying the Object IDin the Input tab. Those objects include groups, notes, photos, orother objects that the plug-in App has published earlier. TheConnection list of the Publish activity lists all objects the plug-inApp publishes. Specify objects that are not included in the Generaltab of the Delete activity when you choose Other.

When this manual was written, information about permissions youmight need to delete an object was available at http://developers.facebook.com/docs/authentication/permissions.

The Delete activity only deletes objects that have an ID. Objects thatdo not have an ID, such as Attending (of an Event), Invited(of an Event), and Maybe (of an Event), are not deletedseparately from the object. For those cases, the whole object, forexample, the event, is deleted if the permissions are set.

20


http://developers.facebook.com/docs/authentication/permissions

http://developers.facebook.com/docs/authentication/permissions


Unlike thisobject

No Select this check box to unlike an object.

The check box displays when you select Post, Comment,Link, or Other from the Object list.

Description


Input

The Input tab includes information in the following table.


graphObjectID String ID of the object to be deleted.

If you intend to delete a post ID, but specify the User ID byaccident, the user with that ID is deleted. If thegraphObjectID is not of the right Object type, and the useraccess token has permission to delete the object to which thegraphObjectID belongs, the plug-in deletes the objectwithout returning any error.


Output


Output ItemDataType Description

deleteResult Boolean It is True if successful.

If the Delete operation is not successful, an error occurs.

Fault





21






RealTimeListenerUse the RealTimeListener activity to subscribe to data changes in Facebook.

An ActiveMatrix BusinessWorks application improves reliability and decreases load times by listeningto changes rather than polling the Facebook servers.If there is a valid subscription, when data changes, Facebook servers make an HTTP POST request tothe callback URL that ActiveMatrix BusinessWorks specifies. The request has a content type ofapplication/json. The body is a JSON-encoded string that contains one or more changes. The output ofthe content is in XML by default; however, the JSON format is also available.

1. An internal Jetty server is set up with an HTTP connection URL. The server receives both HTTPGET requests (for subscription verification) and HTTP POST requests (for actual changed data)from Facebook.

2. The Jetty server makes a POST to the Facebook graph API URL to subscribe to changes on certainFacebook objects, and is ready to handle the verification request.

3. Facebook servers make an HTTP GET request to the callback URL.

4. The Jetty server verifies the verify_token value that ActiveMatrix BusinessWorks passes to Facebookand returns the hub.challenge value. This verification technique prevents malicious apps fromusing the real-time feature as tool for distributed denial-of-service (DDoS) attacks.

General

The General tab includes information in the following table.


Name Yes Name of the RealTimeListener activity.

HTTPConnection

Yes The IP address (or machine name) that you run this listener on, andport of the listener endpoint.

App ID Yes ID of your app.

AccessToken

Yes The access token associated with the app. It is not the user accesstoken.

Object Type No Object you want to subscribe to. Facebook currently allows you tosubscribe to user, permission, and page objects.

22



Fields Yes The list of fields and a list of connections in the selected object thatyou want to subscribe to.

JSONOutput

No Select this check box to receive the output in JSON format. The defaultvalue is text.

Description


Advanced

The Advanced tab includes information in the following table.


SequenceKey

No This field contains an XPath expression that specifies which processesshould run in order. Process instances with sequencing keys thatevaluate to the same value are executed sequentially in the order theprocess instances were created.

CustomJob Id

No This field contains an XPath expression that specifies a custom ID for theprocess instance.

Conversations

The Conversations tab allows you to initiate or join a conversation.

Conversations receive messages after the creation of the process instance, which is initiated or joined byan activity.

The RealTimeListenter activity is used to initiate a conversation. Click the Add New Conversation icon to initiate a conversation. For more details on conversations, see TIBCO ActiveMatrix BusinessWorksApplication Design.

Output


OutputItem Data Type Description

entry String List of changed object entries. The entry contains the following items:

1. id: ID of the object that has changed.

2. uid: Object ID of the changed object entry.

3. time: Time at which the change happened.

4. changed_fields: Fields that are changed for the changed object entry.

object String Object of the notification.

23


Fault








24


Working with the Sample Project

Working through the sample project helps you understand how TIBCO ActiveMatrix BusinessWorksPlug-in for Facebook works.

TIBCO ActiveMatrix BusinessWorks Plug-in for Facebook packages a sample project within theinstaller. The sample project is located in the TIBCO_HOME\bw\palettes\facebook\6.0\samplesdirectory.

The example assumes that a small family-owned purveyor of hand-crafted garden ornaments has anumber of customers. Each customer is a fan of the store's Facebook page, which helps customers tokeep abreast of new products and other exciting developments. The tutorial uses the term fan for anyuser who adds a comment to a page post, likes a post, or adds a post to the company page. Thewebmaster uses TIBCO ActiveMatrix BusinessWorks Plug-in for Facebook to obtain customers'interests and then decide the product direction.

The sample project consists of two processes:

1. The Configurations for ParsingPageFeeds Process collects the user ID of the company's facebookpage fans.

2. The Configurations for ProductDirection Process checks how many company fans are also fans ofthe National Weather Service, and compares the two numbers.

Importing the Sample ProjectA sample project is packaged with the plug-in. Before running the project, you need to import theproject to TIBCO Business Studio.

Procedure

1. Start TIBCO Business Studio.2. Click File > Import.3. In the Import window, expand the General folder and select the Existing Studio Projects into

Workspace item. Click Next.4. Click Browse next to the Select root directory field to locate the sample. Click Finish.

The sample project is located in the TIBCO_HOME\bw\palettes\facebook\6.0\samples directory.

Working with the ParsingPageFeeds-ProductDirection ProjectThe example collects user IDs of the company's fans, and determines product direction by analyzingthe data.

Prerequisites

● Ensure that you have imported the sample project, as described in Importing the Sample Project.● This description assumes that you know how to configure TIBCO BusinessWorks processes. See the

TIBCO BusinessWorks documentation for details.● To configure this example for your own application, you need the Page ID for the company page

and a Facebook Authentication Token.

Procedure

1. Expand the sample project in the Project Explorer view.2. Click Processes > sample > ProductDirection.bwp.

25


3. Click Run > Run Configurations.

4. Expand BusinessWorks Application in the Run Configurations dialog and click BWApplication.

5. Ensure only the sample.application is selected in the Applications tab.

6. Click Run.

7. Click the Terminate icon to stop the process.

Result

The ParsingPageFeeds process collects the user IDs of the company's facebook page fans. The list ofUser IDs of company fans becomes the input to the ProductDirection process, and the output of theMergeUIDs activity is passed on to the next activity. The ProductDirection process determines whichcompany fans are also fans of the National Weather Service, and compares the two numbers. If morethan 50% of the company fans are also passionate about weather, the process gives a green light forproduction of the new product, and then the company crafts a small number of weather stationstastefully framed in Brazilian ironwood, and posts a brief introduction to the product to the companyFacebook page, with a link to the company Web site for more details and photos.

Configurations for the ParsingPageFeeds ProcessThe ParsingPageFeeds process extracts User IDs of the company's fans from the company feed.

The process is designed with the following activities:

Activity Description

NewOperationIn Reads output from the previous activity it connects.

Our Page Feeds A Graph Query that extracts the company's page feed and passes it tothree Mapper activities.

Get Users who posted A Mapper activity that is used to extract all users who posted to thecompany page.

Get Users who likedposts

A Mapper activity that is used to extract all users who liked the post of thecompany page.

Get Users whocommented

A Mapper activity that is used to extract all users who made comment onthe post of the company page.

Merge UIDs A Java Code MergeUIDs activity that combines the output of the threeMapper activities, and passes the output to the next process with a list ofall company fans. The code eliminates duplicates.

26



NewOperationOut Transfers its value as input for the next activity it connects.

Configurations for the ProductDirection ProcessThe ProductDirection process is the top-level process. It determines which company fans are also fansof the National Weather Service, and compares the two numbers. If more than 50% of the company fansare also passionate about weather, the process gives a green light for production of the new product.

The process is designed with the following activities:


Timer Starts the process.

Get our Page Fans Invokes the ParsingPageFeeds process to extract User IDs of all fans of thecompany from the company feed.

Check Fans of otherPage

Iterates over the company fans and checks whether a fan is also interestedin the National Weather Service.

JavaInvoke Compares company fans and users who are both fans of the company andthe National Weather Service. The activity returns true if more than halfof the company's fans are interested in weather.

27


Managing Logs

Logs are used to trace and troubleshoot the plug-in exceptions.

A logback.xml file is located in the TIBCO_HOME\bw\6.0\config\design\logback directory, updatethis file to Setting Up Log Levels and Exporting Logs to a File.

Log LevelsThe plug-in captures logs at different levels.

Log Level Description

Error Indicates that an unrecoverable error has occurred. Depending on the errorseverity, the plug-in may continue with the next operation or may stopaltogether.

Debug Indicates a developer-defined tracing message.

Setting Up Log LevelsBy default, the log level is Error . You can change the log level to trace different messages.

If neither the plug-in log nor the BusinessWorks log is configured in the logback.xml file, the errorlogs of the plug-in are displayed in the Console view by default.

If the plug-in log is not configured, but the BusinessWorks log is configured in the logback.xml file,the configuration for the BusinessWorks log is implemented by the plug-in.

Procedure

1. Navigate to the TIBCO_HOME\bw\6.0\config\design\logback directory and open thelogback.xml file.

2. Add the following node in the User Loggers area to specify the log level for the plug-in.<logger name="com.tibco.bw.palette.facebook.runtime"> <level value="DEBUG"/></logger>

The level tag defines the log level and the value is Error or Debug.

When the level is set to Debug, the input and output of the plug-in activities are alsodisplayed in the Console view. See Log Levels for more details on each log level.

3. Optional: Add the following node in the User Loggers area to specify the log level for an activity.<logger name="com.tibco.bw.palette.facebook.runtime.ActivityNameActivity"> <level value="DEBUG"/></logger>

For example, if you want to set the log level of the Publish activity to Debug, you need to add thefollowing node:<logger name="com.tibco.bw.palette.facebook.runtime.PublishActivity"> <level value="DEBUG"/></logger>

For activities that do not configure with specific log levels, they still inherit log levelsconfigured for the plug-in or BusinessWorks.

4. Save the file.

28


Exporting Logs to a FileYou are allowed to export the plug-in logs to a file by modifying the logback.xml file.

Procedure

1. Navigate to the TIBCO_HOME\bw\6.0\config\design\logback directory and open thelogback.xml file.

When deploying an application in TIBCO Enterprise Administrator, you need to navigateto the TIBCO_HOME\bw\domains\mydomain\appnodes\myspace\mynode directory to findthe logback.xml file.

2. Add the following node to specify the file location.<appender name="FILE" class="ch.qos.logback.core.FileAppender"> <file>c:/bw6-facebook.log</file> <encoder> <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36}-%msg%n</pattern> </encoder></appender>

The file tag defines the location to which the log is exported and the value is the absolute path ofthe file.

You also need to add the file name in the file path.

3. Add the following node to the root node at the bottom of the logback.xml file to enable exportingthe logs to a file. <appender-ref ref="FILE" />

<root level="DEBUG"> <appender-ref ref="STDOUT" /> <appender-ref ref="FILE" /></root>

4. Save the file.

29


Error Codes

The exceptions that are thrown by the plug-in are listed with corresponding descriptions andresolutions.

Error Code and ErrorMessage Role Category Description Resolution

TIBCO-BW-PALETTE-FACEBOOK-200000

Info: [1%].

debugRole

BW-Plug-in Describes the generalDebug information.

No action.


IOException occurredwhile retrieving XMLOutput for activity [1%].

errorRole BW-Plug-in An error occurs whenretrieving XMLOutput for activity.

No action.


Unsupported encoding[1%].

errorRole BW-Plug-in The encodingprovided is notsupported.

Provide UTF-8encoding.


Facebook connectionError, Error message:[1%].

errorRole BW-Plug-in An error occurs in thenetwork connection.

Check thenetworkconnection.


Execute client operationfailed [1%].

errorRole BW-Plug-in An error occurs whenexecuting clientoperation.

Check clientoperation.


BW Facebook activityerror [1%].

errorRole BW-Plug-in An error occurs whenrunning a process.

No action.


Please check token [1%].

errorRole BW-Plug-in Occurs when theinput token is invalid,expired or withwrong permission.

Input valid tokenwith the rightpermission.


Publish activity error:[1%].

errorRole BW-Plug-in Occurs whenconducting thePublish activity.

No action.

30




The value for input fieldprivacy_type must beuppercase and the scopeis{'OPEN','SECRET','FRIENDS','CLOSED'}.

errorRole BW-Plug-in The value for theprivacy_type filed inthe Input tab of thePublish activity is notright.

Provide the rightvalue for theprivacy_typefiled.


File not found. Pleasecheck your upload photoexist or not.

errorRole BW-Plug-in The uploaded photodoes not exist.

Check theexistence of thefile to beuploaded.


Facebook return falsewith no result -- Can notget result from facebook.Please check permission.

errorRole BW-Plug-in Occurs when youhave no permission todo the correspondingoperation, or theinput token is invalid.

Check thepermission andinput valid token.


Number formatexception in readingpage_parameter: [1%].

errorRole BW-Plug-in Occurs when theformat ofmaxNumOfPagevalue is incorrect.

Input correctformat in themaxNumOfPagefield.


JAXB convertion error forclass: [1%].

errorRole BW-Plug-in Occurs whenconverting objectsinto XML by usingJAXB.

No action.


Exception in re-parsingXML. Error message:[1%].

errorRole BW-Plug-in Occurs when re-parsing XML.

No action.


SAX Exception. Errormessage: [1%].

errorRole BW-Plug-in Occurs when parsingJava objects into XML.

No action.


IO Exception in parsingXML. Error message:[1%].

errorRole BW-Plug-in Occurs when parsingXML.

No action.

31




The Invalid Input value.Error message: [1%].

errorRole BW-Plug-in The value in theInput tab is invalid.

Check values inthe Input tab.


Facebook return null.Please check permission/connection.

errorRole BW-Plug-in Occurs whenFacebook returns nosearch result.

Check the searchpermission andthe networkconnection.


IO Expection. ErrorMessage: [1%].

errorRole BW-Plug-in Occurs whenconducting the FQLQuery activity.

No action.


FQL Expection. ErrorMessage: [1%].

errorRole BW-Plug-in Occurs whenconducting the FQLQuery activity.

No action.


Null Schema Nodefound!

errorRole BW-Plug-in Occurs when nullschema node isfound.

Check the schema.


Parse error message:[1%].

errorRole BW-Plug-in Occurs when parsingcolumns.

No action.


The RealTimeListenerstart failed, errormessage: [1%].

errorRole BW-Plug-in Occurs when startingthe Realtime listeneractivity.

No action.


The Jetty stop failed,error message: [1%].

errorRole BW-Plug-in Occurs when startingJetty.

Check networkconnection.


The Jetty start failed,error message: [1%].

errorRole BW-Plug-in Occurs whenstopping Jetty.

Check networkconnection.

32


Date post:	15-Mar-2020
Category:	Documents
Upload:	others
View:	22 times
Download:	0 times

TIBCO ActiveMatrix BusinessWorks Plug-in for …...Plug-In Overview TIBCO ActiveMatrix BusinessWorks...

Documents