Wade Wegner

Build a Native Mobile App Using Salesforce DX and the Mobile SDK

Thu, 01 Feb 2018 00:00:00 +0000

This week I had the opportunity to demo how developers can combine project-based app development with Salesforce DX, the Salesforce CLI, Scratch Orgs, and the Mobile SDK to make – at least, in my humble opinion – a pretty compelling native app dev experience with Salesforce. In this post I’ll share some of the things I did with the hope that, after you look at it, you’ll want to try it out too.

Setup the CLI Plugin for the Mobile SDK

Did you know the Salesforce Mobile team created a CLI plugin? Oh yes they did!

To install it, run the following command:

$ sfdx plugins:install sfdx-mobilesdk-plugin

Now if you run sfdx mobilesdk --help you’ll see all the SDK commands are available.

In case you’re wondering, these commands are no different than the forceios, forcedriod, forcehybrid, and forcereact commands. This plugin is simply a wrapper to include all these commands in a single CLI. A big improvement, in my opinion.

Note: If you’re interested in learning details about the mobile SDK, I suggest you take a look at the Develop with Mobile SDK Trail. I’m not going to get into details about how it operates and how to set it up. These modules can do a much better job.

Setup Your Workspace

Lots of ways you can approach this. Here’s my recommendation:

myproject/
├── force
└── mobile

Yes, looks simple. Don’t worry, there will be more folders.

force will contain our Salesforce DX project and all the associated source and metadata. mobile will contain our mobile application and all the files generated by the Mobile SDK.

So, start off by creating myproject:

$ mkdir myproject && cd myproject

Now, you might as well initialize it as a git repo. Yes, that’s right – a single git repo for both your mobile app and your Salesforce project.

$ git init
$ git remote add origin <yourremote>

Next, let’s create the Salesforce DX project. The first time I tried this out, I did everything manually: created my project, then my scratch org, created the connected app, grabbed the data, and so forth. But if you know anything about me, I’m a lazy developer. Which means I hate to do the same thing more than once. Consequently, I created a script that not only setup my Salesforce DX project for me, but also outputs all the values I’m going to need to connect the mobile app to my Scratch Org for development.

To use the script below, grab my CLI plugin which allows you to create Connected Apps through the CLI: sfdx plugins:install sfdx-waw-plugin

Here’s a script you can use. Create a file like setup.sh (and make it executable chmod +x setup.sh) and add the following to it:

# set the callback URL
callbackUrl="sfdx://success"

# create force project
project="$(sfdx force:project:create -n force)";

# open folder
cd force

# create a scratch org
org="$(sfdx force:org:create -s -f config/project-scratch-def.json)";

# Create a connected app
connectedApp="$(sfdx waw:connectedapp:create -c $callbackUrl -e wade.wegner@gmail.com -n mobile -l mobile -d mobile -s Api,Web,RefreshToken)";
consumerKey="$(echo ${connectedApp} | jq -r .oauthConfig.consumerKey)"

echo "Consumer Key: " $consumerKey

# generate a password
password="$(sfdx force:user:password:generate)"

# get values
display="$(sfdx force:org:display --json)"
result="$(echo ${display} | jq -r .result)"
password="$(echo ${result} | jq -r .password)"
username="$(echo ${result} | jq -r .username)"
instanceUrl="$(echo ${result} | jq -r .instanceUrl)"

# echo values
echo "Username: " $username
echo "Password: " $password
echo "Instance URL: " $instanceUrl
echo "Callback URL: " $callbackUrl

# return to root
cd ..

Then, run it:

$ ./setup.sh

Boom! Neat, right? You’re output should be something like …

$ ./setup.sh
Consumer Key: <snip>
Callback URL: sfdx://success
Username:     test-ppvviujleloj@demo_company.net
Password:     **********
Instance URL: https://mello-yellow-999-dev-ed.cs90.my.salesforce.com

… which contains everything you need to connect with your mobile app.

Speaking of which, let’s create that mobile app.

Create Your Mobile App with the Mobile SDK

This step is pretty easy thanks to all the hard work done by the Salesforce Mobile SDK team. Make sure you’re in the myproject folder and run the following CLI command:

$ sfdx mobilesdk:reactnative:create
    --platform ios
    --appname demo1
    --packagename com.wadewegner.demo1
    --organization WadeWegner.com
    --outputdir mobile

Of course, you likely want to change some of those values. But you get the idea.

That will create everything you need to build and run the native mobile applications. Additionally, the SDK includes a bunch of useful stuff to get you going fast (e.g. some simple pages, wiring up auth, etc).

Okay, now let’s wire it together!

Update the Mobile App to Use Your Scratch Org

Remember the info we echo’d to the console above? It’s time to use it!

Open up Xcode (of course, if you targeted a different platform, use the right tool). You’ll want to open the Xcode workspace (not the project) in Xcode. You’ll find it at myproject/mobile/ios/demo1.xcworkspace.

Open the AppDelegate.m file and update the RemoteAccessConsumerKey to use the Consumer Key from above and OAuthRedirectURI to use the Callback URL from above. (Why we use different names for all these things I’ll never know.)

That’s it for the code! Now, run the app.

Before we launch the mobile app in Xcode, and if you created a React Native app like I did above, be sure to run npm start in the myproject/mobile folder. This ensures you have all the React “stuff” running for your app.

Okay – now you can run the app in Xcode.

Log Into the Mobile App

Let’s go ahead and log into the mobile app and see it in action!

On the login screen, click “Use Custom Domain”.
Paste in the Instance URL we echo’d above (be sure you don’t copy in the https:// as it won’t remove it.)
Then type (or copy) the username and password.
Click the Allow button to use the Connected App for API access.

And presto, your mobile app is working against your scratch org!

Pretty neat!

Conclusion

I hope this has demonstrated that Salesforce DX, and all the tools that comes with it, is a compelling way to combine Salesforce with native mobile apps built using the Mobile SDK. I think it’s good, but I think we can do even better! I’m hoping to get the CLI plugin (and SDK) updated such that those values we echo’d from the script can be injected into the template (via the CLI command) such that it doesn’t require any code updates. Wouldn’t that be sweet?

I hope this helps, and let me know if you have additional ideas on improvement! You can find me on Twitter @WadeWegner.

Authenticate to your Scratch Orgs using the OAuth 2.0 JWT Bearer Flow

Wed, 31 Jan 2018 00:00:00 +0000

A different, if not more accurate or better, name for this blog post could be “Authenticate to a Scratch Org You Didn’t Create and Whose Password You Don’t Know.” I even went out to Twitter to ask for help and, well, Peter Churchill did not disappoint:

"I used JWT Bearer Flow with my Scratch Orgs and Dev Hub - you won't believe what happened next!"
— Peter Churchill (@britishboyindc) January 31, 2018

But, as you can see, I went the boring and conservative route. Naming things, even blog posts, is hard. Anyway …

One of my more popular blog posts recently is Using the OAuth 2.0 JWT Bearer Flow to Support the Salesforce DX CLI. Not only is JWT Bearer Flow a powerful capability for automating continuous integration (you’re not using usernames and passwords, are you?), but setting it up is rather complex and the blog post details the required steps as simply as possible. In this post, I want to build the capability of the JWT Bearer Flow and introduce a capability of the Dev Hub that makes it easier for you to authenticate to newly created Scratch Orgs, even when you’re not on the machine that initially created the scratch org.

Consider, if you will, the following: you have a script that automates these steps every morning:

Creates 50 new scratch orgs (possibly with different scratch org configuration settings).
Installs 3rd party packages that are used/required.
Pushes unpackaged source/metadata required (e.g. custom objects).
Assigns permsets.
Imports sample data.

This isn’t a fictional scenario, as there are a number of ISVs and customers already doing this today as a way to bootstrap environments. But, invariably, the next question is: how do I let a developer, or separate CI system, authenticate to the newly created scratch org?

Turns out, you can setup a Connected App in your Dev Hub to support the JWT OAuth flow that you can then use to authenticate to your scratch org. That’s right, you don’t have to create the Connected App in the scratch org itself (which is good, as you can’t automate it). Using the Connected App in the Dev Hub, you can use the same certificate key and force:auth:jwt:grant command to authenticate directly to a scratch org.

As I said, this is a powerful capability for CI systems that create scratch orgs and then need to auth into them but don’t have access to access token stored in ~/.sfdx during the scratch org creation process.

Without further ado, let’s go started.

Create the certificate & private key

The first step is to create the certificate and private key you’re going to use. I prefer to do this in a place that’s both secure and not related to any specific project I’m working on. This way I can make everything work independent of my current project.

$ cd ~/ && mkdir .certs && cd .certs

$ openssl genrsa -des3 -passout pass:x -out server.pass.key 2048

$ openssl rsa -passin pass:x -in server.pass.key -out server.key

$ rm server.pass.key

$ openssl req -new -key server.key -out server.csr

$ openssl x509 -req -sha256 -days 365 -in server.csr \
    -signkey server.key -out server.crt

When finished, you’ll have the files you need later in the process. And, while I have these files setup to use locally, it’s entirely likely you’ll want to put them on a server to make them more accessible. It’s also not uncommon to encrypt them and use them with systems like Travis CI (see our Continuous Integration Using Salesforce DX Trailhead module for details).

Create the Connected App

We’re going to use a Connected App in our Dev Hub org. This is part of the magic. By having this Connected App in our Dev Hub and setup with JWT Grant, we can use this flow with all of the Scratch Orgs we create.

To make things easier, I like to use my CLI plugin: sfdx-waw-plugin (feel free to contribute here: https://github.com/wadewegner/sfdx-waw-plugin). It includes commands for creating the Connected App (and minimizes the manual steps).

Install the sfdx-waw-plugin to and look at the command:

$ sfdx plugins:install sfdx-waw-plugin

$ sfdx waw:connectedapp:create --help

You’ll want to run this command against your Dev Hub; I’ve aliased mine as HubOrg (not sure why).

$ sfdx waw:connectedapp:create -c http://localhost:1717/OauthRedirect 
    -e [YOUR_EMAIL_ADDRESS] 
    -s Basic,Api,Web,RefreshToken 
    -n jwtrulz 
    -u HubOrg

When you run this command it will output information.

{
   "fullName":"jwtrulz",
   "contactEmail":"wade.wegner@salesforce.com",
   "description":"generated by waw:connectedapp:create",
   "label":"jwtrulz",
   "oauthConfig":{
      "callbackUrl":"http://localhost:1717/OauthRedirect",
      "consumerKey":"[YOUR_CONSUMER_KEY]",
      "scopes":[
         "Basic",
         "Api",
         "Web",
         "RefreshToken"
      ],
      "consumerSecret":"[YOUR_CONSUMER_SECRET]"
   }
}

Grab both the consumerKey and the consumerSecret.

Now we’re going to open our Dev Hub so that we can finish setting up the JWT Bearer Flow. (As I mentioned before, you can’t automate all of this through our APIs today.)

$ sfdx force:org:open -u HubOrg

We’re going to complete the setup of the Connected App. (Unfortunately, there aren’t any APIs exposed to assist you in this process).

Open App Manager, find your Connected App.
Click Edit. Turn on Use digital signatures and choose your server.crt.
Click Manage then Edit Policies. Update Permitted Users.
Click Manage Profiles or Managed Permission Sets and add your profile or permset.

If you need a refresher for any of these steps, see my blog post Using the OAuth 2.0 JWT Bearer Flow to Support the Salesforce DX CLI.

Log into your Dev Hub with `jwt:grant`

For this to work, you’ll want to log into your Dev Hub using force:auth:jwt:grant, not force:auth:web:login.

$ sfdx force:auth:jwt:grant --clientid [YOUR_CONSUMER_KEY] \
    --username [YOUR_DEVHUB_LOGIN] \
    --jwtkeyfile ~/.certs/server.key \
    --setdefaultdevhubusername -a HubOrg

You should see something like:

Successfully authorized YOUR_DEVHUB_LOGIN] with org ID [YOUR_ORG_ID].

It’s worth noting that this step is required. If you’re not logged into your Dev Hub using jwt:grant then the rest of the magic won’t work.

Create a new scratch org and login with `jwt:grant`

Okay, now it’s time for the payoff! Go ahead and create a new scratch org:

$ sfdx force:project:create -n jwtrulz && cd jwtrulz

$ sfdx force:org:create -s -f config/project-scratch-def.json

Copy down the username to the newly screated scratch org. Let’s pretend it’s test-qyczf1ot1p6j@wade.wegner_company.net.

Now, we want to demonstrate that you can authenticate into the scratch org using the JWT Grant flow and the certificate – nothing else. If you’re doing this on your machine, and you want to guarantee that you’re not cheating, you can delete the JSON file that’s storing the creds for the newly created scratch org: rm ~/.sfdx/test-qyczf1ot1p6j@wade.wegner_company.net.json. Not necessary, but it’ll help prove I’m not pulling the wool over your eyes.

Are you ready? Okay, let’s login to your scratch org with the jwt:grant command:

$ sfdx force:auth:jwt:grant --clientid [YOUR_CONSUMER_KEY] \
    --username [YOUR_SCRATCHORG_USERNAME] \
    --jwtkeyfile ~/.certs/server.key \
    --instanceurl https://test.salesforce.com

You should see:

Successfully authorized YOUR_SCRATCHORG_USERNAME] with org ID [YOUR_SCRATCHORG_ID].

