This document extends the Administration Guide by providing information on how to configure and maintain your organization's social vendor configurations so that BITeamwork may integrate with your organization's existing Social Vendor system(s).

The social vendors with which BITeamwork integrates all require something referred to as an "Application" to be established through that social vendor's portal. An "Application" is analogous to a "module" or an "interface" with which third-party applications such as BITeamwork may connect to your organization's social vendor implementation. You are allowed to create one or more "Applications" and in most cases able to restrict access to social vendor information at a granular level.

Setting up the social vendor configuration all the way through to testing the connectivity with BITeamwork breaks down to a few straightforward steps:

  1. 1.) Creating an Application

    This step is all about going into your Social Vendor portal and creating a new Social Vendor "Application".
    Click your respective social vendor below for specific instructions:

  2. 2.) Connect BITeamwork to the Application

    This step is all about taking the information from your new Social Vendor "Application" and plugging the information into BITeamwork's control panel.
    Click your respective social vendor below for specific instructions:

  3. 3.) Testing the Application with BITeamwork as a User

    After you've successfully downloaded and installed BITeamwork, created your respective social vendor "Application", and update the BITeamwork control panel, you may now test connectivity.
    Click your respective social vendor below for specific instructions:

Salesforce.com has the ability to allow access for third-party applications such as BITeamwork to seamlessly communicate with your organization's Salesforce.com and Chatter instances. All of the security remains on Salesforce.com and so does the access control. This section walks you through the steps that your Salesforce.com Administrator would conduct in order to prepare the information you will then use to configure BITeamwork in order to communicate with Salesforce Chatter.

  1. Access your Salesforce.com instance using an account with Administrator access
  2. Using the main navigation, select Setup from the dropdown menu.

    Figure sfdc_app_config_1
  3. On the left navigation panel, expand Create and select Apps.

    Figure sfdc_app_config_2
  4. On the Apps page click the New button in the Connected Apps section.

    Figure sfdc_app_config_3
  5. Complete the Basic Information section form fields that are required.
    1. Connected App Name is the alias name shown to users as they connect from BITeamwork
    2. API Name is the name used permanently to differentiate connected apps
    3. Contact Email is the user who will receive questions regarding the connected app from users, if any

    Figure sfdc_app_config_4
  6. Click the Enable OAuth Settings checkbox in the OAuth Settings section.

    This expands a new form which you will complete following the steps below. OAuth is the security protocol used by almost every large communication tool on the internet today such as Facebook, Chatter, Twitter, etc. Read more about how OAuth works and communicates with BITeamwork.


    Figure sfdc_app_config_5
  7. Complete the OAuth Settings form required fields as follows:
    1. Callback URL is the location on the Oracle BI server where BITeamwork has been installed. This is specific to your Oracle BI implementation.

      For example: http[s]://<bi_server>:9704/bitw/x/social/chatter/callback

    2. Selected OAuth Scopes are the security privileges granted through this app to any third-party application (i.e. BITeamwork) accessing your Salesforce.com instance.

      Three OAuth Scopes are required:

      1. api
      2. id
      3. refresh_token


    Figure sfdc_app_config_6

    Testing vs. Production

    Salesforce.com OAuth protocol requires the callback URL to have a SSL certificate for production implementations. However, when conducting initial tests you may use a non-SSL enabled server name for the callback URL. However, this must be the localhost URL, ex: http://localhost:9704/bitw/x/social/chatter/callback
  8. Click the Save button to save your new connected app.
  9. Review the newly created Connected App

    This area is where you can review the connected app and also collect metadata regarding the connected app that you will then use in the BITeamwork Control Panel.


    Figure sfdc_app_config_7
  10. Retrieve and document the following metadata under the OAuth Settings section. Provide these following details to the Oracle BI Administrator that will configure BITeamwork:
    1. Consumer Key is part 1 of 2 credentials needed for reference in order to access this connected app via a third-party application.
    2. Consumer Secret is part 2 of 2 credentials needed for reference in order to access this connected app via a third-party application. You must click the Click to reveal link in order to capture this text string value.
    3. Callback URL is required by BITeamwork in order to redirect from Salesforce.com to the BI portal once a user has approved connectivity via the connected app.

    Figure sfdc_app_config_8
  11. Done.

