The Winter ’15 platform release brought us the new Queueable Apex interface. This interface is a cool new way to execute asynchronous computations on the Force.com platform, given you already know @future, Scheduled Apex Jobs, and Batch Jobs.
The main differences between @future methods and Queueable Apex jobs are:
- When you enqueue a new job, you get a job ID that you can actually monitor, like batch jobs or scheduled jobs!
- You can enqueue a queueable job inside a queueable job (no more “Future method cannot be called from a future or batch method” exceptions). As for Winter ’15 release, you can chain a maximum of two queueable jobs per call (so a job can fire another job and that’s it!). With Spring ’15 release, this limit has been removed.
- You can have complex Objects (such as SObjects or Apex Objects) in the job context (@future only supports primitive data types)
All I want to do in this article is show a practical use case for this interface (for those impatients out there, the complete code of this article can be found here).
Business requirement: You have to send a callout to an external service whenever a Case is closed.
Constraints: The callout will be a REST POST method that accepts a JSON body with all the non-null Case fields that are filled exactly when the Case is closed (the endpoint of the service will be a simple RequestBin).
The Queueable Apex Use Case
Using a future method, we will pass the case ID to the job and so make a subsequent SOQL query: this is against the requirement to pass the fields we have in the Case at the exact time of the update. This might seem an excessive constraint, but with big ORGs and hundreds of future methods in execution (due to system overload), future methods can actually be executed after minutes, so the Case state can be different from when the future was actually fired.
To store the attempts of callout (and the responses, this is only a helper method that allows for reportization of the attempts) we will use a new SObject called Callout__c with the given fields:
– Case__c: master/detail on Case
– Job_ID__c: external ID / unique / case sensitive, stores the queueable job ID
– Sent_on__c: date/time, when the callout took place
– Duration__c: integer, milliseconds for the callout to be completed (we can report timeouts easily)
– Status__c: picklist, valued are Queued (default), OK (response 200), KO (response != 200) or Failed (exception)
– Response__c: long text, stores the server response
To achive the Business needs, we need a Case trigger:
The trigger iterates bulkily through the trigger’s cases and if they are created as “Closed” or the Status field changes to “Closed,” a new job is enqueued and a Callout__c object is added to the list that will be inserted outside the “for.”
This way we always have evidence on the system that the callout has been fired.
Remember that you can add up to 50 jobs to the queue with System.enqueueJob in a single transaction, so you have to be sure that the trigger makes a maximum of 50 “System.enqueueJob” invocations (this is up to you!).
Let’s have a look at the job class:
The Queueable interface is the main reason of this article, while the Database.AllowsCallouts allow us to send a callout inside the job.
The constructor of the class consists on a single class member assignment:
Finally, let’s watch the main execute method of the job (the one that stores all the aynchronous logic):
These are the steps of execution:
1) Creates the JSON payload to be sent though the POST request (watch the method in the provided github repo) for more details (nothing more than a describe and a map).
2) Gets the Callout__c SObject that was created by the Case trigger (and using the context’s Job ID).
3) Gets the starting time of the callout being executed (to calculate the duration).
4) Tries to make the rest call
a. Server responded with a 200 OK
b. Server responded with a non OK status (e.g. 400, 500)
c. Saves the response body in the Response__c field
5) Callout failed, so the Respose__c field is filled with the stacktrace of the exception (believe me this is super usefull when trying to get what happened, expecially when you have other triggers / code in the “try” branch of the code).
6) Unfortunately, if you try to enqueue another job after a callout is done, you get the “Maximum callout depth has been reached.” exception; this is because you can have only two jobs in the queue chain that makes callouts, so if you queue another job with the Database.AllowsCallouts interface, you get this error. This way the job would have tried to enqueue another equal job for future execution.
7) Sets time fields on the Callout__c object.
8)Finally, creates an Attachment object with the JSON request done: this way it can be expected, knowing the precise state of the Case object sent, and can be re-submitted using a re-submission tool that uses the same code (it could be a Batch job for instance).
This is an example request (if you are curious about what I’m sending):
As already written, the full code for this Queueable Apex use case, with the related metadata, is available on this GitHub repo.
About the author
Enrico Murru (enree.co) is a Solution Architect and Senior Developer at WebResults (Engineering Group).
He started working on the Force.com platform in 2009 and since then he grew a big experience following the growth of the platform; he is also a huge Javascript lover.
In the last years he began to write technical blog posts for the dev community trying to document his fun with the Force.com platform and more.
His daydream is to become the first italian Force.com evalgelist, sharing his passion to all developers, and spend the rest of his professional life (and more) to learn new techs and experimenting.