Extension:Salesforce

From MediaWiki.org
Jump to navigation Jump to search
MediaWiki extensions manual
OOjs UI icon alert-invert.svg
Salesforce Extension
Release status: unstable
Implementation Tag
Description Integration with Salesforce.com API. Adds tags for describing objects and querying records.
Author(s) Eric Santiago (santiertalk)
Latest version 0.1.0 (2007-11-07)
MediaWiki 1.10.0+
License GPL
Download salesforce.zip
Translate the Salesforce extension if it is available at translatewiki.net
Check usage and version matrix.

This extension Configures MediaWiki to allow users the ability to access Saleforce.com. Very useful for admins looking to document customizations or for anyone looking to make Salesforce data available though a public interface. Recommended for Intranet usage; see Extension:LDAP Authentication for a way to limit users via LDAP/Active Directory.

Describe[edit]

Using simple markup tags, users can list all the fields available in a specified standard or custom object. Useful for administrators wanting to quickly build documentation for Saleforce users creating reports.

Query[edit]

Enable wiki users to query records in Salesforce by entering their own SOQL syntax query statement. Query function handles multiple custom and standard objects.

Download instructions[edit]

Download salesforce.zip (42.2 kb)

Installation[edit]

Installing the Extension[edit]

Download the installer file to the Extensions directory of your MediaWiki installation. Uncompress the file using Winzip or a similar application using the exisiting file structure. This should extract the following files;

  • extensions\Salesforce
    • extensions\Salesforce\index.php
    • extensions\Salesforce\soapclient
      • extensions\Salesforce\soapclient\enterprise.wsdl.xml
      • extensions\Salesforce\soapclient\partner.wsdl.xml
      • extensions\Salesforce\soapclient\SforceBaseClient.php
      • extensions\Salesforce\soapclient\SforceEnterpriseClient.php
      • extensions\Salesforce\soapclient\SforceHeaderOptions.php
      • extensions\Salesforce\soapclient\SforcePartnerClient.php

This extension makes use of version 1.1 of Salesforce's PHP Toolkit. The installation file already includes the required files so the tool kit does not need to be installed separately.

Required PHP Extensions[edit]

In order to use the HTTPS protocol you need to enable some of the PHP extensions. Open PHP.ini for editing. Search for "extension=php_curl.dll". There should be a semi-colon in front of that line - remove it to enable the extension. Scroll down and find "extension=php_openssl.dll" and do the same. Now scroll down a bit further and find "extension=php_sockets.dll". Leave this line alone, but insert a new line below it and type "extension=php_soap.dll" on that line. For some reason, this entry doesn't appear in the default configuration. Save the file and exit.

SSL Library Files[edit]

Windows Users: Copy the SSL library files from the PHP installation directory to your Windows system directory. The two files are libeay32.dll and ssleay32.dll. They need to be copied into the system directory, usually c:\windows\system32 on an XP system. If you happen to have OpenSSL already installed on your computer you may find that these files are already installed. If they are, you should only replace them if the ones from the PHP directory are more recent. Change the extensions on the existing ones by adding '.bak' just to be safe.

Modify LocalSettings.php[edit]

To install this extension, add the following to LocalSettings.php :

#Salesforce extension configuration parameters
$wgSFDC_user = "username@salesforce.com";
$wgSFDC_pword = "password"; 
$wgSFDC_allow_qry = false; 
$wgSFDC_allow_desc = false; 
$wgSFDC_qry_max_rows = 10; 
require_once('extensions/Salesforce/index.php');

Configuration parameters[edit]

  • $wgSFDC_user = "username@salesforce.com"; //Salesforce user id
  • $wgSFDC_pword = "password"; //Salesforce password
  • $wgSFDC_allow_qry = false; //allow users to define queries, default is false
  • $wgSFDC_allow_desc = false; //allow users to describe objects, default is false
  • $wgSFDC_qry_max_rows = 10; //for query - sets max number of records returns, overrides LIMIT in query statement

Security Concerns[edit]

Recommended Salesforce User Permission[edit]

Unlike regular SQL statements that allow for deleting and modifying record (ie SQL injection attacks), SOQL is limited to Select statements and retrieving records only. In any case, it is highly suggested that the Salesforce user specified in LocalSettings.php have a role of Read Only. Moreover, setting up a custom role and defining access to specific fields and objects can fine tune access and effectively restrict what information the wiki user can query.

Restricting Anonymous Access[edit]

Allowing anonymous users to query your Salesforce data makes all your Salesforce data available to the world. Protecting a page as described in Manual:Preventing_access#Restrict_editing_of_certain_specific_pages disables the edit tab for all users other than those in the Sysops group. However, since it does not disable the View Source tab, users can still view your query syntax.

