Andy in the Cloud

From BBC Basic to Force.com and beyond…

Category Archives: Apex


by 16 Comments

Mocking SOQL sub-select query results

If your a fan of TDD you’ll hopefully have been following FinancialForce.com‘s latest open source contribution to the Salesforce community, known as ApexMocks. Providing a fantastic framework for writing true unit tests in Apex. Allowing you to implement mock implementations of classes used by the code your testing.

The ability to construct data structures returned by mock methods is critical. If its a method performing a SOQL query, there has been an elusive challenge in the area of queries containing sub-selects. Take a look at the following test which inserts and then queries records from the database.

	@IsTest
	private static void testWithDb()
	{
		// Create records
		Account acct = new Account(
			Name = 'Master #1');
		insert acct;
		List<Contact> contacts = new List<Contact> {
			new Contact (
				FirstName = 'Child',
				LastName = '#1',
				AccountId = acct.Id),
			new Contact (
				FirstName = 'Child',
				LastName = '#2',
				AccountId = acct.Id) };
		insert contacts;

		// Query records
		List<Account> accounts =
			[select Id, Name,
				(select Id, FirstName, LastName, AccountId from Contacts) from Account];

		// Assert result set
		assertRecords(acct.Id, contacts[0].Id, contacts[1].Id, accounts);
	}

	private static void assertRecords(Id parentId, Id childId1, Id childId2, List<Account> masters)
	{
		System.assertEquals(Account.SObjectType, masters.getSObjectType());
		System.assertEquals(Account.SObjectType, masters[0].getSObjectType());
		System.assertEquals(1, masters.size());
		System.assertEquals(parentId, masters[0].Id);
		System.assertEquals('Master #1', masters[0].Name);
		System.assertEquals(2, masters[0].Contacts.size());
		System.assertEquals(childId1, masters[0].Contacts[0].Id);
		System.assertEquals(parentId, masters[0].Contacts[0].AccountId);
		System.assertEquals('Child', masters[0].Contacts[0].FirstName);
		System.assertEquals('#1', masters[0].Contacts[0].LastName);
		System.assertEquals(childId2, masters[0].Contacts[1].Id);
		System.assertEquals(parentId, masters[0].Contacts[1].AccountId);
		System.assertEquals('Child', masters[0].Contacts[1].FirstName);
		System.assertEquals('#2', masters[0].Contacts[1].LastName);
	}

Now you may think you can mock the results of this query by simply constructing the required records in memory, but you’d be wrong! The following code fails to compile with a ‘Field is not writeable: Contacts‘ error on line 16.

		// Create records in memory
		Account acct = new Account(
			Id = Mock.Id.generate(Account.SObjectType),
			Name = 'Master #1');
		List<Contact> contacts = new List<Contact> {
			new Contact (
				Id = Mock.Id.generate(Contact.SObjectType),
				FirstName = 'Child',
				LastName = '#1',
				AccountId = acct.Id),
			new Contact (
				Id = Mock.Id.generate(Contact.SObjectType),
				FirstName = 'Child',
				LastName = '#2',
				AccountId = acct.Id) };
		acct.Contacts = contacts;

While Salesforce have gradually opened up write access to previously read only fields, the most famous of which being Id, they have yet to enable the ability to set the value of a child relationship field. Paul Hardaker contacted me recently to ask if this problem had been resolved, as he had the very need described above. Using his ApexMock’s framework he wanted to mock the return value of a Selector class method that makes a SOQL query with a sub-select.

Driven by an early workaround (I believe Chris Peterson found) to the now historic inability to write to the Id field. I started to think about using the same approach to stich together parent and child records using the JSON serialiser and derserializer. Brace yourself though, because its not ideal, but it does work! And i’ve managed to wrap it in a helper method that can easily be adapted or swept out if a better solution presents itself.

	@IsTest
	private static void testWithoutDb()
	{
		// Create records in memory
		Account acct = new Account(
			Id = Mock.Id.generate(Account.SObjectType),
			Name = 'Master #1');
		List<Contact> contacts = new List<Contact> {
			new Contact (
				Id = Mock.Id.generate(Contact.SObjectType),
				FirstName = 'Child',
				LastName = '#1',
				AccountId = acct.Id),
			new Contact (
				Id = Mock.Id.generate(Contact.SObjectType),
				FirstName = 'Child',
				LastName = '#2',
				AccountId = acct.Id) };

		// Mock query records
		List<Account> accounts = (List<Account>)
			Mock.makeRelationship(
				List<Account>.class,
				new List<Account> { acct },
				Contact.AccountId,
				new List<List<Contact>> { contacts });			

		// Assert result set
		assertRecords(acct.Id, contacts[0].Id, contacts[1].Id, accounts);
	}

NOTE: Credit should also go to Paul Hardaker for the Mock.Id.generate method implementation.

The Mock class is provided with this blog as a Gist but i suspect will find its way into the ApexMocks at some point. The secret of this method is that it leverages the fact that we can in a supported way expect the platform to deserialise into memory the following JSON representation of the very database query result we want to mock.

[
    {
        "attributes": {
            "type": "Account",
            "url": "/services/data/v32.0/sobjects/Account/001G000001ipFLBIA2"
        },
        "Id": "001G000001ipFLBIA2",
        "Name": "Master #1",
        "Contacts": {
            "totalSize": 2,
            "done": true,
            "records": [
                {
                    "attributes": {
                        "type": "Contact",
                        "url": "/services/data/v32.0/sobjects/Contact/003G0000027O1UYIA0"
                    },
                    "Id": "003G0000027O1UYIA0",
                    "FirstName": "Child",
                    "LastName": "#1",
                    "AccountId": "001G000001ipFLBIA2"
                },
                {
                    "attributes": {
                        "type": "Contact",
                        "url": "/services/data/v32.0/sobjects/Contact/003G0000027O1UZIA0"
                    },
                    "Id": "003G0000027O1UZIA0",
                    "FirstName": "Child",
                    "LastName": "#2",
                    "AccountId": "001G000001ipFLBIA2"
                }
            ]
        }
    }
]

The Mock.makeRelationship method turns the parent and child lists into JSON and goes through some rather funky code i’m quite proud off, to splice the two together, before serialising it back into an SObject list and vola! It currently only supports a single sub-select, but can easily be extended to support more. Regardless if you use ApexMocks or not (though you really should try it), i hope this helps you write a few more unit tests than you’ve previous been able.

 


by 92 Comments

Apex Metadata API Q&A

The Apex Metadata API has now been updated to reflect the Metadata API from Winter’15, which means a host of new component types, including the topic on everyones lips, Lightning! Though sadly, my demo around this will have to wait as I hit a platform issue i’ve sent to Salesforce Support to help me with.

This library continues to be incredibly popular, i can get between 1 to 4 questions a week asking how to accomplish certain goals, via my blog and/or issues raised on the GitHub repository. So I’m really pleased to continue to support it and keep it fresh! One day we will get native support for this, but until that day I’ll press on….

A lot of questions i get are around the Apex Metadata API, though almost all are really about using the Metadata API itself regardless of the calling language. So i thought i’d focus this blog on sharing some of the ways i’ve tackled unlocking the secrets of the mighty Metadata API. While the following tips and tricks are given in the context of Apex, some will work just fine in other languages consuming this API.

1. Do I have to download the Metadata API WSDL?

You don’t, just use the MetadataService.cls and its MetadataServiceTest.cls directly in your org. The point of this library is to avoid you having to go through the process of creating and manipulating the generated code from the Salesforce WSDL to Apex tool (the output of which is not directly useable). So unless you find i’m slacking and have not updated the library to the latest version of the platform, your good to go with the latest one in the repository!

2. How do I create X using the Metadata API?

The Apex Metadata API consists of many hundreds of classes within the MetadataService.cls file. Some represent top level Metadata components (items in your org), such as CustomObject, some are child components such as CustomField, others are simply class types referenced by these. Knowing which is which is important to know where to start, as only those classes that represent Metadata components can be used with the CRUD operations.

The easiest way to determine this is to first open the Metadata API documentation and look at the list of components here. The documentation also has a really good topic on how to spot the fact that classes will extend Metadata, if so they represent Metadata component classes you can use with the CRUD operations. As the topic suggests, despite the library having already used the WSDL, it is still worth downloading for reference purposes. While I try to make the Apex code match this extension concept it may not always be possible (Folders are a current gap).