BOOM!

Yes, this is the kind of stuff that I really enjoy. And I know there are a few of you out there who dig this too.

I hope you’ve found this post helpful! It will definitely provide new and powerful ways for you to automate your continuous integration systems and provide more flexible ways for you to design some of your automation.

I hope this helps!

Using Salesforce DX with Trailhead

Tue, 02 Jan 2018 00:00:00 +0000

As you’ve likely seen on Twitter, I’ve really gotten into Trailhead these past few months. In particular, the Superbadges. I not only enjoy the challenge of working through the project, but regularly discover I don’t know nearly as much as I think I do. There’s a ton of useful and practical information in Trailead just waiting for us all to discover.

Of course, I have other motivations for doing Trailhead. I find it’s an amazing way to validate various workflows with Salesforce DX. I’ve logged at least a dozen bugs or feature requests based on trying to get something in Trailhead to work with various things, such as the Salesforce CLI, Scratch Orgs, source synch, or continuous integration.

Numerous people have asked me to share my workflow and tips for getting started. So, please pardon the more tutorial-style post as I write this all out. Also, before you get started, be sure to review the Salesforce DX Setup Guide to ensure you have everything all set!

You’ll find the following in this post:

Logging into your Trailhead playground org in the CLI
Creating a project & scratch org
Completing the challenge and pulling your source
Deploying source to your TPO to verify
Installing required packages
Exporting and importing data
Executing anonymous Apex
Opening up a Lightning App

I thought it’d be good to use the Quick Start: Build Your First App project as the example for this tutorial.

Step 1: Log into your TPO using the CLI

The first thing you’ll want to do is log into your trailhead playground org (TPO) using the Salesforce CLI. Doing this will allow you to target your TPO and deploy your metadata to pass challenges.

Reset your TPO password. You’ll find all the information in the Get Your Trailhead Playground Usernamd and Password module. You have to do this because Trailhead created the TPO for you and you they set the password.
Log into your TPO using your username & password: sfdx force:auth:web:login -a tpo. Notice we’ve aliased it tpo so that it’s easier to target in the future. Once done, you can test this by opening up your TPO with sfdx force:org:open -u tpo and it’ll pop right up. Note: you’ll likely end up having more than one TPO, so a good practice would be to give it an alias that’s specific to your task.

Okay, that completes the initial setup. Now it’s time to dig in.

Step 2: Create a project & scratch org

I like to create a new project for each trail/project/superbadge. This lets me keep all the required source in a place where it’s easy to re-use and also allows me to easily push to a version control system (VCS). (You’re using VCS, right?)

Create a project. For this quick start, I’d do: sfdx force:project:create -n trailblazerapp. This will create a new directory with all the requisite files for using Salesforce DX.
Depending on the challenge, you may want/need to change the default scratch org configuration file. Take a look at the docs to see if there’s anything you want to do.
Create your scratch org. This assumes you already have your Dev Hub setup and ready to go (if not, look here). I do something like sfdx force:org:create -s -f config/project-scratch-def.json. This not only creates the scratch org, but -s makes it the default for the project, meaning all other commands I invoke will default to this scratch org.

Step 3: Complete the challenge in the scratch org and pull the source

You’ll see that the Create the Trailblazer App module has you complete a number of steps. You’ll want to do all of this in the scratch org, not your TPO. Then, when you’ve completed the steps, you can pull it all out of the scratch org so that you have a local copy of all your changes.

This is the eye-opening moment for most people when they start using Salesforce DX. It’s really simple to make changes in your scratch org then externalize them out of the org.

Open your scratch org: sfdx force:org:open
Complete all the steps required for the challenge.
Pull the changes: sfdx force:source:pull

Now you’ll see you’ll see your source in the force-app/main/default folder:

If you haven’t done so before, poke around and take a look. This is what metadata looks like!

Step 4: Deploy to your TPO and verify

At this point, you’re ready to verify you completed the challenge. But the metadata isn’t yet in your TPO. No problem, all the MDAPI commands are available in the CLI. And, since we already logged into your TPO, it’s really simple to deploy it.

Convert your source into the MDAPI format. Simple: sfdx force:source:convert -d mdapiout. This will create a new folder called mdapiout. If you look in it, it will look similar to your source, but there are subtle differences. You can learn about source file format, and it’s benefits, in the docs.

Now, deploy the metadata into your TPO with sfdx force:mdapi:deploy -d mdapiout --wait 100 -u tpo. Notice we’ve targeted the mdapiout folder, we’re using --wait so that it’s synchronous and with -u we’ve targeted our TPO.

You’ll see something like:

 $ sfdx force:mdapi:deploy -d mdapiout --wait 100 -u tpo
 9185 bytes written to /var/folders/9t/rvzqw72n7jj03c4pccmq3vrj7b3gyz/T/mdapiout.zip using 44.179ms
 Deploying /var/folders/9t/rvzqw72n7jj03c4pccmq3vrj7b3gyz/T/mdapiout.zip...

 === Status
 Status:  Pending
 jobid:  0Af4100001aS6FLCA0
 Component errors:  0
 Components deployed:  0
 Components total:  0
 Tests errors:  0
 Tests completed:  0
 Tests total:  0
 Check only: false

 Deployment finished in 9000ms

 === Result
 Status:  Succeeded
 jobid:  0Af4100001aS6FLCA0
 Completed:  2018-01-04T14:02:11.000Z
 Component errors:  0
 Components deployed:  11
 Components total:  11
 Tests errors:  0
 Tests completed:  0
 Tests total:  0
 Check only: false

And that’s it!

Click the Verify button. If you completed everything successfully, you’ll pass. If it fails, you have a few options:
- Update your source, test in scratch org, and re-deploy. In most cases, this will work.
- Maybe you defined the schema for a custom object wrong? You might need to manually (or automatically) delete it in the TPO before you re-deploy.
- When all else fails, create a new TPO. It’s free and not too hard.

Two important notes:

Profiles are messy and need clean-up

Let’s face it, they are. It’s better to use permission sets if you can. But, you’ll notice that when you create schema or do just about anything else, it updates profiles. Did you notice them when you pulled them out of the scratch org?

Often times, when you pull from the scratch org, you’ll pull profiles that don’t exist in your target org. This happens. When it does, simply remove the unwanted profiles from your source (not the MDAPI format) and convert it again into MDAPI format. A tip, shared by SFDX engineer George Murnock and platform architect Shane McLaughlin, is to include **profiles to your .forceignore file. This will force you to use permsets.

Ideally, try to avoid profiles. Sadly, since they’re so pervasive, Trailhead often assumes (and even checks) for the existence of the profile, so sometimes you can’t avoid it.

Script this step to make it easier

I’ve created an alias that makes it really easy to deploy to my TPO.

alias mdd='function _blah(){ sfdx force:source:convert -d mdapiout && /
  sfdx force:mdapi:deploy -d mdapiout --wait 100 -u $1 && rm -rf mdapiout };_blah'

With this alias, I can convert, deploy, and clean all with one command: mdd tpo

Definitely a lot easier!

Additional things to know

Certain modules will require you to do additional things.

Installing required packages

As pointed out by Bonny Hinners, there are times when you need to install some dependencies (typically via an unmanaged package but possibly through a labs app too) into your TPO to complete a challenge. This can give you custom objects and other metadata you’ll use within the challenge. You’ll need to do the same thing with your scratch org.

A good example is the Apex Specialist Superbadge. Notice that the pre-work includes an unmanaged package you need to install.

No problem, we can install this unmanaged package in the scratch org. Then, any changes we make, even if these changes are made against metadata that comes from the package, will get pulled out.

Figure out the package ID. Usually this is pretty simple, if not transparent. Notice the URL for the unmanaged package: https://login.salesforce.com/packaging/installPackage.apexp?p0=04t36000000i5UM. An ID that starts with 04t is a package. Copy this package ID.
Create your scratch org the normal way we highlighted above.
Install the package into your scratch org: sfdx force:package:install -i 04t36000000i5UM --wait 100

That’s it! Now all the required schema and dependencies are in your scratch org.

Exporting and importing data

A few of the challenges will verify that you’ve created data in the TPO. Now, of course you could open the TPO and manually enter the data it’s looking for. But where’s the fun in that? Instead, do it in your scratch org, export it, and then import it into your TPO.

This is a great way to discover some of the useful data import/export commands in the CLI.

Open your scratch org and enter your data. Yes, you can do this through other tools, but let’s face it: the app you’ve built is likely the best interface for creating your data.
Use the CLI to write a query that will grab the data you added: sfdx force:data:soql:query -q "SELECT Waypoint_Name__c FROM Waypoints__c". Ensure you get the data you’re expecting.
Export to JSON files and store in your project (other developers on your team will appreciate you doing this; trust me): sfdx force:data:tree:export -q "SELECT Waypoint_Name__c FROM Waypoints__c" -p -d data. Notice it’s the same query as before. Also, we’re using a plan definition file and exporting it into the data folder.
Now, import the data into your TPO: sfdx force:data:tree:import -p data/Waypoint__c-plan.json -u tpo. This will create the records in our TPO without you having to do it manually.