This extension is best used in scenarios where user access is restricted to trusted individuals. To use MediaWiki as an intranet, see Extension:LDAP Authentication for a way to limit users via LDAP/Active Directory. The following modifications can be added to LocalSettings.php to restrict access to only LDAP/Active Directory users.

## restrict edit to logged in users
$wgGroupPermissions['*']['edit'] = false; 
$wgGroupPermissions['user']['edit'] = true;

# This snippet prevents new registrations from anonymous users
# (Sysops can still create user accounts)
$wgGroupPermissions['*']['createaccount'] = false;

# Pages anonymous (not-logged-in) users may see
$wgWhitelistRead = array( "Main Page", "Special:Userlogin", "-", "MediaWiki:Monobook.css" );
$wgGroupPermissions['*']['read'] = false;

## example of authenticating off of Active Directory for domain "example.org"
## requires SSL and Extension:LDAP Authentication
require_once( 'LdapAuthentication.php' );
$wgAuth = new LdapAuthenticationPlugin();
$wgLDAPDomainNames = array( "example" );
$wgLDAPServerNames = array( "example"=>"dc01.example.org"  );
$wgLDAPSearchStrings = array( "example"=>"example\\USER-NAME"  ); 
$wgLDAPEncryptionType = array( "example"=>"ssl" );
#$wgLDAPUseSSL = true;
$wgLDAPUseSSL = array( "example"=>"true" );
$wgLDAPEncryptionType = array( "example"=>"ssl" );
$wgLDAPUseLocal = false;
$wgLDAPAddLDAPUsers = false;
$wgLDAPUpdateLDAP = false;
$wgLDAPMailPassword = false;
#$wgLDAPRetrievePrefs = true;
$wgLDAPRetrievePrefs = array( "example"=>"true" );
$wgMinimalPasswordLength = 1;
$wgLDAPDebug = 1;

$wgLDAPSearchAttributes = array(
  "example"=>"sAMAccountName"
  );
$wgLDAPBaseDNs = array(#
  "example"=>"dc=example,dc=org"
  );

The above is only an example and may not necessarily work in your environment. See Extension:LDAP Authentication for troubleshooting tips and more information.

Usage[edit]

This tag extension uses a simple markup language in the following format.

<salesforce action="{action}" [query="{SOQL query}"]>{input}</salesforce>

Allowable actions are query and describe.

Describe[edit]

Lists the names, api labels, and descriptive info of fields for a given standard or custom object.

Features[edit]

Any objects referenced in relationship fields are displayed an internal link. For documentation, you can create pages describing all custom and standard objects.


Picklist and multipicklist values are listed.

Syntax:[edit]

<salesforce action="describe">[sfdc_object]</salesforce>


Example[edit]

Describing a standard object.

<salesforce action="describe">account</salesforce>


Describing a custom object (Job Posting). Note the "__c" suffix.

<salesforce action="describe">job_posting__c</salesforce>


Query[edit]

Using this extension, users can retrieve records from Salesforce by entering a query in Salesforce Object Query Language (SOQL) syntax. For more details on SOQL and writing proper SELECT statements see http://www.salesforce.com/us/developer/docs/api/Content/sforce_api_calls_soql_select.htm .

Syntax[edit]

<salesforce action="query" query="{SOQL select statement}">Column name1[,Column name2,...]</salesforce>

Examples[edit]

Querying a single standard object.

<salesforce action="query" query="SELECT Id,FirstName,LastName from Contact WHERE LastName Like 'A%' LIMIT 20">ID,First,Last</salesforce>

Querying two standard objects (Contact and Account) using a reference field (Account.Name).

<salesforce action="query" query="SELECT Id,FirstName,LastName,Account.Name from Contact WHERE LastName Like 'A%' LIMIT 20">ID,First,Last,Employer</salesforce>

Querying two standard objects (Contact and Account) using dotted notation.

<salesforce action="query" query="SELECT c.Id,c.FirstName,c.LastName,a.Name from Contact c, c.Account a WHERE LastName Like 'A%' LIMIT 20">ID,First,Last,Account</salesforce>

Querying a custom and standard object (Job Posting and Account) using dotted notation. In this example, the Job Posting custom object has a field called Employer which reference the Account object.

<salesforce action="query" query="SELECT id,Job_Posting__c.Employer__r.Name, Title__c, Publish_Start__c, Location__c, Function__cd from Job_Posting__c Where Status__c = 'Published' LIMIT 20 Order By Publish_Start__c">Account, Title, City, </salesforce>

Querying a custom object and two standard objects (Application, Contact, and Account) using dotted notation. In this example, the Application custom object has a fields called Contact and Account which reference the Contact and Account objects respectively.

<salesforce action="query" query="Select a.id,a.Name,Contact__r.Name,a.Account__r.Name From Application__c a">name</salesforce>

Select Statement Syntax[edit]