So for example we see that Layout looks like this in the WSDL….

<xsd:complexType name="Layout">
    <xsd:complexContent>
        <xsd:extension base="tns:Metadata">
            <xsd:sequence>
                <xsd:element name="customButtons" minOccurs="0" maxOccurs="unbounded" type="xsd:string"/>
                <xsd:element name="customConsoleComponents" minOccurs="0" type="tns:CustomConsoleComponents"/>
                <xsd:element name="emailDefault" minOccurs="0" type="xsd:boolean"/>
                <xsd:element name="excludeButtons" minOccurs="0" maxOccurs="unbounded" type="xsd:string"/>
                <xsd:element name="feedLayout" minOccurs="0" type="tns:FeedLayout"/>
                <xsd:element name="headers" minOccurs="0" maxOccurs="unbounded" type="tns:LayoutHeader"/>
                <xsd:element name="layoutSections" minOccurs="0" maxOccurs="unbounded" type="tns:LayoutSection"/>
                <xsd:element name="miniLayout" minOccurs="0" type="tns:MiniLayout"/>
                <xsd:element name="multilineLayoutFields" minOccurs="0" maxOccurs="unbounded" type="xsd:string"/>
                <xsd:element name="quickActionList" minOccurs="0" type="tns:QuickActionList"/>
                <xsd:element name="relatedContent" minOccurs="0" type="tns:RelatedContent"/>
                <xsd:element name="relatedLists" minOccurs="0" maxOccurs="unbounded" type="tns:RelatedListItem"/>
                <xsd:element name="relatedObjects" minOccurs="0" maxOccurs="unbounded" type="xsd:string"/>
                <xsd:element name="runAssignmentRulesDefault" minOccurs="0" type="xsd:boolean"/>
                <xsd:element name="showEmailCheckbox" minOccurs="0" type="xsd:boolean"/>
                <xsd:element name="showHighlightsPanel" minOccurs="0" type="xsd:boolean"/>
                <xsd:element name="showInteractionLogPanel" minOccurs="0" type="xsd:boolean"/>
                <xsd:element name="showKnowledgeComponent" minOccurs="0" type="xsd:boolean"/>
                <xsd:element name="showRunAssignmentRulesCheckbox" minOccurs="0" type="xsd:boolean"/>
                <xsd:element name="showSolutionSection" minOccurs="0" type="xsd:boolean"/>
                <xsd:element name="showSubmitAndAttachButton" minOccurs="0" type="xsd:boolean"/>
                <xsd:element name="summaryLayout" minOccurs="0" type="tns:SummaryLayout"/>
            </xsd:sequence>
        </xsd:extension>
    </xsd:complexContent>
</xsd:complexType>

And looks like this in MetadataService.cls…

    public class Layout extends Metadata {
        public String type = 'Layout';
        public String fullName;
        public String[] customButtons;
        public MetadataService.CustomConsoleComponents customConsoleComponents;
        public Boolean emailDefault;
        public String[] excludeButtons;
        public MetadataService.FeedLayout feedLayout;
        public String[] headers;
        public MetadataService.LayoutSection[] layoutSections;
        public MetadataService.MiniLayout miniLayout;
        public String[] multilineLayoutFields;
        public MetadataService.QuickActionList quickActionList;
        public MetadataService.RelatedContent relatedContent;
        public MetadataService.RelatedListItem[] relatedLists;
        public String[] relatedObjects;
        public Boolean runAssignmentRulesDefault;
        public Boolean showEmailCheckbox;
        public Boolean showHighlightsPanel;
        public Boolean showInteractionLogPanel;
        public Boolean showKnowledgeComponent;
        public Boolean showRunAssignmentRulesCheckbox;
        public Boolean showSolutionSection;
        public Boolean showSubmitAndAttachButton;
        public MetadataService.SummaryLayout summaryLayout;
    }

Next find the page for this Metadata type in the Metadata API documentation, in this case Layout is here. Force.com is a complex platform at times, and the number of fields can be quite bewildering. So what i usual do is one or both of the following tricks.

Firstly, when you scroll down to the bottom of the documentation topics, there is usually an example of the component in XML form. Secondly I sometimes use my favourite tool, Force.com or MavensMate to download the component in file form from my org to generate my own example, useful if the documentation example is to basic for your needs. Basically the XML form in either case, matches exactly the data structures and values you need to provide in Apex.

For example the Layout example looks like this…

<Layout xmlns="http://soap.sforce.com/2006/04/metadata">
    <layoutSections>
        <editHeading>true</editHeading>
        <label>System Information</label>
        <layoutColumns>
            <layoutItems>
                <behavior>Readonly</behavior>
                <field>CreatedById</field>
            </layoutItems>
            <layoutItems>
                <behavior>Required</behavior>
                <field>Name</field>
            </layoutItems>
        </layoutColumns>
        <layoutColumns>
            <layoutItems>
                <behavior>Readonly</behavior>
                <field>LastModifiedById</field>
            </layoutItems>
        </layoutColumns>
        <style>TwoColumnsTopToBottom</style>
    </layoutSections>
    <summaryLayout>
        <masterLabel>Great Name</masterLabel>
        <sizeX>4</sizeX>
        <sizeY>2</sizeY>
        <summaryLayoutItems>
            <posX>0</posX>
            <posY>0</posY>
            <field>Name</field>
        </summaryLayoutItems>
    </summaryLayout>
</Layout>

Note you will need to set the fullName field as well, to understand how to format this for your Metadata component refer to the following Q&A items for more discussion. The equivalent Apex code would look like this…

		MetadataService.Layout layout = new MetadataService.Layout();
		layout.fullName = 'Test__c-My Layout';
		layout.layoutSections = new List<MetadataService.LayoutSection>();
		MetadataService.LayoutSection layoutSection = new MetadataService.LayoutSection();
		layoutSection.editHeading = true;
		layoutSection.label = 'System Information';
		layoutSection.style = 'TwoColumnsTopToBottom';
		layoutSection.layoutColumns = new List<MetadataService.LayoutColumn>();
		MetadataService.LayoutColumn layoutColumn = new MetadataService.LayoutColumn();
		layoutColumn.layoutItems = new List<MetadataService.LayoutItem>();
		MetadataService.LayoutItem layoutItem1 = new MetadataService.LayoutItem();
		layoutItem1.behavior = 'Readonly';
		layoutItem1.field = 'CreatedById';
		layoutColumn.layoutItems.add(layoutItem1);
		MetadataService.LayoutItem layoutItem2 = new MetadataService.LayoutItem();
		layoutItem2.behavior = 'Required';
		layoutItem2.field = 'Name';
		layoutColumn.layoutItems.add(layoutItem2);
		layoutSection.layoutColumns.add(layoutColumn);
		layout.layoutSections.add(layoutSection);
		layout.summaryLayout = new MetadataService.SummaryLayout();
		layout.summaryLayout.masterLabel = 'Great name';
		layout.summaryLayout.sizeX = 4;
		layout.summaryLayout.sizeY = 2;
		layout.summaryLayout.summaryLayoutStyle = 'Default';
		layout.summaryLayout.summaryLayoutItems = new List<MetadataService.SummaryLayoutItem>();
		MetadataService.SummaryLayoutItem summaryLayoutItem = new MetadataService.SummaryLayoutItem();
		summaryLayoutItem.posX = 0;
		summaryLayoutItem.posY = 0;
		summaryLayoutItem.field = 'Name';
		layout.summaryLayout.summaryLayoutItems.add(summaryLayoutItem);
		List<MetadataService.SaveResult> results =
			service.createMetadata(
				new MetadataService.Metadata[] { layout });

Note that this is a complex class with many other class types needed to expressed sections etc for the layout. All of these classes will be in the MetadataService.cls class as inner classes. Have this file open as you work your way through mapping the XML structure to the Apex one, so that you can see the field names and their Apex class types. Alternatively you can also have the WSDL open, as the names of the schema types will also match those in Apex.

3. How do I update X using the Metadata API?

Unlike records, you don’t always have to have read the Metadata component in order to update it. Nor do have to complete all the fields, just the ones you want to update. For example the following will update the labels on a Custom Object, but will not for example result in the Description, Custom Help  or other Custom Object information being cleared just because you didn’t set them. Quite handy!