Pretty slick.

Executing anonymous Apex code

There are some things that either don’t fit into the model of source push/pull (e.g. connected apps) or will require you to take a different approach to updating in the org. So, get ready to bust out some anonymous Apex!

Here’s what I do:

I create a folder called scripts. This is where I’ll create my Apex scripts.
Create a file with an .apex extension in the scripts folder. Need to create a scheduled job? Call it scheduledjob.apex.

Write your code. Example:

 System.schedule('WarehouseCallout','0 0 13 * * ?' , 
     new WarehouseSyncSchedule())

Execute the script against your scratch org to test: sfdx force:apex:execute -f scripts/scheduledjob.apex. Note: sometimes to get this right, you’ll want to create a new scratch org to try again. I’ve gone through many iterations sometimes until I finally get it working the way I want.
Execute the script against your TPO: sfdx force:apex:execute -f scripts/servicetoken.apex -u tpo.

Notice how easy that is? And, even better, it’s completely repeatable!

Opening up a Lightning App

In many of the modules you’ll create a lightning app as a test harness called harnessApp.app (see Create and Edit Lightning Components for an example). This test harness is used to test the Lightning Components as you create them. Super helpful!

Now, Trailhead assumes you’re doing your development in the Developer Console. If you’re using Salesforce DX, how do you easily open harnessApp.app to test your component? Well, the CLI let’s you target a specific page:

$ sfdx force:org:open -p c/harnessApp.app

This will directly open your harnessApp.app in the browser, without even having to login. Pretty cool, right?

Of course, if you want to test it in your TPO, just add your alias (e.g. -u tpo).

Wrap it up

That’s pretty much it! You can do this over and over again. The best part is, as I mentioned, you can setup version control and push all your source.

In your project, it’s as simple as the following:

$ git init
$ git remote add origin git@github.com:wadewegner/th-trailblazerapp.git
$ git add -A
$ git commit -m "It works"
$ git push origin master

And then you’ll have a nice repo of your code to refer to in the future: https://github.com/wadewegner/th-trailblazerapp

Hope this helps!

P.S. Thanks to George Murnock for literally finding (and pointing out) hundreds of typos.

Deploy to Salesforce DX

Wed, 13 Sep 2017 00:00:00 +0000

If you’re a Salesforce developer, it’s likely you’ve heard us talk about Salesforce DX these past months. (If not, you’re missing out and you should checkout the official documentation.) Since TrailheaDX, everyone has been able to use the new tools and services we’ve made available as part of the Salesforce DX beta. Personally, I’ve thoroughly enjoyed building all kinds of plugins for the Salesforce CLI.

My primary plugin with lots of functionality: https://github.com/wadewegner/sfdx-waw-plugin
Generate code snippets from templates: https://github.com/wadewegner/sfdx-code-gen
Convert WSDL to Apex: https://github.com/wadewegner/sfdx-wsdl2apex-plugin

One of our top goals has been to make deployment incredibly easy. With the Salesforce CLI, deploying your source is as easy as typing sfdx force:source:push and, within a few moments, your Scratch Org is refreshed with the latest source. This has proved immensely popular with developers looking for better development experiences.

Yet, during the beta, we’ve seen a number of use cases for providing the ability to deploy source into a Scratch Org directly from a source control repository like Github:

You want to quickly try out the latest and greatest from a Christophe Coenraets or René Winkelmeyer blog post. (You know you do!)
You’re not able to access a machine where you can install the Salesforce CLI. (Maybe you’re at a conference?)
Laziness. (It’s okay, it happens to me too.)

Regardless of the reasons, a few of us agree and thought it worth doing something about it.

Without further ado, I’m pleased to introduce Deploy to Salesforce DX, an open-source and community-driven tool for automating Salesforce DX deployments from public repositories to Scratch Orgs.

Background

I started working on this tool a couple months ago. When I began, there were a few blocking issues that prevented it from working. Many thanks to Thomas Dvornik, one of the lead engineers on the Salesforce CLI team, who added the ability to use access tokens minted from a separate Web Server OAuth flow to authenticate to the Dev Hub. (More on this in a future blog post, as it’s an incredibly useful feature.)

Additionally, the first few iterations of this tool significantly lacked polish and simplicity. Without the amazing UX design and development work of Ben Snyder this tool would be an ugly mess.

Last, but not least, I’m grateful for the contribution from Andrew Fawcett. As the official owner of the “Deploy to Salesforce” button, it pleases me that he found it worthwhile to contribute some useful code to this project, and I’m hopeful that he (and others) continue to contribute.

What’s the end game for Deploy to Salesforce DX?

That’s a good question. I’m as curious as you. This started off as a project to see if it was possible. I had numerous questions. Can this run on Heroku? (Yes, in fact it can, powered by the salesforce-cli-buildpack; more on this in another post!) Can we orchestrate a Salesforce DX deployment in one click? (Yes, look at the .salesforcedx.yaml file to see the instructions.) How hard is it to invoke the CLI itself from code? (Turns out, it’s not too bad!) Ultimately, my goal with Deploy to Salesforce DX is to show what’s possible. If it serves nothing more than to let people know all the crazy/awesome things you can do with Salesforce DX, I’ll consider it a success.

I have fully open-source this application, so you can see how it works. Andy and I have already started putting together a set of feature requirements, so feel free to contribute your own. I’d also love it if you contributed, so feel free to fork and send me a pull request.

Try it out

The website itself explains how to get started, to head on over to https://deploy-to-sfdx.com/. There are also a few Github repositories out there that already support the tool:

Want to add this to your own Github repository? Please do! It’s as easy as adding the following tag to your repositories repo:

[![Deploy](https://deploy-to-sfdx.com/dist/assets/images/DeployToSFDX.svg)](https://deploy-to-sfdx.com/)

That will give you a lovely button that users can click on to deploy your source directly into one of their Scratch Orgs.

If you want to further customize your deployment, you can add a .salesforcedx.yaml file in your repo. It’ll look something like this:

scratch-org-def: config/project-scratch-def.json
assign-permset: false
run-apex-tests: true
delete-scratch-org: false
show-scratch-org-url: true

This instructs the service to perform additional or custom activities. Definitely useful if you’ve got a Lightning app or you want to run a set of tests.

Word of warning

Before I close, I want to remind everyone that this is not an official Salesforce service or tool. While I am a Salesforce employee, I’ve built this service on the side. I don’t offer any official support, although I will do my very best to respond to issues. Since the tool only interacts with Scratch Orgs, the risk is minimal. That said, consider yourself warned.

I hope you find this tool useful. It was a lot of fun to build. Thanks again to all the individuals who helped along the way!

Use Workbench with your Scratch Org

Sun, 23 Apr 2017 00:00:00 +0000

The Salesforce Workbench is a powerful set of tools for developers and admins to use with their org. You can easily describe, query, manipulate, and migrate data and metadata through the web browser, using a combination of Partner, Bulk, REST, Streaming, Metadata, and Tooling APIs. It’s completely open-sourced on Github by Ryan Brainard (@RyanBrainard).

And if all of this isn’t enough to convince you of its value, I can almost guarantee that Josh Kaplan (@JoshSfdx) is playing around in Workbench right now!

Recently, I found the need to use the Workbench while working on a side project. Of course, I’m using Salesforce DX and scratch orgs. Scratch orgs provide the perfect environment to quickly development my app and, when I’m done, I delete it. I also use the new source synchronization capabilities to externalize all my source so I can easily commit it in a Github repository.

If you’re one of our Salesforce DX pilot participants, you might be asking yourself: uh, how are you able to use your Scratch org with Workbench when you don’t know your scratch org password, it’s my domain, and it’s not running on production? Well, I’m glad you asked! And not to fear, there are two commands in the Salesforce CLI you can use to make this work!

First, assuming you’re in your project workspace, we’re going to run the command sfdx force:user:password:generate to generate a random password. If you’re not in your project workspace, you use the targetusername (or -u) to specify the scratch org (and consequently the user).

> sfdx force:user:password:generate

Successfully set the password "XXXXXXXX" for user 
scratchorgXXXXXXXXXXXXXX@wade.wegnercompany.com. You can see the password
again by running "force:org:display".

Now you know the password! What’s more, it’s encrypted and stored locally, so running sfdx force:org:display will remind you of the password if you forget it.

Second, you’ll need to know the “my domain” used with the scratch org. This is also generated randomly when the scratch org is created. To get it, you run the same command, sfdx force:org:display:

Key              Value
───────────────  ───────────────────────────────────────────────────────────
Access Token     XXXXXXXXX...
Client Id        SalesforceDevelopmentExperience
Created Date     2017-04-23
Dev Hub Id       XXXXXXXXX...
Edition          Developer Edition
Expiration Date  2017-05-01
Id               XXXXXXXXX...
Instance Url     https://dream-business-XXXX-dev-ed.cs70.my.salesforce.com
Password         XXXXXXXX
Scratch Org      true
Username         scratchorgXXXXXXXXXXXXXX@wade.wegnercompany.com

As you can see, this command includes all kinds of useful information.

Now, armed with this information, it’s easy to log into the Workbench.

Change the Environment to Sandbox.
Click I agree to the terms of service.
Click Login with Salesforce.
Click Use Custom Domain.
Paste your Instance Url into the Custom Domain box and click Continue.
Paste your Username and Password in the box, and click Log In to Sandbox.

Voilà! You’re using Workbench with your Scratch Org.

Of course, these two commands enable all kinds of other useful scenarios, not just logging into the Workbench. Please explore their use and try them out yourself.

I hope this helps!

Show the Salesforce DX Org Config in your Bash Prompt

Sat, 08 Apr 2017 00:00:00 +0000

Using the capabilities of Salesforce DX you can enable some neat tricks. Such as displaying your org configuration in your Bash prompt:

But, first, a little background …

The Salesforce DX CLI provides some powerful capabilities for tracking your Salesforce org. When you login with sfdx force:auth:web:login (-a <alias> lets you alias the org) your credentials are encrypted and stored locally. When running subsequent commands, you can append -u <username|alias> to the command to target an org. Since the CLI stores the refresh token, it can generate a new access token automatically.

Two additional things you should understand are:

The dev hub org vs the default org
Global vs local orgs

The dev hub org is the production org you esignate as the hub to track all of your scratch orgs. (In the future the dev hub will do more.) Some of the CLI commands (i.e. sfdx force:org:create) run against the dev hub org. The default org is the org all other commands run against (i.e. sfdx force:apex:execute).

The Salesforce DX CLI lets you set global orgs for the dev hub and your default org. This means that when you run the commands without -u it will target those global orgs. That is, unless your local workspace has specified a local dev hub org or default org, in which case it will use the local orgs. You can set defaults using sfdx force:config:set or when you create a scratch org using -s (i.e. sfdx force:org:create -s).

While these capabilities are powerful, it can be difficult to keep track which org your currently tracking.

To solve this, I’ve updated my .bash_profile to display the dev hub org and default org. If it doesn’t find a local org for the workspace it will display the global org.

Here’s the .bash_profile code:

It’s not 100% perfect, but it’s extremely useful. Now, the same information could be determine with sfdx force:config:list with the advantage that it’s 100% accurate (my script isn’t accurate in workspace subdirectories, for example), but there’s still some latency we need to workout of the CLI. When that latency is resolved I’ll update to use that command.

Note: this script uses files directly that, frankly, you shouldn’t use. Note that we may change these files at any point. Please do not base anything important on these files directly. Instead, use the CLI.

I hope you find this useful!

Special thanks to Chris Wall (@cwallatx), an amazing architect and developer on the Salesforce DX team, for the inspiration!

Using the OAuth 2.0 JWT Bearer Flow to Support the Salesforce DX CLI

Mon, 03 Apr 2017 00:00:00 +0000

The Salesforce DX (SFDX) CLI makes it easy to run commands as a developer. It also makes it really easy to create scripts that facilitate automation. A great example is the following tweet from Pat Patterson:

#SalesforceDX is awesome! I can create a scratch org for testing from a bash script. Great job, @WadeWegner & team! pic.twitter.com/Nu3yI2UQH0
— Pat Patterson (@metadaddy) March 29, 2017

The praise for SFDX is awesome. Thanks, Pat. But that’s not my purpose for sharing. This script does some awesome stuff. But notice the first command:

sfdx force:auth:jwt:grant --clientid ${CLIENT_ID} \
    --jwtkeyfile ${JWT_KEY_FILE} --username ${HUB_USERNAME} \
    --setdefaultdevhubusername > /dev/null

This command logs into the developer hub using only the client ID, the username, and the JWT key file; it doesn’t require you to interactively login. This is important when you want your scripts to run automatically. For this to work, your local SFDX workspace (i.e. client-side) needs a private key for signing the JWT bearer token payload. The server-side needs a Connected App containing a certificate generated from that private key.

The key to the use of the JWT bearer flow is that it supports the RSA SHA256 algorithm, which uses an uploaded certificate as the signing secret. This gives us the ability to authenticate the CLI without having to interactively login. Perfect for automated builds and scripting. Read the Salesforce documentation for more details on the OAuth 2.0 JWT Bearer Token Flow.

In this post, we’ll create both the key and the certificate, as well as setup the Connected App to facilitate the sfdx force:auth:jwt:grant command.

[Update 4/6/17: you can now install my plugin (sfdx plugins:install sfdx-oss-plugin) and run the command sfdx wadewegner:connectedapp:create -u <username|alias> -n <name> -r to get through step #5. You’ll still need to complete steps #6 and #7.]

Follow these instructions to generate a private key and a certificate signing request. The resulting server.key file contains your private key, and we’re going to use that as input when signing the JWT bearer token payload.
Execute the subsequent instructions to generate a self-signed SSL certificate.
Log into your Developer Hub, and navigate to Setup. Go to App Manager, then click the New Connected App button on the upper-left. (You’re using the Lightning Experience, right?)
Create a new Connected App with information and click Save. Ensure you do the following:
- Set the Callback URL to: http://localhost:1717/OauthRedirect
- Check Use digital signatures and upload your server.crt certificate.
- Add the following OAuth Scopes: basic, api, web, refresh_token
Save your Consumer Key.
Click the Manage button, then Edit Policies. Under the OAuth policies subsection, change the Permitted Users combo box to be Admin approved users are pre-authorized. Then click Save.
Click Manage Profiles OR Manage Permission Sets, and select the profiles and/or perm sets that should be allowed to be pre-authorized to use this Connected App. (For perm sets, create a perm set without any particular permissions, assign it your user, then assign that perm set to the connected app.) Then click Save.

When this is setup correctly, running the command will look like the following:

sfdx force:auth:jwt:grant --clientid ${CLIENT_ID} \
    --jwtkeyfile ${JWT_KEY_FILE} --username ${HUB_USERNAME} \
    --setdefaultdevhubusername

Successfully authorized <USERNAME> with org id 00D460000001PSmEAM

You can see this in action in a sample Travis CI build I have setup for https://github.com/wadewegner/sfdx-travisci.

I hope this post helps! Special thanks to George Murnock (gmurnock__c) for putting together a really helpful document that is the basis of this post.

Creating a Plugin for the Salesforce CLI

Fri, 31 Mar 2017 00:00:00 +0000

This post is valid for the Salesforce DX (SFDX) pilot. Please note that details may change and I’ll do my best to update accordingly.

Recently I highlighted a neat way to use open source software with Salesforce DX. Since then I’ve used Appiphony’s custom base components many, many times in demos and apps I’ve built.

It didn’t take long for me to get tired of removing the Git details when pulling the OSS from Github. So I created sfdx-oss-plugin. With this command, you can run sfdx wadewegner:source:oss -r wadewegner/Strike-Components -p . to grab all the source listed in the SFDX oss manifest into whatever directory you specify. It also makes it really easy to create a SFDX oss manifest file with the command sfdx wadewegner:source:create -p ., which creates the JSON file for everything in the specified path.

Pretty nifty, eh? To try it out:

1) Install the SDFX CLI.

2) Clone the repo: git clone git@github.com:wadewegner/sfdx-oss-plugin.git

3) Install npm modules: npm install