The SOQL SELECT command uses the following syntax:

SELECT fieldList FROM objectType [WHERE The Condition Expression (WHERE Clause)] [ORDER BY] LIMIT ?

For more details on SOQL and writing proper SELECT statements see http://www.salesforce.com/us/developer/docs/api/Content/sforce_api_calls_soql_select.htm .

The $wgSFDC_qry_max_rows value specified by the administrator takes precedence over any LIMIT specified by the Wiki user. The lesser value of the two will be used.

Column Headings Syntax[edit]

Specify the header labels for the columns separated by commas. Column headers are printed in the order they are specified exactly as written. Column values are displayed in the order they appear in the query string.(With some exceptions. See note below)

For example, <salesforce action="query" query="Select id,firstname,lastname,account.name from contact where lastname like 'a%'">Id,First,Last,employer</salesforce> will output;

IdFirstLastemployer
0000000000L9M4qAAFMayraA.Random Hall
0000000000L9NR6AANEmmanuelATome Warner
0000000000L9OhuAAFAbenaAGeneral Malls
0000000000L9PIeAANKathleenACitycorp
0000000000P5nPdAAJAliceAanstoosySBCDF
0000000000L8Z4cAAFKarenAaronWalls Fargo
0000000000MybtqAABJohnAbadHarvid University
0000000000KAwe6AADJosephAbadiTest
0000000000L9P5qAAFJasmineAbairUBS
0000000000O24leAABAbdourazakheAbaniDisnay
200 record(s) returned. (10 max)

Changing the order of the columns specified does not affect the order of the values outputted, only the headers.

<salesforce action="query" query="Select id,firstname,lastname,account.name from contact where lastname like 'a%'">Account,Last,First,Id</salesforce>

AccountLastFirstID
0000000000L9M4qAAFMayraA.Random Hall
0000000000L9NR6AANEmmanuelATome Warner
0000000000L9OhuAAFAbenaAGeneral Malls
0000000000L9PIeAANKathleenACitycorp
0000000000P5nPdAAJAliceAanstoosySBCDF
0000000000L8Z4cAAFKarenAaronWalls Fargo
0000000000MybtqAABJohnAbadHarvid University
0000000000KAwe6AADJosephAbadiTest
0000000000L9P5qAAFJasmineAbairUBS
0000000000O24leAABAbdourazakheAbaniDisnay
200 record(s) returned. (10 max)

To change the order of the values, change the order those fields appear in the Select statement. For example; <salesforce action="query" query="Select id,account.name,firstname,lastname from contact where lastname like 'a%'">ID,Account,First,Last</salesforce>

NOTE:

  • The ID field will always appear in the first column. This is a limitation in the way the Salesforce API Describe call handles the ID field. It may be corrected in later versions.
  • Fields for the base object will always be outputted prior to fields of referenced objects regardless of the order in which they appear in the Select statement. So that <salesforce action="query" query="Select id,account.name,firstname,lastname from contact where lastname like 'a%'">ID,Account,First Name,Last Name</salesforce> will display as


IDAccountFirst NameLast Name
0000000000L9M4qAAFMayraAbernathyRandom Hall
200 record(s) returned. (10 max)


  • The number of column headers should match the number of fields specified in the select statement. Mismatches will result in tables with missing column headers.

<salesforce action="query" query="Select id,firstname,lastname,account.name from contact where lastname like 'a%'">ID,Account,First Name</salesforce> will display as


IDAccountFirst Name
0000000000L9M4qAAFMayraAbernathyRandom Hall
200 record(s) returned. (10 max)


To leave a column header blank use an empty string such as <salesforce action="query" query="Select id,firstname,lastname,account.name from contact where lastname like 'a%'">ID,,,Account</salesforce>

Please Note:

  • Column names cannot include commas
  • At least one column name is required.
  • Remember to use "__c" suffix when referencing custom objects and fields.

Troubleshooting[edit]

Since this is an early release of this extension, I would appreciate any and all assistance in testing. Please note your issues on the Discussion page. Be as specific as possible.

Please use a tool like the APEX toolkit for Eclipse or Salesforce's Apex Explorer to test and verify your SOQL statement before posting it as an issue.

Known issues[edit]

I'm currently working on addressing these items for the stable release

  • $wgSFDC_allow_qry and $wgSFDC_allow_desc do not restict access as expected.
  • Queries are not dynamic. Results are not updated when page is viewed only when edited.

To Do[edit]

  • Figure out a way to get values of referenced object to output in exactly the same order as specified in the select statement
  • Limit the maximum number of records at the time of the API call for faster processing.
  • Add method for Admins to define stored queries that don't show the wiki user the query syntax. This would be a way around some of the security concerns in environments where anonymous access is allowed.
  • Add child/parent information to the describe feature.
  • Add options for defining table colors.

See also[edit]