MetadataService.CustomObject customObject = new MetadataService.CustomObject();
customObject.fullName = 'Test__c';
customObject.pluralLabel = 'Update Labels';
customObject.nameField = new MetadataService.CustomField();
customObject.nameField.type_x = 'Text';
customObject.nameField.label = 'Test Record Upsert';
customObject.deploymentStatus = 'Deployed';
customObject.sharingModel = 'ReadWrite';
List<MetadataService.UpsertResult> results =
  service.upsertMetadata(
    new MetadataService.Metadata[] { customObject });

As always though, there are some exceptions to this rule, which are sadly not documented. Fortunately if you’ve not set certain fields required for an update (and some don’t often make sense) the API is pretty good at telling you which ones you need. At this point however your probably going to want to know what the existing field values are, thus you will need to read the Metadata component, set the fields your wanting to update and then update it. You will of course want read a Metadata component if you want to add to a list of things, such as a PickList.

// Read Custom Field
MetadataService.CustomField customField =
  (MetadataService.CustomField) service.readMetadata('CustomField',
     new String[] { 'Lead.picklist__c' }).getRecords()[0];

// Add pick list values
metadataservice.PicklistValue two = new metadataservice.PicklistValue();
two.fullName= 'second';
two.default_x=false;
metadataservice.PicklistValue three = new metadataservice.PicklistValue();
three.fullName= 'third';
three.default_x=false;
customField.picklist.picklistValues.add(two);
customField.picklist.picklistValues.add(three);

// Update Custom Field
handleSaveResults(
   service.updateMetadata(
      new MetadataService.Metadata[] { customField })[0]);

4. How do I know the Full Name of the Metadata Component?

Metadata components are not referenced using Id’s, they use their Full Name. This can be a little tricky to track down sometimes, especially when it is a component such as a Layout that arrived in the org via a managed package, which means the Full Name will likely need to include the applicable namespace qualification, in some cases more than once!

The first thing i do is use the Developer Workbench to confirm the Full Name.

DeveloperWorkbench-FullName

MetadataService.Report report =
   (MetadataService.Report) service.readMetadata('Report',
      new String[] { 'MyFolder/MyReport' }).getRecords()[0];

As one of the users of the API found out, this can sometimes not give you an accurate result however. So the one known gotcha being Layouts, where the Full Name needs to be qualified twice with the Namespace. For example to retrieve a Layout installed with my DLRS managed package the following code would be required.

Note the dlrs namespace prefix is applied to both the Custom Object name portion of the Layout name, as well as the Layout name itself. In this case i still used the Developer Workbench approach above to get most of the name, then applied this now known adjustment to get it to work. The follow reads a packaged layout.

MetadataService.Layout layout =
   (MetadataService.Layout) service.readMetadata('Layout',
      new String[] { 'dlrs__LookupRollupSummaryLog__c-dlrs__Lookup Rollup Summary Log Layout' }).getRecords()[0];

5. Why does readMetadata not thrown an exception?

The previous examples have been using the readMetadata operation. This operation will not throw any exception if any of the full names given to it are invalid (as in the custom object does not exist). Instead empty records will be returned. For example the following illustrates that even with an invalid custom object Full Name a Metadata record is still returned, but the Full Name is null. So the advice here is to check the FullName for being none null before you trust the contents of information returned from readMetadata…

MetadataService.CustomObject customObject =
   (MetadataService.CustomObject) service.readMetadata('CustomObject',
      new String[] { 'DoesNotExist__c' }).getRecords()[0];
System.assertEquals(customObject.FullName, null);

6. Error ‘x’ is not a valid value for the enum ‘y’

While the Metadata API WSDL does contain a list of valid values for fields, the generated Apex code does not result in Enum’s being created for them sadly. As such you have to know the correct String value to set. This can often be determined from the documentation of course (though i have found a few typos in the docs in the past). So if your still struggling, check the WSDL enumeration to confirm you’ve got the correct value.

For example in the WSDL…

<xsd:complexType name="WebLink">
    <xsd:complexContent>
        <xsd:extension base="tns:Metadata">
            <xsd:sequence>
                ...
                <xsd:element name="displayType" type="tns:WebLinkDisplayType"/>
                ...
            </xsd:sequence>
        </xsd:extension>
    </xsd:complexContent>
</xsd:complexType>
<xsd:simpleType name="WebLinkDisplayType">
    <xsd:restriction base="xsd:string">
        <xsd:enumeration value="link"/>
        <xsd:enumeration value="button"/>
        <xsd:enumeration value="massActionButton"/>
    </xsd:restriction>
</xsd:simpleType>

Then in Apex code…

MetadataService.WebLink webLink = new MetadataService.WebLink();
webLink.fullName = 'Test__c.googleButton';
webLink.availability = 'online';
webLink.displayType = 'button';

7. How can I create or update Apex code?

The only way to create or update an Apex class or Trigger is to use the deploy operation, take a look at the Deploy demo in the library here for more information. I have also used this approach in my DLRS tool here. You can also use the Tooling API if you desire, however this only works in DE orgs, it cannot be used in a Production org. Currently the only way i know to create an Apex class or Trigger in Production is to use the deploy operation.

8. Retrieving Profile or Permission Set Information

You can retrieve a PermissionSet using the readMetadata as follows…

MetadataService.MetadataPort service = createService();
MetadataService.PermissionSet ps = (MetadataService.PermissionSet)
  service.readMetadata('PermissionSet', new String[] { 'Test' }).getRecords()[0];

The following code reads the Administrator Profile.

MetadataService.MetadataPort service = createService();
MetadataService.Profile admin = (MetadataService.Profile)
  service.readMetadata('Profile', new String[] { 'Admin' }).getRecords()[0];

Finally, also worth considering if your querying only, is that you can use SOQL to query the Permission Set objects directly, scroll down to the bottom of this topic to see the object model diagram.

Summary

I hope these will help future Metadata API coders with some of the more obscure behaviours and tasks they need to perform. You can also read more about the Metadata API operations here. If you’ve read all this and still find yourself scratching your head please feel free to raise an issue on the GitHub repository here and I’ll try to help!


by 65 Comments

Calling Flow from Apex

Since Summer’14 it has been possible to invoke a Flow from Apex, through the oddly named Interview system class method start. This blog talks about using this as a means to provide an extensibility mechanism, as an alternative option to asking an Apex developer to implement an Apex interface you’ve exposed. Clicks not code plugins!

Prior to Summer’14 it was only possible to embed a Flow in a Visualforce page, using the the flow:interview component, as described here. But this of course required a UI and hence user interaction to drive it. What if you wanted to allow admins to extend or customise the flow of some Apex logic using Flow from a none UI context?

Enter trigger ready-flows, first introduced as part of the Summer’14 pilot for running Flow from Workflow, which itself is still in Pilot, thought the ability to create trigger ready-flows is now generally available, yipee! Here’s what the docs have to say about them…

You can also build trigger-ready flows. A trigger-ready flow is a flow that can be launched without user interaction, such as from a flow trigger workflow action or the Apex interview.start method. Because trigger-ready flows must be able to run in bulk and without user interaction, they can’t contain steps, screens, choices, or dynamic choices in the active flow version—or the latest flow version, if there’s no active version.

This blog will present the following three examples of calling trigger-ready flows from Apex.

  • Hello World, returning a text value set in a Flow
  • Calc, shows passing in values to a Flow and returning the result of some processing.
  • Record Updater, shows passing in some SObject records to the Flow for processing and returning them.

Hello World Example

Here is a simple example that invokes a Flow that just returns a string value defined within the Flow.

ReturnHelloWorldFlow

ReturnHelloWorldAssignment

The following Apex code calls the above Flow and outputs to the Debug log.

// Call the Flow
Map<String, Object> params = new Map<String, Object>();
Flow.Interview.ReturnHelloWorld helloWorldFlow = new Flow.Interview.ReturnHelloWorld(params);
helloWorldFlow.start();

// Obtain the results
String returnValue = (String) helloWorldFlow.getVariableValue('ReturnValue');
System.debug('Flow returned ' + returnValue);

This outputs the following to the Debug log…

11:18:02.684 (684085568)|USER_DEBUG|[13]|DEBUG|Flow returned Hello from the Flow World!

Calc Example

This example passes in a value, which is manipulated by the Flow and returned.

CalcFlow CalcFlowAssignment

The following code invokes this Flow, by passing the X and Y values in through the Map.

