Building Customer Portals Via Force.com

I recently started playing around with force.com sites a lot more than usual as a means to build a customer portal for a new business I am starting with a few friends. I thought this could be a good avenue since I could create a customer portal that easily integrated with our CRM instance. And since I understand the language and given the ease of Visualforce technology the turnaround time would be rather quick.

Here is the layout of the force.com template:

(showHeader should be turned off so you won't see any Salesforce standard tabs or sidebar)
<apex:page showHeader="false" id="SiteTemplate" standardStylesheets="true">
(A section is reserved for header of the site)
<apex:insert name="header">
<c:SiteHeader />
<hr/>
</apex:insert>
(This section is where you can include the content of each page of your site)
<apex:insert name="body"/>
(A section is reserved for footer of the site)
<apex:insert name="footer">
<hr/>
<c:SiteFooter />
</apex:insert>
</apex:page>

The developers that I spoke to in my network recommended that follow the same pattern when developing my portal.

Things that should be included in the 'SiteHeader' component is the logo, log in and out links, headlines, and site navigation menu (This is done with code snippets...either extracted or some cases newly written). The same way, you can modify the 'SiteFooter' component to add your site's pages footer template. It is also recommend to include your site's shortcuts links and your company copy right message in this section.

Adding the shortcuts links  in the 'SiteFooter' section is very important...particularly if you want to utilize organic search. If you are using dynamic menus this will easily compensate for that.

Next post will demonstrate how to add new pages to the force.com site.

Logging into the Salesforce Sandbox

As I continue to learn Ruby I thought it would be prudent for me to start working on a RoR app. That being since yet to be classified as an expert in this type of development...it is definitely best to work on this app in the Salesforce sandbox. The sandbox allows you to create copies of your environments for development, testing and training, without compromising the data and apps in your production environment. In this post we will go over the multitude of problems people face in order to access the sandbox to test and develop the application.

To start you need to be aware that you won't be able to login from https://login.salesforce.com that's only for production. The correct move is to use the sandbox instance https://test.salesforce.com (or https://cs1.salesforce.com, https://cs2.salesforce.com, etc.). It should be clear that email@domain.com is your regular username, but the "sandbox" part is the actual name of your sandbox. So if you named your sandbox as "sandbox" you would login as joey@example.com.sandbox. If your user account was established after the sandbox was created then it won't be present. A simple sandbox refresh will add your account into the sandbox. This is a pretty common error.

If for some reason that does not work you may be trying to access the incorrect sandbox. Go to the production organization where you can login. Navigate to 'Setup', then 'Data Management', then 'Sandbox' and then click the 'Login' button next to the sandbox you wish you login to.

Another common problem users face is the situation when you are able to use your production password to log into the sandbox...but cannot use it to hook up to the API. As a standard Salesforce trusts users that come through the web UI. However in order to log in to the API, you will need to append an extra bit of user information to your password aka your Security Token.

You can reset this by going to 'Setup', then 'My Personal Information', then finally 'Reset MY Security Token'.

The token will get emailed to you - it will be some obscure alpha-numeric token. Copy this and paste it to the end of your password. For example if your password was 'awesome', and the token was XYZ987xyz, the credentials to pass through would be:

Login: email@domain.com.sandbox

Password: awesomeXYZ987xyz

Now go ahead and make as many mistakes as you like...I do it all the time.

Ruby and Salesforce Integration (Part 2)

Before we begin I have to bring up the fact that the Steelers did beat the Jets. I'm not on the same level of Nostradamus yet...but I'm getting close. When we left off at our last post we created four new Ruby files in our Salesforce directory. And as I previously mentioned we will be using code from Andrew (Super-Size) Interwebdiary to generate an easy login in function.

The following is the code for the extra file we will be using for the simple login:

client_auth_header_handler.rb

 1 require 'soap/header/simplehandler'

 2

 3 class ClientAuthHeaderHandler < SOAP::Header::SimpleHandler

 4   SessionHeader = XSD::QName.new("rn:enterprise.soap.sforce.com", "SessionHeader")

 5

 6   attr_accessor :sessionid

 7   def initialize

 8     super(SessionHeader)

 9     @sessionid = nil

10   end

11

12   def on_simple_outbound

13     if @sessionid

14       {"sessionId" => @sessionid}

15     end

16   end

17

18   def on_simple_inbound(my_header, mustunderstand)

19     @sessionid = my_header["sessionid"]

20   end

21 end

22

For the final portion of code used in the login you will need to change the username, password, and security token to fit your specifications (changes needed are highlighted in red). This code will fetch records from the Account object and post raw output on the screen.

test.rb

 1 require 'rubygems'

 2 gem 'soap4r'

 3 require 'soap/soap'

 4 require 'defaultDriver'

 5 require 'client_auth_header_handler'

 6 require 'soap/wsdlDriver'

 7

 8

 9 d = Soap.new

10 d.wiredump_dev = STDOUT

11

12 h = ClientAuthHeaderHandler.new         

# Create a new handler

13

14 l = d.login(:username => "USERNAME", :password => "PASSWORD" + "SECURITY_TOKEN")

15

16 d.endpoint_url = l.result.serverUrl       

# Change the endpoint to what login tells us it should be

17 h.sessionid = l.result.sessionId            

# Tell the header handler what the session id is

18 d.headerhandler << h                         

# Add the header handler to the Array of headerhandlers

19

20 d.getUserInfo("")  

21 d.query(:queryString=> "select id,name from account")

defaultDriver and client_auth_header_handler (the code from above) are assumed to be in the current directory.

As always you are going to want to test the code. Do this by going to the Ruby console, then the 'sfdc' folder and input the following command:

ruby test.rb

If you run into errors you are going to have look at more API calls in the API docs....which kind of drives me crazy. But sometimes that what it takes when learning new languages.

Next post we will start exploring Ruby and RoR.

Ruby and Salesforce Integration

With the announcement that Salesforce acquired the cloud platform Heroku I had to take a more vested interest in Ruby. Though I was aware of the capabilities of Ruby I would definitely consider myself a newbie with this type of programming. In order to jump on the bandwagon I started an extensive Ruby programming class which will allow me to build my skill set over the next couple of months.

That being said learning Ruby is great and all but the key is using it within the Salesforce platform. The next couple of posts will describe how we will use SOAP to integrate Ruby and Salesforce.

-First you need to install Ruby.  InstantRails 2.0 is radical.

-Access your developer account. Go to Setup->Develop->API then choose "enterprise.wsdl" and save it. Here is an example:

D:\RubyRails\rails_apps\sfdc\enterprise.xml

-Open the Ruby console and then install ‘SOAP4R’ by using this command:

gem install soap4r

You may get an error after running this command that reads "Errno::EADDRNOTAVAIL". This will happen if your Ruby gems are outdated. This is a simple problem to fix by going to the following site:

http://rubygems.org/pages/download  

-After downloading the gems send them to a directory. You can then access that directory from the command line.

-Install the gems with the following command:

ruby setup.rb

At this point everything should be properly installed and you should not run into any errors. Go to the directory where you saved the ‘enterprise.xml’ and use the following command:

ruby wsdl2ruby.rb --wsdl D:\RubyRails\rails_apps\sfdc\enterprise.xml --type client –force

If everything goes well there should be four new files in your Salesforce directory. First step is complete! Next post we will use a code generated from Andrew’s (Super-size) Interwebdiary to generate an easy login function.

Till then fingers crossed the Jets get smashed by the Steelers this weekend.

Visualforce Controllers

The holidays are officially over and now that I have had a few days to recuperate it’s time to get back to work. The application we have been creating is pretty much ready to go… Go back to the Scheduled Invoices tab, and create a new invoice with an effective date two months in the past. Set the Duration to six months; fill out the remaining fields, and click "Save." Mark one of your pending payments as paid and you should now see three lists of payments: Past Due, Pending, and Paid. Granted this application is quite simple…but it was completed in a fraction of time and cost it would take for a traditional application.

So now that the first series of posts have been completed I wanted to jump into Visualforce Controllers. If you remember from previous entries a major component of how our application was rendered was through the use of Visualforce pages. Well a Controller is just Apex Code that analyzes and writes data in the force.com database. Also I need to make sure my blog is longer than a paragraph.

When working with Salesforce it is often required that you will need to display data from the force.com database or even insert data in database variables. Controllers can do these sorts of tasks much more quickly. There are two methods of the Controller that interact with the database variables. The ‘Getter’ method takes the value of the variables and displays it on the Visualforce page. The “Setter” method allows the developer to change the value of the variable using different Visualforce components. These methods operate similarly to the Getter and Setter methods in Java and C++.

A nice thing about the force.com platform is that it provides Standard Controllers, which are basic default controller that have already been implemented.  Though somewhat limited in functionality, you can perform certain changes to the native interface like editing records. Also you can use Apex classes to customize the controller.

My preferred method to the aforementioned Controllers is to create a Custom Controller that is completely user defined. The following is an example of a basic Custom Controller:

Page Code:

<apex:page controller="MyController">
   <apex:form>
         Name: <apex:inputText value="{!name}"/>
        <apex: outputText value="{!mssg}"/>
        <apex:commandLink action="{!Display}" value="Show Message" />
   </apex:form>
</apex:page>

MyController Code:

public class MyController{

      public String name {get ; set;}
      public String mssg {get ; set;}
      public PageReference Display() {
           mssg=’Time To Be Awesome’ + name;
           return null;
      }
}

Awesome!

Workflow Actions

Let me apologize now for the extended duration between this post and my last, Dreamforce took over my life the last two weeks. That being said it was great to meet all my clients face-to-face and I even signed on to do a few non-profit projects in my free time. I correlate this success to finally having some nice K2 Partnering business cards.

Our last course of action for the object is to add Workflow Actions, which is a fairly simple process. Click ‘Add Workflow Action’ and select ‘New Field Update’. We want to make the name ‘Mark Payment Past Due’ and change the field from update to ‘Status’. Finally we need to change the Picklist Options to ‘Past Due’ and hit ‘Save’.

There is one last important thing we need to cover before we can finally say we are done. An immediate action needs to take place that marks a payment as past due if an employee creates an invoice with the effective date in the past. Begin by again clicking ‘Add Workflow Action’ and then ‘Select Existing Action’. Finally change the choose action type drop-down to ‘Field Update’; then go to the Selected Actions list an add the ‘Mark Payment Past Due’ action. Click ‘Save’ and then ‘Done’.  

Finally it is very important that you click the ‘Activate’ link next to the newly created workflow rule, or it will remain dormant and all this work would have gone to waste. Pat yourself on the back…the application is complete. This is just like winning a gold medal at the Olympics.

We will wrap everything up in the next post.

Workflow Rules

When we left off last week our next step was to add functionality to the object that would automatically mark overdue payments. This is done by using the SFDC workflow engine, and more specifically workflow rules. Workflow rules allow the end user to initiate actions based on new records entered, field updates, or even the passage of time. When one of these rules is triggered it can create tasks on Salesforce and assign them to the end user or automatically update field values, send email alerts, and send outbound XML messages.

For our particular object we are going to create a workflow rule that will mark a payment as past due once it has exceeded its due date and has a status of pending. An important thing to remember if you are using a new system is that you will have to set-up a default workflow user. You can set yourself up as the default workflow user by going to

‘Set-Up’, then ‘Customize’, then ‘Workflows & Approvals’, and finally ‘Settings’. Utilize the lookup button next to the ‘Default Workflow User’ field and set yourself up and click ‘Save’.

Once the user is established go to ‘Workflow Rules’ under the ‘Workflows & Approvals’ tab and click ‘New Rule’. Select our Scheduled Payment object and hit ‘Next’. Make the rule name “Schedule Payment – Process Past Due”. Leave the evaluation criteria as the default but add the following new ‘Rules Criteria’:

-         Scheduled Payment: Status Equals Pending

-         Scheduled Payment: Due Date less than TODAY

Click ‘Save’ and hit ‘Next’. Following all of this the workflow actions screen should appear. Basically this screen allows you to set up an action, most likely a field update, to our particular trigger. Initiate this by clicking ‘Add time trigger’, set the time to zero hours after Scheduled Payment: Due Date and click ‘Save’. The following is an example of what the screen should look like:

We will add Workflow Actions in the next post. Until then everyone should go run off all the food you ate this weekend…or at least try. I need to lose the 10 pounds I gained on Thanksgiving.