4) Link the plugin: sfdx plugins:link .

(Perhaps I’ll publish this at somepoint.)

This highlights one of the advantages building our Salesforce CLI on the Heroku CLI. Not only do we get to take advantage of frequent updates (both for features and security) of the Heroku CLI, but we can also take advantage of plugin extensibility.

For the most part, building a plugin for the Salesforce CLI is exactly the same as building a plugin for the Heroku CLI. I think you’ll find sfdx-oss-plugin a very good reference.

One significant change we’ve made is the introduction of a namespace. You can see it on index.js#L16 and in the following sample:

exports.namespace = {
    name: 'wadewegner',
    description: 'commands from Wade Wegner'
};

This organizes all the commands in my plugin under sfdx wadewegner.

Overtime, things will change. I’ll be sure to update this post accordingly.

I hope you’ve found this post useful and that you’re enjoying the Salesforce DX pilot! To add yourself to the Salesforce DX pilot waitlist, enter your info here: http://go.pardot.com/l/27572/2017-01-23/6gh89x

Salesforce DX Strike

Tue, 07 Mar 2017 00:00:00 +0000

Like many people at Salesforce and in the community, I was really excited and impressed to see Lightning Strike by Appiphony. Not to take away from the remarkable tool they built to visually explore and configure Lightning components, I was most excited by the custom Lightning Components they built and released to the community through their Github repository Strike-Components.

Immediately I wanted to try these components out myself. And fortunate, using Salesforce DX, it’s really quite easy.

Here’s a Gist showing the commands I ran to quickly pull these open source Lightning components into my Salesforce DX workspace and push into my scratch org.

I think this is a great example of how Salesforce developers can quickly take advantage of open source software.

In fact, this has me thinking that there’s more we can do as part of Salesforce DX to make this even easier. Stay tuned for more updates!

Salesforce DX Pilot Demos

Mon, 27 Feb 2017 00:00:00 +0000

We’re so excited to have recently launched the Salesforce DX pilot. Our teams have been hard at work on Salesforce DX, and it’s tremendously exciting to have so many of you using the tools and trying out an entirely new way to build applications on the Salesforce platform.

I thought it would be helpful to share with everyone the demos from the Salesforce DX pilot kickoff webinar. This is cut directly from the webinar, so apologies for any rough edges.

If you have any questions, please ask me @WadeWegner.

To add yourself to the Salesforce Pilot waitlist, enter your info here: http://go.pardot.com/l/27572/2017-01-23/6gh89x

Creating a Go Site Extension and Resource Template for Azure

Mon, 05 Jan 2015 00:00:00 +0000

The New Year is a good time to set goals for yourself. I’ve challenged myself this year to explore and ship some apps using the Go language, which is likely no surprise given my recent posts on setting up Go on Windows and running Go on Azure Websites.

As part of my initial explorations, I used Azure Websites to host my Go web apps. The last post I wrote showed my first Go prototype on Azure Websites. While useful as a prototype, it’s arguably not the most straightforward way to go about building and deploying your Go web app. The principal issue is that the Go runtime is not available by default on Azure Websites; we have to configure the website to use downloaded Go binaries. While my first prototype works, Azure has two capabilities you’ve likely never heard of which can help simplify and automate: Site Extensions and the Azure Resource Manager.

So, what did I do? I created a site extension for Go and wrote a resource template and PowerShell script for deploying an Azure Website that installs the site extention. You can find everything in my azure-go-lang-site-extension respository on Github.

Let’s see how it works.

Create the Site Extension

Site Extensions are exactly what the name suggests and provide ways to extend your Azure Website. You create a NuGet package with your code and config, package it up, deploy it to https://www.siteextensions.net/ (actually, any NuGet feed), and later you can apply these packages to your Azure Website. For additional details, please see the Azure Web Site Extensions blog post and the Azure Site Extensions wiki.

I used two important capabilities to get Go setup in the Azure Website: install/uninstall scripts and XML Document Transformation (XDT).

IF NOT EXIST "%WEBROOT_PATH%server.go" (
	cp server.go %WEBROOT_PATH%
)

IF NOT EXIST "%WEBROOT_PATH%go1.4.windows-386.zip" (
	cd /D %WEBROOT_PATH%
	curl -O https://storage.googleapis.com/golang/go1.4.windows-386.zip
	start unzip -o go1.4.windows-386.zip -d .
)

First, I wrote an install script called install.cmd which performs the following tasks:

Copies the server.go file into the webroot. This is the file that serves the HTTP responses and the same one I used in my prototype.
Downloads the Go SDK using curl.
Unzips the Go SDK.

Unzipping the Go SDK can take several minutes. Today, this causes issues when trying to install the site extension from the Azure Portal and the Azure Resource Manager, as it will timeout, throw an error, and continue to retry until it ultimately fails. Consequently, I use the command start to run the unzip operation asynchronously, allowing the install.cmd execution to return and not causing a timeout error. While this solves the problem it is not ideal for if the instance is restarted during the process of unzipping the SDK it could leave us in a faulted state. This is likely a short term issue and I’ll update this post when it is resolved.

<?xml version="1.0" encoding="UTF-8"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform"> 
  <location path="%XDT_SITENAME%" xdt:Locator="Match(path)">
    <system.webServer>
      <handlers xdt:Transform="InsertIfMissing">
        <add name="httpplatformhandler" path="*" verb="*" modules="httpPlatformHandler" resourceType="Unspecified" xdt:Transform="InsertIfMissing" />
      </handlers>
      <httpPlatform processPath="d:\home\site\wwwroot\go\bin\go.exe"
                    arguments="run d:\home\site\wwwroot\server.go"
                    startupTimeLimit="60" xdt:Transform="InsertIfMissing">
        <environmentVariables>
          <environmentVariable name="GOROOT" value="d:\home\site\wwwroot\go" xdt:Transform="InsertIfMissing"/>
        </environmentVariables>
      </httpPlatform>
    </system.webServer>
  </location>
</configuration>

Next, I wrote an XML document transform for the applicationHost.Config file to tell IIS to use our Go binaries for responding to web requests. After the site extension is installed and the first web request is processed, the applicationHost.config file is updated to include the additional configuration details. It’s important to point out the <location> ... <location> element, as this ensures our changes only apply to the correct website; otherwise, anything hosted on this machine is affected.