// Call the Flow
Map<String, Object> params = new Map<String, Object>();
params.put('X', 10);
params.put('Y', 5);
Flow.Interview.Calc calcFlow = new Flow.Interview.Calc(params);
calcFlow.start();

// Obtain the results
Double returnValue = (Double) calcFlow.getVariableValue('ReturnValue');
System.debug('Flow returned ' + returnValue);

This outputs the following to the Debug log…

12:09:55.190 (190275787)|USER_DEBUG|[24]|DEBUG|Flow returned 15.0

Record Updater Example

With the new SObject and SObject Collection types in Summer’14 we can also pass in SObject’s. For example to apply some custom defaulting logic before the records are processed and inserted by the Apex logic. The following simple Flow loops over the records passed in and sets the Description field.

RecordUpdaterFlowRecordUpdaterAssignment

This code constructs a list of Accounts, passes them to the Flow and retrieves the updated list after.

// List of records
List<Account> accounts = new List<Account>{
	new Account(Name = 'Account A'),
	new Account(Name = 'Account B') };

// Call the Flow
Map<String, Object> params = new Map<String, Object>();
params.put('Accounts', accounts);
Flow.Interview.RecordUpdater recordUpdaterFlow = new Flow.Interview.RecordUpdater(params);
recordUpdaterFlow.start();

// Obtain results
List<Account> updatedAccounts =
	(List<Account>) recordUpdaterFlow.getVariableValue('Accounts');
for(Account account : updatedAccounts)
	System.debug(account.Name + ' ' + account.Description);

The follow debug update shows the field values set by the Apex code and those by the Flow…

13:10:31.060 (60546122)|USER_DEBUG|[39]|DEBUG|Account A Description set by Flow
13:10:31.060 (60588163)|USER_DEBUG|[39]|DEBUG|Account B Description set by Flow

Summary

Calling Flows from Apex is quite powerful to provide more complex extensibility back into the hands of admins vs developers. Though depending on your type of solution is somewhat hampered by the lack of the ability to dynamically create a subscriber configured Flow. As such for now is really only useful for none packaged Apex code deployments in production environment, where the referenced Flow’s can be edited (managed packaged Flows cannot be edited).

Despite this, for custom Apex code deployments to production it is quite powerful as it allows tweaks to the behaviour of solutions to be made without needing a developer to go through Sandbox and redeployment etc. Of course your also putting a lot of confidence in the person defining the Flows as well, so use this combo wisely with your customers!

Upvote: I’ve raised an Idea here to allow Apex to Dynamically create Flow Interview instances, with this in place ISV and packaged applications can make more use of this facility to provide clicks not code extensibility to their packaged application logic.

Update: Blog post Flow Factory presents a workaround to the dynamic calling problem.


by 7 Comments

Preview of Advanced Apex Enterprise Patterns Session

At this years Dreamforce i will be presenting not one, but two sessions on Apex Enterprise Patterns this year. The first will be re-run of last years session, Apex Enterprise Patterns : Building Strong Foundations. The second will be a follow on session dealing with more advanced topics around the patterns. Imaginatively entitled Advanced Apex Enterprise Patterns. The current abstract for this session is as follows…

Complex code can easily get out of hand without good design, so in this deep dive you will better understand how to apply the advanced design patterns used by highly experienced Salesforce developers. Starting with Interface & Base Class examples of OO design we quickly move on to new design features including: Application Factory, Field Level Security Support, Selector FieldSet support and Dependency Injection, Mock Testing of Services, Domain and Selector layers.​ By the end you will have a better understanding of how and when to apply these advanced Apex patterns.

If you attended the FinancialForce.com DevTalk in June this year, you will have got a sneak peak of some of the improvements being made to the supporting library for the patterns available in this repo. If you didn’t you’ll have to wait till Dreamforce! Oh go on then, i’ll give you a teaser here…

  • Introduction
  • Selector Enhancements, FieldSet and QueryFactory Support
  • Application Factory Introduction
  • Using Apex Interfaces to implement Common Service Layer Functionality
  • Introducing ApexMocks
  • Using ApexMocks with Service, Selector and Domain Layers
  • Field Level Security Experiment
  • Q&A 

I’m quite excited about all this content, but perhaps if pushed, i’d have to highlight the new Application Factory concept along with the integration with the exciting new ApexMocks library (also from FinancialForce.com R&D). This brings with it easier support for implementing polymorphic use cases in your application and the ability to mock layers of the patterns, such as Unit Of Work, Domain, Selector and Service layers. Allowing to develop true unit tests that are fast to execute by the platform and plentiful in terms of the variation of tests you’ll be able to develop without fear of extending the time your sat waiting for tests to execute!

Its is against my nature to publish a blog without a code sample in it, so i’ll leave you to ponder the following….

	public void applyDiscounts(Set<ID> opportunityIds, Decimal discountPercentage)
	{
		// Create unit of work to capture work and commit it under one transaction
	    fflib_ISObjectUnitOfWork uow = Application.UnitOfWork.newInstance();

		// Query Opportunities
		List<Opportunity> oppRecords =
			OpportunitiesSelector.newInstance().selectByIdWithProducts(opportunityIds);

		// Apply discount via Opportunties domain class behaviour
		IOpportunities opps = Opportunities.newInstance(oppRecords);
		opps.applyDiscount(discountPercentage, uow);

		// Commit updates to opportunities
		uow.commitWork();
	}

Here is a more generic service layer example, leveraging polymorphic Domain classes!

	public void generate(Set<Id> sourceRecordIds)
	{
		// Create unit of work to capture work and commit it under one transaction
		fflib_ISObjectUnitOfWork uow = Application.UnitOfWork.newInstance();

		// Invoicing Factory helps domain classes produce invoices
		InvoicingService.InvoiceFactory invoiceFactory = new InvoicingService.InvoiceFactory(uow);

		// Construct domain class capabile of performing invoicing
		fflib_ISObjectDomain domain =
			Application.Domain.newInstance(
				Application.Selector.selectById(sourceRecordIds));
		if(domain instanceof InvoicingService.ISupportInvoicing)
		{
			// Ask the domain object to generate its invoices
			InvoicingService.ISupportInvoicing invoicing = (InvoicingService.ISupportInvoicing) domain;
			invoicing.generate(invoiceFactory);
			// Commit generated invoices to the database
			uow.commitWork();
			return;
		}

		// Related Domain object does not support the ability to generate invoices
		throw new fflib_Application.ApplicationException('Invalid source object for generating invoices.');
	}

This last example shows how ApexMocks has been integrated into Application Factory concept via the setMock methods. The following is true test of only the service layer logic, by mocking the unit of work, domain and selector layers.

	@IsTest
	private static void callingServiceShouldCallSelectorApplyDiscountInDomainAndCommit()
	{
		// Create mocks
		fflib_ApexMocks mocks = new fflib_ApexMocks();
		fflib_ISObjectUnitOfWork uowMock = new fflib_SObjectMocks.SObjectUnitOfWork(mocks);
		IOpportunities domainMock = new Mocks.Opportunities(mocks);
		IOpportunitiesSelector selectorMock = new Mocks.OpportunitiesSelector(mocks);

		// Given
		mocks.startStubbing();
		List<Opportunity> testOppsList = new List<Opportunity> {
			new Opportunity(
				Id = fflib_IDGenerator.generate(Opportunity.SObjectType),
				Name = 'Test Opportunity',
				StageName = 'Open',
				Amount = 1000,
				CloseDate = System.today()) };
		Set<Id> testOppsSet = new Map<Id, Opportunity>(testOppsList).keySet();
		mocks.when(domainMock.sObjectType()).thenReturn(Opportunity.SObjectType);
		mocks.when(selectorMock.sObjectType()).thenReturn(Opportunity.SObjectType);
		mocks.when(selectorMock.selectByIdWithProducts(testOppsSet)).thenReturn(testOppsList);
		mocks.stopStubbing();
		Decimal discountPercent = 10;
		Application.UnitOfWork.setMock(uowMock);
		Application.Domain.setMock(domainMock);
		Application.Selector.setMock(selectorMock);

		// When
		OpportunitiesService.applyDiscounts(testOppsSet, discountPercent);

		// Then
		((IOpportunitiesSelector)
			mocks.verify(selectorMock)).selectByIdWithProducts(testOppsSet);
		((IOpportunities)
			mocks.verify(domainMock)).applyDiscount(discountPercent, uowMock);
		((fflib_ISObjectUnitOfWork)
			mocks.verify(uowMock, 1)).commitWork();
	}