Yammer has the ability to allow access for third-party applications such as BITeamwork to seamlessly communicate with your organization's Yammer instances. All of the security remains on Yammer.com and so does the access control. This section walks you through the steps that your Yammer Administrator would conduct in order to prepare the information you will then use to configure BITeamwork in order to communicate with Yammer.

  1. Access your Yammer.com instance using an account with Administrator access
    • This could be Yammer.com or your branded Yammer URL
  2. Using the main navigation on the home page, select Setup from the "..." (more) button dropdown menu.

    Figure yammer_app_config_1
  3. Select the Created Apps option.
  4. On the left navigation panel, select Register New App

    Figure yammer_app_config_2
  5. The Register New App dialog window will appear. Enter some basic information about the app on the form fields. Check the checkbox to agree to the terms. Then click the Continue button.

    Figure yammer_app_config_3
  6. You'll be presented with a page to complete the App Directory Configuration. Most of the information you provide here is arbitrary but provide a bit of details about the purposes of this app which is to connect with BITeamwork in your BI System.
    All fields marked with an asterisk are required fields. You cannot create the app without completing those fields.

    Figure yammer_app_config_4
  7. Complete the App Directory Configuration form page. Be sure to add images as it suggests and requires. Click the Save and Deploy button at the bottom of the form page to save the configuration.
    OAuth is the security protocol used by almost every large communication tool on the internet today such as Facebook, Chatter, Twitter, etc. Read more about how OAuth works and communicates with BITeamwork.
  8. Review your configuration to ensure that all configuration information has been successfully input. Note, below is an example screenshot of a Yammer app configuration after being successfully deployed and your application's results will look slightly different.

    Figure yammer_app_config_5

    Testing vs. Production

    Yammer OAuth protocol does NOT require the Expected Redirect (i.e.: callback) URL to have a SSL certificate for production implementations. However, when conducting initial tests you may use a non-SSL enabled server name for the callback URL. This can be any URL but for testing we suggest using the localhost URL, ex: http://localhost:9704/bitw/x/social/yammer/callback
  9. Review the newly created Connected App by clicking on "Basic Info" under the app name from the left panel's My Apps Menu.

    This area is where you can review the connected app and also collect metadata regarding the connected app that you will then use in the BITeamwork Control Panel.

  10. Retrieve and document the following metadata under the OAuth Settings section. Provide these following details to the Oracle BI Administrator that will configure BITeamwork:
    1. Client Key is part 1 of 2 credentials needed for reference in order to access this connected app via a third-party (i.e. BITeamwork) application.
    2. Client Secret is part 2 of 2 credentials needed for reference in order to access this connected app via a third-party application.
    3. Expected Redirect is required by BITeamwork in order to redirect from Yammer to the BI portal once a user has approved connectivity via the connected app.

    Figure yammer_app_config_8
  11. Done.

By default the WebLogic Application Server does not enable wildcard SSL handshakes. As such, the WebLogic Server administrator must configure the server to enable this required configuration for communicating with social vendors.

Please read about this in the Troubleshooting Guide.

BITeamwork must be able to communicate from the application tier servers on which it is installed to the social vendor web portals and end points. Most proxy servers and firewalls leveraged by your company take a deny/allow approach. This means they deny or restrict all access to all TCP/HTTP communications not within the internal network and then allow few exceptions to have access outside of the internal network. These exceptions to outside communication are usually entered by the network administrators via IP address on the firewall/proxy server(s). Access to the Social Vendor's (e.g: Salesforce.com) servers residing outside of your organization's firewall is a pre-requisite for BITeamwork. If you install and attempt to integrate one of the allowed Social Vendor configurations and you receive a network error or a "Cannot connect to remote server" error then there is a very high chance that communication is being blocked by your firewall.

The information below shows the Whitelist IP addresses required per Social Vendor and links to supporting information per each vendor's website.

Salesforce Chatter

                    204.14.232.0/23 (East Coast Data Center set one)
                    204.14.237.0/24 (East Coast Data Center set two)
                    96.43.144.0/22 (Midwest Data Centers)
                    96.43.148.0/22 (Midwest Data Centers)
                    204.14.234.0/23 (West Coast Data Center set one)
                    204.14.238.0/23 (West Coast Data Center set two)
                    182.50.76.0/22 (Japan Data Center)
                            
A quick attempt at whitelisting Salesforce Chatter would be:
                    204.14.232.0/21
                    96.43.144.0/20
                            

Here are official Saleforce.com links to the whitelist APIs:

  • https://help.salesforce.com/apex/HTViewSolution?language=en_US&id=000003652
  • https://help.salesforce.com/HTViewHelpDoc?id=setup_domains.htm&language=en_US
  • https://help.salesforce.com/HTViewHelpDoc?id=remoteaccess_define.htm&language=en_US
  • http://www.salesforce.com/us/developer/docs/api/Content/sforce_api_om_outboundmessaging_security.htm

Yammer

                    *.yammer.com or 204.152.18.0/23
                    *.cloudfront.net
                    *.amazonaws.com
                    *.cotssl.net
                    *.edgekey.net
                            

Here are official Yammer.com links to the whitelist APIs:

  • https://developer.yammer.com/connect/yamm
  • https://www.yammer.com/pdfs/Yammer_Embed_Install_Guide.pdf

In a very rare case, some functionality may leverage special Salesforce.com API features requiring the need to download the Salesforce Client Certificate and installing it on the application server in order to complete transmissions. This is not the case with standard BITeamwork functionality but may be needed for BITeamwork extensions which are offered on a per customer basis. If this is needed, please follow the instructions found here, Setting Up Outbound Messaging