If you have questions on this configuration information, see my earlier post on setting up Go on Azure websites.

Packaging all of this into a site extension is pretty easy as it’s based on NuGet. I first created a Nuspec file to describe the package and then a build script which uses NuGet to create the package. The result is a NuPkg which I then upload to https://www.siteextensions.net/.

At this point you can log into the Azure Portal, create an Azure Website (or use an existing one), and install the Site Extension. Load your website blade and scroll down until you see the Extensions tile.

Through the extensions blade you can browse available Site Extensions. You’ll find Go Lang for Azure Websites. Install it, and you’ll see it listed as one of your site extensions.

Wait a few minutes and click the Browse link; you now have a Go web app running in Azure Websites. Not too bad! Of course, we can make the last step of creating the Azure Website and installing the Site Extension easier with the Azure Resource Manager.

Create the Resource Template

The Azure Resource Manager is a relatively new technology that provides a container for managing the lifecycle of Azure resources (called a resource group), a way to describe and execute the deployment and configuration of a set of Azure resources, and a management layer for these resources. As the resource manager is still in preview, documentation is hard to find; particularly for resource templates. To learn more about the resource manager, I recommend you watch Introduction to Azure Resource Manager from Build 2014 and read the REST API Reference and Template Language guides.

The resource template is nothing more than a JSON file that describes the Azure resources we want to deploy; in this case, it’s an Azure Website along with our Go site extension. Let’s look at the template.

{
  "$schema": "http://schema.management.azure.com/schemas/2014-04-01-preview/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "siteName": {
      "type": "string"
    },
    "hostingPlanName": {
      "type": "string"
    },
    "siteLocation": {
      "type": "string"
    },
    "sku": {
      "type": "string",
      "allowedValues": [
        "Free",
        "Shared",
        "Basic",
        "Standard"
      ],
      "defaultValue": "Free"
    },
    "workerSize": {
      "type": "string",
      "allowedValues": [
        "0",
        "1",
        "2"
      ],
      "defaultValue": "0"
    }
  },
  "variables": {
    "goSite": "[parameters('siteName')]"
  },
  "resources": [
    {
      "apiVersion": "2014-04-01",
      "name": "[parameters('hostingPlanName')]",
      "type": "Microsoft.Web/serverfarms",
      "location": "[parameters('siteLocation')]",
      "properties": {
        "name": "[parameters('hostingPlanName')]",
        "sku": "[parameters('sku')]",
        "workerSize": "0",
        "numberOfWorkers": 1
      }
    },
    {
      "apiVersion": "2014-04-01",
      "name": "[variables('goSite')]",
      "type": "Microsoft.Web/sites",
      "location": "[parameters('siteLocation')]",
      "dependsOn": [
        "[resourceId('Microsoft.Web/serverfarms', parameters('hostingPlanName'))]",
      ],
      "properties": {
        "name": "[variables('goSite')]",
        "webHostingPlan": "[parameters('hostingPlanName')]"
      },
      "resources": [
        {
          "apiVersion": "2014-04-01",
          "name": "web",
          "type": "config",
          "dependsOn": [
            "[resourceId('Microsoft.Web/Sites', variables('goSite'))]"
          ],
          "properties": {
            "appSettings": [
              { "Name": "SCM_SITEEXTENSIONS_FEED_URL", "Value": "http://www.siteextensions.net/api/v2/" },
            ]
          }
        },
        {
          "apiVersion": "2014-04-01",
          "name": "GoLang",
          "type": "siteextensions",
          "dependsOn": [
            "[resourceId('Microsoft.Web/Sites', variables('goSite'))]",
            "[resourceId('Microsoft.Web/Sites/config', variables('goSite'), 'web')]"
            ],
          "properties": { }
        },
      ]
    }
  ]
}

I’m not going to attempt to explain this entire template as that’s well beyond the scope of this post. Take a look at this guide on the template language if you want to learn more.

For our purposes, I want to highlight the last section:

...

{
  "apiVersion": "2014-04-01",
  "name": "GoLang",
  "type": "siteextensions",
  "dependsOn": [
    "[resourceId('Microsoft.Web/Sites', variables('goSite'))]",
    "[resourceId('Microsoft.Web/Sites/config', variables('goSite'), 'web')]"
    ],
  "properties": { }
},

...

Here we tell the resource manager that we want the GoLang site extension installed into our Azure Website. Simple but effective.

To execute this template, use PowerShell. I wrote a script which makes this pretty simple.

Switch-AzureMode -Name AzureResourceManager

$subName = "YOURSUBSCRIPTIONNAME"
$userName = "YOURORGIDUSERNAME"
$securePassword = ConvertTo-SecureString -String "YOURPASSWORD" -AsPlainText -Force
$name = "YOURRESOURCEGROUPNAME"
$location = "West US"
$templateFile = "Template.json"
$siteName = $name + "Site"
$hostingPlanName = $name

$cred = New-Object System.Management.Automation.PSCredential($userName, $securePassword)
Add-AzureAccount -Credential $cred 

Select-AzureSubscription -SubscriptionName $subName
New-AzureResourceGroup -Name $name -Location $location -TemplateFile $templateFile -siteName $siteName -hostingPlanName $hostingPlanName -siteLocation $location -Force
 
Switch-AzureMode -Name AzureServiceManagement

When you run this command it will create a resource group and run the resource template, resulting in a new Azure Website with our site extension installed.

The parameters siteName, hostingPlanName, and siteLocation are all defined within the resource template. For documentation on the New-AzureResourceGroup syntax you can review the MSDN documentation.

And that’s it, my friends. The end result is an Azure Website you can use to start playing around with Go.

There’s a lot of stuff to think about in this blog post. While my goal here was to make it easy to setup Go inside Azure Websites, I hope you see this as an example of how you can take advantage of Site Extensions and the Azure Resource Manager to do some amazing things in Azure.

Special thanks to David Ebbo for his help when creating the site extension!

I hope this helps!

4 Simple Steps to Run Go Language in Azure Websites

Mon, 29 Dec 2014 00:00:00 +0000

A few weeks ago I wrote a GoLang web app and wanted to find a good place to host it. Given I work with the team that builds Azure Websites, it seemed only fitting to host it in Azure Websites. Turns out, it works great! However, there aren’t any resources available that walk you through the steps. Consequently, I wrote the following tutorial.

(Incidentally, if you want to start to use Go Language and run Windows you’ll want to review my post Easy Go Programming Setup for Windows.)

Is this the absolutely authority on running Go Language in Azure Websites? No, but it works. I plan to publish a few more articles on more complex scenarios in the future.

4 Simple Steps

Create your Azure Website in the Azure Portal. Without a doubt the easiest step.
Download and unzip the Go executables. In the Azure Portal select your website blade and scroll down until you see the Console tile.

In the console to the right, type the following commands:

curl -O https://storage.googleapis.com/golang/go1.4.windows-386.zip

unzip go1.4.windows-386.zip

You should see the following:

Be patient with the console as these two operations may take a few moments. It’s purposefully simple.

Note: I’m not sure why it returns Bad Request but so far it doesn’t seem to cause any issues.
Create a server.go file in the wwwroot folder. This is a super simple Go file which will reply for any resource on the website.

package main
	import (
	    "fmt"
	    "net/http"
	    "os" 
	)
	func handler(w http.ResponseWriter, r *http.Request) {
	    fmt.Fprintf(w, "You just browsed page (if blank you're at the root): %s", r.URL.Path[1:])
	}
	func main() {
	    http.HandleFunc("/", handler)
	    http.ListenAndServe(":"+os.Getenv("HTTP\_PLATFORM\_PORT"), nil)
	}