All these examples will be available in the sample application repo once i’ve completed the prep for the session in a few weeks time.

Sadly the FinancialForce.com session on ApexMocks was not selected for Dreamforce 2014, however not to worry! FinancialForce.com will be hosting a DevTalk event during Dreamforce week where Jesse Altman will be standing in for the library author Paul Hardaker (get well soon Paul!), book your place now!

Finally, if you have been using the patterns for a while and have a question you want to ask in this session, please feel free to drop your idea into the comments box below this blog post!


by 37 Comments

Apex Metadata API Streamlined and Simplified for Summer’14

Compared to past updates the Summer’14 update to the Salesforce Metadata API might not look that exciting at first glance, i know it took me a second look to get more excited! This time its perhaps whats not in it thats the most interesting and what it means for new developers trying to use this often elusive API for the first time!

Basically Salesforce have removed from API 31 onwards most of the pesky async operations. For those who read my past blog on these operations, you’ll see that they require a fair bit of work on the callers behalf to keep polling Salesforce for the results. Spring’14 introduced immediate versions of these operations alongside the old async ones, now with Summer’14 the old ones have gone completely from the WSDL! Before you panic, fear not, if your using the API 30 or below endpoints in existing solutions they are still present.

It is clear now that the Salesforce developers behind the Metadata API have been on a mission to clean it up, simplify it and make it more in alignment with how you currently use the Partner API, REST and Tooling API’s from realtime CRUD API perspective. It now also sports an upsert operation, meaning that the set of database operations you can now perform on the vast array of Metadata Component types it contains is complete! As a result it is now much easier to see what operations you need to get things done and because they are immediate your calling code is now much much simpler!

Salesforce is quite special in having an additional database operation in its terminology, known as upsert. Its is available in Apex and through its existing API’s, and now in the Metadata API. For those not familiar, it basically short cuts the need to check if a record or in this case a component already exists if your aim is to create it if it doesn’t exist or update it if it does.

		MetadataService.MetadataPort service = createService();
		MetadataService.CustomObject customObject = new MetadataService.CustomObject();
		customObject.fullName = 'Test__c';
		customObject.label = 'Test';
		customObject.pluralLabel = 'Tests Upsert';
		customObject.nameField = new MetadataService.CustomField();
		customObject.nameField.type_x = 'Text';
		customObject.nameField.label = 'Test Record Upsert';
		customObject.deploymentStatus = 'Deployed';
		customObject.sharingModel = 'ReadWrite';
		List<MetadataService.UpsertResult> results =
			service.upsertMetadata(
				new MetadataService.Metadata[] { customObject });

In addition to these methods some of the old ones still exist, indeed there is no escaping the fact that if your wanting to create or retrieve many metadata components at once the retrieve and and deploy operations are still needed, and understandably still require aysnc type handling by the caller, since they could be quite long running operations.

Upgrade Advice: As always, i’ve updated the Apex Metadata API library to reflect the very latest release of the Metadata API. So if you are upgrading to the latest MetadataService.cls be aware the older methods will also not be present. The release notes here also cover other changes and new features. If your worried about this and don’t need any new component types for an existing project my advice is to stay with the earlier one and reserve this new version for new work. Finally i’ve retired some of the samples from the Apex Metadata API library focusing on using the Async API’s in batch and in Visualforce, as these would not compile anyway, they are of course still accessible through the repos history.

Of course, with most things there is always room for improvement! The ability to be able to run SOQL queries over the Metadata objects would be most welcome, the listMetadata method is just not flexible enough. Also the ability to create Apex Class and Apex Triggers without having to resort to using the deploy operation would also be appreciated.

I think Salesforce have done an amazing job at being committed to their API true to the core strategy here and with these changes it makes it so easy to go forth and do some cool stuff with the API without the extra overhead it had previously. No excuses now! 😉


by 38 Comments

Post Install Apex Metadata API Configuration Solved!

Since I created the Apex Metadata API I get to help all sorts of folks building many different and cool things with it. One that is quite common is to automate post package installation tasks such as updating layouts or picklist values, which are not auto upgraded by the platform.

What makes these use cases a little awkward and less user friendly is that the user installing the package has to perform at least one manual post install step. That is to create the Remote Site Setting to ironically allow the native Apex code to call a native SOAP or REST platform API (see Idea here to remove this need).

What makes it more tricky, is the URL the package install user has to provide for the Remote Site Setting is quite specialised, it has to contain the orgs instance name, the package namespace (if your using the Apex Metadata API from a Visualforce page) and potentially the orgs custom domain name.

blog_chart1As those that follow my blog will know my Declarative Rollup Summary Tool uses the Apex Metadata API and has the same requirement. Since i have defined the Apex Exception User on my package, i get an email notification each time an uncaught exception occurs in the tool. Despite putting instructions on a Welcome page in the tool to setup the Remote Site Setting, i can see by the frequency of System.CalloutException exception i get that this manual post install step is initially being missed.

About the same time i decided to raise an enhancement to remind me to look for a solution or at least better way to indicate this step to the user. I found this question Accessing Metadata API from JavaScript on StackExchange, referencing this earlier one Dynamically set Remote Site in Apex. The infamous Mr Fox had found the answer! Which was to call the Metadata API initially via JavaScript (which is not bound by the Remote Site Setting check). Thankfully since Summer’13 Salesforce supports making API calls from the Visualforce domains, otherwise this would not have been possible due to the browsers cross domain checking! Phew!

I already had configured on the landing tab of the tool a Welcome Visualforce page, so i decided to put the code to auto create the Remote Site Setting here. Note that since Summer’14 you can now also configure a post install page on your package, this would also be a good place. Here is my implementation of the answer given, with a few tweaks, UI and error handling.

Screen Shot 2014-07-29 at 07.39.04

 

You can see that I’ve offered the user two ways, manual and pressing the button. I chose to do this, so that admins would still be aware of what the tool was doing to the configuration in the org, which i feel when using the Metadata API is quite important. Once they press the button it makes the JavaScript callout to the Metadata API and the results are passed back to an apex:actionFunction to refresh the page.

Screen Shot 2014-07-29 at 07.50.59

First I wrote some code to test the API connection, which basically made a callout to the Apex Metadata API and caught any exception. I chose to use the listMetadata API call, but it could have been any. Its not the response we are interested in here, it is if it throws an exception or not. Unfortunately there is no language neutral way of checking the lack of Remote Site Setting, so for now the assumption is any CalloutException is a result of this.

	global static Boolean checkMetadataAPIConnection()
	{
		try {
			MetadataService.MetadataPort service = new MetadataService.MetadataPort();
			service.SessionHeader = new MetadataService.SessionHeader_element();
			service.SessionHeader.sessionId = UserInfo.getSessionId();
			List<MetadataService.ListMetadataQuery> queries = new List<MetadataService.ListMetadataQuery>();
			MetadataService.ListMetadataQuery remoteSites = new MetadataService.ListMetadataQuery();
			remoteSites.type_x = 'RemoteSiteSetting';
			queries.add(remoteSites);
			service.listMetadata(queries, 28);
		} catch (System.CalloutException e) {
			return false;
		}
		return true;
	}

Next I wrote a Visualforce Controller to call this and also calculate the URL needed by the Remote Site Setting. I did this via the Host HTTP Header, as this will include in a subscriber org all of the above attributes.

public with sharing class WelcomeController {

	public String Host {get;set;}

	public String MetadataResponse {get;set;}

	public Boolean MetadataConnectionWarning {get;set;}

	public PageReference checkMetadataAPIConnection()
	{
		// Get Host Domain
		Host = ApexPages.currentPage().getHeaders().get('Host');

		// Attempt to connect to the Metadata API
		MetadataConnectionWarning = false;
		if(!RollupService.checkMetadataAPIConnection())
		{
			// ... See full GitHub code ...
			MetadataConnectionWarning = true;
		}

		return null;
	}

	public PageReference displayMetadataResponse()
	{
		// ... See full GitHub code ...
		return null;
	}
}

Finally the Visualforce page with the JavaScript callout to the Metadata API in it! The code constructs the SOAP XML, makes the call and parses the result for any errors. Before calling an apex:actionFunction to refresh the page (only the key parts of the full page are shown below).

<apex:page controller="WelcomeController"
  tabStyle="LookupRollupSummary__c"
  standardStylesheets="true"
  action="{!checkMetadataAPIConnection}">
<script>
function createRemoteSite()
{
	// Disable button
	document.getElementById('createremotesitebtn').disabled = true;
	// Calls the Metdata API from JavaScript to create the Remote Site Setting to permit Apex callouts
	var binding = new XMLHttpRequest();
	var request =
		'<?xml version="1.0" encoding="utf-8"?>' +
		'<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">'+
			'<env:Header>' +
				'<urn:SessionHeader xmlns:urn="http://soap.sforce.com/2006/04/metadata">' +
					'<urn:sessionId>{!$Api.Session_ID}</urn:sessionId>' +
				'</urn:SessionHeader>' +
			'</env:Header>' +
			'<env:Body>' +
				'<createMetadata xmlns="http://soap.sforce.com/2006/04/metadata">' +
					'<metadata xsi:type="RemoteSiteSetting">' +
						'<fullName>dlrs_mdapi</fullName>' +
						'<description>Metadata API Remote Site Setting for Declarative Rollup Tool (DLRS)</description>' +
						'<disableProtocolSecurity>false</disableProtocolSecurity>' +
						'<isActive>true</isActive>' +
						'<url>https://{!Host}</url>' +
					'</metadata>' +
				'</createMetadata>' +
			'</env:Body>' +
		'</env:Envelope>';
	binding.open('POST', 'https://{!Host}/services/Soap/m/31.0');
	binding.setRequestHeader('SOAPAction','""');
	binding.setRequestHeader('Content-Type', 'text/xml');
	binding.onreadystatechange =
		function() {
			if(this.readyState==4) {
				var parser = new DOMParser();
				var doc  = parser.parseFromString(this.response, 'application/xml');
				var errors = doc.getElementsByTagName('errors');
				var messageText = '';
				for(var errorIdx = 0; errorIdx < errors.length; errorIdx++)
					messageText+= errors.item(errorIdx).getElementsByTagName('message').item(0).innerHTML + '\n';
				displayMetadataResponse(messageText);
			}
		}
	binding.send(request);
}
</script>
<body class="homeTab">
	<apex:form id="myForm">
		<apex:actionFunction name="displayMetadataResponse" action="{!displayMetadataResponse}" rerender="myForm">
			<apex:param name="metadataResponse" assignTo="{!metadataResponse}" value="{!metadataResponse}"/>
		</apex:actionFunction>
		<apex:sectionHeader title="Declarative Rollups for Lookups" subtitle="Welcome"/>
		<apex:pageMessages />
		<apex:outputPanel rendered="{!MetadataConnectionWarning}">
			<input id="createremotesitebtn" type="button" onclick="createRemoteSite();" value="Create Remote Site Setting"/>
		</apex:outputPanel>
	</apex:form>
</body>
</apex:page>

Its worth noting that this solution would also apply to configuring a Remote Site for other types of  Salesforce API callouts, such as Apex Tooling API, since its just the Domain part of the URL that needs to be added. Note you may need to add more Remote Sites if your also planning on calling from a Batch Apex context for example.

I’m really pleased with this implementation, but it is a little two baked into the rollup tool at present. This would make a great addition to the Apex Metadata API library (or maybe something more standalone) as a Visualforce Component for example, so that all you need to do is include the component on your welcome or post install pages to use it. Something for another day or a fellow open source developer to think about perhaps!?!

Security Review Notes: This approach has not gone through Security Review as yet. My feeling is that it should pass as there is president for calling Salesforce SOAP/REST API’s from JavaScript already and indeed was the main reason for Salesforce enabling the API endpoints from a VF domain as noted above in Summer’13. Nor does this approach bypass the CRUD, FLS or Permissions needed by such API’s, e.g. you still need to have Author Apex to permit Metadata API calls regardless of where they are called from. Finally the design approach here is user driven (e.g. they have to press abutton) rather than automated on page load (which they do generally discourage of course).


by 16 Comments

Doing more work with the Unit Of Work

In a previous post I introduced the Unit Of Work class, which is part of the Apex Enterprise Patterns series. As the original post describes it helps you simplify your code when it comes to performing multiple DML statements over related objects, as well as providing a bulkification and transaction management. In this post i would like to share information on a new feature that adds some extensibility to the fflib_SObjectUnitOfWork class.

This new feature addresses use cases where the work you want it to do, does not fit with the use of the existing registerDirty, registerNew or registerDeleted methods. But you do want that work to only be performed during the commitWork method, along with other registered work and within thesame transaction it manages.

Some examples of such situations are…

  • Sending Emails
    You want to register the sending an email once the work has completed and have that email only be sent if the entire unit of work completes.
  • Upsert
    You want to perform an upsert operation along with other insert, update and delete operations performed by the existing functionality.
  • Database class methods
    You want to utilise the Database class methods for additional functionality and/or granularity on some database operations, e.g. emptyRecycleBin, convertToLead, or perform an insert with allOrNothing set to false.
  • Self referencing objects
    You want to perform DML work relating to self referencing objects, something which is currently not supported by the registerNew and registerRelationship methods.
  • Nested Unit Of Works
    Though generally not recommended, if you do happen to have created another fflib_SObjectUnitOfWork instance, you might want to nest another unit of work instance commitWork call with another.

In these cases the class now contains a new Apex Interface, called IDoWork, it is an incredibly simple interface!

/**
* Interface describes work to be performed during the commitWork method
**/
public interface IDoWork
{
   void doWork();
}

To use this interface you implement it and register an instance of the implementing class through the new registerWork method. When the commitWork method is called it will callback on the doWork method for each registered implementations once it has completed the work given to it by the existing methods. In other words after all the DML on the dirty, new or deleted records have been processed.

A SendEmailWork implementation of this interface actually resides internally within the fflib_SObjectUnitOfWork class and is used to support another new method called, registerEmail. I added this to experiment with the feature during development but felt its worth leaving in as an added bonus feature if your writing code thats doing DML and sending emails!

The following example integrates the upsert method on the Database class (which needs a concreate SObject list), but you can really do anything you want in the doWork method!

	public class UpsertUnitOfWorkHelper implements fflib_SObjectUnitOfWork.IDoWork
	{ 		
		public Database.UpsertResult[] Results {get; private set;}
		
		private List<Account> m_records;
		
		public UpsertUnitOfWorkHelper()
		{  
			m_records = new List<Account>();
		}
		
		public void registerAccountUpsert(Account record)
		{
			m_records.add(record);
		}
		
		public void doWork()
		{
			Results = Database.upsert(m_records, false);				
		}
	}

The following is an example of this in use…

		// Create Unit Of Work as normal
		fflib_SObjectUnitOfWork uow =
			new fflib_SObjectUnitOfWork( 
				new Schema.SObjectType[] { 
					Product2.SObjectType, 
					PricebookEntry.SObjectType, 
					Opportunity.SObjectType, 
					OpportunityLineItem.SObjectType });
		
		// Register some custom work
		UpsertUnitOfWorkHelper myUpsertWork = new UpsertUnitOfWorkHelper();
		uow.registerWork(myUpsertWork);
				
		// Do standard work via...		
		
		// uow.registerNew(...)
		
		// uow.registerDeleted(...)
		
		// uow.registerDirty(...)
		
		// Register some custom work via...
		myUpsertWork.registerAccountUpsert(myAccountRecordToUpsert);
		
		// Commit work as normal
		uow.commitWork();
		
		// Optionally, determine the results of the custom work...
		List<Database.UpsertResult> myUpsertResults = myUpsertWork.Results;

In summary, the unit of work helps co-ordinate many things we do that in essence are part of a transaction of work we want to happen as a single unit. This enhancement helps integrate other “work” items your code might have been performing outside the unit of work into that single unit of work and transaction. It also helps bridge some gaps in the unit of work that exist today such as self referencing objects.

Please let me know your thoughts on this new feature and how you see yourself using it!


by 11 Comments

FinancialForce Apex Common Updates

This blog starts a series of updates leading up to Dreamforce 2014, where I am pleased to announce that my Advanced Apex Enterprise Patterns session has just been selected! In the coming series of blogs I will be covering enhancements to the existing base classes supporting the Apex Enterprise Patterns and highlighting some of the more general classes from within the FinancialForce Apex Common repository both reside in.