As a convenience, feel free to use `curl` and download this directly from [my public gist](https://gist.github.com/wadewegner/52a925a7b1607a48d796). Otherwise, you should consider using Kudu or git to get your files into your Azure Website.

`curl -L http://bit.ly/1xtYNRU --output server.go`

Once downloaded, type `type server.go` to confirm you grabbed everything correctly.

Create a Web.Config file in the wwwroot folder. We will use the httpPlatformHandler simpilar to running Tomcat in Azure Websites.

<?xml version="1.0" encoding="UTF-8"?>
	<configuration>
	    <system.webServer>
	        <handlers>
	            <add name="httpplatformhandler" path="\*" verb="\*" modules="httpPlatformHandler" resourceType="Unspecified" />
	        </handlers>
	        <httpPlatform processPath="d:\home\site\wwwroot\go\bin\go.exe" 
	                      arguments="run d:\home\site\wwwroot\server.go" 
	                      startupTimeLimit="60">
	            <environmentVariables>
	              <environmentVariable name="GOROOT" value="d:\home\site\wwwroot\go" />
	            </environmentVariables>
	        </httpPlatform>
	    </system.webServer>
	</configuration>

Again, you can use the following curl command to download the `Web.Config` file:

`curl -L http://bit.ly/1wx4JFY --output Web.Config`

That is it! You can now browse to your Azure Website and see it in action.

For now, try it out here: http://golang.azurewebsites.net/hello

Is there more we can do here? Absolutely, and I intend to cover some additional topics in future posts. However, for now, it feels good knowing that we can push our Go Language code to Azure Websites.

Special thanks to Ranjith Mukkai Ramachandra for his help and answering all my questions quickly and thoroughly!

Easy Go Programming Setup for Windows

Tue, 23 Dec 2014 00:00:00 +0000

I’ve had to do this more than once recently, so I figured I’d document the simple steps for setting up the Go programming language on Windows. Most of this is simple and straightforward. The only tricky part I found is setting up your GOPATH, which defines a convention for storing and building Go code you write and acquire from open source code repositories.

5 Simple Steps

Follow these five simple steps to install Go.

Make sure you have both Git download and Mercurial download installed. With Go programming you’ll make heavy use of open source repositories.
Download and install the latest 64-bit Go MSI distributable (which sets most of the environmental variables for you). https://golang.org/dl/

To make things simple, use the default installation path at C:\Go
Ensure the Go binaries (found in C:\Go\bin) are in your Path system environment variables. To check click System, Advanced system settings, Environment Variables... and open Path under System variables:

An easy way to confirm is to open the command line and type go version:
Setup your Go workspace. This consists of three folders at the root:
```
 bin/
 pkg/
 src/
```
I create a C:\Projects\Go folder as my root Go workspace:
Create the GOPATH environment variable and reference your Go workspace path. To add, click System, Advanced system settings, Environment Variables... and click New... under System variables:

Set the variable name to GOPATH and value to your Go workspace path (e.g. C:\Projects\Go):

You can quickly check to ensure your path has been set by opening the command line and typing echo %GOPATH% and check the output:

And that’s all it takes! You’re ready to get started.

Verify

Want to quickly test and ensure this is all working as expected? Open the command line and type the following:

go get github.com/golang/example/hello
%GOPATH%/bin/hello

You should see the output as “Hello, Go examples!” (refreshingly, not your typical hello world):

I hope this helps!

Build a Windows 8 App for Salesforce With No Code Using Project Siena

Thu, 07 Aug 2014 00:00:00 +0000

Microsoft Project Siena (Beta) is a tool that allows a business user (i.e. non-developer) to quickly building rich business applications for Windows 8. You can learn all about the tool on the Microsoft Project Siena web site and by watching a set of tutorials on the Microsoft Project Siena (Beta) Channel 9 Blog.

Having recently left Salesforce to join Microsoft, I was curious about how to build a Project Siena app that integrated into Salesforce. Project Siena uses the Web Application Description Language, or WADL, to connect to 3rd party SaaS services. WADL is an open web standard that is for REST what WSDL is for SOAP, meaning it describes the service resources and relationships.

The release of the WADL Generator for Project Siena (Alpha) makes the generation of the WADL file extremely easy.

Here’s a video that shows how a developer can define the relationship with Salesforce and create a WADL file that a business user can use within a Project Siena application.

(Watch in full screen for the best experience.)

There are a few reasons I think this is pretty compelling:

I like the separations of concerns. The developer can setup the integration with Salesforce (or any REST API) and define functions used by a business user.
WADL is an open web standard used by many companies, not just Microsoft.
Once in Project Siena, you don’t have to worry about setting up authentication or configuring authorization to the 3rd party SaaS provider. It’s already been done and the settings exist in the WADL file.
The business user has a very rich and interact experience when building the application. As the demo shows, even interacting with a REST API, and seeing the results, is possible at design time.
All the business user really has to care about are controls & functions. (And perhaps a little bit of “Excel-like” coding.)

I think this is only the tip of the iceburg. Take a look at the other Project Siena tutorials to get more ideas about how you can use Project Siena to build applications.

Create an iBeacon Transmitter with the Raspberry Pi

Tue, 20 May 2014 00:00:00 +0000

iBeacon is the Apple trademark for a low-powered, low-cost transmitter that can notify nearby iOS 7 devices of its presence. It uses Bluetooth Low Energy (BLE), also called Bluetooth Smart, technology to transmit an advertisement that includes a universally unique identifier (UUID). Android devices can receive iBeacon advertisements and, fortunately for those of us who like to hack around, it doesn’t take too much work to setup a Raspberry Pi to emit iBeacon advertisements.

Why would you want to do this? Well, if the act of configuring a Raspberry Pi itself isn’t enough of a reward, consider some of the following use cases:

Host a digital scavenger hunt by placing iBeacons with different clues scattered around a conference.
Customize retail offers based on your location in a store and proximity to certain products.
Alert you while you sit at a bar enjoying your favorite craft beer when someone rides off with your bicycle outside.

I particularly enjoy the last use case. Simply tag your bag with a BLE transmitter and then, if it leaves the proximity/region, get alerted!

If you look around the Internet you’ll find hundreds of additional use cases and ideas. The point is, this is cool technology with a lot of different applications and uses.

In this post we’re going to look at how you can start to play around with this using that universal toy for the hacker: the Raspberry Pi.

Required Hardware

Here’s the hardware I use. You don’t have to purchase from Adafruit, but to have the best results I’d recommend you try to get the same hardware I used; otherwise your mileage may vary.

Raspberry Pi Model B 512MB RAM
SD/MicroSD Memory Card (4 GB SDHC)
Bluetooth 4.0 USB Module (v2.1 Back-Compatible)
5V 1A (1000mA) USB port power supply
USB cable - A/MicroB
Miniature WiFi (802.11b/g/n) Module (optional)
Raspberry Pi Case (optional)

The WiFi and Pi Case are optional but I strongly encourage you to get them. They’ll make your life a lot easier.

Setup the Raspberry Pi as an iBeacon Transmitter

Over the past week I’ve had to setup and configure numerous Raspberry Pi’s as iBeacons. Yes, there are a lot of tutorials, but sadly none worked perfectly for me. As so often happens when you’re on the bleeding edge, things change and instructions stagnate. Additionally, I think some of the tutorials are simply wrong or poorly document the process.

Here are the steps I’ve taken to, repeatedly, get Raspberry Pi’s setup as iBeacon transmitters. If you follow these instructions with the above hardware I’m reasonably confident you can get this up and running with no problems.

Step 1: Download an Operating System Image

There are numerous OS images you can use with the Raspberry Pi. I chose to use the Raspbian Debian Wheezy image. The steps below work on the 2014-01-07 release.

Download the image from the official downloads page: http://www.raspberrypi.org/downloads/

Step 2: Write the Image to the SD Card

There are numerous tutorials available for this step.

If you’re using a Mac I recommend Ray Viljoen’s Raspberry PI SD Installer OS X script. Works great.

Step 3: Connect to the Raspberry Pi

Again, you have numerous options for connecting to the device. I personally like to use the Console Cable to connect directly from my Mac but you can also connect with Ethernet & SSH or connect a monitor and keyboard.

It’s worth noting that your default user name is pi and password is raspberry.

Step 4: Initial Device Configuration

Once you connect to the device you should first configure a few settings. Run sudo raspi-config and complete the following six steps.

Choose Expand Filesystem.
You should Change User Password.
Choose Internationalisation Options then I1 Change Locale. I removed the existing setting and chose enUS.UTF-8 UTF-8.
Choose Internationalisation Options then I2 Change Timezone. Set accordingly.
Choose Advanced Options then A2 Hostname. Choose something unique.
Choose Advanced Options then A4 SSH. It’s likely enabled already but you may as well make sure.

Reboot the Raspberry Pi (sudo shutdown -r now) and reconnect.

Step 5: Setup WiFi (Optional)

While not absolutely necessary, I always setup WiFi on my Raspberry Pi so that it doesn’t require Ethernet or a console cable for me to connect via SSH. When you have a lot of devices this is particularly important.

I use the Miniature WifFi (802.11b/g/n) Module.

You’ll need to update your interfaces so that your WiFi connects to your wireless router. Run sudo nano /etc/network/interfaces (or whatever editor you want to use) and update accordingly.

auto lo
 
iface lo inet loopback
iface eth0 inet dhcp
 
allow-hotplug wlan0
auto wlan0
 
iface wlan0 inet dhcp
  wpa-ssid "ssid"
  wpa-psk "password"

Be sure to set your own ssid and password values (and yes, capitalization matters).

If you’re connected over Ethernet you’ll likely want to restart with sudo shutdown -r now but if you’re using your Console Cable you can simply restart the networking with sudo /etc/init.d/networking restart. If you then run ifconfig you should see you now have an IP address. At this point I typically start connecting using SSH.

Step 6: Install Required Libraries

There are a number of open source libraries and tools used in order to send the iBeacon data from the Raspberry Pi. Install the following libraries:

sudo apt-get install libusb-dev 
sudo apt-get install libdbus-1-dev 
sudo apt-get install libglib2.0-dev --fix-missing
sudo apt-get install libudev-dev 
sudo apt-get install libical-dev
sudo apt-get install libreadline-dev

This only takes a few minutes.

Step 7: Download, Make, & Install BlueZ Library

The BlueZ libraries provide support for the core Bluetooth layers and protocols. We have to download, make, and then install the libraries. Run the following commands sequentially:

sudo mkdir bluez
cd bluez
sudo wget www.kernel.org/pub/linux/bluetooth/bluez-5.18.tar.gz
sudo gunzip bluez-5.18.tar.gz
sudo tar xvf bluez-5.18.tar
cd bluez-5.18
sudo ./configure --disable-systemd
sudo make
sudo make install
sudo shutdown -r now

The sudo make command can take a long time to complete. Just let it run. As long as you’ve followed these instructions exactly as I’ve described it should complete without any problem.

Congratulations. You’ve successfully setup your Raspberry Pi to act as an iBeacon transmitter. Of course, it’s not yet transmitting a signal so let’s set that up now.

Setup the Raspberry Pi as an iBeacon Transmitter

At this point we need to start transmitting a signal. Here’s where, depending on what you’re looking to accomplish, you may decide to take a different path. For me, I want my Raspberry Pi iBeacon to do the following:

Initialize and broadcast a signal.
Advertise itself but don’t allow connections.
Broadcast a unique transmission but let me have more than one identifiable iBeacons.

The broadcast has three important identifiers:

proximityUUID: a unique UUID that distinguishes your iBeacons from other iBeacons.
major: used to group related sets of iBeacons.
minor: used to identify a iBeacon within a group.

What’s nice about the Raspberry Pi as a iBeacon is you can choose all these values yourself. Perhaps the easiest way to generate a UUID is to run the following command:

python -c 'import sys,uuid;sys.stdout.write(uuid.uuid4().hex)'|pbcopy && pbpaste && echo

You should get a value such as 636f3f8f64914bee95f7d8cc64a863b5 as the output. This is a 128-bit UUID that our app will use to look for our iBeacon.

Okay, let’s reconnect (if needed) to our Raspberry Pi and run the following commands:

cd bluez/bluez-5.18
sudo tools/hciconfig hci0 up
sudo tools/hciconfig hci0 leadv 3
sudo tools/hciconfig hci0 noscan

Now, run tools/hciconfig and confirm it’s up and running. Your output should look similar to this:

hci0:	Type: BR/EDR  Bus: USB
		BD Address: 00:1A:7D:DA:71:13  ACL MTU: 310:10  SCO MTU: 64:8
		UP RUNNING 
		RX bytes:1136 acl:0 sco:0 events:61 errors:0
		TX bytes:855 acl:0 sco:0 commands:61 errors:0

It’s now time use the hcitool to configure the transmission to use our UUID. Additionally, for this initial device, we’re going to set the major and minor values as 0 by attaching 00 00 00 00 to the end of our UUID. Finally, the last byte we’ll add is the RSSI value of C8.

The command should look like the following:

sudo tools/hcitool -i hci0 cmd 0x08 0x0008 1E 02 01 1A 1A FF 4C 00 02 15 63 6F 3F 8F 64 91 4B EE 95 F7 D8 CC 64 A8 63 B5 00 00 00 00 C8

You might be wondering about some of the other values. Well, the whole thing breaks down like this:

Setup the add packet flags:

  1E
  02 		# Number of bytes that follow in first AD structure
  01  	# Flags AD type
  1A  	# Flags value 0x1A = 000011010  
            bit 0 (OFF) LE Limited Discoverable Mode
            bit 1 (ON) LE General Discoverable Mode
            bit 2 (OFF) BR/EDR Not Supported
            bit 3 (ON) Simultaneous LE and BR/EDR to Same Device Capable (controller)
            bit 4 (ON) Simultaneous LE and BR/EDR to Same Device Capable (Host)
  1A  	# Number of bytes that follow in second (and last) AD structure

Define vendor specific values:

  FF 		# Manufacturer specific data AD type
  4C 00 	# Company identifier code (0x004C == Apple)
  02 		# Byte 0 of iBeacon advertisement indicator
  15 		# Byte 1 of iBeacon advertisement indicator

Our specific UUID values:

6F 3F 8F 64 91 4B EE 95 F7 D8 CC 64 A8 63 B5 # our iBeacon proximity uuid
00 	# Major 
00 	# Minor 
  C8 00 	# Calibrated Tx power

Run the command. Congrats, you’re broadcasting!

Detect Your iBeacon Signal

In a later post I’ll show you how to write your own iOS application to detect iBeacon signals. For now, let’s grab a free application to find our signal.

For an iOS device I recommend Locate iBeacon. It’s easy to use. I don’t have an Android, but I’m sure there are many out there.

When you open the app first select iBeacon Transmitter and hit the + symbol/button to configure our Raspberry Pi iBeacon.

Name: Choose a unique name
Proximity UUID: 636f3f8f-6491-4bee-95f7-d8cc64a863b5 (must he a hex version of our UUID)
Major: 0
Minor: 0
Power: (leave blank)

Save these values, then select the Locate iBeacons button. You should see your iBeacon!

Of course, if you have more than one Raspberry Pi, you can get them both to broadcast. Follow the instructions above except change the mino value to 1 (01 00 in hex):

sudo tools/hcitool -i hci0 cmd 0x08 0x0008 1E 02 01 1A 1A FF 4C 00 02 15 63 6F 3F 8F 64 91 4B EE 95 F7 D8 CC 64 A8 63 B5 00 00 01 00 C8

Pretty awesome!

I hope you’ve found this article on configuring a Raspberry Pi as an iBeacon transmitter useful! If you have questions or issues please feel free to leave a comment.

Salesforce Did What? How We Built the Salesforce Toolkits for .NET

Thu, 15 May 2014 00:00:00 +0000

I had the great pleasure this week to speak at TechEd North America 2014 on how we built the Salesforce Toolkits for .NET. It was a blast, and I wouldn’t be surprised if I was the first Salesforce employee to speak at TechEd. Many thanks to my friends at Microsoft for the opportunity.

Here is the video recording of the talk on Channel 9:

The highlight of the talk for me was that, rather than explain through slides, I built a brand new SDK during the talk and committed it live to Github in this repository. Take a look at the repository and use whatever your find valuable!

While I gave a quick overview of the toolkits and SDKs we built for Salesforce, the focus of the talk was on how they were built. Consequently, I broke the talk into different segments and focused on the following items:

Segment 1: Create a new project with authentication capabilities.

Portable class libraries
Extensibility
Async/Await

Segment 2: Create tests to validate our new library.

Functional tests
Unit tests

Segment 3: Allow our library to run with Mono.NET on non-Windows platforms.

Mono.NET & Xamarin
Continuous integration with Travis CI

Segment 4: Extend our library with additional functionality for developers.

Anonymous types
Dynamics

Segment 5: Package and deploy our library.

NuGet

Segment 6: How to grow community involvement with our project.

Community
Licenses
Issues, features, and bugs in Github
Pull requests

I hope you find this presentation valuable! I had a blast and thoroughly enjoyed it.

Uploading an Attachment to Salesforce with the SOAP and REST APIs

Thu, 01 May 2014 00:00:00 +0000

Earlier today a colleague asked me if I had an example of using Python to create an attachment in Salesforce. I didn’t, but that didn’t stop me from creating a couple. Sadly, our documentation here isn’t the greatest. You can look at the Insert or Update Blob Data for the REST API or Attachment for our SOAP API. If you’re like me, neither document is good enough; I had to continue to dig around to figure out exactly what I needed.

Nevertheless, I got it working. I’d like to share with you two examples: uploading attachments with the REST API and uploading attachments with the SOAP API. For both examples I will use Python.

Why Python?

Well, not only is it fun, but I think Python is also remarkably easy to read. It shouldn’t be too much work for you to adjust to your language of choice.

A few things worth nothing before we go to far:

You will need to base64 encode your file.
An attachment attaches to an object in Salesforce (i.e. Account, Contact, etc.). You’ll need to know the Id (called the ParentId) to which you want to attach.
Python has some great libraries that I’m going to use. This has the added benefit of keeping the code really simple and focused on the task of uploading the attachment.

Without further ado …

Python and Attachments with the REST API

To run this script you’ll need to do the following:

Create a text.txt file in the same directory as the Python script.
Add your user name, password, and security token.
Install simple_salesforce with pip install simple_salesforce. I recommend you first use virtualenv to manage your environment.
Update the instance value (or extract it from the login info).

The code is pretty straightforward. simple_salesforce is great when you want to quickly work with the REST API.

Python and Attachments with the SOAP API

To run this script you’ll need to do the following:

Create a text.txt file in the same directory as the Python script.
Add your user name, password, and security token.
Install beatbox with pip install beatbox. I recommend you first use virtualenv to manage your environment.

Again, this code is pretty straightforward. beatbox is a fantastic way to interact with the SOAP API.

It’s likely over time I’ll learn more that I should add to this post. For now, I’ll leave it as it is; hopefully someone finds it useful.

Enjoy!

Update Records with Python and the Salesforce Bulk API

Wed, 30 Apr 2014 00:00:00 +0000

It’s time to take a little break from .NET and enjoy the many different programming languages you can use when integrating to the Salesforce1 Platform. But first, a public service announcement from Steve Marx:

This week a colleague of mine asked me if I could help him by writing a script to update data he has in Salesforce (okay, he asked me weeks ago, and I only got to it yesterday). In this particular case, he is tracking articles that are written by different members of our team and includes fields such as date published, published url, as well as the # of tweets, likes, and LinkedIn shares. Each week he’s able to use Salesforce to produce dashboards and reports that demonstrate how well (or poorly) articles are doing. The complication was that all the social stats (i.e. # of tweets, likes, and shares) were aggregated manually.

A perfect opportunity for scripting, no?

It’s really not that difficult. All three of these particular services provide a simple API that returns a JSON package with the counts we need. For example, let’s say I want to see counts/shares for my post announcing the Salesforce Toolkits for .NET.

For Twitter, create the URL https://cdn.api.twitter.com/1/urls/count.json?url=http://www.wadewegner.com/2014/01/announcing-the-salesforce-toolkits-for-net/ and parse the following JSON:

{
	"count" : 144,
	"url" : "http://www.wadewegner.com/2014/01/announcing-the-salesforce-toolkits-for-net/"
}

For Facebook, create the URL http://graph.facebook.com/http://www.wadewegner.com/2014/01/announcing-the-salesforce-toolkits-for-net/ and parse the following JSON:

{
	"id": "http://www.wadewegner.com/2014/01/announcing-the-salesforce-toolkits-for-net/",
	"shares": 28
}

For LinkedIn, create the URL: http://www.linkedin.com/countserv/count/share?url=http://www.wadewegner.com/2014/01/announcing-the-salesforce-toolkits-for-net/ and parse the following JSON:

IN.Tags.Share.handleCount({
	"count":18,
	"fCnt":"18",
	"fCntPlusOne":"19",
	"url":"http://www.wadewegner.com/2014/01/announcing-the-salesforce-toolkits-for-net/"
});

Pretty simple, right?

So, now the challenge is using this information to update all the records in Salesforce. Let me quickly describe to you the two approaches I took. The first was fast and simple, but long term has some complications. The second took longer to create but ultimately provides the soundest approach.

Approach 1: Using the Salesforce REST API

I started with this approach. Basically, logged in using the Username-Password authentication flow, grabbed my access token, performed a SOQL query to get all the records with published URLs, looped through them, and then issues an update via the REST API with the proper social counts. Pretty simple.

The problem with this approach is that, eventually, I’m going to hit my REST API limits. Not only is my query an API call, but so too is every update. The plan is for this script to run many times throughout the day. It won’t take too long for me to hit the limit.

Although it is a simple and elegant solution, ultimately it won’t work.

Approach 2: Using the Salesforce Bulk API

As you’ll see, this approach is a lot more involved. However, it’s also rock solid and designed to beyond the scenarios supported by the REST API.

The Bulk API is optimized for loading or deleting large sets of data. You can use it to query, insert, update, upsert, or delete a large number of records asynchronously by submitting batches which are processed in the background by Salesforce.

The easiest way to use Bulk API is to enable it for processing records in Data Loader using CSV files. This avoids the need to write your own client application. However, you can also send it XML, which avoids having to construct or generate CSV files; perfect, in my opinion, for our scenario.

Okay, enough talk. Let’s jump into the code.

Solution

To go really deep with the Bulk API, I recommend you review the Bulk API Developers Guide and watch the Fast Parallel Data Loading with the Bulk API presentation from Steve Bobrowski & Sean Regan.

There are, roughly, four steps involved in using the Bulk API:

Logging in.
Creating a job.
Adding a batch. (Or multiple batches.)
Closing the job (thereby starting it).

To facilitate these steps I created a file called async.py that had the four following methods.

You can see that this method does the following:

It constructs an XML string that includes the user name and password.
Defines some heads; in particular it includes the SOAPAction of login.
A requests post is made to the URL, passing the headers and the encoded data.
It returns the response to use.

Pretty simple and nothing surprising.

A few things worth noting here:

We pass in the instance which we derive from the login response. This is used to call against the correct Salesforce datacenter.
To successfully communicate with the API we need to validate ourselves with the sessionId, which was returned in the login response. This value is used in the header X-SFDC-Session to validate us against the API.
To create the job we have to specify an operation, i.e. insert, update, upsert, and so on.
We pass in the object we’re working with. For example, we’re using a custom object called Byline__c, so that’s what we’ll pass in.
There are two contentType values: CSV and XML. We need to specify which one we’re using.

This creates the job. Next we have to add a batch.

This is likely the most important, and undocumented, step - particularly when using XML.

You will need to construct an XML string that includes all the objects you want to manipulate.
For the purposes of this method I found it easier to create an objects parameter on addBatch and pass it in. We’ll walk through this in detail shortly.
Notice too that the url now includes the jobId that was returned from the createJob response.

Lastly we close the job.

As you can see, this is a pretty simple operation.

Before we pull it all together, let’s look at one more method I’ve created to facilitate the Bulk API operation. The reason I didn’t include this method above is you’ll see it’s very specific to the particular use case; i.e. we’re looping through a lot of data and constructing the object data we’ll eventually pass into the addBatch method.

Okay, there’s a bit going on here. Once you look, though, you’ll see that it’s not too complex.

The first thing to point out is that I’m using a library called simple_salesforce that provides a set of methods for interacting with the Salesforce REST API. Yes, I’m combining SOAP and REST APIs!
I perform a SOQL query to get the records that have a published link. This is returned as a Python dictionary from the query_all method.
Since it’s a dictionary I can easily get all the records and iterate through them all.
Using the URLs I identified above, I use requests to call each of the URLs to get the JSON responses. It’s then simple to pull out the count or shares.
Lastly, we add the data we pulled from the JSON responses and add it to the objectXml string that is ultimately returned. It’s worth noting that the Id value is required; everything else added to this object is updated in Salesforce.

Pretty simple!

Okay, let’s pull this all together.

As you can see, we’re simply calling our methods and evaluating the responses to get data that we pass into other methods.

Get the sessionId from the login. You could also grab the instance here with a simple regex.
Create a job and grab the jobId.
Create the objectXml data and pass it into addBatch to create the batch.
Close the batch, which starts the execution.

Now, let’s look at the job execution. Login into Salesforce and click Setup -> Jobs, and Bulk Data Load Jobs.

You can click the individual job to see the full details.

And that’s a wrap! I hope this helps explain the process so that, when you attempt to do something like this yourself, it won’t take you as long as it took me.

Announcing the Salesforce Accelerators for Windows Store Apps

Fri, 25 Apr 2014 00:00:00 +0000

Yesterday I was pleased to announce the Salesforce Accelerators for Windows Phone 8 Apps. Today I’m excited to tell you about the Salesforce Accelerators for Windows Store Apps:

These accelerators exist to make it easier for you to get started building Windows 8 store apps and work directly with the Salesforce Toolkits for .NET. Take a look at this short video to see just how easy it is to get started.

Let’s look in greater detail at how all of this works.

Using the DeveloperForce.Windows8.Login NuGet

Using the DeveloperForce.Windows8.Login NuGet is pretty straightforward and only involves a few steps.

Setup a Connected App in Salesforce (instructions here). Be sure to Enable OAuth Settings, at least choose Full access (full) and set the Callback URL to sfdc://success.
Install the NuGet Package via the command line …
```
 Install-Package DeveloperForce.Windows8.Login
```
… or using Manage NuGet Packages in Visual Studio. When you install this NuGet package you also get the DeveloperForce.Force and DeveloperForce.Common NuGet packages, which are defined as dependencies.
Open MainPage_SFDC.xaml.cs and change the ConsumerKey value to the one specified by your Connected App.
Open MainPage.xaml.cs wire up the Page_Loaded event. (You can also do this from the designer, as shown in the video.)
Make the MainPage_Loaded asynchronous and call the GetAccessToken method.
Run the application.

As you can see, using the NuGet is quite simple and takes away the guess work and trouble of setting up the user login experience. Nevertheless, it’s worth noting a few things about how it all works.

App_SFDC.xaml.cs is a partial class that extends the functionality of App by defining three public properties: AccessToken, RefreshToken, and InstanceUrl. These values are returned to us and set after the user logs in. Having these as public properties gives us the ability to share these around the app so that we can use them when making subsequent REST API calls.
MainPage_SFDC.xaml.cs is a partial class that extends the default MainPage.xaml.cs through the GetAccessToken method. It contains all the logic for interacting with the WebAuthenticationBroker which manages the authentication process for Windows Store Apps.
The GetAccessToken method first creates a set of URIs for the login process. It then initiates the WebAuthenticationBroker process by calling AuthenticateAsync. If the response comes back as a success the response URI is decoded and the AccessToken, RefreshToken, and InstanceUrl values are specified in the app variable.
Once the login process completes the MainPage.xaml is loaded.

That’s all it takes. After you login you’ll be back on a blank MainPage.xaml but you’ll have your AccessToken available to use when calling the Salesforce1 Platform REST APIs, which is a great transition to the DeveloperForce.Windows8.Samples.Accounts NuGet package accelerator.

Using the DeveloperForce.Windows8.Samples.Accounts NuGet

An access token is worthless if you don’t do anything with it.

Using the DeveloperForce.Windows8.Samples.Accounts NuGet makes it easy to create a page where you can query and view your account information. It is designed to demonstrate how to use the access token and instance url retrieved during the login process.

To use this NuGet, just follow these quick steps:

Install the NuGet Package via the command line …
```
 Install-Package DeveloperForce.Windows8.Samples.Accounts
```
… or using Manage NuGet Packages in Visual Studio.
After calling GetAccessToken navigate the user to the newly added AccountsPage.xaml.

That’s it! Now run it and see it in action.

As with the previous accelerator, it will help if you know a few things about how this works. Here’s the code that makes it function.

You can see that we first set our app variables so that we can get values like AccessToken and InstanceUrl.
Next we create an instance of the ForceClient.
We perform an asynchronous query using a simple SOQL select statement.
Lastly, we take the records and bind them to an accounts grid on the page.

It’s as simple as that!

It is my hope that these accelerators help get you over the initial hurdles that exist when building new applications that integrate with Salesforce. As always, if you have additional ideas (or find bugs!) you can open a new issue on Github or (if you’re so inclinded) take a tab at it yourself and send me a pull request.

I hope this helps!

Announcing the Salesforce Accelerators for Windows Phone 8 Apps

Thu, 24 Apr 2014 00:00:00 +0000

I am pleased to announce the Salesforce Accelerators for Windows Phone 8 Apps, a set of assets designed to make it easier to create new applications using the Salesforce Toolkits for .NET:

The Salesforce Toolkits for .NET, released earlier this year, allow you to interact with the Force.com and Chatter REST APIs using native .NET code on multiple platforms and devices. Many developers and companies have already benefited from these libraries and have built new ASP.NET web applications, Windows Phone 8 apps, and even Windows 8 store apps.

Nevertheless, one of the requests I kept receiving was to create additional tools and samples that make it easier to get started; little nuggets of code that accelerate the process. These accelerators are the answer to those requests and deliver functionality through small, composable NuGet packages.

This short video shows how quick and easy it is to build a Windows Phone 8 app that connects to Salesforce.

Let’s dig a little deeper and look at exactly what is happening.

Using the DeveloperForce.WindowsPhone8.Login NuGet

Using the DeveloperForce.WindowsPhone8.Login NuGet is pretty straightforward and only involves a few steps.

Setup a Connected App in Salesforce (instructions here). Be sure to Enable OAuth Settings, at least choose Full access (full) and set the Callback URL to sfdc://success.
Install the NuGet Package via the command line …
```
 Install-Package DeveloperForce.WindowsPhone8.Login
```
… or using Manage NuGet Packages in Visual Studio. When you install this NuGet package you also get the DeveloperForce.Force and DeveloperForce.Common NuGet packages, which are defined as dependencies.
Set LoginPage.xaml (installed with the NuGet) as the default page by changing Navigation Page in WMAppManifest.xml to Pages\LoginPage.xaml
Open Pages\LoginPage.xaml.cs and change the ConsumerKey value to the one specified by your Connected App.
Run the application.

App_SFDC.xaml.cs is a partial class that extends the functionality of App by defining three public properties: AccessToken, RefreshToken, and InstanceUrl. These values are returned to us and set after the user logs in. Having these as public properties gives us the ability to share these around the app so that we can use them when making subsequent REST API calls.
The LoginPage.xaml has a WebBrowser control. The user will log into Salesforce from within this control.
There is a set of constants defined at the top of the LoginPage.xaml.cs: AuthorizationEndpointUrl, ConsumerKey, CallbackUrl, and ApiVersion. The only value you must change is ConsumerKey as by default it is set to nonsense.
The LoginPage constructor enables scripts on the WebBrowser control. This is required for the login process to work.
The OnNavigatedTo event fires when the user is navigated to the login page. It constructs a URL to the Salesforce login page (using a helper from the DeveloperForce.Common NuGet) and then navigates the WebBrowser control to the page. This is where the user logs in and authorizes the application.
After the user logs in the WebBrowser_Navigating method is fired. If the return URI has the “sfdc://success” callback URI then we know that the login has been successful. The returned querystring contains the AccessToken, RefreshToken, and InstanceUrl; these values are grabbed and stored as global variables.
Lastly, the user is redirected back to the MainPage.xaml after a successful login. (Which you can see on line 18 in the code snippet above.)

Using the DeveloperForce.WindowsPhone8.Samples.Accounts NuGet

An access token is worthless if you don’t do anything with it.

Using the DeveloperForce.WindowsPhone8.Samples.Accounts NuGet makes it easy to create a page where you can query and view your account information. It is designed to demonstrate how to use the access token and instance url retrieved during the login process.

To use this NuGet, just follow these quick steps:

Install the NuGet Package via the command line …
```
 Install-Package DeveloperForce.WindowsPhone8.Samples.Accounts
```
… or using Manage NuGet Packages in Visual Studio.
Instead of navigating the user to the MainPage.xaml after logging in, navigate them to Pages\AccountsPage.xaml. In the WebBrowser_Navigating event on LoginPage.xaml.cs change URI as follows:

That’s it! Now run it and see it in action.

As with the previous accelerator, it will help if you know a few things about how this works. Here’s the code that makes it function.

You can see that we first ensure we have the InstanceUrl and AccessToken variables available.
Next we create an instance of the ForceClient.
We perform an asynchronous query using a simple SOQL select statement.
Lastly, we take the records and bind them to an accounts list on the page.

It’s as simple as that!

I hope this helps!

Wade Wegner

Build a Native Mobile App Using Salesforce DX and the Mobile SDK

Setup the CLI Plugin for the Mobile SDK

Setup Your Workspace

Create Your Mobile App with the Mobile SDK

Update the Mobile App to Use Your Scratch Org

Log Into the Mobile App

Conclusion

Authenticate to your Scratch Orgs using the OAuth 2.0 JWT Bearer Flow

Create the certificate & private key

Create the Connected App

Log into your Dev Hub with jwt:grant

Create a new scratch org and login with jwt:grant

Using Salesforce DX with Trailhead

Step 1: Log into your TPO using the CLI

Step 2: Create a project & scratch org

Step 3: Complete the challenge in the scratch org and pull the source

Step 4: Deploy to your TPO and verify

Profiles are messy and need clean-up

Script this step to make it easier

Additional things to know

Installing required packages

Exporting and importing data

Executing anonymous Apex code

Opening up a Lightning App

Wrap it up

Deploy to Salesforce DX

Background

Try it out

Word of warning

Use Workbench with your Scratch Org

Show the Salesforce DX Org Config in your Bash Prompt

Using the OAuth 2.0 JWT Bearer Flow to Support the Salesforce DX CLI

Creating a Plugin for the Salesforce CLI

Salesforce DX Strike

Salesforce DX Pilot Demos

Creating a Go Site Extension and Resource Template for Azure

Create the Site Extension

Create the Resource Template

4 Simple Steps to Run Go Language in Azure Websites

4 Simple Steps

Easy Go Programming Setup for Windows

5 Simple Steps

Verify

Build a Windows 8 App for Salesforce With No Code Using Project Siena

Create an iBeacon Transmitter with the Raspberry Pi

Required Hardware

Setup the Raspberry Pi as an iBeacon Transmitter

Step 1: Download an Operating System Image

Step 2: Write the Image to the SD Card

Step 3: Connect to the Raspberry Pi

Step 4: Initial Device Configuration

Step 5: Setup WiFi (Optional)

Step 6: Install Required Libraries

Step 7: Download, Make, & Install BlueZ Library

Setup the Raspberry Pi as an iBeacon Transmitter

Detect Your iBeacon Signal

Salesforce Did What? How We Built the Salesforce Toolkits for .NET

Uploading an Attachment to Salesforce with the SOAP and REST APIs

Python and Attachments with the REST API

Python and Attachments with the SOAP API

Update Records with Python and the Salesforce Bulk API

Approach 1: Using the Salesforce REST API

Approach 2: Using the Salesforce Bulk API

Solution

Announcing the Salesforce Accelerators for Windows Store Apps

Using the DeveloperForce.Windows8.Login NuGet

Using the DeveloperForce.Windows8.Samples.Accounts NuGet

Announcing the Salesforce Accelerators for Windows Phone 8 Apps

Using the DeveloperForce.WindowsPhone8.Login NuGet

Using the DeveloperForce.WindowsPhone8.Samples.Accounts NuGet

Log into your Dev Hub with `jwt:grant`

Create a new scratch org and login with `jwt:grant`