This time I will be highlighting some excellent contributions from fellow Force.com MVP Chris Peterson who has recently added more general utility classes to support security and dynamic queries. As well as some improvements from myself to the existing Domain and Selector classes.

In a following blog I’ll be going over in more detail the current results of some experimental work I’ve been doing relating to generic Field Level Security enforcement within the patterns base classes, meanwhile enjoy the new fflib_SecurityUtils class..

New fflib_SecurityUtils.cls

SecurityUtilsThe Salesforce Security Review currently requires that both object level and field level security is enforced by your code. The later of which, field level security has recently stirred up quite a lot of discussion and concern in the ISV community, more on this in the follow up blog post! In the meantime if you read the two Salesforce articles (here and here) describing the requirement and how to implement it in your Apex code (Visualforce offers some built in support for you). If like me, you’ll quickly realise the sample code provided is in reality somewhat verbose for anything more than a single object or field usage!

Enter the fflib_SecurityUtils class! As you can see from the UML representation shown here it’s methods are pretty simple and thus easy to use, an Apex exception is thrown if the user does not have access to the given object and/or fields. Here are some examples of it in use, you can choose to check individually or in bulk a set of fields and the object, covering both CRUD and Field Level Security.


fflib_SecurityUtils.checkObjectIsInsertable(Account.SObjectType);

fflib_SecurityUtils.checkInsert(
   Account.SObjectType,
   new List<Schema.SObjectField>{
      Account.Name,
      Account.ParentId, } );

fflib_SecurityUtils.checkUpdate(
   Lead.SObjectType,
   new List<Schema.SObjectField>{
     Lead.LastName,
     Lead.FirstName,
     Lead.Company } );

This class will also help perform object and field read access checks before making SOQL queries, though you may want to check out the features of the QueryFactory class as it also leverages this utility class internally.

New fflib_QueryFactory.cls

QueryFactory

The key purpose of this class is to make building dynamic SOQL queries safer and more robust than traditional string concatenation or String.format approaches. It also has an option to automatically check read security for the objects and fields given to it.

If your using Fieldsets in your Visualforce pages you’ll know that it’s generally up to you to query these fields, as you can see from the UML diagram, the class supports methods that allow you to provide the Fieldset name and have it automatically include those fields for you in the resulting query.

 

Chris has done an amazing job with this class not only in its feature and function but in its API design, leveraging the fluent model to make coding with it easy to use but also easy to read and understand. He first presented in at the FinancialForce DevTalks event this month, his presentation can be found here. In the presentation he gives some examples and discusses when you should use it and when not. So if your writing code like this currently…

String soql = ‘SELECT ‘;
for(Integer i = 0; i< fieldList.size(); i++){
  soql += fieldList + ‘, ‘;
}
soql = soql.substring(0,soql.length()-2);
soql += conditions != null && conditions.trim().size() > 0 ?  ‘ WHERE ‘ +
    soqlConditions : ‘’;
soql += limit != null && limit.trim().size() > 0 ? ‘ LIMIT ‘+limit;
List<Contact> nonBobs = Database.query(soql);

In it’s simplest form it’s use looks like this..

String soql =
  new fflib_QueryFactory(Contact.SObjectType)
    .selectField(Contact.Name)
    .setLimit(5)
    .toSOQL();

With object and field read security enforcement and Fieldset support would look like this…

String soql =
  new fflib_QueryFactory(Contact.SObjectType)
    .assertIsAccessible().
    .setEnforceFLS(true).
    .selectFields(myFields)
    .selectFieldSet(Contact.fieldSets.ContactPageFieldSet)
    .setCondition(‘Name != “Bob”’)
    .toSOQL();

The class is fully commented and the associated test class has further examples, also Chris is keen to work on API for the SOQL where clause in the future, i look forward to seeing it!

fflib_SObjectSelector.cls (Selector Pattern) Updates

I have updated this base class used to support the Selector pattern, to leverage the fflib_QueryFactory, in doing so you now have the option (as a constructor argument) to enable Field Level Security for fields selected by the selector. The default constructor and prior constructors are still supported, with the addition of the following that now allows you to control Fieldset, object and field level security enforcement respectively. For example…

OpportunitiesSelector oppsSelector =
    new OpportunitiesSelector(includeFieldSetFields, enforceObjectSecurity, enforceFLS);

NOTE: You can of course implement your own Selector default constructor and enable/disable these features by default within that, if you find yourself constantly passing a certain combination of these configurations parameters.

For custom selector methods you can leverage a QueryFactory constructed and initialised based on the Selector information, leaving you to add the additional where clause for the particular query logic the method encapsulates. Because of this you no longer need to add assertIsAccessible as the first line of your custom Selector methods. Prior to adopting QueryFactory a custom selector method might have looked like this…

public Database.QueryLocator queryLocatorReadyToInvoice()
{
  assertIsAccessible();
  return Database.getQueryLocator(
     String.format('SELECT {0} FROM {1} WHERE InvoicedStatus__c = \'\'Ready\'\' ORDER BY {2}',
     new List<String>{getFieldListString(),getSObjectName(),getOrderBy()}));
}

The updated patterns sample applications OpportunitiesSelector example to use the new newQueryFactory base class method, because this method pre-configures the factory with the selector object, fields, order by and fieldsets (if enabled), the new implementation is simplified and more focused on the criteria of the query the method encapsulates.

public Database.QueryLocator queryLocatorReadyToInvoice()
{
  return Database.getQueryLocator(
    newQueryFactory().setCondition('InvoicedStatus__c = \'\'Ready\'\'').toSOQL());
}

This updated fflib_SObjectSelector base class is backwards compatible from the API perspective, so you can choose to continue with the original String.format approach or adopt the newQueryFactory method accordingly. You can further review the old example here, against the new one here.

fflib_SObjectDomain.cls (Domain Pattern) Updates

This base class has to date had minimal functionality in it other than the routing of trigger events to the applicable virtual methods and object security enforcement. To support better configuration of these features and those in the future, i have added a new Domain class configuration feature, accessed via a new Configuration property.

Despite the focus on enforcing security in the above new features and updates, there are times when you want to enforce this in the calling code and not globally. For this reason the base class can now be configured to disable the object security checking (by default performed during the trigger after event), leaving it up to the calling code to enforce. Methods accessed from the new Configuration property can be used to control this.

public class ApplicationLogs extends fflib_SObjectDomain
{
  public ApplicationLogs(List<ApplicationLog__c> records)
  {
    super(records);
    Configuration.disableTriggerCRUDSecurity();
  }
}

Domain Trigger State

I have also been asked to provide a means to maintain member variable state between invocation of the trigger handler methods. Currently if you define a member variable in your Domain class it is reset between the before and after trigger phases. This is due to the default trigger handler recreating your Domain class instance each time.

If you want to retain information or records queried in the before handler methods in your class member variables such that it can be reused in the after handler methods, you can now enable this feature using the following configuration. The following illustrates the behaviour.

public class Opportunties extends fflib_SObjectDomain
{
  public String someState;

  public TestSObjectStatefulDomain(List<Opportunity> sObjectList)
  {
    super(sObjectList);
    Configuration.enableTriggerState();
  }

  public override void onBeforeInsert()
  {
    System.assertEquals(null, someState);
    someState = 'Something';
  }

  public override void onAfterInsert()
  {
    System.assertEquals('Something', someState);
  }
}

This feature is also aware of trigger recursion, meaning if there is such a scenario a new Domain class instance is created (since the records it wraps are new).


by 12 Comments

MavensMate Templates and Apex Enterprise Patterns

mavensmateI’ve been using MavensMate as alternative IDE for coding on Force.com for the past 6 months and loving it more and more to be honest, it receives a strong stream of updates, feels modern, responsive (as much as the underlying platform API’s permit) and is light weight. I’m also getting to grips with the power of the Sublime Text editor (which hosts MavensMate) and it’s excellent find and replace tools for example.  Recently i’ve been working on a feature with the help of the author of this fantastic tool Joe Ferraro.

One of the cool social features of MavensMate is it’s template engine, when ever you create a Apex class, Apex trigger, Visualforce Page or Visualforce Component, you can elect to start editing from scratch or pick one of a growing number of templates, ranging from Batch Apex, Controllers, Schedulers to Unit test templates, including a new one from a new friend in the push for BDD on Force.com, Paul Hardaker (also a FinancialForce.com employee btw). The whole thing is driven by a GitHub repository, if you contribute to that repository (and your pull request is merged) your template is instantly live across the world! Now that’s a social IDE!

I set about developing templates for the Apex Enterprise Patterns and quickly bumped into a gotcha! The previous template engine only took one parameter, the name of the Metadata component (Apex class or trigger name for example). When creating Domain classes or Selectors, the name of the class and the underlying custom object is required. After a quick Twitter conversation and GitHub issue, Joe had already nailed the design for a new feature to fix this situation! You can read more about how to use it here.

DomainTemplate

I’m pleased to report it worked like a charm the first time, great design and very flexible! The templates have now been submitted and successfully merged by Joe into the repository and are now live and ready to use!

  • DomainClass
  • DomainTrigger
  • SelectorClass
  • ServiceClass

The follow screenshot shows the template selection prompt, just start typing and it narrows the options down as you go, press enter and you are prompted for the template parameters. These parameters default to examples defined in the template configuration file, overwrite these with your own following the examples as a naming convention guide. Press enter again and MavensMate will create your class and present it back to you ready for you to start editing!

NewClassTemplateParametersInvoices

If you want to see a quick from zero to Domain class demo check out my demo video below. Thanks again Joe for such a great community tool and providing great support for it!


by 49 Comments

Apex Metadata API and Spring’14 : Keys to the Kingdom!

It seems like an absolute age since i first blogged about the new features Salesforce have added to the Spring’14 version of the Metadata API. This weekend my development org was finally upgraded and I was able to continue the work to upgrade the Apex wrapper around this API. The work is now complete and is formally the hardest and most time consuming upgrade yet, ultimately though the most worthwhile in terms of the way the API can now be used in Apex, it really feels like it has now finally unlocked the keys to the kingdom for Apex developers!

The last blog presented an example of reading and updating a Layout. With this release I’ve now extended this to all Metadata types. The introduction of the real time variants of the CRUD operations is a significant step forward in the usability of this library, particularly if your want to update rather than just create things.

Prior to Spring’14 you had to jump through quite a few hoops to read metadata, involving zip file handling in JavaScript and AJAX or Batch Apex code for handling asynchronous responses, as described in this blog. The async API variants still exist and are still supported, so all your code that used them before still works. There is also some reasons to consider still to use them, which i’ll cover later. Lets get into some new examples, all of which are available in MetadataServiceExamples.cls

Creating a Button and adding it to a Layout

		// Create Custom Button
		MetadataService.WebLink webLink = new MetadataService.WebLink();
		webLink.fullName = 'Test__c.googleButton';
		webLink.availability = 'online';
		webLink.displayType = 'button';
		webLink.encodingKey = 'UTF-8';
		webLink.hasMenubar = false;
		webLink.hasScrollbars = true;
		webLink.hasToolbar = false;
		webLink.height = 600;
		webLink.isResizable = true;
		webLink.linkType = 'url';
		webLink.masterLabel = 'google';
		webLink.openType = 'newWindow';
		webLink.position = 'none';
		webLink.protected_x = false;
		webLink.showsLocation = false;
		webLink.showsStatus = false;
		webLink.url = 'http://www.google.com';
		webLink.width = 600;
		handleSaveResults(
			service.createMetadata(
				new List<MetadataService.Metadata> { webLink })[0]);

		// Read the Layout
		MetadataService.Layout layout =
			(MetadataService.Layout) service.readMetadata('Layout',
				new String[] { 'Test__c-Test Layout' }).getRecords()[0];

		// Add the Custom Button to the Layout
		if(layout.customButtons==null)
			layout.customButtons = new List<String>();
		layout.customButtons.add('googleButton');

		// Update the Layout
		handleSaveResults(
			service.updateMetadata(
				new MetadataService.Metadata[] { layout })[0]);

Add a new Picklist Value

// Read Custom Field
MetadataService.CustomField customField =
    (MetadataService.CustomField) service.readMetadata('CustomField',
        new String[] { 'Lead.picklist__c' }).getRecords()[0];

// Add Picklist values
MetadataService.PicklistValue two = new MetadataService.PicklistValue();
two.fullName= 'second';
two.default_x=false;
MetadataService.PicklistValue three = new MetadataService.PicklistValue();
three.fullName= 'third';
three.default_x=false;
customField.picklist.picklistValues.add(two);
customField.picklist.picklistValues.add(three);	    

// Update Custom Field
handleSaveResults(
    service.updateMetadata(
        new MetadataService.Metadata[] { customField })[0]);

Copy Layout Sections between Layouts

		// Read the source Layout
		MetadataService.Layout sourceLayout =
			(MetadataService.Layout) service.readMetadata('Layout',
				new String[] { 'Test__c-Test Template Layout' }).getRecords()[0];

		// Read the target Layout
		MetadataService.Layout targetLayout =
			(MetadataService.Layout) service.readMetadata('Layout',
				new String[] { 'Test__c-Test Layout' }).getRecords()[0];

		// Add section from source Layout to target Layout
		targetLayout.layoutSections.add(
			sourceLayout.layoutSections[0]);

		// Update target Layout
		handleSaveResults(
			service.updateMetadata(
				new MetadataService.Metadata[] { targetLayout })[0]);

More possibilities…

Salesforce are doing an amazing job with Metadata API coverage these days. If you can see it in the Setup menu, i’d say there is a good chance you can find it in the Metadata API list of support Metadata types. Here are a few interesting use cases that you might want to think about…

  • Copy or merge tools. Ability to save admins potentially a significant number of clicks by writing tools to copy or merge Setup configuration.
  • Setup Wizards. Scripting the creation more complex Setup config, such as Force.com sites or templating the growing set of org Settings.
  • Field usage reporting. Read layouts, validation rules, workflows and search for field references.
  • Writing your own Change Sets, You could write your own scripts to move specific metadata and/or sync things like picklists between orgs.
  • Post install upgrades. Configuration UI to perform post install upgrades to none upgradable components, such as picklists and layouts in the subscriber org.

NOTE: One thing still not possible via the above CRUD methods is the creation of Apex Class or Apex Triggers, the only way (including the Tooling API) of doing this in a Production org, is still via the Metadata API deploy operation, thus the sample code for this in the library is still valid.

Upgrading to the new MetadataService.cls

For the first time since I’ve been refreshing the Apex wrapper MetadataService.cls, some of the metadata type classes and method signatures have changed. This is due to Salesforce changing the Metadata API of course, which they can do because they version at the end point, not at the WSDL level. I’m open to feedback on ways to avoid this in the future, such as the version on the end of the class, e.g. MetadataService30. The changes in this case which i have observed will effect require small changes to your use of the deploy method…

  • MetadataService.checkDeployStatus now takes a boolean argument, called includeDetails, read more here,
  • MetadataService.DeployResult class has a new details property replacing messages, read more here.

NOTE: The deploy example has been updated in the library with the above changes.

Scripting the Release Upgrade Process

I first described in my previous blog, that i have invested in developing a patcher script, a peace of Apex code i have written that parses the default Apex code output from the Generate Apex from WSDL button and automatically applies the usual changes i have been making manually to date to get things to work, plus some new changes to support the new readMetadata operation. I have included the patcher code in the library if you want to take a look at it and have updated the steps in the readme to create your own MetadataService.cls should you want to (in the event i don’t update it in the future for example). You do not need to worry about this if you plan to take the pre-patched MetadataService.cls from the repository, the above is really just an FYI.

Unsupported Metadata Types

The following Metadata types are not supported, as they utilise some specific features the above Patcher script does not support in relation to the use of shared Metadata type base classes. I’m confident these can be supported in the future and will like be working on these as part of the next release. I’ll be giving priority to those that have been the subject of recent questions , such as Flow and Sharing Rules.

  • Flow
  • Sharing Rules
  • Role
  • Custom Shortcut
  • Email Folder
  • Document Folder

Summary

Since its creation, i have been getting a steady flow of questions and requests for this library (evidence by the large examples class these days), so i can see there is demand for it in general, personally i’d still like to see it as a native library without the need to make the callouts. However until that time comes I’ll continue to support the community. Please do let me know what you’ve been getting up to with it and join in creating great community tools to help admins and developers be more productive!